세션 이벤트 스트림

이벤트를 전송하고, 응답을 스트리밍하며, 실행 중 세션을 중단하거나 리디렉션합니다.

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

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

이벤트 유형

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

사용자 이벤트는 에이전트에 전송하여 세션을 시작하고 진행 상황에 따라 조종하는 것입니다.
세션 이벤트, 스팬 이벤트, 에이전트 이벤트는 세션 상태와 에이전트 진행 상황에 대한 관찰성을 위해 사용자에게 전송됩니다.

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

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

이벤트 통합

추가 시나리오

사용자 정의 도구 호출 처리

에이전트가 사용자 정의 도구를 호출할 때:

세션이 도구 이름과 입력을 포함하는 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으로 전환됩니다.

with client.beta.sessions.events.stream(session.id) as stream:
    for event in stream:
        if event.type == "session.status_idle" and (stop := event.stop_reason):
            match stop.type:
                case "requires_action":
                    for event_id in stop.event_ids:
                        # Look up the custom tool use event and execute it
                        tool_event = events_by_id[event_id]
                        result = call_tool(tool_event.name, tool_event.input)

                        # Send the result back
                        client.beta.sessions.events.send(
                            session.id,
                            events=[
                                {
                                    "type": "user.custom_tool_result",
                                    "custom_tool_use_id": event_id,
                                    "content": [{"type": "text", "text": result}],
                                },
                            ],
                        )
                case "end_turn":
                    break

도구 확인

권한 정책에서 도구 실행 전 확인이 필요한 경우:

세션이 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으로 전환됩니다.

with client.beta.sessions.events.stream(session.id) as stream:
    for event in stream:
        if event.type == "session.status_idle" and (stop := event.stop_reason):
            match stop.type:
                case "requires_action":
                    for event_id in stop.event_ids:
                        # Approve the pending tool call
                        client.beta.sessions.events.send(
                            session.id,
                            events=[
                                {
                                    "type": "user.tool_confirmation",
                                    "tool_use_id": event_id,
                                    "result": "allow",
                                },
                            ],
                        )
                case "end_turn":
                    break

사용량 추적

세션 객체는 누적 토큰 통계를 포함하는 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을 사용하므로 해당 기간 내의 연속 턴은 캐시 읽기의 이점을 누리며, 이는 토큰당 비용을 줄입니다.

Was this page helpful?

빌드에이전트에 작업 위임

세션 이벤트 스트림

이벤트를 전송하고, 응답을 스트리밍하며, 실행 중 세션을 중단하거나 리디렉션합니다.

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

이벤트 유형

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

사용자 이벤트는 에이전트에 전송하여 세션을 시작하고 진행 상황에 따라 조종하는 것입니다.
세션 이벤트, 스팬 이벤트, 에이전트 이벤트는 세션 상태와 에이전트 진행 상황에 대한 관찰성을 위해 사용자에게 전송됩니다.

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

이벤트 통합

추가 시나리오

사용자 정의 도구 호출 처리

에이전트가 사용자 정의 도구를 호출할 때:

세션이 도구 이름과 입력을 포함하는 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으로 전환됩니다.

with client.beta.sessions.events.stream(session.id) as stream:
    for event in stream:
        if event.type == "session.status_idle" and (stop := event.stop_reason):
            match stop.type:
                case "requires_action":
                    for event_id in stop.event_ids:
                        # Look up the custom tool use event and execute it
                        tool_event = events_by_id[event_id]
                        result = call_tool(tool_event.name, tool_event.input)

                        # Send the result back
                        client.beta.sessions.events.send(
                            session.id,
                            events=[
                                {
                                    "type": "user.custom_tool_result",
                                    "custom_tool_use_id": event_id,
                                    "content": [{"type": "text", "text": result}],
                                },
                            ],
                        )
                case "end_turn":
                    break

도구 확인

권한 정책에서 도구 실행 전 확인이 필요한 경우:

세션이 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으로 전환됩니다.

with client.beta.sessions.events.stream(session.id) as stream:
    for event in stream:
        if event.type == "session.status_idle" and (stop := event.stop_reason):
            match stop.type:
                case "requires_action":
                    for event_id in stop.event_ids:
                        # Approve the pending tool call
                        client.beta.sessions.events.send(
                            session.id,
                            events=[
                                {
                                    "type": "user.tool_confirmation",
                                    "tool_use_id": event_id,
                                    "result": "allow",
                                },
                            ],
                        )
                case "end_turn":
                    break

사용량 추적

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

Was this page helpful?