Avaliadores personalizados baseados em código no Amazon Bedrock AgentCore

Por que avaliação determinística importa em agentes de produção

Levar um agente de protótipo para produção exige medir qualidade em múltiplas dimensões. O Amazon Bedrock AgentCore Evaluations já oferecia verificações baseadas em Modelo de Linguagem Grande (LLM) no papel de juiz — o chamado LLM-as-a-Judge — para avaliar dimensões subjetivas como utilidade e coerência. Agora, a AWS amplia esse conjunto com os avaliadores personalizados baseados em código, que permitem capturar requisitos específicos de domínio com lógica determinística.

Em setores como serviços financeiros, a qualidade vai muito além da linguagem. Um agente de inteligência de mercado precisa citar preços de ações dentro de uma faixa configurável, seguir um fluxo obrigatório de identificação de corretores antes de acessar perfis financeiros, retornar saídas de ferramentas em um esquema Notação de Objeto JavaScript (JSON) estrito e não expor Informações de Identificação Pessoal (PII). Essas verificações precisam de código determinístico — que produza sempre o mesmo resultado para a mesma entrada — e seria caro ou impreciso delegá-las a um LLM.

Como os avaliadores baseados em código funcionam

Com os avaliadores personalizados baseados em código, a equipe traz uma função AWS Lambda como motor de avaliação. O controle sobre a lógica de pontuação é total: validação por expressões regulares (regex) e estrutural, consultas a dados externos, chamadas a outros serviços ou regras de negócio. O mesmo avaliador pode ser reutilizado em múltiplos contextos sem consumir tokens de um modelo de fundação (FM) a cada requisição.

No modo de avaliação sob demanda, o avaliador atua como uma barreira dentro de fluxos de desenvolvimento e pipelines de Integração Contínua e Entrega Contínua (CI/CD). No modo de avaliação online, ele pontua o tráfego de produção em tempo real. Com o controle total da lógica via Lambda, os avaliadores podem ser adaptados a qualquer necessidade e funcionam de forma consistente mesmo quando os rastros (traces) vêm de diferentes frameworks de agentes.

Ciclo de vida: de spans a resultados pontuados

Um avaliador baseado em código é uma função Lambda registrada no plano de controle do AgentCore. Quando uma avaliação é executada, o AgentCore assume uma função do Gerenciamento de Identidade e Acesso (IAM) na conta do usuário, invoca o Lambda com um payload contendo os spans OpenTelemetry (OTel) do agente e grava a resposta no Amazon CloudWatch Logs como resultado de avaliação.

O payload contém uma versão de esquema, ID do avaliador, nome do avaliador, nível de avaliação e um objeto de entrada com o array de spans OTel da sessão. Para avaliadores no nível de rastro (trace), um campo separado identifica o rastro específico a ser pontuado. Para avaliadores no nível de sessão, o AgentCore omite esse campo e o Lambda pontua a conversa completa.

A resposta do Lambda segue um contrato fixo. Em caso de sucesso, retorna um dicionário com um rótulo (por exemplo, PASS ou FAIL), uma pontuação numérica opcional entre 0,0 e 1,0, e uma string de explicação opcional. Em caso de falha, retorna um dicionário com código e mensagem de erro. O rótulo é obrigatório em toda resposta de sucesso. A pontuação e a explicação alimentam diretamente as métricas do CloudWatch e o painel de Observabilidade do AgentCore.

Cada avaliador opera em um de três níveis definidos no momento do registro: TRACE (por rastro de interação), TOOL_CALL (por chamada de ferramenta) ou SESSION (por sessão completa). Para usar o mesmo Lambda em múltiplos níveis, basta registrá-lo separadamente para cada nível apontando para a mesma função.

Modos de operação: sob demanda e online

O AgentCore Evaluations suporta avaliadores baseados em código em ambos os modos. Um único ID de avaliador serve para desenvolvimento, testes, barreiras de CI/CD e monitoramento contínuo de produção. O contrato do Lambda — incluindo payload, formato de resposta e configuração de IAM — permanece idêntico nos dois modos.

Avaliação sob demanda para desenvolvimento e CI/CD

A avaliação sob demanda se encaixa em três cenários principais:

• Iteração de desenvolvimento: capturar uma sessão, executar o conjunto de avaliadores, inspecionar pontuações e explicações por avaliador, e usar o feedback para guiar a próxima mudança no prompt, definições de ferramentas ou fluxo de memória.
• Testes de regressão: manter uma biblioteca de sessões representativas — incluindo sessões que revelaram falhas anteriormente — e executar o conjunto de avaliadores contra elas. Um avaliador que pontua abaixo do limite sinaliza uma regressão.
• Barreira de implantação em CI/CD: antes de promover uma nova versão do agente para produção, executar o conjunto de avaliadores contra sessões de smoke test e bloquear a implantação se um avaliador baseado em código falhar.

Uma única chamada sob demanda pode referenciar até 10 avaliadores, misturando tipos baseados em código e integrados. Para o agente de exemplo (Market Trends Agent), uma execução pré-implantação combina os avaliadores integrados de Utilidade e Correção com os quatro avaliadores baseados em código, confirmando qualidade de linguagem, integridade de contratos de ferramentas, precisão de preços, ordenação de fluxo de trabalho e segurança de PII em uma única passagem.

Avaliação online para monitoramento contínuo de produção

A avaliação online amostra continuamente o tráfego ao vivo do agente e o pontua contra os avaliadores configurados em uma agenda recorrente. Para configurá-la, é necessário criar uma configuração de avaliação online pelo plano de controle do AgentCore, especificando:

• Avaliadores: até 10 IDs de avaliadores, misturando tipos baseados em código e integrados.
• Fonte de dados: grupo de logs do CloudWatch e nome do serviço OTel para os spans do agente.
• Amostragem: percentual de sessões a avaliar (entre 0,01% e 100%).

A avaliação online é vinculada a um agente apontando diretamente para ele no AgentCore Runtime ou referenciando o grupo de logs do CloudWatch usado pelo agente. O AgentCore então agrupa os spans que representam uma conversa completa e executa a avaliação sobre elas. É possível ajustar o timeout de sessão para que o AgentCore saiba quando tratar uma sessão como concluída — esse timeout deve corresponder à duração típica das sessões do agente para evitar pontuar sessões ainda em andamento.

Cada pontuação de avaliador também aparece como uma métrica do CloudWatch no namespace Bedrock-AgentCore/Evaluations, identificada por nome do avaliador e ID de configuração. Isso permite construir dashboards que plotam validade de esquema, conformidade de fluxo de trabalho e limpeza de PII ao lado de Utilidade e Correção, oferecendo uma visão unificada de qualidade de linguagem e estrutural. Além disso, é possível configurar Alarmes do CloudWatch nessas métricas para alertar a equipe sempre que uma dimensão de qualidade cair abaixo de um limite importante.

Caso de uso: Market Trends Agent

A AWS usa como exemplo o Market Trends Agent, um assistente de inteligência de investimentos construído com LangGraph e implantado no Amazon Bedrock AgentCore Runtime. O código completo está disponível em 02-use-cases/market-trends-agent no repositório de exemplos do AgentCore.

O agente atende corretores financeiros com dados de ações, análise de notícias de múltiplas fontes e perfis de corretores armazenados no AgentCore Memory, adaptando análises à estratégia, interesses e tolerância a risco de cada corretor. A instrumentação OTel do LangGraph publica spans no Amazon CloudWatch através do AgentCore Observability, tornando o agente um ambiente de testes ideal para avaliadores baseados em código e LLM-as-a-Judge.

O exemplo inclui quatro avaliadores cobrindo validação de esquema, precisão numérica, conformidade de fluxo de trabalho e detecção de PII:

• ToolResponseSchemaValidator (nível de trace): filtra spans para o rastro alvo, identifica spans de chamada de ferramenta e verifica a resposta de cada ferramenta contra um padrão esperado — ticker e preço para dados de ações, comprimento e formatação para resumos de notícias.
• StockPriceDriftChecker (nível de trace): verifica preços citados nas respostas do agente contra uma fonte de verdade externa dentro de uma tolerância configurável (padrão de 2%). Extrai pares ticker-preço do texto da resposta, busca preços de referência em um endpoint de dados de mercado e calcula o desvio percentual por par.
• WorkflowContractGSR (nível de sessão): aplica um contrato de fluxo de trabalho de três etapas em toda a sessão: identificar o corretor, operar no perfil do corretor e depois chamar ferramentas de dados de mercado e notícias. O avaliador reconstrói a lista ordenada de chamadas de ferramentas a partir dos spans da sessão e verifica se cada etapa ocorreu na ordem correta.
• BrokerPIILeakChecker (nível de sessão): verifica cada resposta do agente em uma sessão em busca de PII usando a API Amazon Comprehend DetectPiiEntities. O Lambda classifica entidades detectadas em tipos de alto risco (CPF/SSN, cartão de pagamento, conta bancária, documento de identidade, credencial) e detalhes de contato de menor risco (nome, e-mail, telefone, endereço), aplicando limiares diferentes a cada categoria. PII de alto risco retorna FAIL; uso excessivo de PII de menor risco retorna pontuação parcial com contagens. Uma variante baseada em regex está incluída para ambientes que não podem depender do Comprehend.

Pré-requisitos e passos de implementação

O passo a passo leva cerca de 45 minutos e custa menos de US$ 5 em cobranças da AWS nas taxas de amostragem padrão. Para acompanhar, são necessários:

• Uma conta AWS com uma função IAM com acesso ao Amazon Bedrock AgentCore Runtime, Memory e Evaluations, AWS Lambda e Amazon CloudWatch.
• A Interface de Linha de Comando da AWS (AWS CLI) instalada e configurada com permissões para implantar recursos do AgentCore, funções Lambda, logs do CloudWatch e, opcionalmente, Amazon Comprehend.
• AgentCore Observability e CloudWatch Transaction Search habilitados, para que os spans OTel cheguem ao grupo de logs do runtime e ao grupo compartilhado aws/spans. O Transaction Search é uma adesão única no nível da conta — o AgentCore Evaluations não consegue amostrar spans sem ele.
• O repositório agentcore-samples clonado.

O código completo, incluindo o agente, os quatro Lambdas de avaliação e os scripts de implantação, está disponível no diretório do market trend agent. Os passos de implementação cobrem: implantar o Market Trends Agent, implantar os avaliadores, gerar tráfego de teste com quatro cenários integrados (fluxo de corretor feliz, corretor recorrente, isca de PII com CPF/SSN fabricado e conversa anônima), executar avaliação sob demanda e visualizar os resultados da avaliação online.

Se a configuração de avaliação não estiver produzindo resultados ou se houver erros ou pontuações vazias, a Habilidade de Diagnóstico de Avaliação do AgentCore pode ser usada para resolver o problema.

Boas práticas para avaliadores baseados em código

O ponto de partida é identificar as dimensões de qualidade determinísticas onde não há espaço para ambiguidade: restrições exatas de dados como IDs ou valores que devem corresponder a um formato específico, restrições estruturais como sequências obrigatórias de chamadas de ferramentas, e requisitos de conformidade incluindo políticas de PII ou regras regulatórias que precisam de aplicação comprovável. Os avaliadores LLM-as-a-Judge integrados ou personalizados continuam sendo a escolha certa para dimensões subjetivas como utilidade, tom, coerência e qualidade conversacional geral.

A tabela abaixo resume os níveis de avaliação disponíveis:

• TRACE: uma invocação Lambda por rastro, em paralelo — ideal para validação de esquema por resposta, verificações de precisão numérica e varredura de PII por resposta.
• TOOL_CALL: uma invocação Lambda por span correspondente — ideal para validar parâmetros de ferramentas e verificar frescor de recuperação.
• SESSION: uma invocação Lambda por sessão — ideal para verificações de ordenação de fluxo de trabalho, varreduras de PII em toda a sessão e avaliação de sucesso de objetivo.

A recomendação é validar o avaliador contra sessões reais conhecidas no modo sob demanda antes de promovê-lo para avaliação online. Isso confirma que ele detecta os problemas esperados com explicações claras e que integrações com sistemas externos — como detectores de PII ou motores de política — funcionam corretamente em termos de permissões e timeouts. Após essa validação, o avaliador pode ser incorporado ao pipeline de CI/CD como barreira de implantação e depois promovido ao monitoramento contínuo de produção.

Conclusão

Os avaliadores baseados em código estendem a cobertura do AgentCore para as dimensões de qualidade que exigem lógica determinística. No modo sob demanda, atuam como verificações de desenvolvimento e barreiras de implantação em CI/CD, retornando pontuações síncronas e explicações no nível de span. No modo online, o mesmo avaliador registrado pontua sessões de produção ao vivo ao lado dos avaliadores LLM-as-a-Judge integrados e emite resultados como métricas do CloudWatch.

Combinados com os avaliadores integrados, os avaliadores baseados em código movem a confiabilidade do agente do paradigma “parece correto” para o paradigma “verificado por contrato”. Como a lógica vive no Lambda da própria equipe, os verificadores podem evoluir conforme as regras de negócio mudam. Um único registro de avaliador serve para desenvolvimento local, barreiras de CI/CD e monitoramento contínuo de produção, oferecendo um sinal de qualidade consistente do protótipo até a escala.

Para começar, consulte a documentação do Amazon Bedrock AgentCore Evaluations, identifique as propriedades estruturais e de conformidade do seu agente que exigem verificações determinísticas, e implante os avaliadores de exemplo do repositório amazon-bedrock-agentcore-samples.

Fonte

Build custom code-based evaluators in Amazon Bedrock AgentCore (https://aws.amazon.com/blogs/machine-learning/build-custom-code-based-evaluators-in-amazon-bedrock-agentcore/)