Execute um A/B teste com roteamento baseado em metas

Use o padrão de roteamento baseado em destino quando 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. Target-based o roteamento roteia o tráfego entre várias versões do mesmo AgentCore Runtime (endpoints nomeados) ou entre Runtimes totalmente diferentes AgentCore . O AgentCore Gateway registra cada endpoint como um destino separado e encaminha cada sessão para um endpoint ou outro com base nos pesos de tráfego do A/B teste.

Configuração principal para A/B testes baseados em metas:

Este passo a passo implanta duas versões do agente de suporte ao cliente — uma usando Claude Sonnet (controle) e outra usando Claude Opus (tratamento) — cria endpoints nomeados para cada versão, cria um A/B teste, envia tráfego, analisa os resultados e implanta o vencedor.

Para uma comparação detalhada dos padrões de A/B teste, consulte Escolha de um padrão.

Etapa 1: criar o projeto

Crie o projeto com a AgentCore CLI:

agentcore create --name ABTestTargetBased --no-agent
cd ABTestTargetBased

Etapa 2: adicionar o tempo de execução

Adicione o tempo de execução do agente. Você implantará duas versões desse tempo de execução — uma para controle e outra para tratamento — e criará endpoints nomeados para criar um alias para cada versão.

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

Estrutura do projeto:

ABTestTargetBased/
├── agentcore/
│   ├── agentcore.json
│   ├── aws-targets.json
│   └── cdk/
└── app/
    └── csAgent/
        ├── main.py
        └── pyproject.toml

Etapa 3: implantar versões de controle e tratamento

app/csAgent/main.pySubstitua pela versão de controle (usando Claude Sonnet):

"""Customer support agent — control variant."""
from strands import Agent, tool
from strands.models.bedrock import BedrockModel
from bedrock_agentcore.runtime import BedrockAgentCoreApp

app = BedrockAgentCoreApp()
MODEL_ID = "global.anthropic.claude-sonnet-4-5-20250929-v1:0"
SYSTEM_PROMPT = "You are a helpful customer support assistant for Acme Store."


@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}."


agent = Agent(
    model=BedrockModel(model_id=MODEL_ID),
    tools=[lookup_order, initiate_return, apply_discount],
    system_prompt=SYSTEM_PROMPT,
)


@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 a versão de controle (isso cria a versão 1):

agentcore deploy

Agora, atualize main.py para usar um modelo diferente para a variante de tratamento e implante (isso cria a versão 2):

MODEL_ID = "global.anthropic.claude-opus-4-6-v1"

agentcore deploy

Crie endpoints nomeados para cada versão e implante:

agentcore add runtime-endpoint \
  --runtime csAgent \
  --endpoint control \
  --version 1 \
  --description "Control variant — Claude Sonnet"

agentcore add runtime-endpoint \
  --runtime csAgent \
  --endpoint treatment \
  --version 2 \
  --description "Treatment variant — Claude Opus"

agentcore deploy

Agora você tem:

Verifique se o tempo de execução está funcionando:

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

Agora você tem:

Etapa 4: criar configurações de avaliação on-line

Cada endpoint tem seu próprio grupo de log (o nome do grupo de log termina com o nome do endpoint), então você precisa de uma configuração de avaliação on-line por variante:

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

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

agentcore deploy

Depois de cada implantação, anote o ARN da configuração de avaliação on-line — você precisará de ambos 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 5: criar o gateway e os destinos

Um A/B teste baseado em destinos roteia o tráfego por meio de um AgentCore Gateway, portanto, o gateway e seus dois alvos já devem estar implantados antes de você iniciar o teste. Adicione um gateway e registre cada endpoint de tempo de execução como um http-runtime destino e, em seguida, implante:

agentcore add gateway --name csGateway

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

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

agentcore deploy

Etapa 6: criar o A/B teste

Comece o A/B teste comagentcore run ab-test. Cada variante faz referência a um dos destinos de gateway que você criou e tem sua própria configuração de avaliação on-line. O comando inicia o teste diretamente no serviço em relação ao gateway já implantado.

Etapa 7: 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 para qual destino rotear o tráfego. 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 o mesmo destino. 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. Você também pode copiar o URL de invocação completo de: agentcore view ab-test <ab-test-id>

#!/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 8: 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

Etapa 9: 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 10: implantar o vencedor

Depois de interromper o A/B teste, direcione todo o tráfego para a variante vencedora.

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

promoteinterrompe o A/B teste (se ainda estiver em execução), atualiza o endpoint de controle para apontar para a versão do tratamento (por exemplo, atualizando control da versão 1 para a versão 2) e remove o endpoint do 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:

Entendendo os resultados

Quando você ligaGetABTest, a resposta inclui um results objeto quando o pipeline de agregação processa sessões suficientes. Os resultados contêm métricas por avaliador, divididas por variante.

Estrutura de resultados

{
  "results": {
    "analysisTimestamp": "2026-04-30T18:45:00Z",
    "evaluatorMetrics": [
      {
        "evaluatorArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:evaluator/Builtin.Helpfulness",
        "controlStats": {
          "variantName": "C",
          "sampleSize": 24,
          "mean": 0.72
        },
        "variantResults": [
          {
            "variantName": "T1",
            "sampleSize": 6,
            "mean": 0.85,
            "absoluteChange": 0.13,
            "percentChange": 18.1,
            "pValue": 0.032,
            "confidenceInterval": {
              "lower": 0.02,
              "upper": 0.24
            },
            "isSignificant": true
          }
        ]
      }
    ]
  }
}

Referência dos campos

Solução de problemas

A/B o teste não mostra resultados após o envio do tráfego

Os resultados não aparecem imediatamente. O tempo necessário depende do tempo limite da sessão configurado em sua configuração de avaliação on-line — uma sessão é considerada concluída somente depois que nenhuma nova solicitação chega dentro da janela de tempo limite. Após o término da sessão, espere resultados em aproximadamente 15 minutos.

Se os resultados ainda não aparecerem após essa janela: