작업 세션 도구

Work Session은 인프라를 변경하는 MCP 액션의 범위를 감사 가능한 기록으로 제한하는 승인 기반 단위입니다. 호출자가 MCP OAuth나 브라우저 세션으로 인증한 경우, Alpacon 서버는 모든 execute_command 호출과 파일 전송이 활성 Work Session에 연결되어 있을 것을 요구합니다(정적 API 토큰과 서비스 토큰은 이 요구 사항을 우회합니다). 이 도구들은 세션 생성, 조회, 수정, 연장, 종료로 이어지는 전체 생명주기와, 완료된 세션에서 실행되는 AI 기반 보안 분석을 다룹니다. “prod-web-1의 nginx를 재시작할 수 있게 세션을 시작해줘”나 “어제 그 세션에서 무슨 일이 있었는지 보여줘” 같은 요청이 이 도구들로 이어집니다.

AI 에이전트는 Work Session을 승인하거나 거부할 수 없으며, 승인은 사람이 해야 합니다. 세션을 생성하면 흔히 pending 상태로 시작되며, Alpacon 웹 콘솔이나 Slack을 통해 사람이 별도로 승인해야 합니다. Work Session 수정 역시 동일한 승인이 필요한 수정 요청으로 큐에 쌓일 수 있습니다. 두 경우 모두 해당 도구는 그대로 실패하는 대신 구조화된 승인 대기 결과를 반환합니다. 이를 사람에게 전달하고, 승인된 뒤 다시 시도하세요.

execute_command처럼 work_session_id 인자를 받는 다른 도구는 이 인자를 생략하면 ALPACON_WORK_SESSION 환경 변수 값으로 대체합니다. 명시적으로 전달한 인자가 항상 우선합니다.

동일한 흐름을 CLI로 수행하려면 alpacon work-session을 참고하세요. 개념을 이해하려면 작업 세션 개요를 참고하세요.

모든 도구는 workspace(필수)와 region(선택, 미지정 시 설정된 리전 사용)을 공통으로 받습니다. 아래 표에서는 이 공통 파라미터를 생략합니다.

요약

도구설명접근 수준
work_session_create인프라 액션을 감사 가능한 승인 기반 세션으로 범위를 제한하는 Work Session을 생성합니다추가적
work_session_getWork Session의 상태, scope, 서버, 요청자 유형, 만료 시각을 조회합니다읽기 전용
work_session_list상태나 요청자 유형으로 필터링해 Work Session 목록을 조회합니다읽기 전용
work_session_updateWork Session의 제목, 설명, scope, 서버, 만료 시각을 부분 수정합니다멱등적 쓰기
work_session_extend승인되었거나 활성 상태인 Work Session의 만료 시각을 연장합니다멱등적 쓰기
work_session_timelineWork Session의 통합된 시간순 타임라인을 조회합니다읽기 전용
work_session_analyze종료된 Work Session에 대해 AI 보안 분석을 수동으로 트리거합니다멱등적 쓰기
work_session_closeWork Session을 완료 처리하고 AI 보안 분석을 트리거합니다파괴적

생성과 조회

work_session_create

이후 인프라 액션의 범위를 감사 가능한 승인 기반 기록으로 제한하는 Work Session을 생성합니다. description에는 무엇을, 왜 하는지 구체적으로 작성해야 합니다. “유지보수” 같은 모호한 한 줄은 사람이 승인하기 어렵습니다. Markdown을 사용할 수 있습니다. scopes는 이 세션이 허용하는 작업을 선언합니다: command(execute_command), webftp(파일 전송), tunnel(포트 포워딩), sudo(권한 상승). servers는 대상 서버 UUID 목록입니다.

이렇게 생성한 세션은 흔히 pending 상태로 시작하며, 범위 내 액션을 실행하기 전에 사람의 승인이 필요합니다. 이 경우 도구는 원본 세션 객체 대신 구조화된 승인 대기 결과를 반환합니다. work_session_get으로 상태를 폴링하며 active 상태가 될 때까지 기다리세요.

접근 수준: 추가적

파라미터

파라미터타입필수설명
scopesarray예이 세션이 허용하는 작업: command, webftp, tunnel, sudo
serversarray예대상 서버 UUID 목록
expires_atstring예세션이 만료되는 ISO 8601 날짜/시간
descriptionstring예무엇을, 왜 하는지에 대한 설명. Markdown 사용 가능
titlestring아니오짧은 세션 제목

예시

“prod-web-1의 nginx를 재시작할 작업 세션을 시작해줘. command 권한만, 2시간 후 만료로”

에이전트는 scopes=["command"], servers에 prod-web-1의 UUID, 구체적인 description을 담아 work_session_create를 호출하고, 사람의 승인을 기다린 뒤 재시작을 실행합니다.

work_session_get

Work Session의 현재 상태, scope, 서버, 요청자 유형, 만료 시각을 조회합니다. work_session_create나 work_session_update로 만들거나 수정한 세션이 pending을 지나 active 상태가 되었는지 확인할 때 사용합니다.

접근 수준: 읽기 전용

파라미터

파라미터타입필수설명
session_idstring예Work Session ID

예시

“내 작업 세션이 이제 활성화됐어?”

에이전트는 세션 ID로 work_session_get을 호출해 현재 상태를 알려줍니다.

work_session_list

워크스페이스의 Work Session 목록을 조회합니다. status(pending, approved, active, completed, rejected, cancelled, expired, revoked)나 requester_type(user는 사람이 요청한 세션, agent는 AI가 요청한 세션)으로 필터링할 수 있습니다.

접근 수준: 읽기 전용

파라미터

파라미터타입필수설명
statusstring아니오세션 상태로 필터링
requester_typestring아니오user 또는 agent로 필터링
limitinteger아니오반환할 최대 결과 수(기본값: 20)

예시

“에이전트가 연 대기 중인 작업 세션을 모두 보여줘”

에이전트는 status="pending", requester_type="agent"로 work_session_list를 호출합니다.

work_session_timeline

Work Session의 통합된 시간순 타임라인을 조회합니다: 명령, 파일 전송, Websh 활동, sudo 승인이 실행 순서대로 담깁니다. include_records=false로 설정하면 Websh 터미널 기록을 제외해 더 가벼운 응답을 받을 수 있습니다.

접근 수준: 읽기 전용

파라미터

파라미터타입필수설명
session_idstring예Work Session ID
include_recordsboolean아니오Websh 터미널 기록 포함 여부(기본값: true)

예시

“그 작업 세션에서 무슨 일이 순서대로 있었는지 알려줘”

에이전트는 세션 ID로 work_session_timeline을 호출하고 반환된 활동을 실행 순서대로 정리합니다.

수정

work_session_update

Work Session을 부분 수정합니다. 전달한 필드만 반영되며, title 같은 텍스트 필드는 빈 문자열을 전달하면 지워집니다. pending 상태 세션은 즉시 수정됩니다. approved 또는 active 상태 세션은 대신 수정 요청 흐름을 거칩니다. 서버가 변경 사항을 승인 대기 큐에 넣으면 이 도구는 status="pending_approval" 결과를 반환하며, 사람이 별도로 승인해야 변경이 적용됩니다.

expires_at은 세션이 pending 상태일 때만 반영됩니다. approved나 active 상태 세션에서는 무시되므로 대신 work_session_extend를 사용하세요. 종료 상태(completed, rejected, cancelled, expired, revoked) 세션은 수정할 수 없습니다.

접근 수준: 멱등적 쓰기

파라미터

파라미터타입필수설명
session_idstring예Work Session ID
titlestring아니오새 제목. ""을 전달하면 지웁니다
descriptionstring아니오새 설명. ""을 전달하면 지웁니다
scopesarray아니오허용 작업 목록 전체 교체
serversarray아니오대상 서버 UUID 목록 전체 교체
expires_atstring아니오새 만료 시각. 세션이 pending 상태일 때만 반영됩니다

예시

“활성 작업 세션의 서버 목록에 db-02를 추가해줘”

에이전트는 확장된 목록을 담아 work_session_update를 호출합니다. 세션이 active 상태이므로 이 변경은 사람의 승인을 기다리는 수정 요청으로 큐에 쌓입니다.

work_session_extend

승인되었거나 활성 상태인 Work Session의 만료 시각을 연장합니다. 새 expires_at은 현재 만료 시각보다 뒤여야 합니다. 세션에 연결된 sudo 정책이 있다면 함께 연장됩니다.

접근 수준: 멱등적 쓰기

파라미터

파라미터타입필수설명
session_idstring예Work Session ID
expires_atstring예현재 만료 시각보다 늦은 새 ISO 8601 날짜/시간

예시

“내 작업 세션을 1시간 더 연장해줘”

에이전트는 새 만료 시각을 담아 work_session_extend를 호출합니다.

분석과 종료

work_session_analyze

종료 상태인 Work Session(completed, expired, revoked)에 대해 AI 보안 분석을 수동으로 트리거합니다. rejected와 cancelled 세션은 한 번도 활성화된 적이 없으므로 분석할 대상이 없습니다. 분석은 보통 work_session_close로 세션을 종료할 때 자동 실행되며, 이 도구는 실패한 분석을 다시 실행할 때 사용합니다. force=true로 설정하면 pending이나 processing 상태에 멈춰 있는 분석을 재시도합니다. 이때도 서버는 최소 경과 시간 조건을 유지하며 이미 완료된 결과는 절대 폐기하지 않습니다.

접근 수준: 멱등적 쓰기

파라미터

파라미터타입필수설명
session_idstring예Work Session ID
forceboolean아니오pending 또는 processing 상태에 멈춘 분석 재시도(기본값: false)

예시

“그 세션의 보안 분석이 실패했어, 다시 시도해줘”

에이전트는 force=true로 work_session_analyze를 호출해 멈춰 있던 분석을 재시도합니다.

work_session_close

Work Session을 완료 상태로 표시하고 AI 보안 분석(Pass 1–4)을 트리거합니다. 세션 내 모든 명령과 파일 전송이 끝난 뒤 호출하세요.

접근 수준: 파괴적

파라미터

파라미터타입필수설명
session_idstring예Work Session ID

예시

“nginx 문제 해결이 끝났어, 작업 세션을 종료해줘”

에이전트는 세션 ID로 work_session_close를 호출해 세션을 종료하고 AI 보안 분석을 시작시킵니다.

관련 문서

최종 수정: