Flujo de eventos de sesión

La comunicación con los Agentes Gestionados de Claude está basada en eventos. Envías eventos de usuario al agente y recibes eventos de agente y de sesión para rastrear el estado.

Todas las solicitudes a la API de Agentes Gestionados 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.

Los eventos de usuario son lo que envías al agente para iniciar una sesión y dirigirla a medida que avanza.
Los eventos de sesión, eventos de span y eventos de agente se te envían para tener visibilidad sobre el estado de tu sesión y el progreso del agente.

Las cadenas de tipo de evento siguen la convención de nomenclatura {domain}.{action}.

Cada evento incluye una marca de tiempo processed_at que indica cuándo se registró el evento en el servidor. Si processed_at es nulo, significa que el evento ha sido encolado por el harness y se manejará después de que los eventos anteriores terminen de procesarse.

Consulta la referencia de la API de eventos de sesión para el esquema completo de cada tipo de evento.

Integración de eventos

Escenarios adicionales

Manejo de llamadas a 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 bloqueantes están en el arreglo 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 todos los eventos bloqueantes estén resueltos, la sesión vuelve 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 bloqueantes 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 una denegación.
Una vez que todos los eventos bloqueantes se resuelven, la sesión vuelve al estado running.

Seguimiento del uso

El objeto de sesión incluye un campo usage con estadísticas acumuladas de tokens. Obtén la sesión después de que pase a 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 los tokens de entrada no almacenados en caché y output_tokens reporta el total de tokens de salida en todas las llamadas al modelo en la sesión. Los campos cache_creation_input_tokens y cache_read_input_tokens reflejan la actividad de caché de prompts. Las entradas de caché usan un TTL de 5 minutos, por lo que los turnos consecutivos dentro de esa ventana se benefician de las lecturas de caché, lo que reduce el costo por token.

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
        # Busca el evento de uso de herramienta personalizada y ejecútalo
        result=$(call_tool "$event_id")
        # Envía el resultado de vuelta
        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}<&-