Traços de agente

Sobre traces

Traces são registros detalhados de tudo o que um agente faz durante uma execução, incluindo etapas realizadas, dados processados, decisões tomadas e resultados gerados. Cada trace captura uma linha de tempo completa do comportamento do agente, incluindo timestamps, erros, entradas/saídas e metadados contextuais.

Use traces para:

• Depuração e solução de problemas: identifique exatamente onde um agente falhou ou se comportou de forma inesperada.
• Análise de desempenho: avalie a latência, os erros e a taxa de transferência em execuções do agente para otimizar o comportamento.
• Conformidade e auditoria: mantenha um registro verificável do que o agente fez, quando e como — essencial para auditorias ou fluxos de trabalho regulados.
• Melhoria contínua: use insights de traces para ajustar a lógica do agente, adaptar o comportamento ou treinar novos modelos.

A tabela a seguir descreve casos de uso comuns em que a visualização de trace pode aprimorar sua capacidade de depurar, analisar e otimizar o comportamento do agente. Cada exemplo destaca como os dados de trace ajudam a descobrir insights e a tomar melhores decisões durante o desenvolvimento e o monitoramento do tempo de execução.

Use case	O que os traces ajudam você a fazer
O agente falha durante a chamada de ferramenta	Localizar e inspecionar a etapa exata, entradas, saídas e o erro
O desempenho é lento	Use carimbos de data e hora para localizar gargalos
Investigando um pico de erros	Filtrar execuções por status e identificar o padrão
Verificando uma correção de produção	Executar novamente a execução original e confirmar que o problema não ocorre mais
Preparando um relatório de auditoria	Exportar ou revisar traces que mostram caminhos de decisão e dados tratados

Tipos de traces

Existem dois tipos distintos de traces, cada um com um propósito específico na compreensão e análise do comportamento do agente:

• Traces de execução do agente: esses traces capturam a execução passo a passo de um agente durante uma execução ativa ou agendada. Eles mostram como o agente processou dados, invocou ferramentas, lidou com condições e respondeu a diferentes estados em tempo real.
• traces de execução de avaliação: os traces de avaliação são gerados quando um agente é testado contra entradas predefinidas, normalmente durante avaliações de modelos, validações de cenários ou casos de teste. Isso contribui para avaliar a precisão do agente, a qualidade da decisão e o comportamento sob condições controladas.

Acessando traces

Você pode acessar ambos os tipos de traces de dois locais principais:

• Agent Builder – Ao projetar ou testar seu agente, os rastreamentos estão disponíveis diretamente no construtor:

  • O painel inferior é aberto automaticamente para a aba Trilha de execução quando você executa seu agente, mostrando traços ao vivo para a execução atual. Você também pode alternar para a aba Histórico para visualizar execuções anteriores e adicioná-las diretamente a conjuntos de avaliação.

  • As abas Avaliações e Saída fornecem outra visualização de execuções recentes, onde você pode inspecionar o comportamento e os resultados junto com a definição do agente.

• Página Instâncias de agentes – Navegue até a seção Agentes > Instâncias. A partir daqui, selecione um agente específico e selecione qualquer execução para abrir sua visualização de rastreamento, que inclui o rastreamento visual completo e o painel de logs.

Ao visualizar traces para execuções de agente ou execuções de avaliação, você ganha visibilidade sobre a execução do agente. Você pode:

• Consulte os resultados da execução, conforme indicado com nós codificados por cores: sucesso, falha ou repetir.

• Passe o mouse sobre qualquer nó para visualizar: marcas de tempo de início e fim, status de execução, fragmentos de entrada e saída.
• Selecione um nó para visualizar os detalhes, incluindo: cargas JSON completas, logs e erros, métricas de runtime (uso de tokens, latência).

Gerenciamento do acesso a dados de rastreamento

Esta seção descreve como os administradores podem configurar o acesso a dados de rastreamento usando o modelo de controle de acesso baseado em funções.

Para visualizar logs de rastreamento, você precisa das seguintes permissões:

• Logs.View
• Jobs.View

Para obter detalhes sobre permissões de funções padrão, consulte Funções padrão.

A matriz a seguir explica os níveis de visibilidade com base em combinações de permissões. Essas combinações definem quais detalhes do rastreamento você pode visualizar, dependendo de suas permissões baseadas em funções.

Logs.View	Jobs.View	Acessar resultado
Habilitar	Habilitar	Todos os atributos
Habilitar	Desabilitar	Todos os atributos
Desabilitar	Habilitar	Atributos parciais (por exemplo, nome, tipo)
Desabilitar	Desabilitar	Sem acesso

Quando você não tem as permissões necessárias para visualizar dados de rastreamento, você vê uma mensagem que explica se o acesso é total ou parcialmente limitado e fornece orientação para solicitar a permissão necessária.