# Esegui un A/B test con i pacchetti di configurazione
Utilizza lo schema del pacchetto di configurazione quando la modifica che stai testando è puramente di configurazione: un prompt di sistema diverso, un ID del modello diverso o descrizioni degli strumenti diverse. Entrambe le varianti vengono eseguite sullo stesso AgentCore Runtime con diverse versioni del pacchetto di configurazione. Il AgentCore Gateway inserisce il riferimento corretto al pacchetto in ogni richiesta tramite le intestazioni baggage del W3C e l'agente lo legge in fase di esecuzione. Ciò significa che devi implementare un Runtime e una configurazione di valutazione online. AgentCore
Configurazione chiave per i test dei pacchetti A/B di configurazione:
+ Configurazione della variante: `variantConfiguration.configurationBundle` con ARN e versione in bundle
+ Configurazione di valutazione: un'unica configurazione condivisa `onlineEvaluationConfigArn`
Se la modifica che stai testando comporta modifiche al codice, un aggiornamento del framework o un'implementazione dell'agente completamente diversa, utilizza invece il routing basato sul target. Vedi [Eseguire un A/B test con](ab-testing-target-based.md) il routing basato su target.
Questa procedura dettagliata utilizza un agente dell'assistenza clienti come esempio. L'agente gestisce la ricerca degli ordini, i resi e le richieste di discount. Implementerai l'agente, creerai due pacchetti di configurazione con diverse istruzioni di sistema (controllo e trattamento), creerai un A/B test, invierai il traffico, esaminerai i risultati e implementerai il vincitore.
## Fase 1: Creare il progetto
Crea il progetto con la AgentCore CLI:
```
agentcore create --name ABTestConfigBased --no-agent
cd ABTestConfigBased
```
## Fase 2: Aggiungere il runtime
Aggiungi il runtime dell'agente:
```
agentcore add agent \
--name csAgent \
--language Python \
--framework Strands \
--model-provider Bedrock \
--memory none \
--build CodeZip
```
Struttura del progetto:
```
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
```
## Fase 3: Aggiornare il codice dell'agente e distribuirlo
Sostituisci `app/csAgent/main.py` con quanto segue. L'aggiunta chiave è l'`BeforeModelCallEvent`hook che legge il pacchetto di configurazione attivo in fase di esecuzione:
```
"""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()
```
Aggiorna le dipendenze`app/csAgent/pyproject.toml`:
```
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",
]
```
Implementa l'agente dell'assistenza clienti su Runtime AgentCore :
```
agentcore deploy
```
Dopo la distribuzione, annota l'ARN di runtime dall'output (ad esempio,`arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/csAgent-abc123`). Ti servirà per creare pacchetti di configurazione.
Verifica che l'agente sia in esecuzione:
```
agentcore invoke --prompt "What is the status of order ORD-1003?"
```
L'`BeforeModelCallEvent`hook si attiva prima di ogni chiamata LLM, leggendo il pacchetto di configurazione attivo dal contesto della richiesta. Durante un A/B test, il AgentCore Gateway assegna ogni sessione a una variante e propaga il riferimento al pacchetto corrispondente tramite le intestazioni di bagaglio W3C. Il runtime lo rende disponibile`BedrockAgentCoreContext`, in modo che le sessioni di controllo ricevano il pacchetto v1 e le sessioni di trattamento ricevano il pacchetto v2: l'agente applica qualsiasi prompt di sistema presente nel pacchetto ricevuto.
[Per maggiori dettagli, consulta Utilizzare i pacchetti di configurazione in fase di esecuzione.](configuration-bundles-runtime.md)
## Fase 4: Creare pacchetti di configurazione
Crea due pacchetti di configurazione: uno per il controllo (richiesta corrente) e uno per il trattamento (richiesta ottimizzata). Il A/B test suddividerà il traffico tra questi sistemi per misurare quale prompt produce punteggi migliori per i valutatori.
Control bundle: l'attuale prompt di 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
```
Pacchetto terapeutico: un prompt di sistema ottimizzato che indica all'agente di essere più proattivo:
```
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
```
Dopo ogni implementazione, annota l'ARN del pacchetto e l'ID della versione dall'output: ti serviranno per creare il test. A/B
## Fase 5: Creare una configurazione di valutazione online
Un A/B test richiede una configurazione di valutazione online per assegnare un punteggio alle sessioni di entrambe le varianti. La valutazione online confronta i valutatori con il traffico in tempo reale e invia i punteggi al motore statistico del A/B test.
Per le varianti del pacchetto di configurazione, crea un'unica configurazione di valutazione online che monitori il Runtime condiviso: AgentCore
```
agentcore add online-eval \
--name customerSupportEval \
--runtime csAgent \
--evaluator "Builtin.Helpfulness" \
--sampling-rate 100.0 \
--enable-on-create
agentcore deploy
```
Dopo l'implementazione, annota l'ARN della configurazione di valutazione online dall'output: ti servirà durante la creazione A/B del test.
**Suggerimento**
Impostato `--sampling-rate 100.0` durante il A/B test in modo che ogni sessione venga valutata e i risultati raggiungano la significatività statistica più rapidamente. È possibile ridurre la frequenza al termine del test.
Per maggiori dettagli sulle opzioni e sulla configurazione del valutatore, consulta [Creare una valutazione online](create-online-evaluations.md).
## Fase 6: Creare il gateway e il target
Un A/B test config-bundle indirizza il traffico attraverso un AgentCore gateway, quindi il gateway e il relativo target devono essere già implementati prima di iniziare il test. Aggiungi un gateway con il runtime come `http-runtime` destinazione, quindi distribuisci:
```
agentcore add gateway --name csGateway
agentcore add gateway-target \
--name customer-support \
--gateway csGateway \
--type http-runtime \
--runtime csAgent
agentcore deploy
```
## Fase 7: Creare il test A/B
Crea un A/B test che suddivida il traffico 80/20 tra le istruzioni di controllo e quelle di trattamento. Entrambe le varianti fanno riferimento ai pacchetti di configurazione sullo stesso AgentCore Runtime e condividono un'unica configurazione di valutazione online per il punteggio.
**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`avvia un processo di A/B test sul servizio. Il test è IN ESECUZIONE non appena il comando viene restituito. Il passaggio `--disable-on-create` per crearlo si è interrotto. Per rivedere il lavoro`agentcore view ab-test `, esegui o cerca nel lavoro JSON sotto`.cli/jobs/ab-tests/`. Il `--gateway` flag è obbligatorio e deve fare riferimento al gateway distribuito nel passaggio 6. È possibile eseguire un solo test per gateway alla volta. Il comando stampa l'ID del lavoro del test, disponibile anche `--json` come `id` campo. Questo ID è necessario per i comandi del ciclo di vita riportati di seguito.
`--treatment-version`I valori `--control-version` e sono gli ID di versione restituiti quando hai distribuito i bundle di configurazione nel passaggio 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']}")
```
## Passaggio 8: invio del traffico attraverso il gateway AgentCore
Dopo l'esecuzione del A/B test, invia il traffico tramite l'endpoint HTTP AgentCore Gateway. Il AgentCore Gateway assegna ogni richiesta a una variante (controllo o trattamento) in base all'ID della sessione di runtime.
### Come funziona l'assegnazione delle varianti
Il AgentCore Gateway utilizza l'`X-Amzn-Bedrock-AgentCore-Runtime-Session-Id`intestazione per determinare quale variante del pacchetto di configurazione servire. Questa intestazione è **facoltativa**: se non la fornite, il runtime genera automaticamente un ID di sessione. Il AgentCore Gateway utilizza quindi l'ID di sessione (indipendentemente dal fatto che sia stato fornito dall'utente o generato dal runtime) per assegnare la richiesta a una variante in base ai pesi di traffico configurati.
L'assegnazione della sessione è **permanente**: una volta assegnato un ID di sessione a una variante, tutte le richieste successive con lo stesso ID di sessione vengono indirizzate alla stessa variante. Ciò garantisce un'esperienza coerente all'interno di una sessione, pur continuando a distribuire nuove sessioni tra le varianti in base alla suddivisione del traffico.
### Genera traffico per i test
Salva lo script seguente come`loadgen.sh`, sostituendo `` e `` con i valori dell'output di distribuzione:
```
#!/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
```
Esegui lo script :
```
bash loadgen.sh
```
## Fase 9: Ottenere risultati
Esegui un sondaggio sul A/B test per monitorare i risultati man mano che le dimensioni del campione aumentano. I sondaggi non influiscono sulla validità statistica.
**Example**
Ottieni i risultati attuali (sostituiscili `` con l'ID del lavoro riportato nella fase 6):
```
agentcore view ab-test
```
Ottieni risultati in formato JSON:
```
agentcore view ab-test --json
```
Esegui un sondaggio finché i risultati non raggiungono la significatività statistica:
```
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**
Il tempo necessario per la visualizzazione dei risultati dipende principalmente dal timeout della sessione configurato nella configurazione di valutazione online. Una sessione è considerata completa quando non arrivano nuove richieste entro la finestra di timeout. Al termine di una sessione, i risultati vengono in genere visualizzati entro 15 minuti. I risultati si accumulano man mano che vengono completate più sessioni: la significatività statistica migliora con la dimensione del campione.
+ **valore p < 0,05 e positivo`percentChange`:** il trattamento è significativamente migliore del controllo. Valuta la possibilità di utilizzare il trattamento.
+ **valore p < 0,05 e negativo`percentChange`:** il trattamento è significativamente peggiore. Mantieni il controllo.
+ **Valore p >= 0,05:** prove insufficienti per concludere una differenza. Continuate a raccogliere campioni o aumentate il traffico verso il trattamento.
+ **Controlla tutti i valutatori:** un trattamento può migliorare una metrica regredendone un'altra. Esamina tutti i risultati dei valutatori prima di decidere.
Per una spiegazione dettagliata della struttura dei risultati e delle definizioni dei campi, consulta [Comprendere i risultati](ab-testing-target-based.md#target-based-results-shape) nella guida al routing basata sugli obiettivi.
## Fase 10: Conferma i risultati e interrompi il test A/B
Una volta che il A/B test raggiunge la significatività statistica, rivedi i risultati e interrompi l'esperimento.
1. **Conferma la significatività.** Verificate che il valutatore bersaglio abbia `isSignificant: true` ottenuto un risultato positivo `percentChange` sulla variante terapeutica (o confermate che il controllo è il vincitore in caso di regressione del trattamento).
1. **Interrompi il test. A/B ** Esegui `agentcore stop ab-test -i `. Il routing del traffico termina immediatamente e tutte le richieste tornano alla configurazione predefinita. Vedi [Visualizzare, mettere in pausa, riprendere e interrompere](ab-testing-manage.md#manage-ab-test-start-stop).
## Passaggio 11: schiera il vincitore
Dopo aver interrotto il A/B test, indirizza tutto il traffico verso la versione vincente del pacchetto di configurazione.
```
agentcore promote ab-test -i
agentcore deploy
```
`promote`interrompe il A/B test (se è ancora in esecuzione) e aggiorna il pacchetto di configurazione di controllo per utilizzare la versione del trattamento. Esegui `agentcore deploy` per applicare le modifiche.
In alternativa, puoi schierare manualmente il vincitore effettuando una delle seguenti operazioni:
+ **Opzione A:** utilizza [le regole di routing del AgentCore gateway](gateway-rules.md) per indirizzare tutto il traffico con la versione vincente del pacchetto di configurazione.
+ **Opzione B:** aggiorna il pacchetto di configurazione del controllo per utilizzare il prompt del sistema vincente e ridistribuirlo.
+ **Opzione C:** imposta la versione del pacchetto vincente come predefinita nel codice dell'agente e rimuovi la configurazione di test. A/B
Dopo aver schierato il vincitore:
+ **Elimina il A/B test** per ripulire le risorse. Vedi [Eliminare un A/B test](ab-testing-manage.md#manage-ab-test-remove).
+ **Monitora la nuova linea di base.** La valutazione online continua ad assegnare punteggi alle sessioni sulla configurazione vincente. Attenzione alle regressioni.
+ **Inizia l'iterazione successiva.** Le nuove tracce della configurazione vincente forniscono le basi per il prossimo ciclo di raccomandazioni. Scopri [come funziona](optimization-how-it-works.md).
## Esempio: descrizioni degli strumenti di A/B test
È possibile utilizzare lo stesso schema di pacchetto di configurazione per testare descrizioni ottimizzate degli strumenti. A differenza dei A/B test dei prompt di sistema, in cui l'agente legge direttamente il pacchetto, il Gateway applica delle modifiche alla descrizione dello strumento. AgentCore Quando l'agente chiama `tools/list` tramite il gateway, il gateway legge il pacchetto di configurazione e restituisce le descrizioni degli strumenti con le eccezioni applicate. Non sono necessarie modifiche al codice dell'agente.
Per i dettagli su come il gateway applica le sostituzioni alla descrizione degli strumenti, consulta [Comportamento sulle destinazioni MCP](gateway-rules-propagation.md#gateway-rules-propagation-mcp).
### Pacchetti di configurazione
Pacchetto di controllo: descrizioni attuali degli strumenti:
```
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
```
Pacchetto terapeutico: descrizioni degli strumenti ottimizzate sulla base di una raccomandazione:
```
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
```
### Come funziona
1. Quando l'agente chiama `tools/list` tramite il gateway (obiettivi MCP), il A/B test assegna ogni sessione a una variante (controllo o trattamento) sul gateway e risolve il pacchetto di configurazione corrispondente.
1. Gateway legge il pacchetto di configurazione e restituisce le descrizioni degli strumenti con le sostituzioni applicate.
1. L'agente utilizza le descrizioni restituite per la selezione degli strumenti: non sono necessarie modifiche al codice dell'agente.
### Crea il 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
```
I passaggi rimanenti (inviare traffico, ottenere risultati, implementare il vincitore) sono identici al precedente esempio di prompt di sistema.
## Risoluzione dei problemi
Per la risoluzione dei problemi relativi ai A/B test (come i risultati mancanti dopo l'invio del traffico), consulta [Risoluzione dei problemi nella guida al routing](ab-testing-target-based.md#target-based-troubleshooting) basata sulla destinazione.