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:

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 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'BeforeModelCallEventhook 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 dipendenzeapp/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'BeforeModelCallEventhook 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 disponibileBedrockAgentCoreContext, 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.

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.

Per maggiori dettagli sulle opzioni e sulla configurazione del valutatore, consulta Creare una valutazione online.

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.

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-Idintestazione 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 comeloadgen.sh, sostituendo <gateway-id> e <target-name> 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-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

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.

Interpretazione dei risultati

Per una spiegazione dettagliata della struttura dei risultati e delle definizioni dei campi, consulta Comprendere i risultati 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.

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

promoteinterrompe 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:

Fasi successive

Dopo aver schierato il vincitore:

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.

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

Crea il 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

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 basata sulla destinazione.