Como avaliar a trajetória de um agente de IA

Uma resposta final correta pode esconder um caminho ruim. O agente pode ter chamado a tool errada, enviado um identificador inválido, repetido uma busca ou precisado de uma intervenção humana sem registrar isso.

Por isso, avaliar um agente exige olhar para a trajetória, não apenas para a última frase. Neste artigo, trajetória significa a sequência observável de ações entre a entrada do usuário e a resposta final. O foco é o que o sistema fez: tools, argumentos, resultados, estado e decisões de parada.

O recorte é complementar ao guia sobre escolher entre mock e modelo real ao testar agentes. Aquele texto ajuda a separar as camadas de teste. Aqui, a pergunta é outra: o que cada execução deve provar quando o agente usa ferramentas?

Diagrama compara a trajetória esperada e a observada de um agente até a resposta final.

Decisão prática

Registre a trajetória junto com a resposta final.

Exija ordem exata apenas quando a ordem for parte do contrato.

Valide argumentos, tools proibidas e estado final com checagens determinísticas.

Use um avaliador semântico somente para o que uma regra observável não consegue decidir.

O que a trajetória de um agente mede?

A trajetória mede o caminho que o agente seguiu para cumprir uma tarefa. A documentação do Google ADK sobre avaliação separa avaliação de tool use e trajetória da avaliação da resposta final. Essa separação é útil porque uma resposta pode parecer boa mesmo quando o processo teve passos desnecessários ou incorretos.

Imagine um agente que precisa consultar o status de um pedido. O resultado final deve conter o status correto, mas o sistema também pode exigir que ele use get_order, passe o ID do pedido recebido e não chame cancel_order. São três afirmações diferentes: resultado, argumento e limite de ação.

O registro da trajetória não precisa expor o raciocínio privado do modelo. Ele precisa guardar eventos operacionais suficientes para verificar o contrato. Em geral, isso inclui a entrada, as chamadas de tool, argumentos validados, respostas resumidas, mudanças de estado, tentativas, intervenções e a saída.

Esse recorte também conversa com validar argumentos e respostas de tool em TypeScript. A validação protege cada fronteira. A avaliação de trajetória verifica se o agente passou por essas fronteiras na execução completa.

Como registrar uma trajetória sem guardar informação demais?

Um registro útil é pequeno, estável e suficiente para a asserção que você quer fazer. Não copie o prompt inteiro ou cada log de infraestrutura por padrão. Use um formato próprio para eventos que possa sobreviver à troca de provedor.

O exemplo abaixo é ilustrativo. Ele mostra uma representação possível, mas não foi executado neste repositório e não depende de um SDK específico.

type ToolEvent = {
  kind: "tool_call";
  name: string;
  args: Record<string, unknown>;
  result: "ok" | "error";
};

type AgentTrajectory = {
  caseId: string;
  events: ToolEvent[];
  finalState: string;
  humanInterventions: number;
};

O caseId liga o trace ao caso de avaliação sem colocar dados pessoais no relatório. name e args permitem verificar escolha e contrato. result separa uma chamada bem-sucedida de uma tentativa que terminou em erro. finalState evita depender da redação da resposta. humanInterventions mostra quando o resultado só apareceu depois de uma decisão humana.

Adapte o esquema ao risco da aplicação. Para um agente que altera registros, guarde também o alvo normalizado, a versão da política e um identificador de idempotência. Para um coding agent, o equivalente pode ser arquivo tocado, comando executado, teste acionado e artefato produzido. Não inclua segredos, tokens ou payloads completos quando um resumo verificável for suficiente.

Quais asserções uma avaliação de trajetória deve ter?

Comece com asserções observáveis. Elas são mais fáceis de explicar, repetir e rodar no CI. A trajetória esperada não precisa ser uma cópia do transcript. Ela pode declarar somente os limites que importam para a tarefa.

Asserção	Pergunta	Exemplo de falha
Tool permitida	O agente usou uma ação disponível para este caso?	Chamou `delete_order` durante uma consulta.
Argumentos	A tool recebeu os campos e valores esperados?	Usou o ID de outro pedido.
Ordem	Uma etapa precisava acontecer antes de outra?	Publicou antes da aprovação.
Proibição	O agente evitou ações que não fazem parte do caso?	Consultou uma fonte externa desnecessária.
Estado	O efeito observável terminou no estado esperado?	Respondeu “cancelado”, mas o pedido continuou ativo.

O Google Cloud descreve métricas de avaliação de trajetória como correspondência, precisão e recall das chamadas esperadas, além de métricas para uso de uma única tool. A nomenclatura muda entre frameworks, mas a decisão é a mesma: escolha a métrica que corresponde ao contrato, não a mais rígida por default.

Uma checagem de estado costuma ser mais importante que uma lista idêntica de tools. Se duas leituras independentes levam ao mesmo estado e nenhuma ação proibida ocorreu, exigir uma ordem específica pode rejeitar uma execução válida. Em compensação, uma confirmação de pagamento, uma aprovação ou uma migração destrutiva normalmente tem uma ordem que faz parte da segurança.

Quando a ordem exata é uma boa regra?

Use correspondência exata quando a sequência é uma pré-condição do negócio ou da segurança. Um caso simples seria authorize_user antes de read_balance. Outro seria validate_payload, depois request_approval, e só então publish_change.

Não use ordem exata apenas porque o primeiro trace que você viu tinha aquela ordem. O modelo pode escolher duas leituras em paralelo, ou consultar uma fonte secundária antes da principal, sem alterar o resultado nem aumentar o risco. Nesses casos, prefira asserções de conjunto, subsequência ou estado final.

Os avaliadores de trajetória da LangChain AgentEvals separam correspondência estrita, correspondência sem ordem, subconjunto e comparação de argumentos. A existência dessas opções não torna uma delas universalmente correta. Ela ajuda a expressar o contrato que você já deveria ter definido.

Uma política prática pode ficar assim:

const contract = {
  requiredTools: ["get_order"],
  forbiddenTools: ["cancel_order", "delete_order"],
  requiredArgs: { get_order: { id: "ord-7" } },
  order: "any",
  finalState: "order:ord-7:visible",
};

O valor de order é uma decisão do contrato. Se ele for any, a avaliação deve verificar presença, argumentos, proibições e estado. Se for exact, ela deve comparar a sequência inteira. O formato é ilustrativo e precisa ser adaptado ao executor real.

Como separar checagens determinísticas de julgamento semântico?

Uma avaliação semântica é útil quando não existe uma resposta única ou uma regra simples. Ela pode verificar se uma explicação é compreensível, se uma resposta está fundamentada no resultado da tool ou se uma conversa atingiu um objetivo aberto. Ela não deve substituir uma regra que o código consegue verificar diretamente.

Use checagens determinísticas para nome da tool, argumentos, ordem obrigatória, ações proibidas, estado final, schema e limite de tentativas. Reserve um juiz semântico para critérios como clareza, completude ou equivalência de sentido. Mesmo nesse caso, escreva uma rubrica curta e guarde a evidência usada pelo avaliador.

O guia de avaliação do ADK recomenda critérios de trajetória e resposta diferentes. Para CI e regressão, ele indica métricas de tool trajectory e comparação de resposta como opções rápidas e previsíveis. Critérios baseados em rubrica servem quando não há uma resposta de referência confiável.

Essa divisão reduz dois erros. O primeiro é aceitar uma resposta persuasiva que usou a tool errada. O segundo é rejeitar uma resposta correta porque ela não coincidiu palavra por palavra com uma frase de referência. A avaliação deve medir o risco que você realmente quer controlar.

Como levar a avaliação de trajetória para o CI?

Separe o teste rápido do eval que depende de rede, modelo ou juiz. O primeiro deve rodar a cada mudança e verificar traces controlados. O segundo pode rodar em uma agenda, ao alterar prompt ou ao comparar versões de modelo. O artigo sobre evals de regressão para agentes de código no CI entra depois para decidir quais comportamentos anteriores também precisam ser preservados.

Um fluxo mínimo tem estas etapas:

Crie casos com entrada, tools disponíveis, estado inicial e resultado esperado.
Rode o agente e salve uma trajetória sanitizada junto com a resposta.
Aplique checks de tools, argumentos, proibições e estado final.
Rode uma rubrica semântica somente nos casos que passaram pelas regras básicas.
Publique um resumo com falhas, tentativas e intervenção humana.
Transforme cada falha relevante em um caso de regressão versionado.

Um job pode chamar um script próprio, uma ferramenta de avaliação do provedor ou uma biblioteca como AgentEvals. O importante é que o contrato fique visível no repositório e que o relatório mostre a diferença entre resposta final e trajetória.

{
  "case": "show-order-status",
  "required_tools": ["get_order"],
  "forbidden_tools": ["cancel_order"],
  "expected_state": "order:ord-7:visible",
  "checks": ["tool", "args", "forbidden", "state"]
}

Esse arquivo é apenas uma ideia de formato. O ord-7 é um valor de exemplo, não um dado de produção. Em uma suíte real, crie fixtures controladas e evite reutilizar identificadores entre casos que possam alterar o mesmo estado.

Para loops que atravessam sessões e acumulam contexto de trabalho, o autor usa o RemoteCode como sua ferramenta. Essa menção descreve o contexto de produção do autor, não um benchmark ou uma promessa de qualidade.

Quais falhas a trajetória revela que a resposta esconde?

O primeiro sinal é a tool errada com resposta correta. Uma busca secundária pode ter devolvido o mesmo texto do fixture, mas o agente violou o limite que você queria testar. O segundo é o argumento quase certo: o nome da tool está correto, mas o ID, tenant ou filtro pertence ao caso errado.

O terceiro é a intervenção silenciosa. Uma pessoa corrige o payload, aprova uma ação ou repete uma etapa, e o relatório registra apenas “sucesso”. Conte essa decisão como parte da trajetória. Um agente que só termina depois de resgate humano não deve ser comparado com um agente que completou o caso sozinho.

O quarto é o desperdício de caminho. O agente chega ao estado correto depois de chamadas repetidas, leituras sem efeito ou tentativas que uma regra deveria ter bloqueado. Isso não significa que toda trajetória longa esteja errada. Significa que eficiência e intervenção podem ser sinais separados do resultado.

Como verificar se a suíte está medindo o risco certo?

Revise a suíte com um caso aprovado, um caso de argumento inválido, uma tool proibida, uma resposta de erro e uma execução que precisa de intervenção. Não adicione exemplos apenas para aumentar a cobertura aparente. Cada caso deve representar uma decisão que alguém tomaria ao operar o agente.

Confira também o que o relatório não mostra. Se ele guarda somente o texto final, você não consegue distinguir uma trajetória segura de uma trajetória que chegou ao mesmo lugar por acaso. Se ele guarda o transcript completo sem redação, pode vazar dados que não ajudam a avaliação.

Uma revisão útil pergunta:

Os casos definem estado inicial e estado final?
As tools proibidas aparecem explicitamente?
Os argumentos são comparados no nível que importa, sem exigir campos irrelevantes?
A ordem exata está ligada a uma regra de negócio ou segurança?
O relatório registra retries, falhas e intervenção humana?
O juiz semântico recebe somente o contexto necessário?
Uma falha nova vira um caso reproduzível?

Se a resposta para alguma dessas perguntas for “não”, o problema ainda é de contrato de avaliação. Trocar o modelo ou aumentar a pontuação não corrige uma pergunta mal definida.

Perguntas frequentes

Avaliar a resposta final não basta?

Não quando a trajetória carrega risco. Um agente pode responder corretamente depois de consultar uma fonte proibida, usar argumentos errados ou receber ajuda humana. Avalie a resposta para o resultado visível e a trajetória para as ações que produziram esse resultado.

Toda trajetória precisa ter uma ordem esperada?

Não. Exija ordem quando uma etapa depende da anterior, como autorização antes de uma leitura protegida. Para leituras independentes, verifique tools permitidas, argumentos, proibições e estado final sem rejeitar uma ordem equivalente.

Um juiz de IA substitui as asserções do teste?

Não. Use código para verificar campos, tools, estado e regras de segurança. Um juiz pode ajudar com clareza, completude ou equivalência semântica, mas o seu resultado precisa de uma rubrica e de evidência revisável.

Posso avaliar sem usar um framework de agentes?

Sim. O conceito é um contrato sobre eventos observáveis, não uma marca de SDK. Você pode registrar chamadas no seu loop e aplicar asserções com o runner de testes que já usa. Bibliotecas e serviços ajudam a comparar trajetórias, mas não decidem quais ações são permitidas no seu domínio.

Conclusão

Um agente não passa só porque a última frase parece correta. Ele passa quando a execução respeita o contrato que você consegue explicar: escolheu as tools permitidas, enviou argumentos válidos, seguiu a ordem necessária, evitou ações proibidas e terminou no estado esperado.

Comece registrando uma trajetória pequena e sanitizada. Adicione asserções determinísticas antes de um juiz semântico. Depois, leve os casos que falharam para o CI e transforme incidentes em regressões. Assim, a suíte mede o que o agente fez, não apenas a história que ele contou no fim.

Como testar a trajetória de um agente de IA?