Design Doc: Suíte de Avaliação Contínua para Agentes com Bedrock AgentCore

Agentes LLM não são funções determinísticas. Eles combinam um modelo de linguagem (que pode ser atualizado pelo provedor sem aviso explícito), um conjunto de ferramentas com suas próprias APIs e schemas, memória de curto e longo prazo, e uma camada de orquestração que interpreta intenção e encadeia chamadas. Cada um desses componentes pode mudar independentemente, e a interação entre mudanças é onde as regressões mais perigosas se escondem.

Considere um cenário concreto: o agente de suporte ao cliente de uma fintech usa uma ferramenta get_account_balance que retorna valores em centavos. O time de backend migra a API para retornar valores em reais sem atualizar a documentação da ferramenta. O agente continua funcionando, ele chama a ferramenta, recebe um número, e responde ao usuário. Mas agora informa saldos 100x maiores do que o real. Nenhum erro de runtime. Nenhum alarme de latência. A degradação é semântica, não técnica.

Esse é o problema central que uma suíte de avaliação contínua precisa resolver: detectar degradação semântica e comportamental antes que chegue ao usuário, em um sistema onde as peças mudam de forma assíncrona e os erros raramente são exceções, são respostas plausíveis mas incorretas.

O estado da arte em avaliação de agentes ainda está se consolidando. A maioria das equipes que conheço opera com uma combinação de: testes manuais ad hoc antes de releases, algumas métricas de satisfação do usuário coletadas de forma reativa, e alarmes de latência/erro que capturam apenas falhas técnicas. Isso é insuficiente para sistemas que tomam decisões com consequências reais. O que precisamos é de uma disciplina análoga ao que temos em sistemas de software tradicionais, testes unitários, integração, regressão, cobertura, mas adaptada para a natureza probabilística e composicional dos agentes.

A arquitetura que proponho organiza a avaliação em três camadas complementares, cada uma com propósito, frequência e custo distintos. A metáfora útil aqui é a de defesa em profundidade, nenhuma camada sozinha é suficiente, mas juntas formam uma rede de detecção robusta.

Camada 1: Avaliação Offline (Pre-Deploy Gate)

Antes de qualquer versão do agente ser promovida para produção, ela passa por uma bateria de testes offline contra um dataset versionado armazenado no S3. O dataset é estruturado como um conjunto de casos de teste, cada um contendo: a entrada do usuário (ou sequência de turnos para conversas multi-turn), o conjunto esperado de chamadas de ferramenta (com argumentos esperados e tolerâncias), a resposta esperada (ou critérios de avaliação quando não há resposta determinística), e metadados de categoria (tipo de tarefa, nível de dificuldade, se é adversarial).

O Bedrock AgentCore executa o agente em modo de avaliação, com as mesmas ferramentas configuradas, mas em ambiente isolado com ferramentas mockadas que retornam respostas controladas. Isso é crítico: você não quer que testes offline façam chamadas reais a APIs de produção, mas também não quer mocks tão simplificados que não testam o raciocínio do agente sobre as respostas das ferramentas.

As métricas coletadas nessa camada incluem: tool-call accuracy (o agente chamou a ferramenta certa?), argument fidelity (os argumentos estavam corretos dentro de tolerância?), call sequence correctness (para tarefas que requerem sequência específica de chamadas), unnecessary tool calls (o agente chamou ferramentas desnecessárias, indicando raciocínio confuso?), e final response quality avaliada por um LLM-as-judge configurado via Bedrock Evaluations.

O quality gate é definido como um conjunto de thresholds por categoria de métrica. A proposta inicial: tool-call accuracy ≥ 0.90 no conjunto completo, ≥ 0.95 no subconjunto de casos críticos (marcados no dataset), e nenhuma regressão > 5 pontos percentuais em relação à baseline da versão anterior. Esse último critério, regressão relativa, é tão importante quanto o threshold absoluto: um agente que já era ruim em algo não deve piorar ainda mais.

Camada 2: Testes Adversariais

Separados do dataset de avaliação padrão, mantemos um dataset adversarial com categorias específicas: prompt injection attempts (tentativas de fazer o agente ignorar suas instruções de sistema), boundary probing (inputs que testam os limites de políticas, o que o agente faz quando recebe um pedido ambíguo que poderia ser legítimo ou malicioso?), e casos de edge de tool-use (o que acontece quando uma ferramenta retorna um erro inesperado? O agente recupera graciosamente ou entra em loop?).

Esses testes não têm o mesmo regime de pass/fail dos testes funcionais, eles têm critérios de comportamento esperado. Para prompt injection, o critério é que o agente mantenha suas instruções de sistema. Para boundary cases, o critério é que o agente escalona ou recusa de forma apropriada em vez de aluciná-la resposta. Para erros de ferramenta, o critério é recuperação em no máximo N tentativas com fallback gracioso.

Camada 3: Sinais Online (Production Monitoring)

Em produção, instrumentamos um pipeline de avaliação assíncrono que processa uma amostra das conversas reais. O sampling é estratificado, garantimos representação de diferentes tipos de tarefa e não apenas volume. Conversas selecionadas são enviadas para um Step Functions workflow que: extrai os traces de tool-use do AgentCore, executa avaliação LLM-as-judge nos turnos finais, e persiste métricas no CloudWatch com dimensões por versão de agente, tipo de tarefa e ferramenta.

Além do sampling, monitoramos sinais proxy que não requerem avaliação LLM: taxa de conversas que atingem o limite máximo de turnos (indica agente preso em loop), taxa de tool errors não recuperados, taxa de escalação para humano (se aplicável), e distribuição de latência por ferramenta (mudanças de latência podem indicar mudanças de comportamento de chamada).

Um dos aspectos mais negligenciados em sistemas de avaliação de agentes é o gerenciamento do próprio dataset de avaliação. Times constroem um conjunto inicial de casos de teste, executam por meses, e nunca revisam, enquanto o agente evolui para lidar com casos de uso completamente novos que não estão representados. O dataset envelhece e perde poder discriminativo.

A proposta aqui é tratar o dataset de avaliação com a mesma disciplina que tratamos o código: versionamento explícito, changelog, e um processo de curadoria contínua.

Estrutura de versionamento: Cada versão do dataset é um artefato imutável no S3, identificado por um hash de conteúdo e um número de versão semântico (major.minor.patch). O DynamoDB mantém o registry com metadados: data de criação, autor, changelog, cobertura por categoria de tarefa, e a versão do agente contra a qual foi validado. O quality gate sempre executa contra a versão do dataset especificada no manifesto do agente, não contra "latest". Isso é deliberado: garante reprodutibilidade e evita que um dataset novo quebre um agente que estava funcionando bem.

Processo de curadoria: Novos casos de teste entram no dataset por três caminhos. O primeiro é curadoria manual, engenheiros ou especialistas de domínio escrevem casos baseados em requisitos. O segundo é mineração de produção, conversas reais que foram marcadas como problemáticas (via feedback do usuário, escalação, ou detecção automática) são revisadas e convertidas em casos de teste. Esse é o caminho mais valioso: são falhas reais, não hipotéticas. O terceiro é geração sintética, usando um LLM para gerar variações de casos existentes, especialmente para aumentar cobertura de edge cases e cenários adversariais.

O problema do dataset drift: À medida que o agente melhora, casos que antes eram difíceis se tornam triviais. Um dataset que não é atualizado perde poder discriminativo, o agente passa em tudo, mas isso não significa que está funcionando bem em casos novos. A solução é monitorar a distribuição de scores do dataset ao longo do tempo: se a maioria dos casos está com score próximo de 1.0, é hora de adicionar casos mais difíceis. Isso é análogo ao problema de benchmark saturation em ML, quando um modelo atinge performance humana em um benchmark, o benchmark precisa ser substituído, não o modelo declarado perfeito.

Cobertura de tool-use: Para agentes com múltiplas ferramentas, o dataset precisa garantir cobertura adequada de cada ferramenta e de combinações de ferramentas. Mantemos um mapa de cobertura que mostra, para cada ferramenta, quantos casos de teste a exercitam, em quais contextos, e com quais padrões de argumento. Ferramentas novas adicionadas ao agente devem ter cobertura mínima antes de o agente poder ser promovido, essa é uma regra de quality gate adicional.