セッションイベントストリーム

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配列にあります。
システムでツールを実行し、各イベントIDをcustom_tool_use_idパラメータで渡して、結果コンテンツとともにuser.custom_tool_resultイベントを送信します。
すべてのブロッキングイベントが解決されると、セッションは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を使用するため、そのウィンドウ内の連続したターンはキャッシュ読み取りの恩恵を受け、トークンあたりのコストを削減します。

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

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