명령 실행 도구
이 도구들은 AI 에이전트가 하나 이상의 서버에서 셸 명령을 실행하고, 이미 실행된 명령을 조회할 수 있게 합니다. “web-01에서 df -h를 실행하고 결과를 알려줘”나 “이 설정을 스테이징 플릿의 모든 서버에 배포해줘” 같은 요청을 처리합니다.
명령 실행은 항상 호출자에게 ACL 권한이 있어야 합니다. 규칙 관리 방법은 명령 ACL을 참고하세요. 호출자가 MCP OAuth나 브라우저 세션으로 인증하는 경우, 서버는 command 범위를 포함한 활성 작업 세션도 요구합니다. 정적 API 토큰과 서비스 토큰은 이 요구 사항을 우회합니다. 명령을 특정 세션에 연결하려면 work_session_id를 전달하거나, 인자를 생략했을 때 사용할 기본값으로 ALPACON_WORK_SESSION 환경 변수를 설정하세요.
모든 도구는 workspace(필수)와 region(선택, 기본값은 설정된 리전)을 받습니다. 이 공통 파라미터는 아래 표에서 생략합니다.
요약
| 도구 | 설명 | 접근 수준 |
|---|---|---|
list_commands | 최근 명령 실행 이력 조회 | 읽기 전용 |
execute_command | 서버에서 명령을 실행하고 결과 대기 | 추가적 |
execute_command_multi_server | 여러 서버에서 동일한 명령 실행 | 추가적 |
명령 이력
list_commands
서버에서 실행된 최근 명령을 상태, 출력, 타임스탬프와 함께 조회합니다. server_id로 필터링하면 특정 서버의 이력만 볼 수 있습니다. 새 명령을 실행하기 전 기존 실행 이력을 검토하거나, 이전에 제출한 명령의 결과를 확인할 때 사용합니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
server_id | string | 아니오 | 이 서버에서 실행된 명령으로 결과를 필터링 |
limit | integer | 아니오 | 반환할 최대 결과 수 (기본값: 20) |
예시
“db-01 서버에서 실행된 최근 명령 10개를 보여줘”
에이전트는 server_id를 db-01의 UUID로, limit=10으로 설정해 list_commands를 호출하고, 각 명령의 상태·출력·타임스탬프를 반환합니다.
명령 실행
execute_command
서버에서 셸 명령을 실행하고 결과를 기다려, stdout·stderr·종료 코드를 한 번의 호출로 반환합니다. 명령을 실행하는 권장 방법은 이 도구이며, list_commands는 이력만 조회할 뿐 아무것도 실행하지 않습니다. 이 도구는 timeout초(기본값 300, 즉 5분)까지 완료를 폴링하며, 명령이 실제로 실행 중일 때는 마감 시간을 초기화하고, 무한 대기를 막기 위해 timeout의 3배를 상한으로 둡니다.
의존성 체인(run_after), 예약 실행(scheduled_at), stdin 입력(data)을 지원합니다. 명령에 sudo가 필요한데 호출자에게 일치하는 작업 세션 sudo 정책이 없거나 필요한 MFA 재인증이 없으면, 이 도구는 원본 거부 사유 대신 구조화된 승인 대기 결과를 반환합니다. 이를 사람에게 전달해 Alpacon 웹 콘솔에서 승인하거나 세션의 sudo 정책에 명령을 추가하도록 한 뒤 다시 실행하세요.
접근 수준: 추가적
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
server_id | string | 예 | 대상 서버 ID |
command | string | 예 | 실행할 셸 명령 |
shell | string | 아니오 | 명령을 실행할 셸 (기본값: system) |
username | string | 아니오 | 명령을 실행할 시스템 사용자 |
groupname | string | 아니오 | 명령을 실행할 시스템 그룹 (기본값: alpacon) |
env | object | 아니오 | 명령에 설정할 환경 변수 |
run_after | array | 아니오 | 이 명령이 실행되기 전에 완료되어야 하는 명령 ID |
scheduled_at | string | 아니오 | 즉시 실행 대신 미래 시각으로 예약 |
data | string | 아니오 | 명령의 stdin으로 전달할 데이터 |
timeout | integer | 아니오 | 완료를 기다릴 시간(초), 초과 시 타임아웃 (기본값: 300) |
work_session_id | string | 아니오 | 감사를 위해 이 명령을 연결할 작업 세션. 생략 시 ALPACON_WORK_SESSION을 사용 |
예시
“web-01에서
df -h를 실행하고 디스크 사용량을 보여줘”
에이전트는 server_id를 web-01의 UUID로, command="df -h"로 설정해 execute_command를 호출하고 결과를 기다린 뒤 stdout을 사용자에게 보고합니다.
“현재 작업 세션 안에서 api-02의 nginx를 재시작해줘”
에이전트는 work_session_id를 전달하거나(또는 ALPACON_WORK_SESSION에 의존해) 재시작이 해당 세션에 감사 기록으로 남도록 합니다.
execute_command_multi_server
여러 서버에서 동일한 셸 명령을 병렬(기본값)로, 또는 parallel=false로 순차 실행합니다. 서버별 성공/실패 상태를 반환합니다. 이 도구는 명령을 제출만 할 뿐 결과를 기다리지 않으므로, 이후 각 명령의 상태는 list_commands로 확인하세요.
설정 변경 배포, 버전 확인, 여러 서버에서 동일한 진단을 실행하는 등 플릿 전체에 걸친 작업을 execute_command를 반복 호출하지 않고 한 번에 처리할 때 사용합니다.
접근 수준: 추가적
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
server_ids | array | 예 | 대상 서버 ID 목록 |
command | string | 예 | 실행할 셸 명령 |
shell | string | 아니오 | 명령을 실행할 셸 (기본값: system) |
username | string | 아니오 | 명령을 실행할 시스템 사용자 |
groupname | string | 아니오 | 명령을 실행할 시스템 그룹 (기본값: alpacon) |
env | object | 아니오 | 명령에 설정할 환경 변수 |
parallel | boolean | 아니오 | 모든 서버에 동시 제출 (기본값: true). false로 설정하면 순차 제출 |
work_session_id | string | 아니오 | 감사를 위해 이 명령들을 연결할 작업 세션. 생략 시 ALPACON_WORK_SESSION을 사용 |
예시
“웹 서버 3대 모두에서
systemctl status nginx를 실행해줘”
에이전트는 server_ids를 세 서버의 UUID로 설정하고 command="systemctl status nginx"로 execute_command_multi_server를 호출한 뒤, 어떤 서버가 성공하고 실패했는지 보고합니다.