Google mostra como o Agents CLI pega regressão de agentes de IA antes da produção

O problema que lint e teste unitário não pegam

Um agente que funciona na demo e um agente que continua funcionando depois de trocas de modelo, mudança de ferramenta e novos formatos de conversa são dois problemas diferentes. O primeiro leva um fim de semana. O segundo leva um loop: escrever casos de teste, rodar, pontuar, ler o que falhou, mudar o agente, rodar de novo. Se a nota sobe, a mudança foi boa. Se cai, reverte.

Pier Paolo Ippolito e Elia Secchi, do Google, publicaram em 28 de outubro de 2026 no Google Developers Blog um walkthrough completo desse ciclo usando o namespace eval do Agents CLI. O nome técnico para esse processo de subir a nota aos poucos é hill-climbing, e o valor do texto está nos números reais que eles mostram em cada etapa, inclusive quando a mudança piora o agente.

Os cinco comandos do namespace eval

O eval do Agents CLI é pequeno e agnóstico de framework:

• eval generate: roda o agente contra um dataset de casos e grava os traces
• eval grade: pontua os traces gerados usando as métricas configuradas
• eval compare: faz o diff estruturado entre dois resultados
• eval analyze: agrupa falhas em temas
• eval optimize: roda um passe automatizado de hill-climbing no prompt

Montando o projeto e o dataset

O scaffold usado no walkthrough é o template LangChain que acompanha o Agents CLI v1.8.0:

agents-cli create my-agent \
--agent google/agents-cli/extensions/langchain/template@v1.8.0 \
-d cloud_run
cd my-agent && agents-cli install

O projeto já vem com um dataset em tests/eval/datasets/basic-dataset.json, um config em tests/eval/eval_config.yaml e uma métrica LLM↳LLMs48 conteúdosConsiderações básicas de hardware para modelos de linguagem em código aberto: Memória, Desempenho e ViabilidadeMarketing Tech · out 2025Modelos de linguagem sob ataque: o lado obscuro da IA generativaDevSecOps · mai 2025Criando um LLM – modelo de linguagem de grande escala – do zero com TransformersAI · abr 2024Ver tudo em AI →-as-judge em tests/eval/response_quality.py, que nota cada resposta de 1 a 5 em precisão, relevância e clareza usando gemini-3.8-flash como juiz. O dataset padrão tem um único caso trivial, insuficiente para um hill-climb real.

O time expandiu para quatro: uma saudação, uma pergunta de clima que a ferramenta mock responde com um valor fixo, uma pergunta de clima para outra cidade e uma pergunta fora de escopo (quem ganhou a World Series de 2024). Dataset pequeno de propósito: o loop só compensa quando roda em toda mudança, não quando vira um gate de release de uma hora.

A primeira rodada (baseline)

Com o dataset pronto, eval generate roda o agente contra os quatro casos e eval grade pontua os traces resultantes. O resultado da primeira rodada: média 4,0 de 5, desvio padrão 1,4142. Esse desvio importa: uma nota 5,0 uniforme em todos os casos significaria agente perfeito (improvável) ou dataset fácil demais para mostrar variação. 4,0 com dispersão real é uma colina que vale subir.

Injetando uma regressão de propósito

Para demonstrar o loop, o time simulou um erro comum: um dev que trabalha em vários agentes cola o system prompt errado, de um projeto de receitas, no agente de clima.

# Antes
system_prompt="You are a helpful assistant"

# Depois
system_prompt=(
 "You are a professional chef. Help users with recipes, cooking "
 "techniques, and ingredient substitutions. Always suggest a recipe "
 "at the end of every response."
)

O código compila, o agente continua rodando, e nada no pipeline de lint, teste unitário ou checagem de tipo pega o problema. Rodando eval generate e eval grade de novo: média 2,75, desvio padrão 0,9574. Uma queda de 1,25 ponto numa escala de 1 a 5 é o tipo de regressão que passa batido num code review onde o diff parece pequeno ("só uma string mudou").

Onde a regressão bateu, caso a caso

A média isolada avisa que algo piorou; eval compare mostra onde. O comando lê dois arquivos de resultado e devolve um diff estruturado em JSON com as chaves que mudaram e a comparação por caso.

O caso mais sério é sf_weather: a persona de chef desviou a atenção do modelo da ferramenta registrada get_weather, e o agente parou de chamá-la. Nenhum teste unitário pega isso, porque o código roda e a ferramenta continua registrada; só uma avaliação ponta a ponta que julga a resposta em contexto revela que o comportamento do modelo mudou.

Trocar de modelo é mais barato, mas vale a pena?

Uma dúvida comum de hill-climbing é se um modelo mais barato entrega qualidade aceitável. O walkthrough trocou gemini-3.8-flash por gemini-2.5-flash (restaurando o system prompt correto antes) e comparou os resultados.

A média caiu de 4,0 para 2,75, a mesma magnitude da regressão do chef, mas por um motivo completamente diferente: o modelo mais barato empatou em dois casos e desabou só em off_topic, recusando responder com uma ressalva sobre o evento "ainda não ter acontecido" (um artefato do corte de treinamento), o que o juiz penalizou com força. Olhar só a média levaria a descartar gemini-2.5-flash como se fosse tão ruim quanto o prompt quebrado; olhar o detalhe por caso mostra uma troca razoável para a maior parte da carga, com uma limitação pontual em perguntas fora de escopo sobre eventos recentes.

Dois cuidados aqui, segundo o próprio texto do Google: um prompt afinado para um modelo mais forte costuma vazar capacidade quando portado para um mais fraco, então a comparação correta é "modelo fraco com prompt próprio" contra "modelo forte com prompt próprio". E o modelo juiz (que faz a nota) precisa ficar constante entre as duas rodadas; trocar o juiz é outro experimento.

Agendando o loop e disparando alerta

O Agents CLI não vem com um scheduler embutido, mas os comandos de eval são feitos para entrar em infraestrutura padrão: um cron job ou Cloud Scheduler rodando eval generate e eval grade todo dia contra um dataset de regressão maior (dezenas a centenas de casos, já que roda só uma vez ao dia), salvando o resultado numa pasta com a data.

Um arquivo de resultado que ninguém olha não é um alerta. O padrão sugerido é um script que compara a média da rodada nova contra um baseline e sai com código de erro quando a queda passa de um limiar:

b, c = mean(args.baseline), mean(args.candidate)
drop = b - c
if drop > args.threshold:
 print(f"FAIL: mean dropped {b:.3f} → {c:.3f}")
 sys.exit(1)
print(f"OK: mean {b:.3f} → {c:.3f}")

Rodado contra o par baseline 4,0 / candidato 2,75 da regressão do chef, com limiar de 0,1, o script imprime FAIL: mean dropped 4.000 → 2.750 e sai com código 1; contra dois resultados idênticos, sai com OK e código 0. É esse código de saída que um GitHub Actions, cron ou Cloud Scheduler usa para disparar o alerta.

Otimização automática de prompt com GEPA

Para projetos ADK (não para a extensão LangChain usada no resto do walkthrough), eval optimize roda um passe de hill-climbing automatizado usando o framework GEPA: propõe variantes de prompt, pontua cada uma, mantém as que melhoram a métrica e itera. O comando é escopado só ao prompt, não a ferramentas, estrutura ou modelo do agente.

O próprio Google alerta que o GEPA às vezes encontra melhorias genuínas e às vezes encontra variantes que pontuam mais alto por overfitting na métrica específica. A disciplina recomendada é rodar eval optimize no dataset de regressão, onde a melhoria é mensurável, e revisar cada candidato antes de promovê-lo para o agente.

O que muda pra quem constrói agente aqui

Um dado do texto merece atenção especial: um estudo controlado do próprio Google achou que agentes de código usando o Agents CLI rodam quatro vezes mais avaliações que agentes sem ele, mas mudam o agente depois de uma avaliação com a mesma frequência do baseline. Ou seja, o ganho de comportamento vem do que entra no build desde o início, não do volume de iteração interna.

Em resumo: evaluation é necessária, mas não suficiente; a qualidade vem de agir no que a avaliação mostra, não de rodar mais vezes. Para quem constrói agente no Brasil, as lições práticas do walkthrough valem mais que o anúncio em si: dataset pequeno que roda em todo commit bate dataset gigante que vira shelfware, o arquivo de resultado completo é a evidência (não só a média), dataset e config de expectativa devem ficar em arquivos separados versionados, e a média sozinha mente, como mostrou a troca de modelo.

Quem quiser reproduzir o loop começa com uvx google-agents-cli setup e agents-cli create my-agent; a documentação completa do namespace eval está em google.github.io/agents-cli/cli e o código-fonte em github.com/google/agents-cli.

Fonte: Google Developers Blog