Flusso di eventi della sessione

La comunicazione con Claude Managed Agents è basata su eventi. Invii eventi utente all'agente e ricevi eventi agente e sessione per tracciare lo stato.

Tipi di evento

Gli eventi fluiscono in due direzioni.

• Gli eventi utente sono ciò che invii all'agente per avviare una sessione e guidarla mentre progredisce.
• Gli eventi di sessione, gli eventi span e gli eventi agente ti vengono inviati per osservabilità nello stato della sessione e nel progresso dell'agente.

Le stringhe del tipo di evento seguono una convenzione di denominazione {domain}.{action}.

Ogni evento include un timestamp processed_at che indica quando l'evento è stato registrato lato server. Se processed_at è null, significa che l'evento è stato messo in coda dall'harness e verrà gestito dopo che gli eventi precedenti avranno completato l'elaborazione.

Vedi il riferimento API degli eventi di sessione per lo schema completo di ogni tipo di evento.

Integrazione degli eventi

Scenari aggiuntivi

Gestione delle chiamate di strumenti personalizzati

Quando l'agente invoca uno strumento personalizzato:

1. La sessione emette un evento agent.custom_tool_use contenente il nome dello strumento e l'input.
2. La sessione si mette in pausa con un evento session.status_idle contenente stop_reason: requires_action. Gli ID evento di blocco si trovano nell'array stop_reason.requires_action.event_ids.
3. Esegui lo strumento nel tuo sistema e invia un evento user.custom_tool_result per ciascuno, passando l'ID evento nel parametro custom_tool_use_id insieme al contenuto del risultato.
4. Una volta risolti tutti gli eventi di blocco, la sessione torna a running.

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}<&-

Conferma dello strumento

Quando una politica di autorizzazione richiede una conferma prima che uno strumento venga eseguito:

1. La sessione emette un evento agent.tool_use o agent.mcp_tool_use.
2. La sessione si mette in pausa con un evento session.status_idle contenente stop_reason: requires_action. Gli ID degli eventi di blocco si trovano nell'array stop_reason.requires_action.event_ids.
3. Invia un evento user.tool_confirmation per ciascuno, passando l'ID dell'evento nel parametro tool_use_id. Imposta result su "allow" o "deny". Usa deny_message per spiegare un rifiuto.
4. Una volta risolti tutti gli eventi di blocco, la sessione torna a running.

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}<&-

Tracciamento dell'utilizzo

L'oggetto sessione include un campo usage con statistiche cumulative dei token. Recupera la sessione dopo che diventa inattiva per leggere i totali più recenti e usali per tracciare i costi, applicare budget o monitorare il consumo.

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

input_tokens riporta i token di input non memorizzati in cache e output_tokens riporta i token di output totali in tutte le chiamate del modello nella sessione. I campi cache_creation_input_tokens e cache_read_input_tokens riflettono l'attività di caching dei prompt. Le voci della cache utilizzano un TTL di 5 minuti, quindi i turni consecutivi all'interno di quella finestra beneficiano delle letture della cache, che riducono il costo per token.