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.

Feedback sobre execuções de agente (visualização)

O feedback é um mecanismo crítico para interpretar e melhorar os runtimes de agente. Permite que você revise o comportamento, diagnostique problemas e documente padrões significativos de como um agente toma decisões.

Além da depuração, o feedback atua como a entrada principal para a memória episódica baseada em feedback, permitindo que o agente refine sua política de decisão gradualmente, sem exigir regravações completas de solicitações para cada ajuste.

A relação entre feedback e memória

Embora o feedback atue como uma ferramenta de anotação, sua aplicação mais potente está em influenciar a memória episódica.

O fornecimento de feedback em um trace destaca comportamentos que o agente deve replicar ou evitar em execuções futuras.

• Evolução sobre a repetição: ao contrário de resoluções estáticas, a memória baseada em feedback permite que o comportamento do agente melhore ao longo do tempo. O agente aprende a reconhecer padrões sinalizados como corretos ou incorretos.
• Melhoria direcionada: essa abordagem é mais valiosa em fluxos em que o agente está frequentemente "quase certo" ou em que a política de decisão ainda está em desenvolvimento.
• Memória seletiva: nem todos os feedbacks se tornam memória automaticamente. Você deve determinar ativamente quais anotações representam oportunidades de aprendizado de alto valor para evitar que feedback de baixa qualidade ou inconsistente degrade o desempenho.

Onde aplicar feedback

Você pode fornecer feedback em qualquer período dentro de um trace de agente. Essa flexibilidade permite que você anote chamadas de ferramentas específicas, verificações de proteção ou saídas de LLM ao revisar ou diagnosticar comportamento.

Apenas o feedback aplicado ao período de execução do agente é elegível para memória episódica. Embora você possa anotar qualquer parte do trace para análise, apenas o feedback anexado diretamente ao período de execução do agente será armazenado e recuperado como memória em execuções futuras.

Quando aplicar feedback

Embora o fornecimento de feedback em todos os traces maximizaria o aprendizado iterativo, na prática, você deve concentrar-se em traces que ofereçam o maior valor para otimização.

Concentre-se nos seguintes cenários:

• Cenários críticos: traces envolvendo decisões de alto risco ou erros de alto impacto.
• Padrões recorrentes: áreas em que o agente enfrenta dificuldades constantes ou exibe falhas repetitivas.
• Decisões difíceis: instâncias em que o agente enfrentou uma escolha complexa.
• Sentimento negativo: execuções que resultaram em uma experiência do usuário ruim.
• Comportamento do modelo: exemplos que ilustram claramente um comportamento específico para o agente copiar ou evitar rigorosamente.

A aplicação de feedback é crucial para melhoria contínua. Permite que você codifique melhores comportamentos de forma incremental, tornando as execuções do agente mais confiáveis e consistentes.

• Priorizar traces: concentre-se em traces de cenários críticos, erros de alto impacto ou padrões recorrentes em que o agente tem dificuldades.
• Cenários de alto valor: priorize iterações que representam decisões difíceis para o agente, demonstram sentimento negativo do usuário ou ilustram claramente um comportamento que você deseja que o agente copie ou evite.
• Áreas de foco: identifique claramente sobre o que você está fornecendo feedback:
  • Saída: o resultado final atendeu às expectativas?
  • Execução do plano (trajetória): o agente realizou as etapas da tarefa na ordem esperada?
  • Comentários: use comentários para enriquecer o feedback e informar a recuperação de memória.