Session Plan 도구

Session Plan 도구 (Session Plan Tool)

한 에이전트가 현재 세션의 계획을 쓰고, 준비됐다고 알리고, 호스트가 다음 턴을 실행 에이전트로 라우팅하게 하는 방법을 설명해요.

출처: 문서

본문

session_plan 도구셋은 한 에이전트에게 현재 세션의 계획을 쓸 자리, 계획이 준비됐다는 신호, 그리고 호스트가 다음 턴을 실행 에이전트로 라우팅하게 할 자리를 제공해요.

plan 도구셋과 다릅니다 — plan은 여러 세션에 걸쳐 여러 에이전트가 협업하는 공유 명명 계획용이에요. session_plan은 세션당 하나의 일시적 계획으로, ID로 그 세션에 범위가 한정돼요.

계획은 다음 아래에 Markdown 파일로 저장돼요:

~/.cagent/session_plans/<session-id>.md

도구 표면은 세 도구예요:

도구	설명
`write_session_plan`	이 세션의 계획을 markdown으로 생성 또는 교체. 세션당 정확히 하나의 계획
`read_session_plan`	현재 세션에 쓰인 계획을 읽고 markdown으로 반환
`exit_plan_mode`	계획이 검토 준비됐다고 신호. 스스로 에이전트를 전환하지는 않음

구성

toolsets:
  - type: session_plan

구성 옵션은 없어요. 계획 경로는 세션 ID에서 파생되고, 에이전트는 계획 이름을 짓지 않아요.

도구셋을 표준 방식으로 하위 집합으로 제한하세요:

# 계획을 소비하지만 (재)쓰거나 확정할 수 없는 에이전트.
toolsets:
  - type: session_plan
    tools:
      - read_session_plan

exit_plan_mode를 언제 호출할까

계획을 완성했고 다음 턴에서 바꿀 의도가 없으면 exit_plan_mode를 호출하세요. 세션에 계획이 존재하는지 검증하고 "준비 완료" 도구 결과를 반환해요. 스스로 에이전트를 전환하거나 사용자 승인을 구하지 않아요 — 다음 턴 라우팅은 호스트 애플리케이션이 소유해요(예: 도구 결과를 읽거나, 사용자가 토글하는 UI 수단, 또는 에이전트에 선언된 handoff).

이 분리는 도구를 여러 UI에서 재사용 가능하게 해 줘요: 도구 결과를 인라인으로 출력하는 CLI, 계획 모드 토글을 가진 채팅 UI, handoff로 다음 턴을 자동 라우팅하는 서버가 모두 서로 밟지 않고 같은 신호를 소비할 수 있어요.

저장과 정리

계획은 원자적으로(임시 파일 + 이름 바꾸기) 쓰이는 markdown 파일이라서, 동시 읽는 쪽(이 프로세스든 다른 프로세스든)이 부분 쓰기를 볼 수 없어요.
도구셋 첫 사용 시 최선 노력 스윕이 계획 디렉터리 아래 30일보다 오래된 계획 파일을 제거해요. 오래된 세션의 발가벗겨진 계획이 쌓이지 않아요.
세션 ID가 파일을 직접 식별해요. 인프로세스 뮤텍스나 리비전 카운터는 없어요. 두 세션이 같은 경로로 매핑될 수 없기 때문이에요.

이벤트

write_session_plan이 성공할 때마다 session_plan_updated 이벤트가 발생해요:

{
  "type": "session_plan_updated",
  "session_id": "...",
  "path": "/Users/.../.cagent/session_plans/<session-id>.md",
  "content": "# my plan\n...",
  "agent_name": "planner"
}

계획을 인라인으로 렌더링하는 임베더는 파일을 다시 읽지 않고 구독해 갱신할 수 있어요.

호스트에서 세션 계획 관리

세션 계획은 그 세션에 속해요: 호스트는 읽고 내보낼 수 있지만 절대 변경할 수 없어요.

CLI — docker agent plans 명령 그룹이 세션 계획을 공유 계획과 함께 나열·읽고(get --session <id>), 내보내요. 변경(update, status, delete)은 소유권 규칙을 설명하는 지원되지 않는 오류로 거부돼요.
TUI — /plans 브라우저(전체 키바인딩 표는 plan 도구셋 문서 참고)가 현재 세션의 계획을 세션 범위 행으로 포함해요. 다른 세션의 계획은 절대 나열되지 않아요. 그 식별자는 세션 ID이고 버전 열은 -를 보여줘요 — 세션 계획에는 버전이 없어요. Enter는 상세 뷰(범위, 세션 ID, 갱신 시각, 스크롤 가능한 markdown)를 열고, x는 작업 디렉터리에 session-plan-<id>.md로 내보냅니다(기존 파일 덮어쓰기 거부). e는 외부 편집기($VISUAL 또는 $EDITOR)에서 계획 본문을 열어 편집합니다 — 쓰기는 무방비이고 의도적으로 마지막 작성자가 이겨요. status와 delete는 세션 계획이 그것을 지원하지 않음을 보여줍니다(세션 계획은 자기 세션에 속하고 공유 계획 메타데이터가 없음). 브라우저는 session_plan_updated 이벤트에서 라이브로 갱신되어, 에이전트가 방금 쓴 계획이 다시 열지 않아도 나타나요.

예시

두 에이전트 워크플로: root는 실행하고 planner는 계획해요. /plan은 planner로 핸드오프하고, exit_plan_mode는 "준비 완료"를 신호하며, 호스트가 다음에 뭘 할지 결정해요.

agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: Executes approved plans
    instruction: |
      You execute plans the planner has handed off. When you see a message
      that a plan has been approved, read it with read_session_plan and work
      through its steps in order.
    toolsets:
      - type: session_plan
        tools:
          - read_session_plan
      - type: filesystem
      - type: shell
    commands:
      plan:
        description: "Switch to the planner"
        agent: planner

  planner:
    model: anthropic/claude-sonnet-4-5
    description: Investigates and writes plans for review
    instruction: |
      Investigate the user's request, then write the plan with
      write_session_plan. Iterate with the user until the plan is complete,
      then call exit_plan_mode to mark it ready for review.
    toolsets:
      - type: session_plan
      - type: filesystem
        readonly: true
      - type: user_prompt

examples/session_plan.yaml에서 완전한 작동 예시를 확인하세요.

오류 처리

read_session_plan과 exit_plan_mode는 write_session_plan 전에 호출되면 "no plan written yet" 오류를 반환해요.
write_session_plan은 세션 ID를 검증하고 계획 디렉터리를 벗어날 수 있는 것은 거부해요. 실제로 런타임이 UUID를 생성하므로, 임베더가 직접 만든 ID를 제공할 때만 발동해요.

팁 session_plan vs plan vs todo vs tasks 한 에이전트가 다른 에이전트가 실행하기 전에 사용자 검토용 접근법을 초안할 때 session_plan을 사용하세요(일시적, 세션당 하나). 여러 세션에 걸쳐 여러 에이전트가 협업하는 공유 명명 계획에는 plan을. 가벼운 세션 내 작업 목록에는 todo를. 우선순위와 의존성이 있는 구조화된 영구 작업 데이터베이스에는 tasks를 사용하세요.

더 알아보기 (Learn more)

Plan 도구로 공유 명명 계획 쓰기
User Prompt 도구로 사용자에게 질문하기