Fluxo de eventos da sessão

A comunicação com Claude Managed Agents é baseada em eventos. Você envia eventos de usuário para o agente e recebe eventos de agente e de sessão de volta para acompanhar o status.

Todas as requisições à API de Managed Agents requerem o cabeçalho beta managed-agents-2026-04-01. O SDK define o cabeçalho beta automaticamente.

Tipos de eventos

Os eventos fluem em duas direções.

Eventos de usuário são o que você envia ao agente para iniciar uma sessão e orientá-la conforme ela avança.
Eventos de sessão, eventos de span e eventos de agente são enviados a você para observabilidade do estado da sua sessão e do progresso do agente.

As strings de tipo de evento seguem a convenção de nomenclatura {domain}.{action}.

Todo evento inclui um timestamp processed_at indicando quando o evento foi registrado no servidor. Se processed_at for nulo, significa que o evento foi enfileirado pelo harness e será tratado após os eventos anteriores terminarem de ser processados.

Consulte a referência da API de eventos de sessão para o esquema completo de cada tipo de evento.

Integrando eventos

Cenários adicionais

Tratando chamadas de ferramentas personalizadas

Quando o agente invoca uma ferramenta personalizada:

A sessão emite um evento agent.custom_tool_use contendo o nome e a entrada da ferramenta.
A sessão pausa com um evento session.status_idle contendo stop_reason: requires_action. Os IDs de eventos bloqueantes estão no array stop_reason.requires_action.event_ids.
Execute a ferramenta em seu sistema e envie um evento user.custom_tool_result para cada um, passando o ID do evento no parâmetro custom_tool_use_id junto com o conteúdo do resultado.
Assim que todos os eventos bloqueantes forem resolvidos, a sessão volta para o estado running.

Confirmação de ferramenta

Quando uma política de permissão requer confirmação antes que uma ferramenta seja executada:

A sessão emite um evento agent.tool_use ou agent.mcp_tool_use.
A sessão pausa com um evento session.status_idle contendo stop_reason: requires_action. Os IDs de eventos bloqueantes estão no array stop_reason.requires_action.event_ids.
Envie um evento user.tool_confirmation para cada um, passando o ID do evento no parâmetro tool_use_id. Defina result como "allow" ou "deny". Use deny_message para explicar uma negação.
Assim que todos os eventos bloqueantes forem resolvidos, a sessão volta ao estado running.

Rastreamento de uso

O objeto de sessão inclui um campo usage com estatísticas cumulativas de tokens. Busque a sessão após ela ficar ociosa para ler os totais mais recentes e use-os para rastrear custos, aplicar orçamentos ou monitorar o 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 não armazenados em cache e output_tokens reporta o total de tokens de saída em todas as chamadas de modelo na sessão. Os campos cache_creation_input_tokens e cache_read_input_tokens refletem a atividade de cache de prompt. As entradas de cache usam um TTL de 5 minutos, portanto turnos consecutivos dentro dessa janela se beneficiam de leituras de cache, que reduzem o custo 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 o evento de uso de ferramenta personalizada e o executa
        result=$(call_tool "$event_id")
        # Envia o resultado de volta
        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
        # Aprovar a chamada de ferramenta pendente
        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}<&-