명령 실행 도구

이 도구들은 AI 에이전트가 하나 이상의 서버에서 셸 명령을 실행하고, 이미 실행된 명령을 조회할 수 있게 합니다. “web-01에서 df -h를 실행하고 결과를 알려줘”나 “이 설정을 스테이징 플릿의 모든 서버에 배포해줘” 같은 요청을 처리합니다.

명령 실행은 항상 호출자에게 ACL 권한이 있어야 합니다. 규칙 관리 방법은 명령 ACL을 참고하세요. 호출자가 MCP OAuth나 브라우저 세션으로 인증하는 경우, 서버는 command 범위를 포함한 활성 작업 세션도 요구합니다. 정적 API 토큰과 서비스 토큰은 이 요구 사항을 우회합니다. 명령을 특정 세션에 연결하려면 work_session_id를 전달하거나, 인자를 생략했을 때 사용할 기본값으로 ALPACON_WORK_SESSION 환경 변수를 설정하세요.

요약

명령 이력

list_commands

서버에서 실행된 최근 명령을 상태, 출력, 타임스탬프와 함께 조회합니다. server_id로 필터링하면 특정 서버의 이력만 볼 수 있습니다. 새 명령을 실행하기 전 기존 실행 이력을 검토하거나, 이전에 제출한 명령의 결과를 확인할 때 사용합니다.

접근 수준: 읽기 전용

파라미터

예시

“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)을 지원합니다. 명령이 결과를 만들지 못하고 종료 상태(denied, rejected, stuck)에 도달하면, 이 도구는 타임아웃을 기다리지 않고 즉시 폴링을 멈추고 오류를 반환합니다.

명령 자체가 실행되기 전에 사람의 승인이 필요한 경우(아래에서 설명하는 sudo 처리와는 별개인 작업 세션 승인 절차), 이 도구는 awaiting_approval 상태의 구조화된 승인 대기 결과를 반환합니다. 승인 대기 중에는 명령을 다시 실행하지 마세요. 재제출은 별도의 승인이 필요하며, 원래 요청이 승인되면 명령이 중복 실행될 위험이 있습니다. 승인을 기다린 뒤 list_commands로 결과를 확인하세요.

명령에 sudo가 필요한데 비대화형 거부가 발생하면, 이 도구는 항상 거부 사유를 설명하는 자유 텍스트 힌트를 반환합니다. 사람이 직접 해결할 수 있는 세 가지 거부 사유(작업 세션 sudo 정책 부재, 필요한 MFA 재인증, 승인 대기 중인 sudo 요청)에 대해서는 이 힌트에 더해 구조화된 승인 대기 블록도 함께 반환하므로, 에이전트가 텍스트를 해석하지 않고 안정적인 카테고리로 분기할 수 있습니다. 사람은 Alpacon 웹 콘솔이나 CLI의 work-session update --sudo로 세션의 sudo 정책에 명령을 추가하거나, 재인증을 완료하거나, 요청을 승인한 뒤 다시 실행할 수 있습니다. SUDO_RISK_DENIED는 여기에 포함되지 않습니다. 런타임 위험 평가에 의한 강한 거부로 재시도나 승인 대상이 아니며, 이 경우에는 자유 텍스트 힌트만 반환됩니다.

접근 수준: 추가적

파라미터

command에 인라인 credential(시크릿 성격의 KEY=VALUE, 패스워드 플래그, 패스워드가 포함된 connection string)이 있으면, 서버는 명령을 저장하기 전에 command_inline_credential로 호출을 거부합니다. 시크릿은 env로 전달하세요. env는 쓰기 전용이라 명령 이력이나 감사 로그에 남지 않습니다.

예시

“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를 반복 호출하지 않고 한 번에 처리할 때 사용합니다.

접근 수준: 추가적

파라미터

예시

“웹 서버 3대 모두에서 systemctl status nginx를 실행해줘”

에이전트는 server_ids를 세 서버의 UUID로 설정하고 command="systemctl status nginx"로 execute_command_multi_server를 호출한 뒤, 어떤 서버가 성공하고 실패했는지 보고합니다.

관련 문서

• 작업 세션: OAuth 및 브라우저 기반 명령 실행에 필요한 작업 세션을 생성하고 관리합니다
• 접근 제어·승인: execute_command를 통제하는 명령 ACL 규칙을 관리합니다
• 파일 전송 도구: 동일한 서버로 파일을 업로드·다운로드합니다