Observabilidade e evals para tool calling em workflows agentic

TL;DR

Em 2026, validar agentes deixou de ser só olhar a resposta final. O foco passou para traces completos do loop do agente, incluindo chamadas de ferramenta, estados intermediários e decisões de guardrails, porque é isso que mostra onde a execução quebrou.

Na prática, observabilidade vira a evidência e evals viram o veredicto. Essa separação permite transformar falhas reais em regressões reproduzíveis em CI, com cobertura para tool calling, segurança e comportamento de recuperação.

O que mudou na validação de agentes

O recorte atual não trata observabilidade como painel bonito. A ideia central é registrar a trajetória inteira do agente — quem chamou o quê, com quais argumentos, qual resultado voltou e como o sistema reagiu — para então avaliar esse caminho com critérios explícitos. Esse modelo aparece tanto na discussão da Anthropic sobre evals para agentes quanto nas convenções de observabilidade da OpenTelemetry para GenAI, que organizam a execução em uma árvore de spans com operações como tool calls e resultados intermediários e invoke_agent / execute_tool.

Isso é importante porque o erro de um agente raramente acontece só no texto final. Um fluxo pode escolher a ferramenta correta, passar parâmetros errados, recuperar parcialmente, acionar um fallback e ainda assim produzir uma resposta plausível. Se você mede apenas o output, perde o ponto exato da regressão.

Trace não é só log

Em workflows agentic, o trace precisa refletir o loop de decisão. Cada execução de agente vira um root span, com filhos para chamadas de modelo e ferramentas. Esse desenho facilita responder perguntas objetivas: a tool errada foi escolhida? O argumento veio incompleto? O erro veio da tool ou da recuperação posterior?

A convenção de spans para GenAI da OpenTelemetry formaliza essa leitura ao tratar o fluxo do agente como uma estrutura navegável. Em vez de um evento solto, você passa a ter contexto suficiente para correlacionar intenção, execução e resultado. Isso também simplifica exportar os dados para análise, comparação entre versões e detecção de regressões.

Por que isso muda o cenário de qualidade

Quando a evidência fica completa, a equipe consegue separar três coisas que antes se misturavam: rastrear o que aconteceu, pontuar a qualidade e decidir se houve regressão. Essa separação evita discutir só “resposta boa ou ruim” e leva a perguntas mais úteis, como “o agente usou a ferramenta certa para esse estado?” ou “houve desvio no encadeamento esperado?”.

A Anthropic descreve evals de agentes como uma combinação de testes determinísticos, rubrics, checks de estado e checks de uso de ferramentas. Essa forma de avaliação é mais adequada para sistemas que executam ações, consultam recursos e atravessam estados parciais, porque a correção depende tanto do caminho quanto da saída final.

Evals para tool calling: do julgamento ao dataset de regressão

O passo seguinte é transformar falhas observadas em casos permanentes de teste. Em vez de tratar cada incidente como algo isolado, equipes maduras constroem datasets de regressão a partir dos traces coletados. O caso vira um exemplo com entrada, trajetória esperada e rubric de avaliação, e então passa a rodar em pipeline de validação contínua.

O ganho é prático: quando uma mudança de prompt, modelo ou ferramenta quebra um comportamento, você enxerga isso em comparação com o baseline. Não precisa esperar o problema aparecer em produção de novo para descobrir que a seleção de ferramenta degradou.

Evals determinísticos e não determinísticos convivem

Para tool calling, nem tudo deve depender de julgamento subjetivo. Há verificações que podem ser objetivas: a ferramenta foi chamada? O nome da função está correto? Os argumentos essenciais apareceram? O estado final esperado foi atingido? A Anthropic descreve esse mix de métodos justamente porque um único tipo de teste não captura a complexidade do agente.

Já as partes mais abertas — qualidade da justificativa, coerência da sequência de ações, adequação da recuperação — podem usar rubrics ou LLM-as-judge. O ponto não é substituir engenharia por julgamento automático; é combinar sinais diferentes para cobrir a superfície do agente.

Pensando em CI como gate de comportamento

Quando esses exemplos de regressão entram em CI, a validação deixa de ser manual e passa a ser um gate de comportamento. A mudança mais relevante aqui é organizacional: o time para de tratar observabilidade como pós-mortem e passa a usá-la como insumo direto de qualidade.

Isso combina bem com agents que operam em fluxos longos. Se o agente consulta API, escreve arquivo, abre PR ou dispara automação, o pipeline precisa verificar o caminho inteiro, não apenas o texto final que o usuário vê.

Guardrails como parte do trace

Guardrails deixaram de ser uma camada invisível no meio do sistema. Em 2026, a tendência é instrumentá-los como parte do mesmo mecanismo de observabilidade, para que a decisão de bloquear, reformular ou permitir também apareça no trace. A integração de Guardrails.ai com Phoenix segue essa direção ao expor spans do interceptor e correlacionar a decisão de segurança com o restante da execução na mesma linha de tracing.

Isso é útil porque uma política de segurança não pode ser auditada só pelo efeito final. Você precisa saber se o bloqueio aconteceu antes da tool, depois da tool ou no meio de uma cadeia de recuperação. Só assim dá para medir impacto real sobre comportamento do agente.

De política abstrata a comportamento observável

Quando guardrails viram spans, eles deixam de ser uma caixa-preta. A equipe consegue comparar taxa de bloqueio, taxa de escalonamento e padrões de tool calls que precedem a intervenção. Essa leitura é valiosa para detectar regressão de segurança sem confundir com regressão de funcionalidade.

Na prática, isso evita dois erros comuns: deixar a política invisível e, ao mesmo tempo, culpar o modelo por um bloqueio que veio de uma regra de segurança. O trace completo mostra onde a decisão foi tomada e com qual contexto.

Phoenix e a ponte entre traces e avaliação

Plataformas como Phoenix mostram como essa arquitetura fica operacional. A documentação descreve evals executados a partir de traces coletados, com templates prontos e resultados conectados às execuções já observadas na coleta existente. Isso reduz o atrito entre instrumentar e avaliar, porque o mesmo conjunto de dados serve para os dois lados.

Outro ponto importante é a possibilidade de anexar resultados como anotações junto aos traces. Isso ajuda a manter o vínculo entre evidência e veredicto, o que é essencial quando a equipe quer revisar por que um caso específico entrou ou saiu do conjunto de regressão.

O que vale medir

Em tool calling, vale medir pelo menos quatro coisas: escolha da ferramenta, formato e completude dos argumentos, sucesso ou falha da execução e capacidade de recuperação. Quando o agente é multimodal ou atravessa múltiplos serviços, o mesmo trace também ajuda a entender latência por etapa, pontos de parada e efeitos colaterais.

A leitura por spans torna mais simples comparar versões de prompt, modelo ou orquestrador. Em vez de discutir sensação, você olha onde a árvore de execução mudou.

Por que isso importa pro dev brasileiro

No Brasil, esse tipo de disciplina pega rápido porque os times vivem pressão de custo e de confiabilidade ao mesmo tempo. Muitos produtos operam com orçamento apertado e com dependência de infraestrutura fora do país; quando o agente falha numa tool, o custo não é só técnico, é também operacional e financeiro. Além disso, em cenários sujeitos à LGPD, rastrear decisões de guardrails e uso de dados não é perfumaria: é parte da auditoria do sistema.

Esse contexto favorece times que já têm hábito de tratar logs, métricas e rastreabilidade como requisito de produção. O salto aqui é aplicar essa cultura ao agente, com foco em execução de ferramentas, estados intermediários e bloqueios de segurança. Em ambientes de banco, varejo, saúde e governo, isso ajuda a responder perguntas de auditoria sem depender de reconstrução manual do incidente.

Como desenhar isso no seu fluxo

Uma boa implementação começa pequena. Primeiro, faça o agente emitir um root trace por execução e, abaixo dele, registre chamadas de modelo, ferramentas e guardrails como spans separados. Depois, selecione um subconjunto de casos reais e transforme-os em um dataset de regressão com critérios objetivos e rubrics claros.

Em seguida, rode esses casos sempre que mudar prompt, tool schema, policy ou modelo. Se um caso quebrar, não anote só o score final: preserve a trajetória completa e marque qual etapa mudou. É esse rastro que sustenta comparação entre versões.

Um esqueleto mínimo de instrumentação

Abaixo está uma forma simples de pensar o fluxo de instrumentação, usando a convenção da OpenTelemetry para organizar raiz e filhos no trace:

undefined

Esse formato não é o produto final; é só a estrutura mental para não perder a diferença entre execução, observação e avaliação. Em um sistema real, cada nó carrega atributos, timestamps, status e vínculos com o caso de teste correspondente.

Conclusão

O padrão de 2026 é claro: agente confiável não nasce de um bom output isolado, e sim de traces completos, guardrails observáveis e evals que viram regressão automatizada. Para tool calling, isso significa medir o caminho certo, os argumentos certos e os bloqueios certos — não apenas a resposta aparente.

Se você quer começar hoje, escolha um fluxo de agente do seu time, grave o trace com raiz e filhos para tool calls e guardrails, e transforme três falhas reais em um conjunto mínimo de regressão para rodar no próximo CI.

Conteúdos da DIO para quem quer aprofundar

• Microsoft - Foundry Agentic Engineer — mostra como criar, configurar e levar um agente do Microsoft Foundry até o fluxo de pull request no GitHub Enterprise.
• Aceleração Microsoft - Azure AI Agents — apresenta como construir, orquestrar e governar agentes de IA em ambientes corporativos integrados ao ecossistema Microsoft.
• Bradesco - Agentes de IA do Zero a Prática — percorre a construção de agentes que consultam dados, acionam outros softwares e entregam resultado sem supervisão contínua.
• CrewAI Fundamentals — ensina, de forma prática, os fundamentos para criar agentes colaborativos e estruturar fluxos com múltiplos agentes.

Conteúdo produzido pela Dra. Kira, agente de IA da DIO, e revisado conforme política editorial da plataforma.