Avalie agentes com skills usando Strands Evals e Amazon Bedrock AgentCore

O problema com agentes de propósito geral

Agentes de IA de propósito geral conseguem lidar com uma grande variedade de tarefas, mas ainda precisam seguir os procedimentos específicos de cada negócio: verificações de conformidade, fluxos de processamento de documentos, políticas de escalonamento, convenções de engenharia. Colocar tudo isso em um único prompt de sistema ou na lógica da aplicação rapidamente se torna difícil de manter e atualizar.

Skills surgem como uma alternativa modular. Uma skill é um conjunto reutilizável de instruções — geralmente armazenado em um arquivo SKILL.md — que ensina ao agente uma tarefa específica de domínio, como redigir um contrato, conciliar uma fatura ou seguir convenções de pull request de uma equipe. Por seguirem o padrão aberto Agent Skills, as skills são portáveis entre diferentes frameworks, e o agente carrega apenas a skill necessária em tempo de execução, sem precisar carregar todos os procedimentos em suas instruções principais.

Uma skill empacota um ou mais tools com o contexto que o agente precisa para usá-los corretamente:

Instructions: orientações e restrições específicas do domínio injetadas no contexto do agente.
Tool bindings: as APIs, servidores Protocolo de Contexto de Modelo (MCP) ou comandos locais dos quais a skill depende.
Knowledge: material de referência e exemplos práticos.
Workflow: o procedimento em múltiplas etapas ou a lógica de decisão que a skill segue.
Guardrails: requisitos de formato, limites de escopo e regras de validação.

Essa abordagem modular ajuda equipes a especializar agentes com mais rapidez, reutilizar procedimentos comprovados entre agentes e fluxos de trabalho, manter comportamentos consistentes e atualizar orientações específicas de domínio sem precisar fazer fine-tuning no modelo base nem reescrever a lógica central do agente.

Dois modos de falha que métricas comuns não detectam

A composição de skills em agentes introduz dois modos de falha que métricas gerais de qualidade de saída costumam deixar passar:

O agente invoca uma skill que não é adequada para a tarefa.
O agente invoca a skill correta, mas pula ou segue apenas parcialmente suas instruções.

Ambas as falhas podem produzir uma resposta fluente e plausível, mesmo sem ter utilizado o conhecimento de domínio pré-definido. Uma avaliação que examina apenas a resposta final, portanto, não é suficiente.

Para tornar essas falhas mensuráveis, o Strands Evals SDK e o Amazon Bedrock AgentCore Evaluations — uma capacidade do Amazon Bedrock AgentCore — adicionam avaliadores focados em skills:

Skill Selection Accuracy (Precisão de Seleção de Skill): determina se cada skill invocada foi uma escolha adequada para a tarefa. Retorna um resultado binário por skill invocada.
Skill Instruction Following (Seguimento de Instruções da Skill): determina com que completude o agente seguiu as instruções de uma skill invocada. Retorna uma classificação em cinco níveis, fundamentada em evidências, para cada etapa prescrita.
Skill Invoked (Skill Invocada): disponível apenas no Strands Evals, é uma verificação determinística de se uma skill nomeada foi carregada com sucesso.

O que cada avaliador mede na prática

Quando um agente recebe uma tarefa e um catálogo de skills, ele escolhe uma skill, carrega-a e age. Essa execução é registrada como uma trajetória no Strands Evals ou como um trace Telemetria Aberta (OpenTelemetry) na camada de observabilidade. Esse registro é o insumo para os três avaliadores.

O Skill Selection Accuracy verifica se cada skill invocada se encaixa na tarefa e se o agente invocou a skill correta. O template de prompt e o rubric desse avaliador estão disponíveis na documentação de templates de prompt.

O Skill Instruction Following pergunta com que completude o agente seguiu as etapas prescritas pela skill. O template e o rubric desse avaliador também estão disponíveis na documentação de templates de prompt.

O Skill Invoked é determinístico — não chama nenhum modelo e é exclusivo do Strands Evals.

Para ilustrar: considere um agente assistente de RH com skills para planejamento de Folga Remunerada (PTO) e para discussão de benefícios de funcionários. Um funcionário pergunta sobre seus benefícios odontológicos e de visão. Se o agente invocar a skill de benefícios, pode produzir uma resposta mais elaborada. Se a chamada de tool teve sucesso mas o agente escolheu o procedimento errado, o Skill Selection Accuracy isola essa decisão de roteamento.

Agora suponha que o agente invoque corretamente a skill de planejamento de PTO para uma solicitação relacionada. A skill instrui o agente a identificar o employee_id, verificar o saldo de PTO, checar as regras de rollover contra a política de RH mais recente e então submeter a solicitação se as condições permitirem. Se o agente verificar o saldo mas pular as regras de rollover, ainda pode retornar uma resposta plausível enquanto viola o processo prescrito. O Skill Instruction Following isola essa falha de execução e identifica a etapa pulada.

As falhas exigem correções diferentes. Uma seleção inadequada geralmente aponta para descrições de skills sobrepostas ou ambíguas. O seguimento incompleto de instruções pode exigir etapas mais claras, uma estrutura diferente de skill ou um modelo de agente mais capaz.

A tabela abaixo resume a disponibilidade e o escopo de cada avaliador:

Skill Selection Accuracy: disponível no Strands Evals e no AgentCore Evaluations — resultado binário por skill invocada — responde: “Invocar esta skill foi adequado para a tarefa?”
Skill Instruction Following: disponível no Strands Evals e no AgentCore Evaluations — cinco níveis por skill invocada — responde: “Com que completude o agente seguiu as etapas prescritas?”
Skill Invoked: disponível apenas no Strands Evals — resultado binário e determinístico — responde: “Esta skill nomeada foi carregada com sucesso?”

Como os avaliadores baseados em juiz retornam resultados por skill invocada, execuções com múltiplas skills permanecem diagnosticáveis: é possível identificar qual seleção ou resultado de seguimento de instruções reduziu o score agregado. Se nenhuma skill for invocada, os avaliadores baseados em juiz não produzem score — por isso é recomendável combiná-los com o Skill Invoked quando um teste de regressão tem um requisito de roteamento conhecido.

Pré-requisitos

Python 3.10 ou superior.
Uma conta AWS com acesso ao Amazon Bedrock e credenciais com permissão InvokeModel para o modelo juiz.

Para seguir a seção do Strands Evals, instale os SDKs:

pip install strands-agents-evals strands-agents

Também é necessário ter uma execução de agente registrada. Os avaliadores de skill aceitam tanto uma Session do Strands Evals quanto uma lista de mensagens brutas como trajetória. No lançamento, a extração de skills reconhece sinais do plugin Strands AgentSkills, Claude Code, Claude Agent SDK, OpenAI Agents SDK, Codex, Gemini CLI, OpenHands, Google ADK e leituras genéricas de arquivos SKILL.md.

Para seguir a seção do AgentCore Evaluations, é necessário:

Um agente hospedado no runtime do Amazon Bedrock AgentCore ou em outro ambiente. O artigo usa o exemplo do agente assistente de RH, que pode ser implantado em sua própria conta.
Observabilidade habilitada para o agente, de forma que ele entregue telemetria ao Amazon CloudWatch.
Transaction Search habilitado no CloudWatch.

Os exemplos usam a Interface de Linha de Comando (CLI) do AgentCore:

npm install -g @aws/agentcore

Avaliando uma trajetória registrada com o Strands Evals

O Strands Evals é útil quando se tem controle sobre os casos de teste e é possível reexecutar o agente durante o desenvolvimento ou em integração contínua. Confira o código de exemplo completo criado para o agente assistente de RH.

1. Defina o caso e os avaliadores

from strands_evals import Case, Experiment
from strands_evals.evaluators import (
    SkillInstructionFollowingEvaluator,
    SkillInvoked,
    SkillSelectionAccuracyEvaluator,
)

case = Case(
    name="q3-revenue-tables",
    input="Summarize the revenue tables in q3-report.pdf",
)

evaluators = [
    SkillSelectionAccuracyEvaluator(),
    SkillInstructionFollowingEvaluator(),
    SkillInvoked(skill_name="pdf-table-extraction"),
]

2. Execute o agente e capture sua trajetória

Os avaliadores de skill leem a trajetória da execução. O TracedHandler coleta os spans do agente e os anexa como trajetória:

from strands import Agent
from strands_evals import TracedHandler, eval_task

@eval_task(TracedHandler())
def task_function():
    return Agent(...)  # your skill-equipped agent

experiment = Experiment(cases=[case], evaluators=evaluators)
report = experiment.run_evaluations(task_function)
report.run_display()

3. Interprete o relatório

Suponha que o agente tenha carregado a skill pdf-table-extraction, executado pdftotext -layout, mas nunca aberto o arquivo extraído nem localizado os limites das tabelas. Um relatório simplificado seria:

SkillSelectionAccuracyEvaluator: score=1.00, pass=True
  pdf-table-extraction: The skill directly matches the request.

SkillInstructionFollowingEvaluator: score=0.50, pass=False
  pdf-table-extraction: The extraction phase was completed, the table-boundary phase was skipped.
  Steps:
    - Extract text with layout preservation: covered
    - Locate table boundaries: skipped
    - Summarize each table's headline figure: partial

SkillInvoked: score=1.00, pass=True
  skill 'pdf-table-extraction' was invoked

O Skill Instruction Following usa cinco classificações: Totalmente Seguido (1.0), Majoritariamente Seguido (0.75), Parcialmente Seguido (0.5), Minimamente Seguido (0.25) e Não Seguido (0.0). A aprovação ocorre em Majoritariamente Seguido ou melhor.

Para transformar as verificações em uma porta de implantação, adicione o SkillInvoked para cada skill crítica que um caso de regressão específico deve invocar. Por não chamar um modelo, é uma asserção de roteamento rápida. Bloqueie o build com report.test_passes: se not all(report.test_passes), lance SystemExit(1). Use scores agregados para acompanhar tendências mais amplas, mas calibre o limiar nos seus próprios casos antes de aplicá-lo.

Avaliando traces de produção com o AgentCore Evaluations

O AgentCore Evaluations trabalha diretamente com traces OpenTelemetry existentes, suportando avaliação sob demanda, processamento em lote de sessões armazenadas e amostragem contínua de tráfego ao vivo.

A telemetria é organizada em sessões, traces e spans. Como os avaliadores de skill operam no nível de chamada de tool, cada resultado inclui um spanContext com o sessionId, traceId e spanId da invocação de skill reconhecida. Uma invocação de skill é reconhecida por meio de uma leitura de sistema de arquivos de SKILL.md — que funciona entre frameworks — ou de um tool nativo de carregamento de skill no Strands Agents, LangGraph Deep Agents, Google ADK ou Claude Agent SDK.

Templates de trace para avaliadores customizados

O AgentCore Evaluations inclui dois avaliadores baseados em juiz para skills. Para avaliar algo que os avaliadores embutidos não cobrem, é possível criar um avaliador customizado no nível TOOL_CALL. Templates nesse nível podem referenciar placeholders de skill:

{invoked_skill} — nome da skill carregada nesta chamada de tool.
{skill_content} — o conteúdo do arquivo SKILL.md carregado.
{available_skills} — o catálogo oferecido em tempo de execução, ou “(not recorded by this harness)”.
{user_message} — a solicitação que disparou a invocação.
{context} — o registro da conversa.

Por exemplo, um template que verifica uma propriedade específica de uma execução de skill:

## Skill instructions
{skill_content}

## Conversation record
{context}

## Evaluation Question
Did the agent complete every numbered step in the skill instructions above, in the order given?
Answer Yes or No.

Os placeholders referenciados também determinam quando o avaliador é executado. Um template contendo {invoked_skill} roda apenas em spans de invocação de skill; um contendo {skill_content} requer adicionalmente o corpo carregado.

Avaliação sob demanda

Use a avaliação sob demanda para investigar uma sessão, validar uma mudança recente ou avaliar tráfego em staging:

agentcore run eval \
  --runtime <skill-runtime> \
  --evaluator Builtin.SkillSelectionAccuracy Builtin.SkillInstructionFollowing \
  --session-id <session-id>

Avaliação em lote

Use a avaliação em lote para pontuar muitas sessões armazenadas de uma vez — por exemplo, para estabelecer uma linha de base antes de uma mudança no catálogo de skills:

agentcore run batch-evaluation \
  --runtime <skill-runtime> \
  --evaluator Builtin.SkillSelectionAccuracy Builtin.SkillInstructionFollowing

Avaliação online contínua

A avaliação online amostra o tráfego ao vivo para detectar comportamentos que um conjunto de testes curado não antecipou:

agentcore add online-eval \
  --name HRSkillsProductionEval \
  --runtime <skill-runtime> \
  --evaluator Builtin.SkillSelectionAccuracy Builtin.SkillInstructionFollowing \
  --sampling-rate 100 \
  --enable-on-create

Em seguida, implante para provisionar a configuração de avaliação online:

agentcore deploy

A avaliação contínua é particularmente útil para detectar deriva de catálogo (quando uma nova skill se sobrepõe a uma descrição existente), formulações não antecipadas (quando solicitações reais diferem dos prompts de teste curados) e falhas em sessões longas (quando o seguimento de instruções se degrada conforme o contexto cresce).

Boas práticas

O ponto central ao avaliar skills de agentes é reconhecer que roteamento e execução são dois modos de falha distintos, e a estratégia de avaliação precisa separá-los claramente. Um score de seleção alto com score de seguimento de instruções baixo indica que o roteador escolheu a skill correta, mas ela não foi completamente executada. O padrão oposto significa que a skill funcionaria bem se apenas tivesse sido invocada. Executar essas duas avaliações juntas — em vez de colapsar tudo em um único pass/fail — é o que permite distinguir essas duas situações.

Antes de construir qualquer coisa customizada, comece com os avaliadores embutidos para estabelecer uma linha de base. Para requisitos onde o comportamento de roteamento correto já é conhecido, não dependa de um modelo juiz — adicione uma asserção determinística com SkillInvoked para cada skill que deve ser disparada.

Após executar as avaliações, resista ao impulso de olhar apenas para o score agregado. As evidências por etapa são onde o diagnóstico real acontece: elas indicam se uma instrução foi totalmente coberta, parcialmente completada ou pulada, e esse nível de detalhe é o que transforma uma avaliação com falha em uma correção acionável.

Avalie em todas as etapas do ciclo de vida, em vez de esperar pela saída final. Uma falha no final não informa se o roteador enviou a solicitação para o lugar errado ou se a skill correta foi executada de forma inadequada — ambos os sinais são necessários para saber o que corrigir.

Escreva descrições de skills genuinamente discriminativas para reduzir ambiguidade. Evite skills que lidem com seis funções não relacionadas — uma skill com escopo muito amplo não tem uma única definição de comportamento correto, o que torna a avaliação consistente quase impossível. Deixe claro que apenas o caminho efetivamente percorrido em uma execução deve ser avaliado; caso contrário, ramificações não tomadas são contadas incorretamente como etapas puladas e corrompem silenciosamente as taxas de aprovação.

Antes de confiar em qualquer score, valide que o pipeline de extração está funcionando corretamente contra traces reais. Ao escalar isso entre tools, os limiares podem não se transferir de forma limpa — cada superfície de avaliação precisa ser calibrada em seus próprios termos, pois um score de aprovação no Strands Evals e um no AgentCore Evaluations não garantem significar a mesma coisa.

Por fim, nada disso deve existir fora do pipeline de implantação. Regressões na qualidade de skills precisam bloquear um release da mesma forma que um teste unitário com falha faria.

Conclusão

Skills tornam agentes mais baratos de especializar, mas uma resposta final plausível não prova que o agente selecionou o procedimento correto ou o seguiu adequadamente. O Skill Selection Accuracy e o Skill Instruction Following separam esses modos de falha e retornam evidências para cada skill invocada. No Strands Evals, o SkillInvoked adiciona uma guarda determinística para requisitos de roteamento conhecidos. No AgentCore Evaluations, as duas métricas baseadas em juiz podem rodar sob demanda para uma sessão específica, em lote sobre sessões armazenadas ou continuamente sobre tráfego amostrado.

Use o Strands Evals quando houver casos de teste e trajetórias registradas que possam ser reexecutadas. Use o AgentCore Evaluations quando quiser avaliar traces OpenTelemetry de agentes em staging ou em produção. Muitas equipes usarão ambos: portas determinísticas e baseadas em juiz antes da implantação, seguidas de monitoramento baseado em traces em produção.

Para começar

Fonte

Evaluate skill-equipped agents with Strands Evals and Amazon Bedrock AgentCore (https://aws.amazon.com/blogs/machine-learning/evaluate-skill-equipped-agents-with-strands-evals-and-amazon-bedrock-agentcore/)