Observabilidade de agentes de IA: o que registrar desde o primeiro dia

A observabilidade de agentes de IA é a prática de registrar o suficiente sobre o que um agente faz, na ordem certa e com o contexto de cada passo, para que uma pessoa consiga reconstruir qualquer execução depois. Para uma empresa, o conjunto mínimo é o registro completo da execução (trace), cada chamada de ferramenta com a permissão e o resultado, cada pedido de aprovação com o seu desfecho, e o custo por execução e por tarefa concluída. Comece a registrar isso antes de o agente tocar em qualquer coisa que importe, porque evidência não pode ser reconstruída de memória depois que o trabalho terminou.

Principais pontos

• Dê a cada execução um identificador único que conecte o gatilho, as chamadas ao modelo, as chamadas de ferramentas, as aprovações e a saída final.
• Registre cada chamada de ferramenta com a identidade e a permissão usadas, e não apenas a resposta final.
• Trate cada aprovação como um evento, com solicitante, aprovador, decisão e data e hora.
• Meça o custo por tarefa concluída, para que variações de gasto possam ser explicadas por volume, novas tentativas ou mudanças de versão.
• Defina retenção, acesso e anonimização antes da primeira execução em produção, e não depois do primeiro incidente.

Por que os registros importam mais quando o agente age

Quando um assistente apenas rascunha texto, uma pessoa lê a saída e julga o resultado. Um agente é diferente. Ele lê um registro, escolhe uma ferramenta, redige uma solicitação, espera uma aprovação e então age, e a mensagem final mostra apenas a última dessas decisões. À medida que o agente ganha capacidade, ele pode percorrer caminhos mais longos, usar mais ferramentas e lidar com casos para os quais ninguém escreveu uma regra. A empresa precisa, então, de evidências que não dependam de o próprio agente explicar o que fez depois do fato.

Observabilidade é a disciplina de tornar o comportamento de um sistema visível a partir dos registros que ele deixa para trás. A introdução à observabilidade da OpenTelemetry separa três tipos de sinal conhecidos: traces, que mostram o caminho de uma tarefa; métricas, que mostram tendências em muitas tarefas; e logs, que guardam o detalhe por trás de cada passo. Esse vocabulário se aplica bem a agentes. Os traces respondem o que aconteceu nesta execução, as métricas respondem se o comportamento está se desviando, e os logs respondem por que um passo específico foi dado.

Um teste prático é simples. Escolha uma execução qualquer e pergunte: o que o agente fez, com qual permissão, por instrução de quem e com que custo? Se a resposta exigir que alguém se lembre da execução ou que pesquise em vários sistemas sem relação entre si, o agente ainda não é observável de forma útil.

O registro da execução: o que uma tarefa precisa deixar para trás

Cada execução do agente precisa de um identificador que una o pedido que a iniciou, as chamadas ao modelo, as chamadas de ferramentas, as aprovações e a saída. Sem esse identificador, a empresa fica com fragmentos que não se conectam. O trace deve registrar o gatilho (qual pessoa, sistema ou canal iniciou a execução), a versão do agente, o conjunto de instruções e a versão do modelo em uso, os itens de memória lidos pelo identificador, os horários de início e fim, o status final e quaisquer erros ou novas tentativas.

As informações de versão merecem atenção especial. Uma mudança nas instruções, na memória ou no modelo é uma mudança de comportamento, então precisa aparecer em todos os traces, e não apenas em uma nota de versão. Esse é o principal motivo para que as mudanças em um agente gerenciado passem por um pedido registrado e aprovado. O processo está descrito em como solicitar e aprovar mudanças em um agente de IA gerenciado.

Para nomes de campos compartilhados, as convenções semânticas da OpenTelemetry para IA generativa definem atributos para o modelo, a operação e o uso de tokens. Usar nomes padronizados significa que seus traces podem ser lidos por pessoas e ferramentas fora da equipe que construiu o agente, o que importa quando a equipe muda.

Chamadas de ferramentas e permissões: o registro do que o agente tocou

As chamadas de ferramentas são o ponto em que o agente altera coisas, por isso exigem o registro mais cuidadoso. Para cada chamada, registre o nome e a versão da ferramenta, o escopo de permissão sob o qual ela rodou, a identidade em nome da qual a chamada foi feita, os parâmetros, o status do resultado, um resumo curto do resultado e se uma pessoa aprovou a ação. Campos sensíveis devem ser anonimizados ou guardados como hash, com a regra de anonimização documentada.

Registre as tentativas negadas com o mesmo cuidado que as chamadas bem-sucedidas. Uma chamada recusada mostra o que o agente tentou fazer, o que muitas vezes é o primeiro sinal de que as instruções saíram do rumo ou de que uma entrada está tentando direcionar o agente. A orientação da OWASP sobre autorização trata as decisões de acesso como algo que deve ser aplicado e verificado, e uma chamada negada é evidência de que a aplicação funcionou. A folha de referência da OWASP sobre prevenção de injeção de prompt acrescenta um ponto relacionado: conteúdo de fora da empresa, como uma página web ou um e-mail recebido, pode carregar instruções. Registre qual entrada externa influenciou uma chamada de ferramenta, para que a trilha mostre de onde veio uma ação surpreendente.

Cenário ilustrativo: um agente de suporte pode consultar pedidos e rascunhar solicitações de reembolso, mas emitir um reembolso exige aprovação de um gestor. O trace de um cliente mostra uma chamada de leitura, uma chamada de rascunho, um pedido de aprovação com o identificador do gestor e uma chamada de reembolso feita em nome do gestor, depois da aprovação. Se algum dia uma chamada de reembolso aparecer em nome do próprio agente, o modelo de permissões está errado, e o registro mostra exatamente onde procurar.

Aprovações: provar quem autorizou o quê

Uma aprovação é um evento, não uma caixa marcada. Cada registro de aprovação deve conter um identificador do pedido, a ação descrita em linguagem simples e com os parâmetros exatos, a regra da política que exigiu a aprovação, a identidade do aprovador, a decisão (aprovada, rejeitada ou alterada), a data e hora, o tempo gasto para decidir e a ação executada depois. Registre também as aprovações que expiraram sem decisão, porque uma fila crescente de pedidos sem resposta é um sinal operacional por si só.

Vincule cada aprovação aos seus parâmetros. Uma aprovação dada para o reembolso de um valor não deve cobrir silenciosamente outro valor ou outro cliente. Se o agente propuser uma versão alterada, essa versão precisa de aprovação própria. É aqui que muitas equipes descobrem que a etapa de aprovação registra um sim, mas não registra a que foi dito sim.

Os registros de aprovação também são a evidência das revisões periódicas. Quando alguém perguntar se o agente ainda tem direito de executar uma ação, a resposta deve vir desses registros, e não da lembrança de quem um dia concordou com algo.

Sinais de custo e uso que continuam legíveis

O custo é o sinal com mais chance de surpreender uma empresa, e o que mais costuma ser medido de forma errada. Acompanhe os tokens de entrada e saída por chamada ao modelo, o número de chamadas ao modelo e de chamadas de ferramentas por execução, as novas tentativas e a atividade de cache quando o provedor informar. O cache de prompts, por exemplo, pode mudar o custo de um contexto repetido, então o trace deve mostrar se houve uso de cache em determinada chamada.

A orientação da FinOps Foundation sobre economia unitária aponta a unidade de medida certa: o custo por unidade de resultado do negócio, e não o gasto total. O gasto total sobe quando o agente tem mais sucesso, o que é bom, então uma conta crescente, sozinha, diz pouco. O custo por tarefa concluída mostra se o agente está ficando mais ou menos eficiente no trabalho em si.

Segmente esses números por agente, por fluxo de trabalho e por versão. Configure alertas para mudanças súbitas no custo por execução, e não para o total mensal, porque uma mudança súbita geralmente indica um erro, um ciclo de novas tentativas ou uma instrução alterada. Mantenha os limites nas notas operacionais, para que quem lê o alerta saiba como é o funcionamento normal.

Um plano de registro para o primeiro dia

A sequência a seguir pode ser aplicada a qualquer primeiro agente antes que ele trabalhe com tarefas reais.

• Defina o nome do agente, o dono de negócio e a única tarefa que ele executa, e decida o esquema de identificadores dos traces.
• Escreva o esquema de eventos para execuções, chamadas de ferramentas, aprovações e custos antes de construir o agente, para que a instrumentação seja planejada e não colocada depois.
• Decida o que é guardado na íntegra, o que recebe hash ou anonimização e o que nunca é guardado, incluindo segredos e dados pessoais desnecessários.
• Defina retenção e acesso: quem pode ler os traces, por quanto tempo são mantidos e onde ficam armazenados.
• Execute uma tarefa supervisionada e reconstrua-a usando apenas os registros. Se alguma etapa não puder ser reconstruída, corrija o esquema antes de entrar em produção.
• Configure dois ou três alertas desde o início: aumento de chamadas negadas, acúmulo de aprovações pendentes e mudança no custo por tarefa concluída além de uma faixa acordada.
• Marque a primeira revisão dos registros com o dono de negócio, em data fixa, e registre o que foi decidido.

O NIST AI Risk Management Framework trata esse tipo de rastreabilidade como parte da gestão de risco de IA ao longo de todo o ciclo de vida do sistema, e não como um detalhe para a equipe de engenharia resolver depois.

Como a Be Human faz isso: em um projeto gerenciado, a Be Human define o esquema de eventos durante o primeiro ciclo de trabalho, instrumenta o agente para que cada execução, chamada de ferramenta, aprovação e sinal de custo seja registrado sob um único identificador, e mantém esses registros sob as mesmas regras de acesso das permissões do agente. O monitoramento revisa os sinais de forma recorrente, as revisões de permissões usam os registros de aprovação como evidência, e a resposta a incidentes começa pelo trace, e não pela lembrança de alguém. O escopo permanece propositalmente pequeno: um papel, sua memória e suas ferramentas, e um critério de sucesso que os registros realmente consigam medir.

Quem lê os registros, e com que frequência

Registros que ninguém lê são um custo de armazenamento com rótulo de conformidade. Defina um responsável por cada agente que leia as exceções toda semana, revise o custo por tarefa concluída todo mês e revise as permissões todo trimestre. A revisão de permissões deve usar como ponto de partida os registros de aprovação e de chamadas negadas, seguindo os passos em como fazer uma revisão de permissões dos seus agentes de IA.

O responsável não precisa ler todos os traces. Ele precisa saber como é uma execução normal, quais sinais indicam que algo mudou e para quem ligar quando os sinais se alterarem. Se você não tem certeza de qual processo deve receber um agente primeiro, e o que a trilha dele deve mostrar no primeiro dia, faça o diagnóstico gratuito de IA da Be Human para encontrar a primeira tarefa que vale a pena entregar a um agente.

Perguntas frequentes

Precisamos de um produto específico de observabilidade de IA, ou as ferramentas de log que já usamos resolvem? As ferramentas de log e rastreamento existentes podem fazer a maior parte do trabalho, desde que os eventos do agente sejam estruturados com identificadores e campos consistentes. A parte difícil é o esquema e a disciplina de registrar aprovações, permissões e versões, algo que nenhuma ferramenta decide por você. Escolha as ferramentas depois de escrever o esquema, e não antes.

Devemos guardar os prompts e as saídas do modelo na íntegra? Guarde o suficiente para reconstruir uma decisão, mas não tudo por padrão. Conteúdos completos podem conter dados pessoais, segredos ou conhecimento confidencial, então defina, campo a campo, o que fica na íntegra, o que é resumido e o que recebe hash. Documente essas regras e revise-as com o responsável pela proteção de dados.

Por quanto tempo os logs dos agentes devem ser mantidos? O período de retenção deve seguir suas obrigações legais, seus contratos e o tempo necessário para investigar uma reclamação ou um incidente no seu setor. Mantenha os registros de aprovação e de permissões pelo menos pelo mesmo tempo que as decisões de negócio que eles sustentam. Uma divisão comum e defensável é reter o conteúdo detalhado por menos tempo e os registros de resumo e aprovação por mais tempo.

Qual é o primeiro alerta a configurar? Comece com um alerta sobre chamadas de ferramentas negadas, porque ele revela tanto permissões mal configuradas quanto possíveis tentativas de direcionar o agente. Em seguida, adicione um alerta para pedidos de aprovação que fiquem sem resposta além de um prazo acordado. Um alerta de custo baseado no custo por tarefa concluída vem depois, quando você tiver algumas semanas de comportamento normal para comparar.

Orientação editorial Be Human. Exemplos são ilustrativos, salvo atribuição explícita. Fontes oferecem contexto; a implementação depende do seu processo.