# Exécuter un A/B test avec des ensembles de configuration
Utilisez le modèle de bundle de configuration lorsque la modification que vous testez concerne uniquement la configuration, qu'il s'agisse d'une invite système différente, d'un identifiant de modèle différent ou de descriptions d'outils différentes. Les deux variantes s'exécutent sur le même AgentCore environnement d'exécution avec des versions de bundle de configuration différentes. La AgentCore passerelle injecte la bonne référence de bundle dans chaque demande via les en-têtes de bagages du W3C, et votre agent la lit au moment de l'exécution. Cela signifie que vous déployez une configuration AgentCore d'exécution et une configuration d'évaluation en ligne.
Configuration clé pour les A/B tests de bundle de configuration :
+ Configuration des variantes : `variantConfiguration.configurationBundle` avec l'ARN du bundle et la version
+ Configuration d'évaluation : une seule configuration partagée `onlineEvaluationConfigArn`
Si la modification que vous testez implique des modifications de code, une mise à niveau du framework ou une implémentation d'agent totalement différente, utilisez plutôt le routage basé sur la cible. Voir [Exécuter un A/B test avec un routage basé sur des cibles](ab-testing-target-based.md).
Cette procédure pas à pas utilise un agent du support client comme exemple. L'agent gère les recherches de commandes, les retours et les demandes de discount. Vous déploierez l'agent, créerez deux ensembles de configuration avec des instructions système différentes (contrôle et traitement), créerez un A/B test, enverrez du trafic, examinerez les résultats et déploierez le gagnant.
## Étape 1 : Création du projet
Créez le projet avec la AgentCore CLI :
```
agentcore create --name ABTestConfigBased --no-agent
cd ABTestConfigBased
```
## Étape 2 : ajouter le runtime
Ajoutez le runtime de l'agent :
```
agentcore add agent \
--name csAgent \
--language Python \
--framework Strands \
--model-provider Bedrock \
--memory none \
--build CodeZip
```
Structure du projet :
```
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
```
## Étape 3 : mise à jour du code de l'agent et déploiement
Remplacez `app/csAgent/main.py` par ce qui suit. L'ajout clé est le `BeforeModelCallEvent` hook qui lit le bundle de configuration actif au moment de l'exécution :
```
"""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()
```
Mettre à jour `app/csAgent/pyproject.toml` les dépendances :
```
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",
]
```
Déployez l'agent de support client sur AgentCore Runtime :
```
agentcore deploy
```
Après le déploiement, notez l'ARN d'exécution indiqué dans la sortie (par exemple,`arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/csAgent-abc123`). Vous en aurez besoin pour créer des ensembles de configuration.
Vérifiez que l'agent est en cours d'exécution :
```
agentcore invoke --prompt "What is the status of order ORD-1003?"
```
Le `BeforeModelCallEvent` hook se déclenche avant chaque appel LLM, lisant le bundle de configuration actif dans le contexte de la demande. Lors d'un A/B test, la AgentCore passerelle attribue chaque session à une variante et propage la référence de bundle correspondante via les en-têtes de bagages du W3C. L'environnement d'exécution le rend disponible via`BedrockAgentCoreContext`, de sorte que les sessions de contrôle reçoivent le bundle v1 et les sessions de traitement reçoivent le bundle v2. L'agent applique l'invite système figurant dans le bundle qu'il reçoit.
Pour plus de détails, consultez la section [Utiliser les ensembles de configuration lors de l'exécution](configuration-bundles-runtime.md).
## Étape 4 : créer des ensembles de configuration
Créez deux ensembles de configuration : un pour le contrôle (invite actuelle) et un pour le traitement (invite optimisée). Le A/B test répartira le trafic entre ces deux indicateurs afin de déterminer quelle invite donne les meilleurs scores aux évaluateurs.
Bundle de contrôle — l'invite système actuelle :
```
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
```
Ensemble de traitements : une invite système optimisée qui demande à l'agent d'être plus proactif :
```
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
```
Après chaque déploiement, notez l'ARN du bundle et l'ID de version figurant dans la sortie. Vous en aurez besoin lors de la création du A/B test.
## Étape 5 : Création d'une configuration d'évaluation en ligne
Un A/B test nécessite une configuration d'évaluation en ligne pour évaluer les sessions des deux variantes. L'évaluation en ligne compare les évaluateurs au trafic réel et transmet les résultats au moteur statistique du A/B test.
Pour les variantes du bundle de configuration, créez une configuration d'évaluation en ligne unique qui surveille le AgentCore Runtime partagé :
```
agentcore add online-eval \
--name customerSupportEval \
--runtime csAgent \
--evaluator "Builtin.Helpfulness" \
--sampling-rate 100.0 \
--enable-on-create
agentcore deploy
```
Après le déploiement, notez l'ARN de configuration d'évaluation en ligne indiqué dans la sortie. Vous en aurez besoin lors de la création du A/B test.
**Astuce**
Réglé `--sampling-rate 100.0` pendant les A/B tests pour que chaque session soit évaluée et que les résultats atteignent une signification statistique plus rapidement. Vous pouvez baisser le taux une fois le test terminé.
Pour plus de détails sur les options et la configuration de l'évaluateur, voir [Créer une évaluation en ligne](create-online-evaluations.md).
## Étape 6 : Création de la passerelle et de la cible
Un A/B test de bundle de configuration achemine le trafic via une AgentCore passerelle, de sorte que la passerelle et sa cible doivent déjà être déployées avant que vous ne commenciez le test. Ajoutez une passerelle avec le runtime comme `http-runtime` cible, puis déployez :
```
agentcore add gateway --name csGateway
agentcore add gateway-target \
--name customer-support \
--gateway csGateway \
--type http-runtime \
--runtime csAgent
agentcore deploy
```
## Étape 7 : Création du A/B test
Créez un A/B test qui répartit le trafic 80/20 entre les invites de contrôle et de traitement. Les deux variantes font référence à des ensembles de configuration sur le même AgentCore environnement d'exécution et partagent une seule configuration d'évaluation en ligne pour la notation.
**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`lance une tâche de A/B test sur le service. Le test est en cours dès le retour de la commande. La passe `--disable-on-create` pour le créer s'est arrêtée. Pour consulter le job`agentcore view ab-test `, exécutez ou consultez le JSON du job ci-dessous`.cli/jobs/ab-tests/`. L'`--gateway`indicateur est obligatoire et doit faire référence à la passerelle que vous avez déployée à l'étape 6. Un seul test peut être exécuté par passerelle à la fois. La commande imprime l'ID de tâche du test, qui est également disponible `--json` sous forme de `id` champ. Vous avez besoin de cet identifiant pour les commandes de cycle de vie ci-dessous.
Les `--treatment-version` valeurs `--control-version` et sont les ID de version renvoyés lorsque vous avez déployé les ensembles de configuration à l'étape 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']}")
```
## Étape 8 : envoyer du trafic via la AgentCore passerelle
Une fois le A/B test exécuté, envoyez le trafic via le point de terminaison HTTP AgentCore Gateway. La AgentCore passerelle attribue chaque demande à une variante (contrôle ou traitement) en fonction de l'ID de session d'exécution.
### Comment fonctionne l'attribution de variantes
La AgentCore passerelle utilise l'`X-Amzn-Bedrock-AgentCore-Runtime-Session-Id`en-tête pour déterminer la variante du bundle de configuration à servir. Cet en-tête est **facultatif**. Si vous ne le fournissez pas, le moteur d'exécution génère automatiquement un identifiant de session. La AgentCore passerelle utilise ensuite l'ID de session (que vous l'ayez fourni ou que le moteur d'exécution l'ait généré) pour attribuer la demande à une variante en fonction de vos pondérations de trafic configurées.
L'attribution de session **est** permanente : une fois qu'un identifiant de session est attribué à une variante, toutes les demandes suivantes portant le même identifiant de session sont acheminées vers la même variante. Cela garantit une expérience cohérente au sein d'une session tout en répartissant les nouvelles sessions entre les variantes en fonction de la répartition du trafic.
### Générer du trafic pour les tests
Enregistrez le script suivant sous le `loadgen.sh` nom, en `` remplaçant `` et par les valeurs de votre sortie de déploiement :
```
#!/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
```
Exécutez le script :
```
bash loadgen.sh
```
## Étape 9 : Obtenir des résultats
Interrogez le A/B test pour surveiller les résultats à mesure que la taille des échantillons augmente. Le sondage n'affecte pas la validité des statistiques.
**Example**
Obtenez les résultats actuels (remplacez-les `` par l'ID de tâche indiqué à l'étape 6) :
```
agentcore view ab-test
```
Obtenez les résultats au format JSON :
```
agentcore view ab-test --json
```
Effectuez un sondage jusqu'à ce que les résultats atteignent une signification statistique :
```
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
```
**Note**
Le temps nécessaire pour que les résultats apparaissent dépend principalement du délai d'expiration de session configuré dans votre configuration d'évaluation en ligne. Une session est considérée comme terminée lorsqu'aucune nouvelle demande n'arrive dans le délai imparti. À la fin d'une session, les résultats apparaissent généralement dans les 15 minutes. Les résultats s'accumulent au fur et à mesure que de nouvelles sessions se terminent ; la signification statistique s'améliore avec la taille de l'échantillon.
+ **valeur p < 0,05 et positive `percentChange` :** le traitement est nettement meilleur que le traitement témoin. Envisagez de déployer le traitement.
+ **valeur p < 0,05 et négative `percentChange` :** le traitement est nettement pire. Gardez le contrôle.
+ **valeur de p >= 0,05 :** preuves insuffisantes pour conclure à une différence. Continuez à prélever des échantillons ou augmentez le trafic vers le traitement.
+ **Vérifiez tous les évaluateurs :** un traitement peut améliorer un indicateur tout en régressant un autre. Passez en revue tous les résultats de l'évaluateur avant de prendre une décision.
Pour une explication détaillée de la structure des résultats et des définitions de champs, voir [Comprendre les résultats](ab-testing-target-based.md#target-based-results-shape) dans le guide de routage basé sur les cibles.
## Étape 10 : Confirmer les résultats et arrêter le A/B test
Une fois que le A/B test atteint une signification statistique, passez en revue les résultats et arrêtez l'expérience.
1. **Confirmez l'importance.** Vérifiez que l'évaluateur cible a donné `isSignificant: true` un résultat positif à `percentChange` la variante du traitement (ou confirmez que le contrôle est gagnant si le traitement régresse).
1. **Arrêtez le A/B test.** Exécutez `agentcore stop ab-test -i `. Le routage du trafic prend fin immédiatement et toutes les demandes reprennent la configuration par défaut. Voir [Afficher, mettre en pause, reprendre et arrêter](ab-testing-manage.md#manage-ab-test-start-stop).
## Étape 11 : Déployer le gagnant
Après avoir arrêté le A/B test, acheminez tout le trafic vers la version du bundle de configuration gagnante.
```
agentcore promote ab-test -i
agentcore deploy
```
`promote`arrête le A/B test (s'il est toujours en cours d'exécution) et met à jour le bundle de configuration de contrôle pour utiliser la version du traitement. Exécutez `agentcore deploy` pour appliquer les modifications.
Vous pouvez également déployer manuellement le gagnant en effectuant l'une des opérations suivantes :
+ **Option A :** utilisez les [règles de routage de AgentCore Gateway](gateway-rules.md) pour acheminer tout le trafic avec la version du bundle de configuration gagnante.
+ **Option B :** mettez à jour le bundle de configuration de contrôle pour utiliser l'invite du système gagnant et redéployez-le.
+ **Option C :** Définissez la version du bundle gagnant comme version par défaut dans votre code d'agent et supprimez la configuration de A/B test.
Après avoir déployé le gagnant :
+ **Supprimez le A/B test** pour nettoyer les ressources. Voir [Supprimer un A/B test](ab-testing-manage.md#manage-ab-test-remove).
+ **Surveillez la nouvelle référence.** L'évaluation en ligne poursuit les sessions de notation sur la configuration gagnante. Surveillez les régressions.
+ **Commencez l'itération suivante.** Les nouvelles traces issues de la configuration gagnante constituent la base du prochain cycle de recommandation. Découvrez [comment cela fonctionne](optimization-how-it-works.md).
## Exemple : descriptions A/B des outils de test
Vous pouvez utiliser le même modèle de bundle de configuration pour tester les descriptions d'outils optimisées. Contrairement aux A/B tests d'invite du système où l'agent lit directement le bundle, les remplacements de description de l'outil sont appliqués par la AgentCore passerelle. Lorsque l'agent appelle `tools/list` via la passerelle, celle-ci lit le bundle de configuration et renvoie les descriptions des outils avec les dérogations appliquées. Aucune modification du code d'agent n'est nécessaire.
Pour plus de détails sur la manière dont la passerelle applique les remplacements de description des outils, voir [Comportement sur les cibles MCP.](gateway-rules-propagation.md#gateway-rules-propagation-mcp)
### Ensembles de configuration
Bundle de contrôle — descriptions des outils actuels :
```
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
```
Ensemble de traitements : descriptions d'outils optimisées à partir d'une recommandation :
```
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
```
### Comment ça marche
1. Lorsque l'agent appelle `tools/list` via la passerelle (cibles MCP), le A/B test attribue chaque session à une variante (contrôle ou traitement) de la passerelle et résout le bundle de configuration correspondant.
1. Gateway lit le bundle de configuration et renvoie les descriptions des outils avec les remplacements appliqués.
1. L'agent utilise les descriptions renvoyées pour sélectionner les outils ; aucune modification du code de l'agent n'est requise.
### Créez le A/B test
```
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
```
Les étapes restantes (envoyer du trafic, obtenir des résultats, déployer le gagnant) sont identiques à celles de l'exemple d'invite système précédent.
## Résolution des problèmes
Pour résoudre les problèmes liés aux A/B tests (tels que l'absence de résultats après l'envoi de trafic), consultez la section [Résolution des problèmes](ab-testing-target-based.md#target-based-troubleshooting) dans le guide de routage basé sur les cibles.