Rastreamento

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

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

Para consultar o status da sessão, eventos em tempo real, saídas salvas e uso pela API, comece por Observabilidade.

O rastreamento é habilitado por padrão para novas sessões. Você pode inspecionar os rastreamentos no painel ou exportá-los pela API.

Abra um rastreamento

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

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

Leia um rastreamento

Comece pela sessão e depois explore um turno:

1. Sessão: cada entrada em Logs → Agentes é uma sessão. Abra-a para ver sua linha do tempo e lista de turnos. Por exemplo, um usuário pode perguntar sobre um pedido e depois fazer uma pergunta complementar na mesma sessão.
2. Turno: expanda um turno para ver o trabalho realizado durante aquele ciclo. Um turno pode incluir várias respostas do modelo e chamadas de ferramentas. Uma mensagem de acompanhamento enviada após o término do turno inicia outro turno na mesma sessão.
3. Etapas do turno: o rastreamento agrupa as respostas do modelo e as chamadas de ferramentas sob o agente raiz ou o subagente que as realizou. Cada etapa registrada é chamada de segmento.

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

Agente

Um segmento 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 que as realizou.

O painel de detalhes mostra:

• Tipo de agente: agente raiz (root) ou subagente (subagent).
• Agente: seu ID, nome, modelo e instruções, quando registrados.
• Uso: as contagens de tokens registradas desse agente. Essas contagens abrangem apenas o próprio agente; não incluem seus subagentes.
• Duração e Status do resultado: quanto tempo o trabalho registrado levou e se foi concluído, falhou ou está incompleto.

Geração

Um segmento 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ê sua entrada e produz uma resposta. Essa resposta pode solicitar uma ferramenta. Depois que a ferramenta retorna, o modelo pode produzir outra resposta em uma nova geração.

• Entrada: entradas registradas associadas àquela resposta, como uma mensagem do usuário ou o resultado de uma ferramenta.
• Saída: itens registrados produzidos pelo modelo, como o texto de uma resposta ou uma chamada de ferramenta.
• Modelo: o modelo usado para a resposta, quando registrado.

Ferramenta

Um segmento de ferramenta descreve uma chamada de ferramenta e seu resultado registrado.

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

• Chamada: a solicitação à ferramenta, incluindo o nome da ferramenta e os argumentos, quando presentes.
• Resultado: a resposta registrada da ferramenta, quando disponível.
• Status do resultado e Erro: o resultado registrado e os 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 separado Resultado pode estar vazio porque a resposta MCP fica armazenada em Chamada.

Tempos e status

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

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

A duração de um segmento de agente inclui suas etapas filhas. As etapas podem se sobrepor: dois subagentes executados simultaneamente por 10 segundos correspondem a cerca de 10 segundos de tempo decorrido.

Uso de tokens

Tokens no resumo da sessão mostra o uso da sessão. Uso em um segmento de agente mostra as contagens de tokens registradas desse agente.

Os dados de uso podem chegar após o término do turno. Um valor em branco ou null significa que a contagem é desconhecida. Isso não significa que o agente usou zero tokens. As contagens podem mudar à medida que mais dados de uso ficam disponíveis e não representam uma fatura final.

Quando os rastreamentos ficam prontos

Os rastreamentos são criados após o término de um turno. A resposta do agente pode aparecer antes que seu rastreamento ou os dados de uso de tokens estejam prontos.

Os eventos da sessão em tempo real mostram o progresso enquanto o agente ainda está trabalhando.

Exporte os rastreamentos da sessão

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

Defina OPENAI_API_KEY e substitua sess_123 pelo ID da sua 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 rastreamentos dessa página em um único payload OTLP. Envie-o 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 usando last_id como valor de after, mantendo o mesmo valor de order. Salve ou envie cada página antes de buscar a próxima e repita até que has_more seja false.

As exportações incluem apenas os rastreamentos disponíveis no momento de cada solicitação. Para exportar o histórico, espere os turnos da sessão terminarem e aguarde até que os rastreamentos apareçam. A exportação não configura o envio automático de rastreamentos futuros.

Exporte os rastreamentos de um agente

Para exportar os rastreamentos das várias sessões de um agente, primeiro liste as sessões com o filtro agent_id. Substitua agent_123 pelo ID do seu 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 rastreamentos da sessão, conforme descrito acima.
2. Quando a lista de sessões apresentar has_more: true, passe o last_id dessa lista como valor de 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 apresente has_more: false.

O filtro seleciona as sessões pelo agente raiz. Mantenha o cursor da lista de sessões separado do cursor de rastreamentos de cada sessão.

Exemplo: um turno com dois subagentes

Este exemplo se baseia em uma sessão registrada. O agente raiz chama uma ferramenta MCP enquanto dois subagentes executam um comando e buscam documentos. Os nomes dos subagentes foram simplificados abaixo; as contagens e durações vêm do rastreamento 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 está Concluído, com duração de 1m 37s.

Expandir o turno revela o agente raiz e suas etapas filhas. O rastreamento contém 3 segmentos de agente (o agente raiz e dois subagentes), 11 segmentos de geração e 10 segmentos de ferramenta.

Esta árvore agrupa as gerações e chamadas de ferramentas repetidas. Ela mostra as relações entre pais e filhos; 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. Sua Saída contém mensagens e dois itens spawn_agent_call. Essas chamadas também aparecem como segmentos de Ferramenta, e os subagentes resultantes aparecem como segmentos de Agente subordinados ao 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 send_input_call. As respostas do modelo e as ferramentas de cada subagente pertencem ao respectivo segmento.

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

Uma chamada de ferramenta MCP

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

O painel Chamada inclui estes campos:

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

Este trecho mostra parte da chamada registrada. O mesmo painel contém seus arguments e a resposta MCP em output. O painel separado Resultado tem o valor null. O campo Segmento pai do segmento aponta para o agente raiz.

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

Tempos e uso nesta sessão

Os dois segmentos de subagentes se sobrepõem na linha do tempo. O Subagente A leva 24s e o Subagente B leva 21s, ambos dentro do segmento de 1m 37s do agente raiz. O painel arredonda essas durações exibidas.

O painel Uso de cada segmento 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.