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

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
        # Look up the custom tool use event and execute it
        result=$(call_tool "$event_id")
        # Send the result back
        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}<&-