Rastreamento

Uma sessão reúne a conversa e o trabalho do agente. Uma sessão pode conter vários turnos, cada um correspondente a um ciclo de trabalho. Um rastro mostra as etapas de um turno, incluindo as respostas do modelo, as chamadas de ferramentas e o trabalho delegado a outros agentes.

O painel de rastreamento mostra o que o agente fez, com as entradas, as saídas, a duração e o status registrados em cada etapa.

Para consultar o status da sessão, os eventos em tempo real, a saída salva e os dados de uso pela API, comece pelo guia de observabilidade.

O rastreamento fica habilitado por padrão nas novas sessões. Você pode examinar os rastros no painel ou exportá-los pela API.

Abrir um rastro

1. Abra Logs → Agentes e selecione o projeto em que você executou o agente.
2. Localize a sessão em Pesquisar logs. Use Adicionar filtro para filtrar por modelo, status ou data.
3. Selecione a sessão para abrir a linha do tempo e a lista de turnos.
4. Expanda um turno e selecione uma etapa na linha do tempo ou na lista de eventos para ver os detalhes.

O resumo da sessão mostra o status, o modelo, o horário de início, a última atividade, o número de turnos e o uso de tokens registrado.

Interpretar um rastro

Comece pela sessão e examine um de seus turnos:

1. Sessão: cada item em Logs → Agentes corresponde a uma sessão. Abra a sessão para ver a linha do tempo e a lista de turnos. Por exemplo, um usuário pode perguntar sobre um pedido e depois fazer outra pergunta sobre ele na mesma sessão.
2. Turno: expanda um turno para ver o trabalho realizado nesse ciclo. Um turno pode incluir várias respostas do modelo e chamadas de ferramentas. Uma nova mensagem enviada após o fim do turno inicia outro turno na mesma sessão.
3. Etapas do turno: o rastro agrupa as respostas do modelo e as chamadas de ferramentas sob o agente raiz ou o subagente responsável por elas. Cada etapa registrada é chamada de span.

Selecione um span para ver o status, a duração, os horários de início e término e os dados registrados:

Agente

Um span de agente agrupa o trabalho realizado pelo agente raiz ou por um subagente, outro agente encarregado de parte da tarefa. As respostas do modelo e as chamadas de ferramentas aparecem sob o agente responsável por elas.

O painel de detalhes mostra:

• Tipo de agente: agente raiz (root) ou subagente (subagent).
• Agente: ID, nome, modelo e instruções do agente, quando registrados.
• Uso: contagens de tokens registradas apenas para o próprio agente. Os tokens dos subagentes são contabilizados separadamente.
• Duração e Status do resultado: quanto tempo o trabalho registrado levou e se foi concluído, falhou ou está incompleto.

Geração

Um span de geração agrupa as entradas e saídas registradas do modelo. Cada turno pode ter várias gerações.

Durante a inferência, o modelo lê a entrada e produz uma resposta. Essa resposta pode solicitar o uso de uma ferramenta. Depois que a ferramenta retorna um resultado, o modelo pode produzir outra resposta em uma nova geração.

• Entrada: entradas registradas para essa resposta, como uma mensagem do usuário ou o resultado de uma ferramenta.
• Saída: itens que o modelo produziu e que foram registrados, como o texto da resposta ou uma chamada de ferramenta.
• Modelo: modelo usado para produzir a resposta, quando registrado.

Ferramenta

Um span de ferramenta descreve uma chamada de ferramenta e o resultado registrado.

Os spans de ferramenta incluem chamadas às suas funções e a ferramentas em servidores MCP (Model Context Protocol). Pesquisas na Web e execuções de comandos também podem aparecer como spans de ferramenta.

• Chamada: solicitação enviada à ferramenta, incluindo o nome da ferramenta e os argumentos, quando presentes.
• Resultado: resposta registrada da ferramenta, quando disponível.
• Status do resultado e Erro: resultado registrado e detalhes do erro, quando presentes.

Em uma chamada de ferramenta MCP, Chamada contém o rótulo do servidor (server_label), o nome da ferramenta (name) e os argumentos (arguments). A resposta e o erro são registrados ali como output e error, quando disponíveis. O painel Resultado pode ficar vazio porque a resposta MCP é armazenada em Chamada.

Duração e status

A linha do tempo mostra a ordem das etapas e quais delas se sobrepõem. Ampliar mostra as etapas mais curtas em mais detalhes. Ajustar linha do tempo mostra a sessão inteira.

Cada span mostra sua duração e o status do resultado. Os spans que falharam também podem incluir detalhes registrados do erro.

A duração de um span de agente inclui as etapas subordinadas a ele. As etapas podem se sobrepor. Se dois subagentes são executados ao mesmo tempo por 10 segundos, o tempo decorrido é de cerca de 10 segundos.

Uso de tokens

O campo Tokens no resumo da sessão mostra o uso de tokens da sessão. O campo Uso em um span de agente mostra as contagens de tokens registradas para esse agente.

Os dados de uso podem chegar após o fim do turno. Um valor em branco ou null indica que a contagem é desconhecida. Isso não significa que o agente usou zero tokens. As contagens podem mudar conforme novos dados de uso chegam e não representam a cobrança final.

Quando os rastros ficam disponíveis

Os rastros são gerados após o fim de cada turno. A resposta do agente pode aparecer antes que o rastro ou os dados de uso de tokens estejam disponíveis.

Os eventos da sessão em tempo real mostram o progresso enquanto o agente trabalha.

Exportar os rastros de uma sessão

Baixe os rastros da sessão para examiná-los em outra ferramenta de rastreamento. O endpoint GET /v1/agents/sessions/{session_id}/traces retorna uma página de rastros com dados em JSON no formato OpenTelemetry Protocol (OTLP).

Defina OPENAI_API_KEY e substitua sess_123 pelo ID da sessão. Este exemplo usa cURL e jq para salvar uma página como traces.otlp.json:

1
2
3
4
5
6curl --fail-with-body \
  "https://api.openai.com/v1/agents/sessions/sess_123/traces?limit=20&order=asc" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: agents=v1" \
  --output trace-page.json && \
jq '{resourceSpans: [.data[].otlp.resourceSpans[]]}' trace-page.json > traces.otlp.json

O comando reúne os rastros dessa página em um único payload OTLP. Envie o payload ao endpoint OTLP/HTTP do seu provedor de rastreamento usando a autenticação do provedor.

Para exportar a sessão inteira, verifique trace-page.json. Quando has_more for true, solicite a próxima página passando last_id como after e mantendo o mesmo valor de order. Salve ou envie cada página antes de buscar a próxima. Repita até que has_more seja false.

A exportação inclui apenas os rastros disponíveis no momento de cada solicitação. Para exportar o histórico, aguarde o fim dos turnos da sessão e dê tempo para que os rastros apareçam. A exportação não configura o envio automático de rastros futuros.

Exportar os rastros de um agente

Para exportar rastros de várias sessões de um agente, primeiro liste as sessões usando o filtro agent_id. Substitua agent_123 pelo ID do agente:

1
2
3
4curl --fail-with-body \
  "https://api.openai.com/v1/agents/sessions?agent_id=agent_123&limit=100&order=asc" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: agents=v1"

1. Para cada sessão em data, use o respectivo id para exportar todas as páginas de rastros da sessão conforme descrito acima.
2. Quando a lista de sessões indicar has_more: true, passe o last_id dessa lista como after para buscar a próxima página. Mantenha os mesmos valores de agent_id e order.
3. Repita até que a lista de sessões indique has_more: false.

O filtro considera o agente raiz da sessão. Mantenha o cursor da lista de sessões separado do cursor de rastros de cada sessão.

Exemplo de um turno com dois subagentes

Este exemplo se baseia em uma sessão registrada. O agente raiz chama uma ferramenta MCP enquanto um subagente executa um comando e o outro busca documentos. Os nomes dos subagentes foram simplificados no exemplo. As contagens e durações vêm do rastro registrado.

Sessão e turno

O cabeçalho da sessão mostra 1 turno, 10 chamadas de ferramentas e 252.468 tokens. O status da sessão é Ociosa, e o Turno 1 aparece como Concluído, com duração de 1 min 37 s.

Ao expandir o turno, você vê o agente raiz e as etapas subordinadas a ele. O rastro contém 3 spans de agente (o agente raiz e dois subagentes), 11 spans de geração e 10 spans de ferramenta.

A árvore abaixo agrupa gerações e chamadas de ferramentas repetidas. Ela mostra a hierarquia das etapas. A linha do tempo mostra quando cada etapa foi executada.

Session: Idle
└── Turn 1: Completed                              1m 37s
    └── Root agent                                1m 37s
        ├── 6 generations
        ├── 2 tools: spawn_agent_call
        ├── Subagent A                               24s
        │   ├── 2 generations
        │   └── Tool: command_execution               2s
        ├── Subagent B                               21s
        │   ├── 3 generations
        │   ├── 2 tools: notion.fetch              2s each
        │   └── Tool: send_input_call                 0ms
        ├── Tool: demo_capability_probe              87ms
        └── 3 tools: wait_for_agents_call

Trabalho do modelo e delegação

A primeira Geração do agente raiz inclui a mensagem do usuário em Entrada. A Saída contém mensagens e dois itens spawn_agent_call. Essas chamadas também aparecem como spans de Ferramenta, e os subagentes criados aparecem como spans de Agente sob o agente raiz.

O subagente A tem suas próprias gerações e uma chamada à ferramenta command_execution. O subagente B tem três gerações, duas chamadas MCP a notion.fetch e uma chamada a send_input_call. As respostas do modelo e as chamadas de ferramentas de cada subagente aparecem no span do respectivo subagente.

O agente raiz também tem três spans de ferramenta wait_for_agents_call. Sua última geração contém uma mensagem e tem duração registrada de 6 s.

Uma chamada de ferramenta MCP

O span demo_capability_probe do agente raiz é um span de Ferramenta concluído, com duração de 87 ms. Seu Tipo de ferramenta é mcp_call.

O painel Chamada inclui os seguintes campos:

123456{
  "type": "mcp_call",
  "server_label": "demo_local",
  "name": "demo_capability_probe",
  "status": "completed"
}

Esse trecho mostra parte da chamada registrada. O mesmo painel contém os argumentos em arguments e a resposta MCP em output. O painel Resultado, exibido separadamente, mostra null. O campo Span pai aponta para o agente raiz.

Os dois spans de notion.fetch do subagente B têm a mesma estrutura, com mcp_call como tipo de ferramenta, a resposta MCP em Chamada e o span do subagente como span pai.

Duração e uso de tokens nesta sessão

Os spans dos dois subagentes se sobrepõem na linha do tempo. O subagente A leva 24 s e o subagente B leva 21 s, ambos dentro do span de 1 min 37 s do agente raiz. O painel arredonda as durações exibidas.

O painel Uso de cada span de agente mostra as contagens de tokens registradas para o próprio agente:

Nesta sessão registrada, a soma dos totais dos três agentes corresponde aos 252.468 tokens exibidos no cabeçalho da sessão.