Crie suítes de teste que evoluem com seu agente usando gerenciamento de datasets no Amazon Bedrock AgentCore

Por que datasets de teste importam para agentes de IA

Agentes de IA são, por natureza, não determinísticos. O mesmo input pode gerar respostas diferentes entre execuções, o que torna um único resultado de avaliação praticamente sem valor. Sem inputs estáveis como base, é impossível saber se uma pontuação melhorou porque o agente ficou melhor — ou simplesmente porque o modelo amostrou de forma diferente naquela rodada.

Mas estabilidade de inputs sozinha não resolve tudo. Um juiz baseado em Modelo de Linguagem Grande (LLM) consegue dizer se uma resposta parece útil. Ele não consegue dizer se o preço da ação está correto, se o fluxo de ferramentas rodou na ordem certa ou se Informações de Identificação Pessoal (PII) vazaram entre sessões. Para essas verificações, é preciso ter ground truth: a resposta esperada, a sequência de ferramentas necessária e as asserções que precisam ser verdadeiras independentemente de como a resposta foi formulada.

Sem ground truth, você está medindo a aparência de correção — não a correção em si. Datasets versionados resolvem os dois problemas ao mesmo tempo: mantêm os inputs estáveis para que as pontuações sejam comparáveis entre execuções, e carregam o ground truth que dá significado a essas pontuações.

Os dois laços de avaliação de agentes

A avaliação de agentes acontece em dois contextos distintos, e cada um tem necessidades específicas.

O laço interno é a mesa do desenvolvedor. Você invoca o agente, lê as pontuações, ajusta a descrição de uma ferramenta e invoca de novo. O ciclo dura minutos. O problema não é rodar avaliações — é que os casos de teste tendem a ser o que estava à mão: perguntas escritas semana passada ou uma sessão que você salvou por acaso. Quando uma pontuação melhora, você quer acreditar que o ajuste funcionou. Mas sem inputs estáveis por baixo, não há como saber se o agente melhorou ou se as perguntas ficaram mais fáceis.

O laço externo é o pipeline de Integração Contínua/Entrega Contínua (CI/CD). Antes de uma mudança ir para produção, algo precisa garantir que nada quebrou. A maioria das equipes tem esse portão. O que elas frequentemente não têm é um conjunto estável e versionado de inputs com asserções explícitas. Isso significa que o portão está testando o que alguém apontou por último — sem ground truth para checar. Um pipeline que aprova um build porque as perguntas mudaram não está capturando regressões, está deixando-as passar.

Um dataset versionado fecha essa lacuna. O desenvolvedor cuida das falhas no laço interno. No laço externo, uma versão publicada desse dataset vira o portão: imutável, com ground truth intacto, testando os mesmos cenários do sprint passado e do anterior.

Dois tipos de cenários de teste

Os Datasets no Amazon Bedrock AgentCore suportam dois tipos de schema que atendem a esses dois laços de forma diferente.

Cenários predefinidos

São retrospectivos. Você já sabe exatamente quais queries o usuário vai enviar e sabe como é uma resposta correta: a resposta esperada, a sequência de ferramentas e as asserções que precisam ser verdadeiras. Você os escreve, e o avaliador verifica se o agente os atendeu. Uma vez que uma falha é formalizada como cenário predefinido, ela aparece em todas as execuções de avaliação futuras. Eles pertencem ao portão do laço externo porque os critérios de aprovação e reprovação são explícitos, repetíveis e não dependem de como a conversa aconteceu.

Cenários de simulação de usuário

São prospectivos. Em vez de roteirizar turnos, você descreve uma persona: quem é o ator, o que ele quer alcançar e como ele se comunica. Um ator baseado em LLM conduz uma conversa real de múltiplos turnos com o agente até que o objetivo seja atingido ou o limite de turnos seja alcançado. Você não roteiriza o que o ator diz — a cobertura emerge da interação. Para mais detalhes, consulte a documentação de Simulação de Usuário no guia do AgentCore.

A diferença é fundamental: um cenário predefinido testa se o agente lida corretamente com um input específico. Um cenário simulado testa se o agente consegue satisfazer um tipo de usuário, qualquer que seja o caminho que esse usuário tome. A simulação é especialmente útil no laço interno, quando você ainda não sabe quais modos de falha ainda não foram descobertos. As falhas que surgem se tornam candidatas a cenários predefinidos na próxima versão do dataset.

O agente de exemplo: Market Trends Agent

Para ilustrar o fluxo completo, a AWS usa o Market Trends Agent, uma aplicação LangGraph implantada no AgentCore Runtime. O agente atende corretores de investimento em instituições financeiras. Um corretor envia algo como “Sou Sarah Chen da Morgan Stanley, focada em tech e energia limpa — o que está acontecendo com a NVDA hoje?” O agente identifica o corretor, armazena suas preferências na memória do AgentCore, recupera o preço atual da ação e busca notícias relevantes. Quando Sarah volta no dia seguinte, o agente lembra o perfil dela e personaliza a resposta.

As ferramentas disponíveis no agente são:

• get_stock_data — preço atual, variação diária e volume para um ticker.
• search_news — busca de notícias financeiras em múltiplas fontes (Bloomberg, Reuters, CNBC, WSJ, FT).
• identify_broker — extrai a identidade do corretor da mensagem para consulta na memória.
• get_broker_financial_profile — lê preferências armazenadas, tolerância a risco e foco setorial.
• update_broker_financial_interests — grava novas preferências na memória de longo prazo.

Três modos de falha recorrentes justificam casos de teste permanentes: preços defasados (o agente cita um número que derivou mais de 2% do valor ao vivo por reutilizar uma resposta de ferramenta em cache), verificação de identidade ignorada (o agente pula direto para get_broker_financial_profile sem chamar identify_broker primeiro, podendo entregar o perfil do corretor errado) e vazamento de PII (informações pessoais de um corretor aparecem na resposta de uma sessão diferente).

Exemplo de cenário predefinido

PreDefinedScenario{
    "scenario_id": "broker_profile_onboarding",
    "turns": [
        {
            "input": (
                "Hi, I'm Sarah Chen from Morgan Stanley. "
                "I focus on tech and clean energy. "
                "Risk tolerance: moderate-high. "
                "Client base: institutional and high-net-worth."
            )
        }
    ],
    "expected_trajectory": {"toolNames": ["identify_broker", "update_broker_financial_interests"]},
    "assertions": [
        "Agent identifies the broker by name and firm.",
        "Agent stores the broker's sector preferences and risk tolerance.",
        "Agent acknowledges receipt of the profile and offers to help.",
    ],
    "metadata": {"category": "onboarding", "priority": "high"},
}

Exemplo de cenário simulado

Um analista sênior de tecnologia simulado pode abrir com uma pergunta ampla sobre NVDA. Ele pressiona quando a resposta parece rasa, pede uma comparação com AMD e só sinaliza conclusão quando tem algo citável para uma ligação com cliente. Ninguém roteirizou esses turnos — o ator os gerou a partir do perfil.

SimulatedScenario(
    scenario_id="sim-tech-analyst-nvda-amd-deep-dive",
    scenario_description=(
        "A senior technology research analyst probes for a deep, citable NVDA vs AMD briefing ahead of a client call."
    ),
    actor_profile=ActorProfile(
        traits={
            "expertise": "senior",
            "focus": "semiconductors",
            "style": "skeptical and data-driven",
        },
        context=(
            "Senior sell-side technology analyst preparing talking points for a high-value client call. "
            "Expects multi-layered analysis, not surface-level summaries, and will push back when answers feel generic or thin."
        ),
        goal=(
            "Pressure-test the agent's semiconductor domain depth by asking about NVIDIA, then insisting on richer detail, "
            "requesting a structured comparison with AMD, and only concluding when she has citable points for a client conversation."
        ),
    ),
    input=(
        "I'm prepping for a client call and need a quick but solid briefing on NVIDIA. "
        "Start with NVDA's recent performance and positioning in semiconductors."
    ),
    max_turns=8,
    assertions=[
        "Agent provides an initial NVDA summary with recent performance and positioning",
        "Agent responds with deeper fundamentals, product/roadmap, or moat detail for NVDA",
        "Agent produces a structured NVDA vs AMD comparison (e.g., valuation, growth, segments)",
        "Agent includes specific, citable data points or metrics suitable for a client call"
    ],
)

Vale destacar como a simulação funciona internamente: o ator roda em um modelo do Bedrock especificado em SimulationConfig. A cada turno, o ator recebe a resposta do agente e produz três elementos — seu raciocínio interno sobre se o objetivo foi atingido, a próxima mensagem a enviar e um sinal de parada. A conversa termina quando o ator sinaliza conclusão, quando max_turns é atingido ou quando o ator não produz próxima mensagem. Como o caminho da conversa é dinâmico, cenários simulados não suportam expected_trajectory nem expected_response por turno — use asserções para o ground truth.

Como os datasets funcionam no AgentCore

Os datasets são recursos de primeira classe no AgentCore, com ARNs (Nomes de Recurso da Amazon), autorização via Gerenciamento de Identidade e Acesso (IAM) e tags. Não é necessário provisionar buckets no Amazon Simple Storage Service (Amazon S3) nem configurar serviços externos.

O fluxo de trabalho segue três princípios principais:

• Rascunho e publicação: cada dataset tem um rascunho mutável onde você adiciona e remove cenários livremente. Quando quiser um checkpoint estável, publique. O rascunho vira uma versão numerada imutável. Fixe uma execução de avaliação na Versão 3 e ela usará exatamente os cenários que estavam na Versão 3, independentemente do que você adicionou ao rascunho depois.
• Validação de schema na gravação: você declara o tipo de schema ao criar o dataset, e cada cenário é validado contra esse schema antes de ser aceito. Exemplos malformados são rejeitados na ingestão, e não no meio de uma execução de avaliação de 30 minutos.
• Um dataset, múltiplos executores: carregue um dataset com DatasetManagementServiceProvider e passe para o executor sob demanda (feedback rápido por cenário) ou para o executor em lote (pontuação agregada em muitas sessões). Os mesmos cenários, asserções e ID de dataset funcionam tanto na iteração local quanto no portão de deployment.

Passo a passo da implementação

O walkthrough completo leva cerca de 30 minutos. Os pré-requisitos são: uma conta AWS com permissões para AgentCore Runtime, Memory, Evaluations e Amazon CloudWatch; AWS Command Line Interface (AWS CLI) configurado; CloudWatch Transaction Search habilitado (opt-in único por conta); e o repositório de amostras clonado com o Market Trends Agent implantado via uv run python deploy.py. O código completo está disponível no repositório de amostras do AgentCore.

O fluxo de trabalho sugerido pela AWS segue estas etapas:

• Implantar o agente: execute uv run python deploy.py para provisionar o AgentCore Runtime, Memory, papel IAM e container ECR. O ARN do agente é gravado em .agent_arn.
• Criar e versionar os datasets: execute uv run python optimization/manage_dataset.py --no-cleanup para criar dois datasets e publicar uma versão imutável de cada. O dataset predefinido inclui cinco casos de teste roteirizados cobrindo os modos de falha principais. O dataset simulado inclui três cenários de persona de ator. O script também demonstra o fluxo de curadoria do dia a dia: adicionar novos exemplos, atualizar os existentes e excluir casos obsoletos antes de publicar.
• Executar a avaliação: execute uv run python optimization/user_simulated_dataset.py para carregar os cenários simulados, invocar o agente contra cada um e aguardar os spans chegarem no CloudWatch. O script então submete uma avaliação em lote com Correção, Utilidade e Taxa de Sucesso de Objetivo. Pontuações e explicações por cenário são impressas no console.
• Iterar — corrigir e reavaliar: atualize a descrição da ferramenta ou o prompt do sistema com base nas explicações da avaliação. Adicione o novo caso de borda ao rascunho com add_examples_and_wait(), publique uma nova versão com create_dataset_version_and_wait() e execute novamente. Como os cenários e asserções são idênticos entre execuções, a comparação antes/depois isola o efeito da sua mudança. Alternativamente, é possível usar as recomendações diretas do AgentCore via optimize_agent.py, que usa o avaliador como sinal e sugere melhorias no prompt do sistema e nas descrições de ferramentas.

Após concluir esses passos, o dataset persiste como recurso gerenciado na conta AWS. Jobs de avaliação futuros podem referenciar o mesmo ID de dataset e versão — seja disparados da máquina do desenvolvedor, de um pipeline CI/CD ou de uma verificação de regressão agendada.

Modos de uso: sob demanda vs. em lote

Use o executor sob demanda quando precisar de feedback imediato por cenário durante o desenvolvimento em datasets menores, gerenciando a concorrência você mesmo. Use o executor em lote para medir qualidade agregada em um dataset grande ou comparar duas versões do agente em escala.

Para portões de deployment, fixe a avaliação em uma versão publicada e reprove o build se qualquer avaliador cair abaixo do seu limiar. Como a versão é imutável, o portão testa os mesmos cenários em cada Pull Request, independentemente do que foi adicionado ao rascunho desde então.

O mesmo dataset versionado também alimenta a otimização do AgentCore. Quando você usa a API de Recomendações para gerar prompts de sistema ou descrições de ferramentas melhorados, as pontuações de avaliação que embasam essas decisões estão ancoradas no seu dataset. O mesmo vale para testes A/B que validam essas melhorias contra tráfego real. Inputs estáveis tornam o laço de otimização confiável, em vez de ser um efeito colateral de um conjunto de testes em constante mudança.

Boas práticas para adotar desde cedo

• Baseie a suíte em incidentes reais: os cenários que mais capturam problemas são os originados de falhas reais de produção. Perguntas inventadas testam falhas imaginárias.
• Use predefinidos para profundidade, simulados para amplitude: cenários predefinidos protegem os bugs já encontrados. Cenários simulados revelam os que ainda não foram. Um dataset saudável inclui os dois tipos.
• Publique uma versão antes de cada mudança: versões são imutáveis e não custam nada para manter. Quando você estiver depurando uma regressão de pontuação meses depois, vai querer saber exatamente quais cenários estavam em jogo em cada checkpoint.
• Um dataset, muitas versões: resista à tentação de criar um novo dataset a cada sprint. O valor está na continuidade. O mesmo ID de dataset acumula cada falha que o agente já teve, e cada avaliação futura herda esse histórico. Criar um novo dataset significa começar do zero.

Conclusão

Uma suíte de testes só é útil se permanecer estável. Quando os inputs mudam entre execuções, as pontuações medem a deriva do conjunto de testes — não a melhoria do agente. O gerenciamento de datasets no AgentCore entrega casos de teste versionados e validados por schema como recurso gerenciado. Falhas de produção viram cenários de regressão permanentes, personas simuladas geram cobertura que ninguém conseguiria roteirizar manualmente, e versões imutáveis permitem comparações honestas entre releases do agente.

O bug de preço que um corretor reportou no trimestre passado agora é um caso de teste. Cada mudança no prompt do sistema, cada atualização de descrição de ferramenta e cada troca de modelo é avaliada contra ele. A suíte acumula o conhecimento institucional sobre como o agente já falhou — e responsabiliza todas as versões futuras por essa história.

Para começar, consulte a documentação do Amazon Bedrock AgentCore e o exemplo do Market Trends Agent.

Fonte

Build a test suite that grows with your agent with dataset management in Amazon Bedrock AgentCore (https://aws.amazon.com/blogs/machine-learning/build-a-test-suite-that-grows-with-your-agent-with-dataset-management-in-amazon-bedrock-agentcore/)