세션 이벤트 스트림

Claude Managed Agents와의 통신은 이벤트 기반입니다. 에이전트에 사용자 이벤트를 전송하고, 상태를 추적하기 위해 에이전트 및 세션 이벤트를 수신합니다.

모든 Managed Agents API 요청에는 managed-agents-2026-04-01 베타 헤더가 필요합니다. SDK는 베타 헤더를 자동으로 설정합니다.

이벤트 유형

이벤트는 두 방향으로 흐릅니다.

사용자 이벤트는 세션을 시작하고 진행 중에 방향을 조정하기 위해 에이전트에 전송하는 것입니다.
세션 이벤트, 스팬 이벤트, 에이전트 이벤트는 세션 상태와 에이전트 진행 상황을 관찰하기 위해 수신됩니다.

이벤트 유형 문자열은 {domain}.{action} 명명 규칙을 따릅니다.

모든 이벤트에는 이벤트가 서버 측에서 기록된 시점을 나타내는 processed_at 타임스탬프가 포함됩니다. processed_at이 null이면 이벤트가 하네스에 의해 큐에 추가되었으며 이전 이벤트 처리가 완료된 후 처리될 것임을 의미합니다.

각 이벤트 유형의 전체 스키마는 세션 이벤트 API 참조를 참조하세요.

이벤트 통합

추가 시나리오

커스텀 도구 호출 처리

에이전트가 커스텀 도구를 호출할 때:

세션은 도구 이름과 입력이 포함된 agent.custom_tool_use 이벤트를 방출합니다.
세션은 stop_reason: requires_action이 포함된 session.status_idle 이벤트와 함께 일시 중지됩니다. 차단 이벤트 ID는 stop_reason.requires_action.event_ids 배열에 있습니다.
시스템에서 도구를 실행하고 각각에 대해 user.custom_tool_result 이벤트를 전송하며, custom_tool_use_id 파라미터에 이벤트 ID와 결과 콘텐츠를 전달합니다.
모든 차단 이벤트가 해결되면 세션은 running 상태로 다시 전환됩니다.

도구 확인

권한 정책이 도구 실행 전 확인을 요구하는 경우:

세션이 agent.tool_use 또는 agent.mcp_tool_use 이벤트를 발생시킵니다.
세션이 stop_reason: requires_action을 포함하는 session.status_idle 이벤트와 함께 일시 중지됩니다. 차단 이벤트 ID는 stop_reason.requires_action.event_ids 배열에 있습니다.
각각에 대해 user.tool_confirmation 이벤트를 전송하고, tool_use_id 파라미터에 이벤트 ID를 전달합니다. result를 "allow" 또는 "deny"로 설정합니다. 거부 시 deny_message를 사용하여 이유를 설명합니다.
모든 차단 이벤트가 해결되면 세션이 다시 running 상태로 전환됩니다.

사용량 추적

세션 객체에는 누적 토큰 통계가 담긴 usage 필드가 포함되어 있습니다. 세션이 유휴 상태로 전환된 후 세션을 가져와 최신 합계를 읽고, 이를 사용하여 비용을 추적하거나 예산을 적용하거나 소비량을 모니터링할 수 있습니다.

{
  "id": "sesn_01...",
  "status": "idle",
  "usage": {
    "input_tokens": 5000,
    "output_tokens": 3200,
    "cache_creation_input_tokens": 2000,
    "cache_read_input_tokens": 20000
  }
}

input_tokens는 캐시되지 않은 입력 토큰을 보고하고, output_tokens는 세션 내 모든 모델 호출에 걸친 총 출력 토큰을 보고합니다. cache_creation_input_tokens 및 cache_read_input_tokens 필드는 프롬프트 캐싱 활동을 반영합니다. 캐시 항목은 5분 TTL을 사용하므로, 해당 시간 내에 연속으로 이루어지는 턴은 캐시 읽기의 혜택을 받아 토큰당 비용이 절감됩니다.

exec {fd}< <(curl -sS -N --fail-with-body \
  "https://api.anthropic.com/v1/sessions/$SESSION_ID/stream?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" \
  -H "Accept: text/event-stream")

while IFS= read -r -u "$fd" line; do
  [[ $line == data:* ]] || continue
  data="${line#data: }"
  [[ $(jq -r '.type' <<<"$data") == "session.status_idle" ]] || continue
  case $(jq -r '.stop_reason.type // empty' <<<"$data") in
    requires_action)
      while IFS= read -r event_id; do
        # 커스텀 도구 사용 이벤트를 조회하고 실행
        result=$(call_tool "$event_id")
        # 결과를 다시 전송
        jq -n --arg id "$event_id" --arg result "$result" \
          '{events: [{type: "user.custom_tool_result", custom_tool_use_id: $id, content: [{type: "text", text: $result}]}]}' |
          curl -sS --fail-with-body \
            "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")
      ;;
    end_turn)
      break
      ;;
  esac
done
exec {fd}<&-

exec {fd}< <(curl -sS -N --fail-with-body \
  "https://api.anthropic.com/v1/sessions/$SESSION_ID/stream?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" \
  -H "Accept: text/event-stream")

while IFS= read -r -u "$fd" line; do
  [[ $line == data:* ]] || continue
  data="${line#data: }"
  [[ $(jq -r '.type' <<<"$data") == "session.status_idle" ]] || continue
  case $(jq -r '.stop_reason.type // empty' <<<"$data") in
    requires_action)
      while IFS= read -r event_id; do
        # Approve the pending tool call
        jq -n --arg id "$event_id" \
          '{events: [{type: "user.tool_confirmation", tool_use_id: $id, result: "allow"}]}' |
          curl -sS --fail-with-body \
            "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")
      ;;
    end_turn)
      break
      ;;
  esac
done
exec {fd}<&-