Flujo de eventos de sesión

La comunicación con Claude Managed Agents es basada en eventos. Envías eventos de usuario al agente y recibes eventos de agente y sesión para rastrear el estado.

Todas las solicitudes de la API de Managed Agents requieren el encabezado beta managed-agents-2026-04-01. El SDK establece el encabezado beta automáticamente.

Tipos de eventos

Los eventos fluyen en dos direcciones.

Eventos de usuario son lo que envías al agente para iniciar una sesión y dirigirla mientras progresa.
Eventos de sesión, eventos de span y eventos de agente se te envían para observabilidad en tu estado de sesión y progreso del agente.

Las cadenas de tipo de evento siguen una convención de nombres {domain}.{action}.

Cada evento incluye una marca de tiempo processed_at indicando cuándo fue registrado el evento en el servidor. Si processed_at es nulo, significa que el evento ha sido puesto en cola por el arnés y será manejado después de que los eventos anteriores terminen de procesarse.

Integrando eventos

Escenarios adicionales

Manejando llamadas de herramientas personalizadas

Cuando el agente invoca una herramienta personalizada:

La sesión emite un evento agent.custom_tool_use que contiene el nombre de la herramienta y la entrada.
La sesión se pausa con un evento session.status_idle que contiene stop_reason: requires_action. Los IDs de eventos de bloqueo están en el array stop_reason.requires_action.event_ids.
Ejecuta la herramienta en tu sistema y envía un evento user.custom_tool_result para cada uno, pasando el ID del evento en el parámetro custom_tool_use_id junto con el contenido del resultado.
Una vez que se resuelven todos los eventos de bloqueo, la sesión transiciona de vuelta a running.

Confirmación de herramientas

Cuando una política de permisos requiere confirmación antes de que se ejecute una herramienta:

La sesión emite un evento agent.tool_use o agent.mcp_tool_use.
La sesión se pausa con un evento session.status_idle que contiene stop_reason: requires_action. Los IDs de eventos de bloqueo están en el array stop_reason.requires_action.event_ids.
Envía un evento user.tool_confirmation para cada uno, pasando el ID del evento en el parámetro tool_use_id. Establece result en "allow" o "deny". Usa deny_message para explicar un rechazo.
Una vez que se resuelven todos los eventos de bloqueo, la sesión vuelve a la transición a running.

Seguimiento de uso

El objeto de sesión incluye un campo usage con estadísticas de tokens acumulativos. Obtén la sesión después de que se quede inactiva para leer los totales más recientes y úsalos para rastrear costos, aplicar presupuestos o monitorear el 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 reporta tokens de entrada sin caché y output_tokens reporta tokens de salida totales en todas las llamadas de modelo en la sesión. Los campos cache_creation_input_tokens y cache_read_input_tokens reflejan la actividad de almacenamiento en caché de indicaciones. Las entradas de caché utilizan un TTL de 5 minutos, por lo que los turnos consecutivos dentro de esa ventana se benefician de lecturas de caché, que reducen el costo por 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