Sitzungs-Ereignisstrom

Die Kommunikation mit Claude Managed Agents ist ereignisbasiert. Sie senden Benutzerereignisse an den Agenten und erhalten Agenten- und Sitzungsereignisse zurück, um den Status zu verfolgen.

Alle Managed Agents API-Anfragen erfordern den managed-agents-2026-04-01 Beta-Header. Das SDK setzt den Beta-Header automatisch.

Ereignistypen

Ereignisse fließen in zwei Richtungen.

Benutzerereignisse sind das, was Sie an den Agenten senden, um eine Sitzung zu starten und sie während des Fortschritts zu steuern.
Sitzungsereignisse, Span-Ereignisse und Agentenereignisse werden an Sie gesendet, um Einblick in Ihren Sitzungsstatus und den Fortschritt des Agenten zu erhalten.

Ereignistyp-Zeichenketten folgen der Namenskonvention {domain}.{action}.

Jedes Ereignis enthält einen processed_at-Zeitstempel, der angibt, wann das Ereignis serverseitig aufgezeichnet wurde. Wenn processed_at null ist, bedeutet dies, dass das Ereignis vom Harness in die Warteschlange gestellt wurde und nach Abschluss der vorherigen Ereignisse verarbeitet wird.

Die vollständige Schema-Beschreibung jedes Ereignistyps finden Sie in der Sitzungsereignisse-API-Referenz.

Ereignisse integrieren

Weitere Szenarien

Umgang mit benutzerdefinierten Tool-Aufrufen

Wenn der Agent ein benutzerdefiniertes Tool aufruft:

Die Sitzung gibt ein agent.custom_tool_use-Ereignis aus, das den Tool-Namen und die Eingabe enthält.
Die Sitzung pausiert mit einem session.status_idle-Ereignis, das stop_reason: requires_action enthält. Die blockierenden Ereignis-IDs befinden sich im Array stop_reason.requires_action.event_ids.
Führen Sie das Tool in Ihrem System aus und senden Sie für jedes ein user.custom_tool_result-Ereignis, wobei Sie die Ereignis-ID im Parameter custom_tool_use_id zusammen mit dem Ergebnisinhalt übergeben.
Sobald alle blockierenden Ereignisse aufgelöst sind, wechselt die Sitzung zurück zu running.

Tool-Bestätigung

Wenn eine Berechtigungsrichtlinie eine Bestätigung vor der Ausführung eines Tools erfordert:

Die Sitzung gibt ein agent.tool_use- oder agent.mcp_tool_use-Ereignis aus.
Die Sitzung pausiert mit einem session.status_idle-Ereignis, das stop_reason: requires_action enthält. Die blockierenden Ereignis-IDs befinden sich im Array stop_reason.requires_action.event_ids.
Senden Sie für jedes ein user.tool_confirmation-Ereignis und übergeben Sie die Ereignis-ID im Parameter tool_use_id. Setzen Sie result auf "allow" oder "deny". Verwenden Sie deny_message, um eine Ablehnung zu erläutern.
Sobald alle blockierenden Ereignisse aufgelöst sind, wechselt die Sitzung zurück in den Zustand running.

Nutzung verfolgen

Das Sitzungsobjekt enthält ein usage-Feld mit kumulativen Token-Statistiken. Rufen Sie die Sitzung ab, nachdem sie in den Leerlauf wechselt, um die neuesten Gesamtwerte zu lesen, und verwenden Sie diese, um Kosten zu verfolgen, Budgets durchzusetzen oder den Verbrauch zu überwachen.

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

input_tokens gibt nicht zwischengespeicherte Eingabe-Token an und output_tokens gibt die gesamten Ausgabe-Token über alle Modellaufrufe in der Sitzung hinweg an. Die Felder cache_creation_input_tokens und cache_read_input_tokens spiegeln die Prompt-Caching-Aktivität wider. Cache-Einträge verwenden eine TTL von 5 Minuten, sodass aufeinanderfolgende Gesprächsrunden innerhalb dieses Zeitfensters von Cache-Lesevorgängen profitieren, die die Kosten pro Token reduzieren.

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
        # Das benutzerdefinierte Tool-Verwendungsereignis nachschlagen und ausführen
        result=$(call_tool "$event_id")
        # Das Ergebnis zurücksenden
        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}<&-