Execute um A/B teste com pacotes de configuração

Use o padrão do pacote de configuração quando a alteração que você estiver testando for puramente de configuração — um prompt de sistema diferente, um ID de modelo diferente ou descrições de ferramentas diferentes. Ambas as variantes são executadas no mesmo AgentCore Runtime com diferentes versões do pacote de configuração. O AgentCore Gateway injeta a referência correta do pacote em cada solicitação por meio dos cabeçalhos de bagagem do W3C, e seu agente a lê em tempo de execução. Isso significa que você implanta um AgentCore Runtime e uma configuração de avaliação on-line.

Configuração chave para A/B testes do pacote de configuração:

Se a alteração que você está testando envolver alterações de código, uma atualização da estrutura ou uma implementação de agente totalmente diferente, use o roteamento baseado em destinos. Consulte Executar um A/B teste com roteamento baseado em metas.

Este passo a passo usa um agente de suporte ao cliente como exemplo. O agente lida com pesquisas de pedidos, devoluções e solicitações de descontos. Você implantará o agente, criará dois pacotes de configuração com solicitações de sistema diferentes (controle e tratamento), criará um A/B teste, enviará tráfego, analisará os resultados e implantará o vencedor.

Etapa 1: criar o projeto

Crie o projeto com a AgentCore CLI:

agentcore create --name ABTestConfigBased --no-agent
cd ABTestConfigBased

Etapa 2: adicionar o tempo de execução

Adicione o tempo de execução do agente:

agentcore add agent \
  --name csAgent \
  --language Python \
  --framework Strands \
  --model-provider Bedrock \
  --memory none \
  --build CodeZip

Estrutura do projeto:

ABTestConfigBased/
├── agentcore/
│   ├── agentcore.json      # Project and resource configuration
│   ├── aws-targets.json    # Deployment target (account and region)
│   └── cdk/                # CDK infrastructure (auto-managed)
└── app/
    └── csAgent/
        ├── main.py         # Agent entrypoint
        └── pyproject.toml  # Python dependencies

Etapa 3: atualizar o código do agente e implantar

app/csAgent/main.pySubstitua pelo seguinte. A principal adição é o BeforeModelCallEvent gancho que lê o pacote de configuração ativo em tempo de execução:

"""Customer support agent with configuration bundle integration."""
from strands import Agent, tool
from strands.models.bedrock import BedrockModel
from strands.hooks.events import BeforeModelCallEvent
from bedrock_agentcore.runtime import BedrockAgentCoreApp, BedrockAgentCoreContext

app = BedrockAgentCoreApp()
DEFAULT_MODEL_ID = "global.anthropic.claude-sonnet-4-5-20250929-v1:0"
DEFAULT_SYSTEM_PROMPT = "You are a helpful customer support assistant."


@tool
def lookup_order(order_id: str) -> str:
    """Look up an order by ID."""
    orders = {
        "ORD-1001": {"status": "delivered", "item": "Blue T-Shirt", "total": "$29.99"},
        "ORD-1002": {"status": "in_transit", "item": "Running Shoes", "est_delivery": "2026-04-05"},
        "ORD-1003": {"status": "delayed", "item": "Wireless Headphones", "days_late": 5},
    }
    return str(orders.get(order_id, {"error": f"Order {order_id} not found"}))


@tool
def initiate_return(order_id: str, reason: str) -> str:
    """Initiate a return for an order."""
    return f"Return initiated for {order_id}. Reason: {reason}. Return label sent to customer email."


@tool
def apply_discount(order_id: str, discount_percent: int, reason: str) -> str:
    """Apply a discount to an order."""
    return f"Applied {discount_percent}% discount to {order_id}. Reason: {reason}."


def dynamic_config_hook(event: BeforeModelCallEvent):
    """Read config bundle and apply system prompt before every model call."""
    config = BedrockAgentCoreContext.get_config_bundle()
    event.agent.system_prompt = config.get("system_prompt", DEFAULT_SYSTEM_PROMPT)


agent = Agent(
    model=BedrockModel(model_id=DEFAULT_MODEL_ID),
    tools=[lookup_order, initiate_return, apply_discount],
    system_prompt=DEFAULT_SYSTEM_PROMPT,
)
agent.hooks.add_callback(BeforeModelCallEvent, dynamic_config_hook)


@app.entrypoint
def invoke(payload, context):
    result = agent(payload.get("prompt", "Hello"))
    return {"response": result.message["content"][0]["text"]}


if __name__ == "__main__":
    app.run()

Atualizar app/csAgent/pyproject.toml dependências:

dependencies = [
    "aws-opentelemetry-distro",
    "bedrock-agentcore >= 1.8.0",
    "boto3",
    "botocore[crt] >= 1.35.0",
    "strands-agents[otel] >= 1.13.0",
    "opentelemetry-distro",
    "opentelemetry-instrumentation",
]

Implante o agente de suporte ao cliente no AgentCore Runtime:

agentcore deploy

Após a implantação, observe o ARN do tempo de execução na saída (por exemplo,arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/csAgent-abc123). Você precisará dele para criar pacotes de configuração.

Verifique se o agente está em execução:

agentcore invoke --prompt "What is the status of order ORD-1003?"

O BeforeModelCallEvent gancho é acionado antes de cada chamada do LLM, lendo o pacote de configuração ativo a partir do contexto da solicitação. Durante um A/B teste, o AgentCore Gateway atribui cada sessão a uma variante e propaga a referência do pacote correspondente por meio dos cabeçalhos de bagagem do W3C. O tempo de execução disponibiliza isso por meio deBedrockAgentCoreContext, portanto, as sessões de controle recebem o pacote v1 e as sessões de tratamento recebem o pacote v2 — o agente aplica qualquer prompt do sistema que está no pacote que recebe.

Para obter mais detalhes, consulte Usar pacotes de configuração em tempo de execução.

Etapa 4: criar pacotes de configuração

Crie dois pacotes de configuração — um para controle (alerta atual) e outro para tratamento (aviso otimizado). O A/B teste dividirá o tráfego entre eles para medir qual prompt gera melhores pontuações para o avaliador.

Pacote de controle — o prompt atual do sistema:

agentcore add config-bundle \
  --name customerSupportControl \
  --components '{
    "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/csAgent-abc123": {
      "configuration": {
        "system_prompt": "You are a helpful customer support assistant for Acme Store."
      }
    }
  }'

agentcore deploy

Pacote de tratamento — um prompt otimizado do sistema que instrui o agente a ser mais proativo:

agentcore add config-bundle \
  --name customerSupportTreatment \
  --components '{
    "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/csAgent-abc123": {
      "configuration": {
        "system_prompt": "You are a customer support assistant for Acme Store. Be proactive: check order status before the customer asks, offer discounts for delayed orders, and summarize actions taken at the end of each response."
      }
    }
  }'

agentcore deploy

Depois de cada implantação, anote o ARN do pacote e o ID da versão na saída — você precisará deles ao criar A/B o teste.

Etapa 5: criar uma configuração de avaliação on-line

Um A/B teste requer uma configuração de avaliação on-line para pontuar sessões de ambas as variantes. A avaliação on-line compara os avaliadores em relação ao tráfego ao vivo e envia as pontuações ao mecanismo estatístico do A/B teste.

Para variantes do pacote de configuração, crie uma única configuração de avaliação on-line que monitore o Runtime compartilhado AgentCore :

agentcore add online-eval \
  --name customerSupportEval \
  --runtime csAgent \
  --evaluator "Builtin.Helpfulness" \
  --sampling-rate 100.0 \
  --enable-on-create

agentcore deploy

Após a implantação, anote o ARN da configuração de avaliação on-line na saída — você precisará dele ao criar A/B o teste.

Para obter mais detalhes sobre as opções e a configuração do avaliador, consulte Criar avaliação on-line.

Etapa 6: criar o gateway e o destino

Um A/B teste de pacote de configuração roteia o tráfego por meio de um AgentCore gateway, portanto, o gateway e seu destino já devem estar implantados antes de você iniciar o teste. Adicione um gateway com o tempo de execução como http-runtime destino e implante:

agentcore add gateway --name csGateway

agentcore add gateway-target \
  --name customer-support \
  --gateway csGateway \
  --type http-runtime \
  --runtime csAgent

agentcore deploy

Etapa 7: criar o A/B teste

Crie um A/B teste que divida o tráfego 80/20 entre as instruções de controle e tratamento. Ambas as variantes fazem referência a pacotes de configuração no mesmo AgentCore Runtime e compartilham uma única configuração de avaliação on-line para pontuação.

Etapa 8: Enviar tráfego pelo AgentCore Gateway

Depois que o A/B teste estiver em execução, envie tráfego pelo endpoint HTTP do AgentCore Gateway. O AgentCore Gateway atribui cada solicitação a uma variante (controle ou tratamento) com base no ID da sessão de tempo de execução.

Como funciona a atribuição de variantes

O AgentCore Gateway usa o X-Amzn-Bedrock-AgentCore-Runtime-Session-Id cabeçalho para determinar qual variante do pacote de configuração deve ser veiculada. Esse cabeçalho é opcional — se você não o fornecer, o tempo de execução gerará uma ID de sessão automaticamente. Em seguida, o AgentCore Gateway usa a ID da sessão (seja ela fornecida por você ou gerada pelo tempo de execução) para atribuir a solicitação a uma variante com base nos pesos de tráfego configurados.

A atribuição da sessão é fixa: quando uma ID de sessão é atribuída a uma variante, todas as solicitações subsequentes com a mesma ID de sessão são encaminhadas para a mesma variante. Isso garante uma experiência consistente em uma sessão e, ao mesmo tempo, distribui novas sessões entre variantes de acordo com sua divisão de tráfego.

Gere tráfego para testes

Salve o script a seguir comoloadgen.sh, substituindo <gateway-id> e <target-name> com os valores de sua saída de implantação:

#!/bin/bash
export AWS_ACCESS_KEY_ID=$(aws configure get aws_access_key_id)
export AWS_SECRET_ACCESS_KEY=$(aws configure get aws_secret_access_key)
export AWS_SESSION_TOKEN=$(aws configure get aws_session_token)

GATEWAY_URL="https://<gateway-id>.gateway.bedrock-agentcore.us-west-2.amazonaws.com/<target-name>/invocations"

PROMPTS=(
  "What is the status of order ORD-1003?"
  "I want to return order ORD-1001, it doesn't fit."
  "My order ORD-1003 is late. Can I get a discount?"
  "Where is my order ORD-1002?"
  "I need help with a return for order ORD-1001. The color is wrong."
  "Can you check on order ORD-1003? I've been waiting forever."
  "I'd like to cancel order ORD-1002 if it hasn't shipped yet."
  "Order ORD-1003 is delayed again. This is unacceptable."
  "What's your return policy for order ORD-1001?"
  "My headphones order ORD-1003 still hasn't arrived. What can you do?"
)

for i in $(seq 1 30); do
  PROMPT="${PROMPTS[$(( (i - 1) % ${#PROMPTS[@]} ))]}"
  echo "=== Request $i: $PROMPT ==="
  curl -s --aws-sigv4 "aws:amz:us-west-2:bedrock-agentcore" \
    --user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
    -H "x-amz-security-token: $AWS_SESSION_TOKEN" \
    -H "Content-Type: application/json" \
    -H "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: $(uuidgen)" \
    -d "{\"prompt\": \"$PROMPT\"}" \
    -X POST \
    "$GATEWAY_URL"
  echo ""
  sleep 2
done

Execute o script :

bash loadgen.sh

Etapa 9: obter resultados

Faça uma pesquisa com o A/B teste para monitorar os resultados à medida que o tamanho das amostras aumenta. A pesquisa não afeta a validade estatística.

Como interpretar os resultados do

Para obter uma explicação detalhada da estrutura de resultados e das definições de campo, consulte Entendendo os resultados no guia de roteamento baseado em metas.

Etapa 10: Confirme os resultados e interrompa o A/B teste

Quando o A/B teste atingir significância estatística, revise os resultados e interrompa o experimento.

Etapa 11: implantar o vencedor

Depois de interromper o A/B teste, direcione todo o tráfego para a versão vencedora do pacote de configuração.

agentcore promote ab-test -i <ab-test-id>
agentcore deploy

promoteinterrompe o A/B teste (se ainda estiver em execução) e atualiza o pacote de configuração de controle para usar a versão de tratamento. Execute agentcore deploy para aplicar as alterações.

Como alternativa, você pode implantar manualmente o vencedor fazendo o seguinte:

Próximas etapas

Depois de posicionar o vencedor:

Exemplo: descrições A/B de ferramentas de teste

Você pode usar o mesmo padrão de pacote de configuração para testar as descrições otimizadas das ferramentas. Diferentemente dos A/B testes de alerta do sistema, nos quais o agente lê o pacote diretamente, as substituições da descrição da ferramenta são aplicadas pelo Gateway. AgentCore Quando o agente liga tools/list pelo gateway, o gateway lê o pacote de configuração e retorna as descrições da ferramenta com as substituições aplicadas. Nenhuma alteração no código do agente é necessária.

Para obter detalhes sobre como o gateway aplica as substituições da descrição da ferramenta, consulte Comportamento em alvos MCP.

Pacotes de configuração

Pacote de controle — descrições atuais da ferramenta:

agentcore add config-bundle \
  --name toolDescControl \
  --components '{
    "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/csAgent-abc123": {
      "configuration": {
        "tools": {
          "lookup_order": {
            "description": "Look up an order by ID."
          },
          "initiate_return": {
            "description": "Initiate a return for an order."
          },
          "apply_discount": {
            "description": "Apply a discount to an order."
          }
        }
      }
    }
  }'

agentcore deploy

Pacote de tratamento — descrições otimizadas da ferramenta a partir de uma recomendação:

agentcore add config-bundle \
  --name toolDescTreatment \
  --components '{
    "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/csAgent-abc123": {
      "configuration": {
        "tools": {
          "lookup_order": {
            "description": "Look up order details including status, item, and total by order ID. Use when the customer asks about an order or references an order number."
          },
          "initiate_return": {
            "description": "Start a return process for an order. Use only when the customer explicitly requests a return or exchange, not for order status inquiries."
          },
          "apply_discount": {
            "description": "Apply a percentage discount to an order. Use when compensating for service issues such as delivery delays. Requires a reason."
          }
        }
      }
    }
  }'

agentcore deploy

Como funciona

Crie o A/B teste

agentcore run ab-test \
  --mode config-bundle \
  --name toolDescTest \
  --gateway csGateway \
  --runtime csAgent \
  --control-bundle toolDescControl \
  --control-version <control-bundle-version-id> \
  --treatment-bundle toolDescTreatment \
  --treatment-version <treatment-bundle-version-id> \
  --online-eval customerSupportEval \
  --control-weight 80 \
  --treatment-weight 20

As etapas restantes (enviar tráfego, obter resultados, implantar o vencedor) são idênticas ao exemplo anterior de prompt do sistema.

Solução de problemas

Para solucionar problemas de A/B teste (como resultados ausentes após o envio do tráfego), consulte Solução de problemas no guia de roteamento baseado em metas.