Seu Agente IA errou. Você consegue descobrir o caminho que levou ao erro?

Quando um atendente humano comete um erro, normalmente conseguimos perguntar o que aconteceu. Podemos verificar qual informação ele recebeu, o que entendeu, onde pesquisou e por que tomou determinada decisão.

Com um Agente de Inteligência Artificial, essa investigação precisa acontecer de outra forma.

A empresa pode até encontrar a resposta incorreta no histórico da conversa. O problema é que a mensagem enviada ao cliente representa apenas o resultado final de uma execução que pode ter envolvido diversas etapas: interpretação da solicitação, consulta a documentos, busca em sistemas externos, chamadas de ferramentas, validações, tentativas que falharam e decisões sobre qual ação executar.

Sem observabilidade, a empresa enxerga a resposta, mas não consegue reconstruir o caminho que produziu aquela resposta.

O histórico da conversa mostra apenas parte da execução

Imagine que um cliente pergunte a um Agente IA:

“Vocês têm horário disponível para amanhã às 14h?”

O Agente responde que sim. O cliente se organiza, chega ao local e descobre que o horário nunca esteve disponível.

Ao abrir o histórico da conversa, a empresa encontra a pergunta e a resposta. Isso permite constatar que houve um erro, mas não explica sua origem.

O Agente consultou a agenda antes de responder? A ferramenta de disponibilidade retornou uma falha? O sistema demorou demais e o Agente continuou sem esperar o resultado? A consulta trouxe informações desatualizadas? O modelo interpretou o retorno de forma incorreta? Existia alguma instrução permitindo confirmar um horário sem realizar a reserva?

Todas essas situações podem produzir exatamente a mesma mensagem para o cliente.

Por isso, observar apenas a conversa não é suficiente para diagnosticar um Agente em produção. O histórico mostra o que foi dito. A observabilidade precisa mostrar o que aconteceu.

Observar um Agente não significa apenas guardar mensagens

A documentação de observabilidade de Agentes do Google Cloud define observabilidade como uma forma de obter informações sobre o estado interno e o comportamento dessas aplicações.

Isso envolve acompanhar elementos como:

• interações com o modelo;
• prompts e respostas;
• consumo de tokens;
• uso de ferramentas;
• sequência de execução;
• latência de cada etapa;
• erros e tentativas malsucedidas;
• aplicação de políticas de segurança;
• qualidade das respostas.

A documentação de tracing do OpenAI Agents SDK segue uma direção semelhante. O sistema registra eventos ocorridos durante uma execução, como gerações do modelo, chamadas de ferramentas, transferências entre Agentes, validações de segurança e eventos personalizados da aplicação.

Esses registros podem ser utilizados para visualizar, depurar e monitorar fluxos durante o desenvolvimento e depois que o Agente começa a atender clientes reais.

Observabilidade, portanto, não é apenas armazenar o que o cliente escreveu e o que o Agente respondeu. É registrar o que aconteceu entre esses dois momentos.

Isso também não significa exigir que o modelo exponha uma cadeia completa de raciocínio interno. O objetivo operacional é manter evidências suficientes para reconstruir a execução: quais entradas foram utilizadas, quais fontes foram consultadas, quais ferramentas foram chamadas, quais resultados retornaram e como o fluxo avançou até a resposta final.

O que é um trace de Agente?

Um trace é o registro de uma execução completa, do início ao fim.

Dentro dele existem operações menores, normalmente chamadas de spans. Cada span representa uma etapa com início, fim, duração, status e informações relacionadas àquela operação.

Uma execução simples poderia ser representada da seguinte maneira:

1. Mensagem recebida: o cliente pergunta sobre disponibilidade.

2. Chamada ao modelo: o Agente identifica que precisa consultar a agenda.

3. Chamada de ferramenta: o Agente envia data, horário e unidade para a API de disponibilidade.

4. Resposta da ferramenta: a API informa que não existem horários livres.

5. Nova chamada ao modelo: o Agente recebe o resultado e prepara a resposta.

6. Mensagem enviada: o cliente é informado de que o horário não está disponível.

No OpenAI Agents SDK, o trace representa a operação completa de um fluxo. Os spans registram as operações que ocorreram dentro dele, incluindo horários de início e término, identificação do trace, relação com a etapa anterior e dados específicos de cada ação.

Essa estrutura permite sair de uma constatação genérica, como “o Agente respondeu errado”, para um diagnóstico mais preciso:

“A API informou corretamente que não havia disponibilidade, mas o resultado foi interpretado de forma incorreta antes da resposta ao cliente.”

Também seria possível descobrir que a ferramenta sequer foi chamada, que a API demorou mais do que o limite configurado ou que o Agente usou informações antigas presentes no histórico da conversa.

É essa diferença que transforma um histórico em uma ferramenta de diagnóstico.

O que precisa ser registrado em uma execução

Um sistema de observabilidade útil deve permitir responder algumas perguntas básicas sobre cada atendimento.

Qual versão estava em produção?

O registro precisa identificar qual Agente executou a tarefa, qual modelo foi utilizado e quais versões das instruções, ferramentas e configurações estavam publicadas naquele momento.

Sem versionamento, a equipe pode investigar o comportamento usando o prompt atual, mesmo que o erro tenha ocorrido com uma configuração anterior.

Imagine que uma regra tenha sido alterada na segunda-feira e a reclamação do cliente tenha chegado na quarta. Se a empresa não souber qual versão estava ativa no momento da conversa, pode concluir que o erro é impossível de reproduzir.

Na prática, não está reproduzindo a mesma execução.

A observabilidade deve relacionar cada trace com informações como:

• identificação do Agente;
• versão das instruções;
• modelo utilizado;
• configurações relevantes;
• versão das ferramentas;
• ambiente em que a execução ocorreu;
• data e horário da publicação.

Quais informações foram entregues ao modelo?

O modelo raramente recebe apenas a mensagem mais recente do cliente.

O contexto pode incluir o histórico da sessão, instruções do sistema, informações cadastrais, dados do CRM, documentos recuperados, regras comerciais, resultados de ferramentas e mensagens produzidas por outros Agentes.

A observabilidade deve permitir identificar quais desses elementos participaram da execução.

Caso contrário, a equipe não consegue saber se o modelo gerou uma interpretação inadequada ou se recebeu uma informação incorreta antes mesmo de começar a responder.

Esse ponto também ajuda a diagnosticar situações em que o Agente recebeu informações demais. Como discutimos no conteúdo sobre por que prompt não é operação, aumentar instruções e contexto não substitui uma arquitetura capaz de entregar a informação correta no momento adequado.

Quais fontes foram consultadas?

Quando o Agente utiliza uma base de conhecimento, não basta registrar que houve uma consulta.

É importante saber:

• qual busca foi realizada;
• quais filtros foram aplicados;
• quais documentos foram encontrados;
• quais versões desses documentos estavam disponíveis;
• quais trechos foram entregues ao modelo;
• qual foi a relevância atribuída aos resultados;
• o que aconteceu quando nenhuma informação foi encontrada.

Um Agente pode responder incorretamente porque o documento estava desatualizado, porque a recuperação encontrou um trecho pouco relevante ou porque nenhuma informação foi localizada e o fluxo não tratou essa ausência.

Considere um Agente comercial que informa o preço errado de um serviço. O modelo pode ter recuperado uma tabela antiga, misturado condições de dois produtos ou usado um documento que deveria estar arquivado.

Sem registrar a fonte e o trecho utilizado, a equipe encontra o preço incorreto na conversa, mas não consegue descobrir de onde ele veio.

Quais ferramentas foram acionadas?

Agentes em produção podem consultar estoque, verificar pagamentos, emitir propostas, agendar reuniões, atualizar cadastros, registrar informações no CRM ou transferir atendimentos.

Cada chamada de ferramenta deve registrar pelo menos:

• ferramenta utilizada;
• parâmetros enviados;
• horário da chamada;
• resultado recebido;
• código de status;
• tempo de resposta;
• quantidade de tentativas;
• falhas ou exceções;
• estratégia adotada depois da falha.

O Google Cloud recomenda acompanhar chamadas, sucessos, falhas, latência e dados trocados com ferramentas e APIs externas.

Esse registro é especialmente importante porque um Agente precisa de ferramentas para resolver problemas reais. A capacidade de agir aumenta a utilidade do sistema, mas também amplia a quantidade de pontos em que uma execução pode falhar.

Em que ordem os eventos aconteceram?

A sequência dos eventos pode ser tão importante quanto o conteúdo de cada um.

Uma ferramenta pode ter retornado o resultado correto, mas somente depois de o Agente já ter enviado a resposta. Duas operações podem ter ocorrido em paralelo. Uma tentativa pode ter falhado e acionado uma estratégia alternativa. Um subagente pode ter recebido a tarefa sem todo o contexto necessário.

Métricas isoladas não revelam essas relações.

Agentes podem escolher ferramentas e caminhos diferentes para solicitações semelhantes. Por isso, saber que uma API demorou cinco segundos não é suficiente. É necessário saber em qual atendimento ela foi chamada, o que aconteceu antes, o que ocorreu depois e se sua resposta ainda foi considerada pelo Agente.

Os traces fornecem essa linha do tempo.

A visualização de traces do Gemini Enterprise Agent Platform, por exemplo, permite inspecionar execuções completas e operações individuais, como chamadas ao modelo, requisições de API e uso de ferramentas externas.

Onde houve lentidão ou erro?

Uma resposta pode estar correta e, ainda assim, representar um problema operacional se demorar tempo demais.

Por isso, a observabilidade deve mostrar tanto a duração total da execução quanto a latência de cada etapa.

Assim, a equipe consegue descobrir se o atraso aconteceu:

• na geração do modelo;
• na consulta à base de conhecimento;
• na chamada de uma API externa;
• em uma fila interna;
• na transferência entre Agentes;
• em uma política de validação;
• no envio da mensagem ao canal.

Essa análise evita conclusões apressadas. Uma empresa pode trocar o modelo esperando reduzir a demora, quando o verdadeiro gargalo está em uma integração externa.

A visualização granular dos spans também permite inspecionar atributos, códigos de status e erros de operações específicas.

Um mesmo erro aparente pode ter causas completamente diferentes

Considere um Agente comercial que envia um preço incorreto para um cliente.

O problema pode ter acontecido porque:

• o documento consultado continha uma tabela antiga;
• a busca recuperou o produto errado;
• o modelo ignorou uma condição comercial;
• a ferramenta de orçamento recebeu uma quantidade incorreta;
• a API aplicou uma regra desatualizada;
• uma chamada falhou e o Agente improvisou uma resposta;
• a resposta de outro sistema chegou depois do envio ao cliente;
• a configuração publicada não era a versão esperada.

No histórico da conversa, todos esses cenários aparecem da mesma forma: uma proposta com o valor errado.

No trace, cada cenário deixa evidências diferentes.

Se a fonte estava desatualizada, o problema está na governança do conhecimento. Se a busca recuperou o documento errado, pode ser necessário revisar a indexação ou os filtros. Se os parâmetros da ferramenta estavam incorretos, o esquema de entrada ou a descrição da função precisa de ajustes. Se houve uma falha externa sem tratamento, o fluxo precisa impedir que o Agente continue como se tivesse recebido uma confirmação.

Sem rastreamento, a tendência é alterar o prompt para tentar corrigir qualquer problema.

Com rastreamento, a equipe consegue intervir no componente que realmente falhou.

Tratar toda falha como problema de instrução cria uma sequência de correções isoladas. Esse comportamento pode fazer o sistema parecer mais controlado sem demonstrar que ficou melhor. Por isso, observabilidade e avaliação contínua de Agentes IA precisam funcionar juntas.

O trace ajuda a localizar a causa. A avaliação transforma o erro encontrado em um teste que poderá ser repetido nas próximas versões.

Observabilidade também revela erros silenciosos

Nem toda falha gera uma reclamação imediata.

Um Agente pode deixar de atualizar o CRM, consultar uma ferramenta desnecessária, repetir chamadas, consumir mais tokens do que deveria ou demorar alguns segundos a mais em cada atendimento.

A resposta final continua parecendo aceitável, mas o processo está ficando mais caro, lento ou inconsistente.

A observabilidade ajuda a identificar comportamentos como:

• aumento do número médio de chamadas ao modelo;
• repetição de consultas à mesma ferramenta;
• crescimento da latência após uma nova versão;
• falhas frequentes em determinada integração;
• aumento do consumo de tokens;
• transferências humanas desnecessárias;
• operações concluídas sem registro no CRM;
• respostas enviadas antes da confirmação de uma ação;
• chamadas realizadas com parâmetros incompletos.

Esses sinais dificilmente seriam encontrados pela leitura manual de algumas conversas.

Uma ferramenta pode apresentar uma taxa de falha de 8% sem que cada erro gere uma reclamação. Um Agente pode chamar a mesma API três vezes em vários atendimentos, elevando custo e latência sem alterar a resposta visível.

A partir desse acompanhamento, observabilidade deixa de ser apenas uma forma de explicar incidentes. Ela se torna parte da melhoria contínua da operação.

O tema se conecta diretamente à necessidade de medir se um Agente IA está funcionando com indicadores que vão além do tempo de resposta. Conclusão de tarefas, precisão, falhas de ferramentas, custo e necessidade de intervenção humana também precisam ser acompanhados.

Logs, métricas e traces cumprem funções diferentes

Uma operação completa normalmente precisa combinar logs, métricas e traces.

Logs registram acontecimentos específicos

Os logs registram eventos individuais.

Eles podem indicar que:

• uma chamada falhou;
• uma validação bloqueou uma ação;
• uma exceção foi gerada;
• uma tentativa foi repetida;
• uma ferramenta retornou um código inesperado;
• uma regra de segurança foi aplicada.

Um log ajuda a responder o que aconteceu em determinado componente.

Métricas mostram tendências

As métricas transformam acontecimentos em números agregados.

Elas podem mostrar:

• taxa de erro por ferramenta;
• latência média do Agente;
• consumo de tokens;
• número de execuções;
• quantidade de chamadas ao modelo;
• percentual de tarefas concluídas;
• volume de transferências humanas;
• custo médio por atendimento.

Uma métrica ajuda a descobrir que existe um problema, mas nem sempre explica sua causa.

Traces conectam a execução

Os traces mostram o caminho percorrido por uma solicitação específica.

Se uma métrica indicar que a latência aumentou, o trace ajuda a descobrir em qual etapa isso aconteceu. Se um log registrar uma falha em uma API, o trace mostra qual atendimento foi afetado e o que o Agente fez depois do erro.

A observabilidade se torna mais útil quando essas informações compartilham identificadores.

Um atendimento, uma sessão, uma execução, um trace e seus respectivos eventos precisam poder ser correlacionados. Sem essa ligação, a empresa possui muitos dados, mas continua sem conseguir reconstruir o incidente.

O que fazer quando uma ferramenta falha?

Registrar a falha é apenas a primeira parte.

O fluxo também precisa definir o que o Agente deve fazer depois.

Se o sistema de pagamentos estiver indisponível, o Agente deve tentar novamente? Informar o cliente? Criar uma tarefa para a equipe? Transferir a conversa? Guardar a solicitação para execução posterior?

A resposta depende do tipo de ferramenta e do impacto da ação.

Uma consulta de endereço pode permitir uma nova tentativa automática. Uma emissão de cobrança não deve ser repetida sem cuidado, pois duas tentativas podem criar cobranças duplicadas. Uma atualização cadastral pode exigir confirmação antes de ser reenviada.

Por isso, o trace deve registrar não apenas a primeira falha, mas também a estratégia adotada depois dela.

Uma boa investigação precisa mostrar:

1. qual chamada falhou;

2. qual erro foi recebido;

3. quantas tentativas foram realizadas;

4. qual regra de contingência foi acionada;

5. se houve comunicação com o cliente;

6. se a tarefa foi concluída posteriormente;

7. se uma pessoa precisou intervir.

Sem esse registro, a empresa pode encontrar o erro inicial e ainda não saber se o sistema se recuperou corretamente.

O cuidado necessário com dados sensíveis

Quanto mais detalhado for o rastreamento, maior será a responsabilidade sobre os dados armazenados.

Prompts, respostas, documentos recuperados e parâmetros de ferramentas podem conter informações pessoais, comerciais, médicas ou financeiras.

A empresa precisa definir:

• quais dados serão registrados;
• quais campos devem ser ocultados;
• quem poderá acessar cada informação;
• por quanto tempo os registros serão mantidos;
• onde serão armazenados;
• como serão protegidos;
• como solicitações de exclusão serão tratadas;
• quais informações podem ser utilizadas em avaliações.

A documentação da OpenAI alerta que spans de geração e de ferramentas podem armazenar entradas e saídas potencialmente sensíveis. O SDK oferece configurações para impedir a captura desse conteúdo quando necessário.

O Google Cloud também separa metadados operacionais, como latência, códigos de status e estrutura da execução, do conteúdo potencialmente sensível de prompts e respostas. Isso permite aplicar políticas de armazenamento e acesso diferentes.

Essa separação é útil porque a equipe técnica pode precisar visualizar a latência e o código de erro de uma ferramenta sem ter acesso ao conteúdo completo da conversa do cliente.

Observabilidade não deve significar registrar indiscriminadamente tudo o que passa pelo Agente. Ela precisa ser construída junto com regras de privacidade, retenção, segurança e controle de acesso.

Para operações que tratam informações pessoais, essa discussão também deve considerar os cuidados apresentados no conteúdo sobre IA no atendimento e LGPD.

O nível de observabilidade deve crescer com a autonomia

Um chatbot que apenas responde perguntas usando um conjunto pequeno de informações apresenta um risco limitado. Mesmo assim, algum nível de registro continua sendo necessário.

O cenário muda quando o Agente recebe autorização para executar ações.

Quanto maior a capacidade de alterar cadastros, emitir documentos, enviar propostas, movimentar etapas comerciais, realizar agendamentos ou consultar informações restritas, maior precisa ser a capacidade de reconstruir cada execução.

Antes de ampliar a autonomia, a empresa deveria conseguir responder:

• Qual solicitação foi recebida?
• Qual configuração do Agente estava ativa?
• Qual modelo foi utilizado?
• Quais dados foram entregues ao modelo?
• Quais fontes foram consultadas?
• Quais ferramentas foram acionadas?
• Quais parâmetros foram enviados?
• O que cada sistema retornou?
• Quanto tempo cada etapa levou?
• Alguma validação foi executada?
• Houve tentativa de repetição?
• Onde aconteceu a falha?
• Qual foi a ação final?
• Quem poderia autorizar aquela operação?

Esse último ponto se relaciona com a necessidade de definir identidade, permissões e responsabilidade em Agentes IA. Saber que uma ação ocorreu não basta. A empresa também precisa saber qual Agente a executou, em nome de quem e com qual nível de autorização.

Se essas perguntas não puderem ser respondidas, a organização está concedendo autonomia sem possuir os instrumentos necessários para supervisioná-la.

Como começar sem construir uma estrutura excessiva

A empresa não precisa começar com o sistema de observabilidade mais complexo possível.

O primeiro passo é identificar as ações que apresentam maior impacto.

Um Agente que apenas responde perguntas pode começar registrando:

• identificação da conversa;
• versão das instruções;
• modelo utilizado;
• documentos recuperados;
• tempo total de resposta;
• erros de geração.

Um Agente que consulta ferramentas também precisa registrar chamadas, parâmetros, resultados e latência.

Quando o Agente executa ações que alteram sistemas, o controle deve crescer. Nesse caso, é necessário incluir identidade, autorização, confirmações, tentativas, resultado final e possibilidade de auditoria.

Uma implementação inicial pode seguir esta ordem:

1. criar um identificador único para cada execução;

2. relacionar esse identificador à conversa e à sessão;

3. registrar a versão do Agente e do modelo;

4. registrar consultas à base de conhecimento;

5. instrumentar chamadas de ferramentas;

6. separar logs, métricas e traces;

7. criar alertas para falhas de maior impacto;

8. definir regras de retenção e acesso;

9. transformar incidentes reais em avaliações;

10. revisar a cobertura conforme a autonomia aumenta.

O objetivo não é armazenar o máximo possível. É registrar o necessário para investigar o que realmente pode dar errado.

O objetivo não é impedir todos os erros

Nenhum sistema complexo opera sem falhas.

O objetivo da observabilidade não é criar a ilusão de que um Agente nunca errará. É garantir que, quando algo acontecer, a empresa consiga localizar a execução, reconstruir os eventos, identificar a causa e corrigir o componente responsável.

Essa capacidade separa uma demonstração de Inteligência Artificial de uma operação preparada para atender clientes reais.

Em uma demonstração, basta que o Agente produza algumas respostas convincentes.

Em produção, é necessário entender o que aconteceu quando a resposta não foi convincente, quando uma ferramenta falhou, quando uma ação indevida foi executada ou quando o atendimento demorou mais do que deveria.

Antes de aumentar a autonomia do seu Agente, verifique se sua equipe consegue reconstruir uma execução do começo ao fim.