Fluxo de eventos da sessão

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

Tipos de eventos

Os eventos fluem em duas direções.

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

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

Cada 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 o processamento.

Integrando eventos

Cenários adicionais

Tratando chamadas de ferramentas personalizadas

Quando o agente invoca uma ferramenta personalizada:

1. A sessão emite um evento agent.custom_tool_use contendo o nome da ferramenta e a entrada.
2. A sessão pausa com um evento session.status_idle contendo stop_reason: requires_action. Os IDs de eventos de bloqueio estão no array stop_reason.requires_action.event_ids.
3. 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.
4. Assim que todos os eventos de bloqueio forem resolvidos, a sessão fará a transição de volta para running.

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

Confirmação de ferramenta

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

1. A sessão emite um evento agent.tool_use ou agent.mcp_tool_use.
2. A sessão pausa com um evento session.status_idle contendo stop_reason: requires_action. Os IDs de eventos bloqueadores estão no array stop_reason.requires_action.event_ids.
3. 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.
4. Uma vez que todos os eventos bloqueadores sejam resolvidos, a sessão faz a transição de volta para running.

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

Rastreamento de uso

O objeto de sessão inclui um campo usage com estatísticas de tokens cumulativas. Busque a sessão depois que 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 relata tokens de entrada não armazenados em cache e output_tokens relata tokens de saída totais 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 as rodadas consecutivas dentro dessa janela se beneficiam de leituras de cache, que reduzem o custo por token.