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.

Tutte le richieste API di Managed Agents richiedono l'intestazione beta managed-agents-2026-04-01. L'SDK imposta automaticamente l'intestazione beta.

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 di span e gli eventi agente ti vengono inviati per l'osservabilità dello stato della sessione e del 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.

Integrazione degli eventi

Scenari aggiuntivi

Gestione delle chiamate di strumenti personalizzati

Quando l'agente invoca uno strumento personalizzato:

La sessione emette un evento agent.custom_tool_use contenente il nome dello strumento e l'input.
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.
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.
Una volta risolti tutti gli eventi di blocco, la sessione torna a running.

Conferma dello strumento

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

La sessione emette un evento agent.tool_use o agent.mcp_tool_use.
La sessione si mette in pausa con un evento session.status_idle contenente stop_reason: requires_action. Gli ID degli eventi bloccanti si trovano nell'array stop_reason.requires_action.event_ids.
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.
Una volta risolti tutti gli eventi bloccanti, la sessione torna a running.

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 nella cache e output_tokens riporta il totale dei token di output 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 successivi all'interno di quella finestra beneficiano delle letture della cache, che riducono il costo per token.

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