멀티에이전트 세션

멀티에이전트 세션 - Claude API Docs

멀티에이전트는 리서치 프리뷰 기능입니다. 액세스 요청을 통해 사용해 보세요.

멀티에이전트 오케스트레이션을 통해 하나의 에이전트가 다른 에이전트들과 협력하여 복잡한 작업을 완료할 수 있습니다. 에이전트들은 각자 격리된 컨텍스트를 가지고 병렬로 작동할 수 있으며, 이를 통해 출력 품질을 향상시키고 완료 시간을 단축할 수 있습니다.

모든 Managed Agents API 요청에는 managed-agents-2026-04-01 베타 헤더가 필요합니다. 리서치 프리뷰 기능에는 추가 베타 헤더가 필요합니다. SDK는 이러한 베타 헤더를 자동으로 설정합니다.

작동 방식

모든 에이전트는 동일한 컨테이너와 파일시스템을 공유하지만, 각 에이전트는 자체 세션 스레드에서 실행됩니다. 스레드는 자체 대화 기록을 가진 컨텍스트 격리 이벤트 스트림입니다. 코디네이터는 기본 스레드(세션 수준 이벤트 스트림과 동일)에서 활동을 보고하며, 코디네이터가 위임을 결정할 때 런타임에 추가 스레드가 생성됩니다.

스레드는 영속적입니다: 코디네이터는 이전에 호출한 에이전트에게 후속 메시지를 보낼 수 있으며, 해당 에이전트는 이전 턴의 모든 내용을 유지합니다.

각 에이전트는 해당 에이전트가 생성될 때 정의된 자체 구성(모델, 시스템 프롬프트, 도구, MCP 서버 및 스킬)을 사용합니다. 도구와 컨텍스트는 공유되지 않습니다.

위임할 작업

멀티에이전트 세션은 전체 목표 내에 잘 정의된 전문화된 작업이 여러 개 있을 때 가장 효과적입니다:

코드 리뷰: 집중된 시스템 프롬프트와 읽기 전용 도구를 가진 리뷰어 에이전트.
테스트 생성: 프로덕션 코드를 건드리지 않고 테스트를 작성하고 실행하는 테스트 에이전트.
리서치: 코디네이터에게 결과를 요약하여 전달하는 웹 도구를 가진 검색 에이전트.

호출 가능한 에이전트 선언

에이전트를 정의할 때 호출이 허용된 추가 에이전트 ID를 나열합니다:

orchestrator=$(curl -fsS https://api.anthropic.com/v1/agents \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<EOF
{
  "name": "Engineering Lead",
  "model": "claude-sonnet-4-6",
  "system": "You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.",
  "tools": [
    {
      "type": "agent_toolset_20260401"
    }
  ],
  "callable_agents": [
    {"type": "agent", "id": "$REVIEWER_AGENT_ID", "version": $REVIEWER_AGENT_VERSION},
    {"type": "agent", "id": "$TEST_WRITER_AGENT_ID", "version": $TEST_WRITER_AGENT_VERSION}
  ]
}
EOF
)

callable_agents의 각 항목은 기존 에이전트의 ID여야 합니다. 위임은 한 단계만 지원됩니다: 코디네이터는 다른 에이전트를 호출할 수 있지만, 해당 에이전트들은 자체적으로 다른 에이전트를 호출할 수 없습니다.

그런 다음 오케스트레이터를 참조하는 세션을 생성합니다:

호출 가능한 에이전트들은 오케스트레이터의 구성에서 확인됩니다. 세션 생성 시 이들을 참조할 필요가 없습니다.

세션 스레드

세션 수준 이벤트 스트림(/v1/sessions/:id/stream)은 기본 스레드로 간주되며, 모든 스레드에 걸친 모든 활동의 요약된 뷰를 포함합니다. 호출된 에이전트들의 개별 추적은 볼 수 없지만, 그들의 작업 시작과 종료는 확인할 수 있습니다. 세션 스레드는 특정 에이전트의 추론과 도구 호출을 자세히 살펴볼 수 있는 곳입니다.

세션 상태도 모든 에이전트 활동의 집계입니다; 적어도 하나의 스레드가 running 상태이면 전체 세션 상태도 running이 됩니다.

세션의 모든 스레드를 나열하는 방법은 다음과 같습니다:

특정 스레드에서 이벤트를 스트리밍합니다:

스레드의 과거 이벤트를 나열합니다:

멀티에이전트 이벤트 유형

이러한 이벤트들은 최상위 세션 스트림에서 멀티에이전트 활동을 표시합니다.

유형	설명
`session.thread_created`	코디네이터가 새 스레드를 생성했습니다. `session_thread_id`와 `model`을 포함합니다.
`session.thread_idle`	에이전트 스레드가 현재 작업을 완료했습니다.
`agent.thread_message_sent`	에이전트가 다른 스레드에 메시지를 보냈습니다. `to_thread_id`와 `content`를 포함합니다.
`agent.thread_message_received`	에이전트가 다른 스레드로부터 메시지를 받았습니다. `from_thread_id`와 `content`를 포함합니다.

스레드에서의 도구 권한 및 커스텀 도구

callable_agent 스레드가 클라이언트로부터 무언가가 필요할 때(권한으로 always_ask 도구를 실행하거나, 커스텀 도구의 결과), 요청은 session_thread_id 필드와 함께 세션 스트림에 표시됩니다. 플랫폼이 대기 중인 스레드로 다시 라우팅할 수 있도록 응답을 게시할 때 동일한 session_thread_id를 포함하세요.

session_thread_id가 있는 경우: 이벤트가 서브에이전트 스레드에서 발생했습니다. 응답에 이를 그대로 포함하세요.
session_thread_id가 없는 경우: 이벤트가 기본 스레드에서 발생했습니다. 해당 필드 없이 응답하세요.
tool_use_id를 기준으로 요청과 응답을 매칭하세요.

아래 예시는 응답을 라우팅하기 위해 도구 확인 핸들러를 확장합니다. 동일한 패턴이 user.custom_tool_result에도 적용됩니다.

session=$(curl -fsS https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{"agent": "'$ORCHESTRATOR_ID'", "environment_id": "'$ENVIRONMENT_ID'"}')

curl -fsS "https://api.anthropic.com/v1/sessions/$SESSION_ID/threads" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  | jq -r '.data[] | "[\(.agent_name)] \(.status)"'

curl -fsSN "https://api.anthropic.com/v1/sessions/$SESSION_ID/threads/$THREAD_ID/stream" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" |
  while IFS= read -r line; do
    [[ $line == data:* ]] || continue
    json=${line#data: }
    case $(jq -r '.type' <<<"$json") in
      agent.message)
        printf '%s' "$(jq -j '.content[] | select(.type == "text") | .text' <<<"$json")"
        ;;
      session.thread_idle)
        break
        ;;
    esac
  done

curl -fsS "https://api.anthropic.com/v1/sessions/$SESSION_ID/threads/$THREAD_ID/events" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  | jq -r '.data[] | "[\(.type)] \(.processed_at)"'

while IFS= read -r event_id; do
  pending=$(jq -r --arg id "$event_id" '.[$id]' <<<"$events_by_id")
  thread_id=$(jq -r '.session_thread_id // empty' <<<"$pending")
  jq -n --arg id "$event_id" --arg thread "$thread_id" '
    {events: [
      {type: "user.tool_confirmation", tool_use_id: $id, result: "allow"}
      + (if $thread != "" then {session_thread_id: $thread} else {} end)
    ]}' |
    curl -fsS "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?beta=true" \
      -H "x-api-key: $ANTHROPIC_API_KEY" \
      -H "anthropic-version: 2023-06-01" \
      -H "anthropic-beta: managed-agents-2026-04-01" \
      -H "content-type: application/json" \
      -d @-
done < <(jq -r '.stop_reason.event_ids[]' <<<"$data")