Quando um agente erra no passo 17, como descobrir onde ele saiu do caminho? Um chatbot comum recebe uma pergunta e devolve uma resposta. Um agente pode pesquisar, abrir arquivos, chamar uma ferramenta, comparar resultados e tentar de novo.
Quando um agente erra no passo 17, como descobrir onde ele saiu do caminho?
Um chatbot comum recebe uma pergunta e devolve uma resposta. Um agente pode pesquisar, abrir arquivos, chamar uma ferramenta, comparar resultados e tentar de novo. Se o resultado final estiver errado, olhar apenas a última frase não explica o problema.
Pense simples: tracing é o registro organizado da viagem inteira do agente.
TL;DR
Um trace mostra o caminho percorrido pelo agente, do pedido até a resposta.
Cada etapa pode guardar ferramenta usada, entrada, saída, duração, custo e erro.
Tracing ajuda a corrigir falhas e também a descobrir passos lentos ou caros.
O registro deve esconder senhas e dados pessoais que não precisam aparecer.
A analogia da trilha de pegadas
Imagine que um pequeno robô entrou numa cozinha para fazer um bolo.
No fim, o bolo ficou salgado. Saber apenas que “o bolo deu errado” não resolve. Você precisa seguir as pegadas:
leu a receita
→ pegou um pote
→ leu o rótulo errado
→ colocou sal no lugar de açúcar
→ assou o boloAgora o erro ficou visível. O forno não era o problema. A falha aconteceu quando o robô escolheu o pote.
Um trace faz isso com o trabalho da IA. Ele organiza cada passo numa linha do tempo, como pegadas numeradas.
Por que isso está em alta
Agentes estão ganhando mais ferramentas, memória e liberdade para tomar pequenos caminhos. Isso torna o trabalho mais útil, mas também mais difícil de entender olhando só o começo e o fim.
A documentação atual do OpenAI Agents SDK trata tracing como parte do próprio kit de agentes. Plataformas como LangSmith também organizam chamadas de modelos, ferramentas e subagentes numa sequência visível. O nome pode mudar entre produtos, mas a ideia é a mesma: guardar a história da execução para observar e melhorar o sistema.
Quanto mais passos um agente consegue dar, mais importante fica enxergar por onde ele passou.
O que aparece em um trace
Um trace útil costuma responder perguntas simples:
Qual pedido iniciou o trabalho?
Que agente ou subagente cuidou de cada parte?
Qual ferramenta foi chamada?
O que a ferramenta devolveu?
Quanto tempo cada etapa levou?
Onde apareceu um erro ou uma nova tentativa?
Qual foi o resultado final?
Cada caixinha dessa linha do tempo também pode ser chamada de span. Não precisa decorar o nome. Pense em um span como uma pegada; o trace é a trilha completa.
Um exemplo prático
Imagine um agente que prepara uma lista de clientes para uma reunião.
Ele precisa buscar o cliente no CRM, ler os últimos emails e montar um resumo. O resultado chega sem a negociação mais recente.
Sem tracing, alguém pode culpar o modelo de IA.
Com tracing, a equipe vê isto:
09:00:01 recebeu o nome do cliente
09:00:02 buscou o cadastro no CRM — sucesso
09:00:03 buscou emails dos últimos 30 dias — sucesso
09:00:04 encontrou 0 mensagens
09:00:05 criou o resumo sem avisar que faltavam emailsAo abrir a etapa dos emails, a equipe descobre que a busca usou o endereço antigo do cliente. O conserto não é “trocar a IA”. É corrigir o endereço usado pela ferramenta e ensinar o agente a avisar quando a busca volta vazia.
Tracing não é apenas um log gigante
Um log comum pode ser uma pilha de frases técnicas misturadas. Um trace liga pai e filho:
Preparar reunião
├── Consultar CRM
├── Buscar emails
│ └── Tentar novamente
└── Escrever resumoEssa árvore mostra qual etapa chamou outra etapa. Assim, uma tentativa repetida não parece um evento solto.
Também fica fácil comparar duas execuções: por que ontem levou 8 segundos e hoje levou 40? Por que uma usou duas ferramentas e outra usou nove?
Tracing, avaliação e aprovação são diferentes
tracing mostra o que aconteceu;
avaliação decide se o resultado foi bom;
aprovação humana pausa antes de uma ação importante;
log de auditoria guarda o recibo de quem mudou algo.
Eles trabalham juntos. O trace conta a história. A avaliação dá uma nota. A aprovação impede um passo arriscado sem autorização. O recibo prova a ação final.
O cuidado com dados sensíveis
Uma trilha detalhada pode guardar mais do que deveria: nomes, contratos, mensagens, tokens ou senhas.
Por isso, tracing bom não significa copiar tudo. Antes de registrar, eu faria três perguntas:
1. Precisamos mesmo guardar este dado? 2. Podemos esconder ou apagar a parte sensível? 3. Quem pode abrir este trace e por quanto tempo?
Nunca coloque senha ou chave de API no trace. Para dados pessoais, registre apenas o necessário para entender o problema.
Como começar pequeno
Escolha um agente real e registre cinco pontos:
1. início do pedido; 2. chamada de cada ferramenta; 3. resultado ou erro da ferramenta; 4. tempo de cada etapa; 5. resposta final.
Depois, provoque uma falha segura, como buscar um arquivo que não existe. Veja se a trilha deixa claro onde o problema nasceu e como o agente reagiu.
Se uma pessoa consegue encontrar o passo quebrado em dois minutos, o trace já está ajudando.
Perguntas rápidas
O que é tracing de agentes de IA?
É o registro organizado de todos os passos de uma execução, desde o pedido inicial até a resposta final, incluindo modelos, ferramentas, tempo e erros.
Trace e log são a mesma coisa?
Não exatamente. Um log registra eventos. Um trace conecta esses eventos numa sequência e mostra quais etapas são filhas de outras etapas.
Para que serve o tracing?
Serve para encontrar erros, entender decisões, medir lentidão e custo, comparar execuções e transformar casos reais em testes melhores.
Tracing melhora a resposta sozinho?
Não. Ele mostra onde melhorar. A equipe ainda precisa corrigir a ferramenta, o contexto, a regra ou o modelo que causou o problema.
O trace pode guardar dados pessoais?
Pode, se o sistema registrar entradas e saídas sem cuidado. Por isso, dados sensíveis devem ser removidos, mascarados ou ter acesso e prazo de retenção controlados.
Como testar tracing hoje?
Rode uma tarefa pequena, force um erro seguro e confira se a linha do tempo mostra o pedido, a ferramenta, o erro, a tentativa de recuperação e a resposta final.
Conclusão
Um agente sem tracing é como um robô que volta da cozinha com um bolo ruim e não conta o que fez.
Com a trilha de pegadas, você encontra o pote errado, o passo lento e a ferramenta que falhou. A conversa deixa de ser “a IA errou” e vira “o erro começou aqui”.
Se o seu agente já usa mais de uma ferramenta, não espere o primeiro problema grande. Registre uma execução hoje e tente explicar cada passo para outra pessoa.
Para continuar, leia também [o que é avaliação de agentes de IA](/blog/o-que-e-avaliacao-de-agentes-de-ia), [o que são hooks de agentes](/blog/o-que-sao-hooks-de-agentes-de-ia) e [o que é aprovação humana](/blog/o-que-e-aprovacao-humana-em-agentes-de-ia).