Ejecute una A/B prueba con paquetes de configuración

Utilice el patrón del paquete de configuración cuando el cambio que esté probando sea puramente de configuración: una línea de comandos del sistema diferente, un identificador de modelo diferente o descripciones de herramientas diferentes. Ambas variantes se ejecutan en el mismo AgentCore entorno de ejecución con diferentes versiones del paquete de configuración. El AgentCore Gateway introduce la referencia de paquete correcta en cada solicitud mediante las cabeceras de equipaje del W3C y su agente la lee en tiempo de ejecución. Esto significa que debe implementar una configuración de tiempo de AgentCore ejecución y una configuración de evaluación en línea.

Configuración clave para las A/B pruebas de paquetes de configuración:

Si el cambio que está probando implica cambios de código, una actualización del marco o la implementación de un agente completamente diferente, utilice el enrutamiento basado en objetivos en su lugar. Consulte Ejecutar una A/B prueba con un enrutamiento basado en objetivos.

En este tutorial se utiliza un agente de atención al cliente como ejemplo. El agente gestiona las búsquedas de pedidos, las devoluciones y las solicitudes de descuento. Desplegará el agente, creará dos paquetes de configuración con diferentes indicaciones del sistema (control y tratamiento), creará una A/B prueba, enviará el tráfico, revisará los resultados y desplegará el agente ganador.

Paso 1: Crear el proyecto

Cree el proyecto con la AgentCore CLI:

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

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

Agregue el tiempo de ejecución del agente:

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

Estructura del proyecto:

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

Paso 3: Actualizar el código del agente e implementarlo

app/csAgent/main.pySustitúyalo por lo siguiente. La adición clave es el BeforeModelCallEvent enlace que lee el paquete de configuración activo en tiempo de ejecución:

"""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()

Actualizar 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 el agente de atención al cliente en AgentCore Runtime:

agentcore deploy

Tras la implementación, anote el ARN del tiempo de ejecución de la salida (por ejemplo,arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/csAgent-abc123). Lo necesitará para crear paquetes de configuración.

Compruebe que el agente se esté ejecutando:

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

El BeforeModelCallEvent enlace se activa antes de cada llamada de LLM y lee el paquete de configuración activo del contexto de la solicitud. Durante una A/B prueba, el AgentCore Gateway asigna cada sesión a una variante y propaga la referencia del paquete correspondiente a través de las cabeceras de equipaje del W3C. El tiempo de ejecución permite que esté disponibleBedrockAgentCoreContext, por lo que las sesiones de control reciben el paquete v1 y las sesiones de tratamiento reciben el paquete v2. El agente aplica las indicaciones del sistema que figuren en el paquete que reciben.

Para obtener más información, consulte Usar paquetes de configuración en tiempo de ejecución.

Paso 4: Crear paquetes de configuración

Cree dos paquetes de configuración: uno para el control (solicitud actual) y otro para el tratamiento (solicitud optimizada). La A/B prueba dividirá el tráfico entre ellos para medir qué indicador arroja mejores puntuaciones para los evaluadores.

Paquete de control: el indicador actual del 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

Paquete de tratamiento: un mensaje del sistema optimizado que indica al agente que sea más proactivo:

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

Después de cada implementación, anote el ARN del paquete y el ID de versión del resultado; los necesitará al crear la A/B prueba.

Paso 5: Cree una configuración de evaluación en línea

Una A/B prueba requiere una configuración de evaluación en línea para puntuar las sesiones de ambas variantes. La evaluación en línea compara a los evaluadores con el tráfico en tiempo real y envía las puntuaciones al motor estadístico de la A/B prueba.

Para las variantes del paquete de configuración, cree una única configuración de evaluación en línea que supervise el tiempo de AgentCore ejecución compartido:

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

agentcore deploy

Tras la implementación, anote el ARN de la configuración de evaluación en línea del resultado; lo necesitará 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 6: Cree la puerta de enlace y el destino

Una A/B prueba de paquete de configuración enruta el tráfico a través de una AgentCore puerta de enlace, por lo que la puerta de enlace y su destino ya deben estar implementados antes de iniciar la prueba. Agregue una puerta de enlace con el 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 \
  --gateway csGateway \
  --type http-runtime \
  --runtime csAgent

agentcore deploy

Paso 7: Crea la A/B prueba

Cree una A/B prueba que divida el tráfico 80/20 entre las indicaciones de control y las de tratamiento. Ambas variantes hacen referencia a paquetes de configuración en el mismo AgentCore tiempo de ejecución y comparten una única configuración de evaluación en línea para la puntuación.

Paso 8: 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 utiliza el X-Amzn-Bedrock-AgentCore-Runtime-Session-Id encabezado para determinar qué variante del paquete de configuración debe utilizarse. 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 a la misma variante. 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:

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

Para obtener una explicación detallada de la estructura de los resultados y las definiciones de los campos, consulte Comprender los resultados en la guía de enrutamiento basada en objetivos.

Paso 10: 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 11: Despliega al ganador

Tras detener la A/B prueba, dirija todo el tráfico a la versión ganadora del paquete de configuración.

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

promotedetiene la A/B prueba (si aún se está ejecutando) y actualiza el paquete de configuración de control para usar la versión de tratamiento. Ejecute agentcore deploy para aplicar los cambios.

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

Siguientes pasos

Tras implementar el ganador:

Ejemplo: descripciones A/B de herramientas de prueba

Puede usar el mismo patrón de paquetes de configuración para probar las descripciones optimizadas de las herramientas. A diferencia de A/B las pruebas rápidas del sistema, en las que el agente lee el paquete directamente, AgentCore Gateway aplica las modificaciones de la descripción de la herramienta. Cuando el agente llama tools/list a través de la puerta de enlace, la puerta de enlace lee el paquete de configuración y devuelve las descripciones de las herramientas con las anulaciones aplicadas. No es necesario cambiar el código del agente.

Para obtener más información sobre cómo la puerta de enlace aplica las anulaciones de descripción de las herramientas, consulte Comportamiento de los objetivos MCP.

Paquetes de configuración

Paquete de control: descripciones actuales de las herramientas:

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

Paquete de tratamiento: descripciones de herramientas optimizadas a partir de una recomendación:

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

Funcionamiento

Cree la A/B prueba

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

Los pasos restantes (enviar tráfico, obtener resultados, implementar el ganador) son idénticos a los del ejemplo anterior de la línea de comandos del sistema.

Resolución de problemas

Para solucionar problemas relacionados con las A/B pruebas (como la falta de resultados después de enviar tráfico), consulte Solución de problemas en la guía de enrutamiento basado en destinos.