Ejecute una A/B prueba con enrutamiento basado en objetivos

Utilice el patrón de enrutamiento basado en el destino cuando el cambio que esté probando implique cambios de código, una actualización del marco o la implementación de un agente completamente diferente. Target-based el enrutamiento enruta el tráfico entre varias versiones del mismo AgentCore entorno de ejecución (denominados puntos finales) o entre entornos de ejecución completamente diferentes AgentCore . El AgentCore Gateway registra cada punto final como un destino independiente y enruta cada sesión a uno u otro punto final en función de las ponderaciones de tráfico de la A/B prueba.

Configuración clave para las A/B pruebas basadas en objetivos:

En este tutorial se utilizan dos versiones del agente de atención al cliente (una con Claude Sonnet (control) y otra con Claude Opus (tratamiento). Crea puntos finales con nombre para cada versión, crea una A/B prueba, envía el tráfico, revisa los resultados e implementa la versión ganadora.

Para ver una comparación detallada de los patrones de A/B prueba, consulte Elegir un patrón.

Paso 1: Crea el proyecto

Cree el proyecto con la AgentCore CLI:

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

Paso 2: Añadir el tiempo de ejecución

Añada el tiempo de ejecución del agente. Implementará dos versiones de este tiempo de ejecución (una para el control y otra para el tratamiento) y, a continuación, creará puntos finales con nombre para asignar un alias a cada versión.

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

Estructura del proyecto:

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

Paso 3: Implementar las versiones de control y tratamiento

app/csAgent/main.pySustitúyala por la versión de control (utilizando 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()

Actualice app/csAgent/pyproject.toml las dependencias:

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",
]

Implemente la versión de control (esto crea la versión 1):

agentcore deploy

Ahora actualice main.py para usar un modelo diferente para la variante de tratamiento e impleméntelo (esto crea la versión 2):

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

agentcore deploy

Cree puntos finales con nombre para cada versión e implemente:

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

Ahora tiene:

Compruebe que el tiempo de ejecución funciona:

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

Ahora tiene:

Paso 4: Crear configuraciones de evaluación en línea

Cada punto final tiene su propio grupo de registros (el nombre del grupo de registros termina con el nombre del punto final), por lo que necesita una configuración de evaluación en línea 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

Después de cada implementación, anote el ARN de la configuración de evaluación en línea; necesitará ambos al crear la A/B prueba.

Para obtener más información sobre las opciones y la configuración del evaluador, consulte Crear una evaluación en línea.

Paso 5: Cree la puerta de enlace y los objetivos

Una A/B prueba basada en objetivos enruta el tráfico a través de una AgentCore puerta de enlace, por lo que la puerta de enlace y sus dos objetivos ya deben estar implementados antes de iniciar la prueba. Agregue una puerta de enlace y registre cada punto final de tiempo de ejecución como http-runtime destino y, a continuación, implemente:

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

Paso 6: Crea la A/B prueba

Comience la A/B prueba conagentcore run ab-test. Cada variante hace referencia a uno de los objetivos de pasarela que ha creado y tiene su propia configuración de evaluación en línea. El comando inicia la prueba directamente en el servicio en la puerta de enlace ya implementada.

Paso 7: Enviar tráfico a través de la AgentCore puerta de enlace

Una vez A/B ejecutada la prueba, envíe el tráfico a través del punto final HTTP de la AgentCore puerta de enlace. El AgentCore Gateway asigna cada solicitud a una variante (control o tratamiento) en función del ID de la sesión en tiempo de ejecución.

Cómo funciona la asignación de variantes

La AgentCore puerta de enlace usa el X-Amzn-Bedrock-AgentCore-Runtime-Session-Id encabezado para determinar a qué objetivo enrutar el tráfico. Este encabezado es opcional: si no lo proporciona, el motor de ejecución genera un ID de sesión automáticamente. A continuación, el AgentCore Gateway utiliza el ID de sesión (tanto si lo has proporcionado como si lo ha generado el tiempo de ejecución) para asignar la solicitud a una variante en función de las ponderaciones de tráfico configuradas.

La asignación de sesiones es fija: una vez que se asigna un ID de sesión a una variante, todas las solicitudes posteriores con ese mismo ID de sesión se dirigen al mismo destino. Esto garantiza una experiencia coherente dentro de una sesión y, al mismo tiempo, distribuye las nuevas sesiones entre las variantes en función de la división del tráfico.

Genera tráfico para realizar pruebas

Guarde el siguiente script comoloadgen.sh, sustituyendo <gateway-id> y por <target-name> los valores del resultado de la implementación. También puede copiar la URL de invocación completa deagentcore 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

Ejecute el script :

bash loadgen.sh

Paso 8: Obtenga resultados

Realice un sondeo A/B de la prueba para monitorear los resultados a medida que aumenta el tamaño de la muestra. El sondeo no afecta a la validez estadística.

Interpretación de los resultados

Paso 9: Confirme los resultados y detenga la prueba A/B

Una vez que la A/B prueba alcance la significación estadística, revise los resultados y detenga el experimento.

Paso 10: Despliega al ganador

Tras detener la A/B prueba, dirija todo el tráfico a la variante ganadora.

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

promotedetiene la A/B prueba (si aún se está ejecutando), actualiza el punto final de control para que apunte a la versión del tratamiento (por ejemplo, al actualizar control de la versión 1 a la versión 2) y elimina el punto final del tratamiento. Ejecute agentcore deploy para aplicar los cambios.

Como alternativa, puedes desplegar el ganador manualmente mediante una de las siguientes acciones:

Siguientes pasos

Tras desplegar al ganador:

Comprensión de los resultados

Cuando llamasGetABTest, la respuesta incluye un results objeto una vez que la canalización de agregación haya procesado suficientes sesiones. Los resultados contienen métricas por evaluador desglosadas por variante.

Estructura 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
          }
        ]
      }
    ]
  }
}

Referencia de campos

Resolución de problemas

A/B la prueba no muestra resultados después de enviar el tráfico

Los resultados no aparecen inmediatamente. El tiempo necesario depende del tiempo de espera de la sesión configurado en la configuración de evaluación en línea: una sesión se considera completa solo cuando no llegan nuevas solicitudes dentro del período de tiempo de espera. Una vez finalizada la sesión, los resultados se obtienen en aproximadamente 15 minutos.

Si los resultados siguen sin aparecer después de esta ventana: