# 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:
+ Configuración de variantes: `variantConfiguration.configurationBundle` con ARN y versión del paquete
+ Configuración de evaluación: una única compartida `onlineEvaluationConfigArn`
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](ab-testing-target-based.md).
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.py`Sustitú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é disponible`BedrockAgentCoreContext`, 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](configuration-bundles-runtime.md).
## 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.
**sugerencia**
Se configura `--sampling-rate 100.0` durante la A/B prueba para que se evalúe cada sesión y los resultados alcancen una significación estadística más rápida. Puede reducir la tasa una vez finalizada la prueba.
Para obtener más información sobre las opciones y la configuración del evaluador, consulte [Crear una evaluación en línea](create-online-evaluations.md).
## 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.
**Example**
```
agentcore run ab-test \
--mode config-bundle \
--name customerSupportPromptTest \
--gateway csGateway \
--runtime csAgent \
--control-bundle customerSupportControl \
--control-version \
--treatment-bundle customerSupportTreatment \
--treatment-version \
--online-eval customerSupportEval \
--control-weight 80 \
--treatment-weight 20
```
`agentcore run ab-test`inicia un trabajo de A/B prueba en el servicio. La prueba se ejecutará en cuanto vuelva el comando. Pase `--disable-on-create` para crearla detenida. Para revisar el trabajo`agentcore view ab-test `, ejecute o busque en el JSON del trabajo`.cli/jobs/ab-tests/`. El `--gateway` indicador es obligatorio y debe hacer referencia a la puerta de enlace que implementaste en el paso 6. Solo se puede ejecutar una prueba por puerta de enlace a la vez. El comando imprime el identificador del trabajo de la prueba, que también está disponible en el `id` campo. `--json` Necesita este ID para los comandos de ciclo de vida que aparecen a continuación.
`--treatment-version`Los valores `--control-version` y son los ID de versión devueltos al implementar los paquetes de configuración en el paso 3.
```
import boto3
import uuid
client = boto3.client("bedrock-agentcore", region_name="us-west-2")
response = client.create_ab_test(
name="customerSupportPromptTest",
gatewayArn="arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/gw-abc123",
roleArn="arn:aws:iam::123456789012:role/ABTestRole",
evaluationConfig={
"onlineEvaluationConfigArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:online-evaluation-config/eval-abc123"
},
variants=[
{
"name": "C",
"weight": 80,
"variantConfiguration": {
"configurationBundle": {
"bundleArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:configuration-bundle/customerSupportControl-Ab1Cd2Ef3G",
"bundleVersion": "12345678-1234-1234-1234-123456789012"
}
}
},
{
"name": "T1",
"weight": 20,
"variantConfiguration": {
"configurationBundle": {
"bundleArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:configuration-bundle/customerSupportTreatment-Ab1Cd2Ef3G",
"bundleVersion": "12345678-1234-5678-9abc-123456789012"
}
}
}
],
enableOnCreate=True,
clientToken=str(uuid.uuid4()),
)
ab_test_id = response["abTestId"]
print(f"Created A/B test: {ab_test_id}")
print(f"Status: {response['status']}")
print(f"Execution status: {response['executionStatus']}")
```
## 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 como`loadgen.sh`, sustituyendo `` y por `` 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.bedrock-agentcore.us-west-2.amazonaws.com//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.
**Example**
Obtenga los resultados actuales (``sustitúyalos por el identificador de trabajo del paso 6):
```
agentcore view ab-test
```
Obtenga los resultados como JSON:
```
agentcore view ab-test --json
```
Realice una encuesta hasta que los resultados alcancen significación estadística:
```
import boto3
import time
client = boto3.client("bedrock-agentcore", region_name="us-west-2")
ab_test_id = "customerSupportPromptTest-Ab1Cd2Ef3G"
while True:
response = client.get_ab_test(abTestId=ab_test_id)
status = response["status"]
exec_status = response["executionStatus"]
print(f"Status: {status}, Execution: {exec_status}")
results = response.get("results")
if results:
print(f"Analysis timestamp: {results.get('analysisTimestamp')}")
for metric in results["evaluatorMetrics"]:
evaluator = metric["evaluatorArn"]
control = metric["controlStats"]
print(f"\nEvaluator: {evaluator}")
print(f" Control: mean={control['mean']:.3f}, n={control['sampleSize']}")
for variant in metric["variantResults"]:
print(f" {variant['variantName']}: mean={variant['mean']:.3f}, "
f"n={variant['sampleSize']}, "
f"pValue={variant.get('pValue', 'N/A')}, "
f"significant={variant['isSignificant']}")
if variant["isSignificant"]:
print(f" >>> Statistically significant! "
f"Change: {variant.get('percentChange', 0):.1f}%")
# Check if any evaluator has reached significance
all_significant = all(
variant["isSignificant"]
for metric in results["evaluatorMetrics"]
for variant in metric["variantResults"]
)
if all_significant:
print("\nAll evaluators have reached statistical significance.")
break
time.sleep(300) # Poll every 5 minutes
```
**nota**
El tiempo que tardan en aparecer los resultados depende principalmente 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 cuando no llegan nuevas solicitudes dentro del período de tiempo de espera. Una vez finalizada la sesión, los resultados suelen aparecer en 15 minutos. Los resultados se acumulan a medida que se completan más sesiones; la significación estadística mejora con el tamaño de la muestra.
+ **Valor p < 0,05 y positivo`percentChange`:** el tratamiento es significativamente mejor que el control. Considere implementar el tratamiento.
+ **Valor p < 0,05 y negativo`percentChange`:** el tratamiento es significativamente peor. Mantén el control.
+ **Valor p >= 0.05:** No hay pruebas suficientes para concluir una diferencia. Continúe recolectando muestras o aumente el tráfico al tratamiento.
+ **Compruebe todos los evaluadores:** un tratamiento puede mejorar una métrica y hacer retroceder otra. Revise todos los resultados de los evaluadores antes de tomar una decisión.
Para obtener una explicación detallada de la estructura de los resultados y las definiciones de los campos, consulte [Comprender los resultados](ab-testing-target-based.md#target-based-results-shape) 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.
1. **Confirme la significancia.** Compruebe que el evaluador objetivo tiene `isSignificant: true` un resultado positivo `percentChange` en la variante de tratamiento (o confirme que el control es el ganador si el tratamiento ha retrocedido).
1. **Detenga la prueba A/B .** Ejecute `agentcore stop ab-test -i `. El enrutamiento del tráfico finaliza inmediatamente y todas las solicitudes vuelven a la configuración predeterminada. Consulte [Ver, pausar, reanudar y detener](ab-testing-manage.md#manage-ab-test-start-stop).
## 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
agentcore deploy
```
`promote`detiene 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:
+ **Opción A:** utilice [las reglas de enrutamiento de AgentCore Gateway](gateway-rules.md) para enrutar todo el tráfico con la versión del paquete de configuración ganadora.
+ **Opción B:** actualice el paquete de configuración de control para utilizar el indicador del sistema ganador y volver a implementarlo.
+ **Opción C:** establece la versión del paquete ganador como la predeterminada en tu código de agente y elimina la configuración de A/B prueba.
Tras implementar el ganador:
+ **Elimine la A/B prueba** para limpiar los recursos. Consulte [Eliminar una A/B prueba](ab-testing-manage.md#manage-ab-test-remove).
+ **Supervise la nueva línea base.** La evaluación en línea continúa con las sesiones de puntuación de la configuración ganadora. Esté atento a las regresiones.
+ **Inicie la siguiente iteración.** Las nuevas trazas de la configuración ganadora constituyen la base para el siguiente ciclo de recomendaciones. Vea [cómo funciona](optimization-how-it-works.md).
## 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](gateway-rules-propagation.md#gateway-rules-propagation-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
1. Cuando el agente llama `tools/list` a través de la puerta de enlace (objetivo del MCP), la A/B prueba asigna cada sesión a una variante (control o tratamiento) de la puerta de enlace y resuelve el paquete de configuración correspondiente.
1. Gateway lee el paquete de configuración y devuelve las descripciones de las herramientas con las anulaciones aplicadas.
1. El agente utiliza las descripciones devueltas para seleccionar las herramientas; no es necesario cambiar el código del agente.
### Cree la A/B prueba
```
agentcore run ab-test \
--mode config-bundle \
--name toolDescTest \
--gateway csGateway \
--runtime csAgent \
--control-bundle toolDescControl \
--control-version \
--treatment-bundle toolDescTreatment \
--treatment-version \
--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](ab-testing-target-based.md#target-based-troubleshooting) en la guía de enrutamiento basado en destinos.