# Esegui un A/B test con il routing basato sulla destinazione
Usa lo schema di routing basato sulla destinazione quando la modifica che stai testando comporta modifiche al codice, un aggiornamento del framework o un'implementazione dell'agente completamente diversa. Target-based il routing indirizza il traffico tra più versioni dello stesso AgentCore Runtime (denominate endpoint) o tra Runtime completamente diversi. AgentCore Il AgentCore Gateway registra ogni endpoint come destinazione separata e indirizza ogni sessione verso un endpoint o l'altro in base ai pesi del traffico del test. A/B
Configurazione chiave per i test basati sul target: A/B
+ Configurazione della variante: `variantConfiguration.target` con il nome del target AgentCore Gateway
+ Configurazione di valutazione: `perVariantOnlineEvaluationConfig` (una configurazione di valutazione online per variante, poiché ogni endpoint ha il proprio gruppo di log)
+ Filtro Gateway: `gatewayFilter.targetPaths` elenca i percorsi intercettati dal AgentCore Gateway A/B
Questa procedura dettagliata implementa due versioni dell'agente dell'assistenza clienti, una che utilizza Claude Sonnet (controllo) e una che utilizza Claude Opus (trattamento), crea endpoint denominati per ogni versione, crea un A/B test, invia traffico, esamina i risultati e distribuisce il vincitore.
**Nota**
Questa procedura dettagliata è destinata agli agenti ospitati su un Runtime. AgentCore Se il tuo agente viene eseguito **all'esterno** AgentCore di un Runtime (un agente di terze parti o ospitato autonomamente, ad esempio su AWS Lambda), [consulta invece Esegui A/B un test per agenti ospitati all'esterno AgentCore](ab-testing-3p-agents.md) di.
Per un confronto dettagliato dei modelli di A/B test, consulta [Scelta di un](ab-testing.md#ab-testing-pattern-comparison) modello.
## Fase 1: Creare il progetto
Crea il progetto con la AgentCore CLI:
```
agentcore create --name ABTestTargetBased --no-agent
cd ABTestTargetBased
```
## Fase 2: Aggiungere il runtime
Aggiungere il runtime dell'agente. Implementerai due versioni di questo runtime, una per il controllo e una per il trattamento, quindi creerai endpoint denominati per assegnare un alias a ciascuna versione.
```
agentcore add agent \
--name csAgent \
--language Python \
--framework Strands \
--model-provider Bedrock \
--memory none \
--build CodeZip
```
Struttura del progetto:
```
ABTestTargetBased/
├── agentcore/
│ ├── agentcore.json
│ ├── aws-targets.json
│ └── cdk/
└── app/
└── csAgent/
├── main.py
└── pyproject.toml
```
## Fase 3: Implementazione delle versioni di controllo e trattamento
Sostituisci `app/csAgent/main.py` con la versione di controllo (usando Claude Sonnet):
```
"""Customer support agent — control variant."""
from strands import Agent, tool
from strands.models.bedrock import BedrockModel
from bedrock_agentcore.runtime import BedrockAgentCoreApp
app = BedrockAgentCoreApp()
MODEL_ID = "global.anthropic.claude-sonnet-4-5-20250929-v1:0"
SYSTEM_PROMPT = "You are a helpful customer support assistant for Acme Store."
@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}."
agent = Agent(
model=BedrockModel(model_id=MODEL_ID),
tools=[lookup_order, initiate_return, apply_discount],
system_prompt=SYSTEM_PROMPT,
)
@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",
]
```
Distribuisci la versione di controllo (questo crea la versione 1):
```
agentcore deploy
```
Ora aggiorna `main.py` per utilizzare un modello diverso per la variante di trattamento e distribuisci (questo crea la versione 2):
```
MODEL_ID = "global.anthropic.claude-opus-4-6-v1"
```
```
agentcore deploy
```
Crea endpoint denominati per ogni versione e distribuisci:
```
agentcore add runtime-endpoint \
--runtime csAgent \
--endpoint control \
--version 1 \
--description "Control variant — Claude Sonnet"
agentcore add runtime-endpoint \
--runtime csAgent \
--endpoint treatment \
--version 2 \
--description "Treatment variant — Claude Opus"
agentcore deploy
```
Ora hai:
+ Runtime endpoint`control`: serve la versione 1 con Claude Sonnet.
+ Runtime endpoint`treatment`: serve la versione 2 con Claude Opus.
Verifica che il runtime funzioni:
```
agentcore invoke --runtime csAgent --prompt "What is the status of order ORD-1003?"
```
Ora hai:
+ Runtime endpoint`control`: serve la versione 1 con Claude Sonnet.
+ Runtime endpoint`treatment`: serve la versione 2 con Claude Opus.
## Fase 4: Creare configurazioni di valutazione online
Ogni endpoint ha il proprio gruppo di log (il nome del gruppo di log termina con il nome dell'endpoint), quindi è necessaria una configurazione di valutazione online per variante:
```
agentcore add online-eval \
--name controlEvalTb \
--runtime csAgent \
--endpoint control \
--evaluator "Builtin.Helpfulness" \
--sampling-rate 100.0 \
--enable-on-create
agentcore add online-eval \
--name treatmentEvalTb \
--runtime csAgent \
--endpoint treatment \
--evaluator "Builtin.Helpfulness" \
--sampling-rate 100.0 \
--enable-on-create
agentcore deploy
```
Dopo ogni implementazione, prendi nota della configurazione di valutazione online ARN: ti serviranno entrambi durante la creazione A/B del test.
Per maggiori dettagli sulle opzioni e sulla configurazione del valutatore, consulta [Creare una](create-online-evaluations.md) valutazione online.
## Fase 5: Creare il gateway e gli obiettivi
Un A/B test basato su target indirizza il traffico attraverso un AgentCore gateway, pertanto il gateway e le sue due destinazioni devono essere già implementati prima di iniziare il test. Aggiungi un gateway e registra ogni endpoint di runtime come `http-runtime` destinazione, quindi distribuisci:
```
agentcore add gateway --name csGateway
agentcore add gateway-target \
--name customer-support-control \
--gateway csGateway \
--type http-runtime \
--runtime csAgent \
--runtime-endpoint control
agentcore add gateway-target \
--name customer-support-treatment \
--gateway csGateway \
--type http-runtime \
--runtime csAgent \
--runtime-endpoint treatment
agentcore deploy
```
## Fase 6: Creare il test A/B
Inizia il A/B test con`agentcore run ab-test`. Ogni variante fa riferimento a uno degli obiettivi del gateway che hai creato e dispone di una propria configurazione di valutazione online. Il comando avvia il test direttamente sul servizio rispetto al gateway già distribuito.
**Example**
```
agentcore run ab-test \
--mode target-based \
--name customerSupportTargetTest \
--gateway csGateway \
--runtime csAgent \
--control-target customer-support-control \
--treatment-target customer-support-treatment \
--control-online-eval controlEvalTb \
--treatment-online-eval treatmentEvalTb \
--control-weight 80 \
--treatment-weight 20
```
Il test viene ESEGUITO non appena il comando viene restituito. Il passaggio `--disable-on-create` per crearlo si è interrotto. Il `--gateway` flag è obbligatorio e deve fare riferimento al gateway distribuito nel passaggio 5. È 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.
```
import boto3
import uuid
REGION = "us-west-2"
ACCOUNT_ID = "123456789012"
# Runtime ARNs from Step 2 deployment output
CONTROL_RUNTIME_ARN = f"arn:aws:bedrock-agentcore:{REGION}:{ACCOUNT_ID}:runtime/ABTestTargetBased_CustomerSupportControl-abc123"
TREATMENT_RUNTIME_ARN = f"arn:aws:bedrock-agentcore:{REGION}:{ACCOUNT_ID}:runtime/ABTestTargetBased_CustomerSupportTreatment-def456"
# Online evaluation config ARNs from Step 3
CONTROL_EVAL_ARN = f"arn:aws:bedrock-agentcore:{REGION}:{ACCOUNT_ID}:online-evaluation-config/controlEvalTb-abc123"
TREATMENT_EVAL_ARN = f"arn:aws:bedrock-agentcore:{REGION}:{ACCOUNT_ID}:online-evaluation-config/treatmentEvalTb-def456"
# IAM roles
GATEWAY_ROLE_ARN = f"arn:aws:iam::{ACCOUNT_ID}:role/AgentCoreGatewayRole"
AB_TEST_ROLE_ARN = f"arn:aws:iam::{ACCOUNT_ID}:role/ABTestRole"
cp_client = boto3.client("bedrock-agentcore-control", region_name=REGION)
dp_client = boto3.client("bedrock-agentcore", region_name=REGION)
# 1. Create an AgentCore Gateway
gateway_response = cp_client.create_gateway(
name="customerSupportTargetTest-gw",
roleArn=GATEWAY_ROLE_ARN,
authorizerType="AWS_IAM",
clientToken=str(uuid.uuid4()),
)
gateway_id = gateway_response["gatewayId"]
gateway_arn = gateway_response["gatewayArn"]
print(f"Created AgentCore Gateway: {gateway_id}")
# 2. Add control runtime as an AgentCore Gateway target
cp_client.create_gateway_target(
gatewayIdentifier=gateway_id,
name="customer-support-control",
targetConfiguration={
"http": {
"agentcoreRuntime": {
"arn": CONTROL_RUNTIME_ARN,
"qualifier": "DEFAULT"
}
}
},
clientToken=str(uuid.uuid4()),
)
print("Added target: customer-support-control")
# 3. Add treatment runtime as an AgentCore Gateway target
cp_client.create_gateway_target(
gatewayIdentifier=gateway_id,
name="customer-support-treatment",
targetConfiguration={
"http": {
"agentcoreRuntime": {
"arn": TREATMENT_RUNTIME_ARN,
"qualifier": "DEFAULT"
}
}
},
clientToken=str(uuid.uuid4()),
)
print("Added target: customer-support-treatment")
# 4. Create the A/B test
response = dp_client.create_ab_test(
name="customerSupportTargetTest",
gatewayArn=gateway_arn,
roleArn=AB_TEST_ROLE_ARN,
evaluationConfig={
"perVariantOnlineEvaluationConfig": [
{"name": "C", "onlineEvaluationConfigArn": CONTROL_EVAL_ARN},
{"name": "T1", "onlineEvaluationConfigArn": TREATMENT_EVAL_ARN}
]
},
gatewayFilter={
"targetPaths": ["/customer-support-control/*"]
},
variants=[
{
"name": "C",
"weight": 80,
"variantConfiguration": {
"target": {"name": "customer-support-control"}
}
},
{
"name": "T1",
"weight": 20,
"variantConfiguration": {
"target": {"name": "customer-support-treatment"}
}
}
],
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 7: 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 a quale destinazione indirizzare il traffico. 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 allo stesso obiettivo. 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. Puoi anche copiare l'URL di invocazione completo da: `agentcore view ab-test `
```
#!/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 8: 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 del passaggio 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 = "customerSupportTargetTest-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 nelle configurazioni 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.
## Fase 9: 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 destinazione predefinita. Vedi [Visualizzare, mettere in pausa, riprendere e interrompere](ab-testing-manage.md#manage-ab-test-start-stop).
## Passaggio 10: schiera il vincitore
Dopo aver interrotto il A/B test, indirizza tutto il traffico verso la variante vincente.
```
agentcore promote ab-test -i
agentcore deploy
```
`promote`interrompe il A/B test (se è ancora in esecuzione), aggiorna l'endpoint di controllo in modo che punti alla versione del trattamento (ad esempio, eseguendo l'aggiornamento `control` dalla versione 1 alla versione 2) e rimuove l'endpoint 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 il traffico da entrambi i target verso l'obiettivo vincente.
+ **Opzione B:** rimuovi l'obiettivo perdente dal AgentCore Gateway e indirizza tutto il traffico verso il vincitore.
+ **Opzione C:** aggiorna l'obiettivo perdente in modo che punti all'endpoint vincente.
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).
## Comprendere i risultati
Quando si chiama`GetABTest`, la risposta include un `results` oggetto una volta che la pipeline di aggregazione ha elaborato un numero sufficiente di sessioni. I risultati contengono metriche per valutatore suddivise per variante.
### Struttura dei risultati
```
{
"results": {
"analysisTimestamp": "2026-04-30T18:45:00Z",
"evaluatorMetrics": [
{
"evaluatorArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:evaluator/Builtin.Helpfulness",
"controlStats": {
"variantName": "C",
"sampleSize": 24,
"mean": 0.72
},
"variantResults": [
{
"variantName": "T1",
"sampleSize": 6,
"mean": 0.85,
"absoluteChange": 0.13,
"percentChange": 18.1,
"pValue": 0.032,
"confidenceInterval": {
"lower": 0.02,
"upper": 0.24
},
"isSignificant": true
}
]
}
]
}
}
```
### Riferimento ai campi
| Campo | Description |
| --- | --- |
| `analysisTimestamp` | Data dell'ultima volta che il servizio ha calcolato le statistiche. |
| `evaluatorMetrics` | Una voce per valutatore nella configurazione di valutazione online. |
| `controlStats.mean` | Punteggio medio del valutatore in tutte le sessioni di controllo. |
| `controlStats.sampleSize` | Numero di sessioni con punteggio per la variante di controllo. |
| `variantResults[].mean` | Punteggio medio del valutatore in tutte le sessioni di trattamento. |
| `variantResults[].sampleSize` | Numero di sedute con punteggio per la variante di trattamento. |
| `variantResults[].absoluteChange` | Differenza tra media del trattamento e media di controllo. |
| `variantResults[].percentChange` | Miglioramento percentuale (positivo) o regressione (negativo) rispetto al controllo. |
| `variantResults[].pValue` | Probabilità che la differenza osservata sia dovuta al caso. Al di sotto di 0,05 indica una significatività statistica. |
| `variantResults[].confidenceInterval` | Intervallo di confidenza del 95% per la variazione assoluta (`lower`e i `upper` limiti). |
| `variantResults[].isSignificant` | `true`quando il valore p < 0,05 e le dimensioni del campione sono sufficienti. |
## Risoluzione dei problemi
### A/B il test non mostra risultati dopo l'invio del traffico
I risultati non vengono visualizzati immediatamente. Il tempo necessario dipende dal timeout della sessione configurato nella configurazione di valutazione online: una sessione viene considerata completa solo dopo che non arrivano nuove richieste entro la finestra di timeout. Al termine di una sessione, aspettatevi risultati entro circa 15 minuti.
Se i risultati non vengono ancora visualizzati dopo questa finestra:
+ **Verifica il gruppo di log di valutazione online.** La configurazione di valutazione online deve puntare al gruppo di log di output dell'agente di runtime. Se la configurazione di valutazione online fa riferimento a un gruppo di log diverso (o a uno che non riceve intervalli dal runtime), le sessioni non verranno valutate e il A/B test non produrrà mai risultati.
+ **Controlla il nome del gruppo di log.** Per il routing basato sulla destinazione, ogni endpoint ha il proprio gruppo di log (il nome del gruppo di log termina con il nome dell'endpoint). Assicurati che ogni configurazione di valutazione online faccia riferimento al gruppo di log dell'endpoint corretto.
+ **Verifica che il runtime stia emettendo intervalli.** Controlla CloudWatch i log per il gruppo di log previsto. Gli attributi chiave che stai cercando in ogni intervallo:
+ `aws.agentcore.gateway.routing_experiment_arn`
+ `aws.agentcore.gateway.routing_experiment_variant_name`(valori: `C` o`T1`)
+ `session.id`
+ **Verifica CLI-created rispetto alle configurazioni manuali.** Se è stato utilizzato`agentcore add online-eval --runtime `, la CLI configura automaticamente il gruppo di log corretto. Se hai creato la configurazione di valutazione online manualmente tramite l'API, assicurati che AgentCore Online Eval `dataSourceConfig.cloudWatchLogs.logGroupNames` Config corrisponda al gruppo di log di span del runtime.