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 :

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.

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 viaBedrockAgentCoreContext, 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.

É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.

Pour plus de détails sur les options et la configuration de l'évaluateur, voir Créer une évaluation en ligne.

É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.

É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-Iden-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 <target-name> remplaçant <gateway-id> 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-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

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.

Interprétation des résultats

Pour une explication détaillée de la structure des résultats et des définitions de champs, voir Comprendre les résultats 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.

É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 <ab-test-id>
agentcore deploy

promotearrê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 :

Étapes suivantes

Après avoir déployé le gagnant :

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.

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

Créez le A/B test

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

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 dans le guide de routage basé sur les cibles.