Führen Sie einen A/B Test mit Konfigurationspaketen durch

Verwenden Sie das Muster des Konfigurationspakets, wenn es sich bei der Änderung, die Sie testen, um eine reine Konfiguration handelt — eine andere Systemaufforderung, eine andere Modell-ID oder andere Toolbeschreibungen. Beide Varianten laufen auf derselben AgentCore Runtime mit unterschiedlichen Versionen des Konfigurationspakets. Das AgentCore Gateway fügt jeder Anfrage über W3C-Baggage-Header die richtige Paketreferenz hinzu, und Ihr Agent liest sie zur Laufzeit. Das bedeutet, dass Sie eine AgentCore Runtime- und eine Online-Evaluierungskonfiguration bereitstellen.

Schlüsselkonfiguration für A/B Tests im Konfigurationspaket:

Wenn die Änderung, die Sie testen, Codeänderungen, ein Framework-Upgrade oder eine völlig andere Agentenimplementierung beinhaltet, verwenden Sie stattdessen zielbasiertes Routing. Weitere Informationen finden Sie unter Ausführen eines A/B Tests mit zielbasiertem Routing.

In dieser exemplarischen Vorgehensweise wird ein Kundendienstmitarbeiter als Beispiel verwendet. Der Agent bearbeitet Bestellungen, Rücksendungen und Rabattanfragen. Sie stellen den Agenten bereit, erstellen zwei Konfigurationspakete mit unterschiedlichen Systemaufforderungen (Steuerung und Behandlung), erstellen einen A/B Test, senden Traffic, überprüfen die Ergebnisse und stellen den Gewinner bereit.

Schritt 1: Erstellen Sie das Projekt

Erstellen Sie das Projekt mit der AgentCore CLI:

agentcore create --name ABTestConfigBased --no-agent
cd ABTestConfigBased

Schritt 2: Fügen Sie die Laufzeit hinzu

Fügen Sie die Agenten-Laufzeit hinzu:

agentcore add agent \
  --name csAgent \
  --language Python \
  --framework Strands \
  --model-provider Bedrock \
  --memory none \
  --build CodeZip

Struktur des Projekts:

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

Schritt 3: Aktualisieren Sie den Agentencode und stellen Sie ihn bereit

Ersetzen Sie ihn app/csAgent/main.py durch den folgenden Text. Die wichtigste Ergänzung ist der BeforeModelCallEvent Hook, der das aktive Konfigurationspaket zur Laufzeit liest:

"""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()

app/csAgent/pyproject.tomlAbhängigkeiten aktualisieren:

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",
]

Stellen Sie den Kundensupport-Mitarbeiter für AgentCore Runtime bereit:

agentcore deploy

Notieren Sie sich nach der Bereitstellung den Runtime-ARN aus der Ausgabe (z. B.arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/csAgent-abc123). Sie benötigen ihn, um Konfigurationspakete zu erstellen.

Stellen Sie sicher, dass der Agent läuft:

agentcore invoke --prompt "What is the status of order ORD-1003?"

Der BeforeModelCallEvent Hook wird vor jedem LLM-Aufruf ausgelöst und liest das aktive Konfigurationspaket aus dem Anforderungskontext. Während eines A/B Tests weist das AgentCore Gateway jede Sitzung einer Variante zu und gibt die entsprechende Bundle-Referenz über W3C-Baggage-Header weiter. Die Runtime stellt dies zur VerfügungBedrockAgentCoreContext, sodass Kontrollsitzungen Paket v1 und Behandlungssitzungen Paket v2 erhalten — der Agent wendet die Systemaufforderung an, die sich in dem Paket befindet, das er empfängt.

Weitere Informationen finden Sie unter Verwenden von Konfigurationspaketen zur Laufzeit.

Schritt 4: Konfigurationspakete erstellen

Erstellen Sie zwei Konfigurationspakete — eines für die Steuerung (aktuelle Eingabeaufforderung) und eines für die Behandlung (optimierte Eingabeaufforderung). Im A/B Test wird der Traffic zwischen diesen aufgeteilt, um zu messen, welche Aufforderung zu besseren Ergebnissen der Evaluatoren führt.

Kontrollpaket — die aktuelle Systemaufforderung:

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

Behandlungspaket — eine optimierte Systemaufforderung, die den Agenten anweist, proaktiver zu handeln:

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

Notieren Sie sich nach jeder Bereitstellung den Bundle-ARN und die Versions-ID aus der Ausgabe — Sie benötigen diese, wenn Sie den A/B Test erstellen.

Schritt 5: Erstellen Sie eine Online-Testkonfiguration

Für einen A/B Test ist eine Online-Evaluierungskonfiguration erforderlich, um Sitzungen aus beiden Varianten zu bewerten. Bei der Online-Auswertung werden die Evaluatoren anhand des Live-Traffics verglichen und die Ergebnisse werden in die Statistik-Engine des A/B Tests eingespeist.

Erstellen Sie für Varianten des Konfigurationspakets eine einzige Konfiguration für die Online-Evaluierung, die die gemeinsame AgentCore Laufzeit überwacht:

agentcore add online-eval \
  --name customerSupportEval \
  --runtime csAgent \
  --evaluator "Builtin.Helpfulness" \
  --sampling-rate 100.0 \
  --enable-on-create

agentcore deploy

Notieren Sie sich nach der Bereitstellung den ARN der Online-Evaluierungskonfiguration aus der Ausgabe — Sie benötigen ihn, wenn Sie den A/B Test erstellen.

Weitere Informationen zu den Optionen und der Konfiguration des Evaluators finden Sie unter Online-Evaluierung erstellen.

Schritt 6: Erstellen Sie das Gateway und das Ziel

Ein A/B Config-Bundle-Test leitet den Datenverkehr über ein AgentCore Gateway weiter, sodass das Gateway und sein Ziel bereits bereitgestellt sein müssen, bevor Sie den Test starten. Fügen Sie ein Gateway mit der Runtime als http-runtime Ziel hinzu und stellen Sie dann Folgendes bereit:

agentcore add gateway --name csGateway

agentcore add gateway-target \
  --name customer-support \
  --gateway csGateway \
  --type http-runtime \
  --runtime csAgent

agentcore deploy

Schritt 7: Erstellen Sie den A/B Test

Erstellen Sie einen A/B Test, der 80/20 den Verkehr zwischen den Kontroll- und Behandlungsaufforderungen aufteilt. Beide Varianten verweisen auf Konfigurationspakete auf derselben AgentCore Runtime und verwenden eine einzige Online-Evaluierungskonfiguration für die Bewertung.

Schritt 8: Senden Sie den Datenverkehr über das Gateway AgentCore

Nachdem der A/B Test ausgeführt wurde, senden Sie den Datenverkehr über den AgentCore Gateway-HTTP-Endpunkt. Das AgentCore Gateway weist jede Anfrage auf der Grundlage der Runtime-Sitzungs-ID einer Variante (Kontrolle oder Behandlung) zu.

Wie funktioniert die Variantenzuweisung

Das AgentCore Gateway verwendet den X-Amzn-Bedrock-AgentCore-Runtime-Session-Id Header, um zu bestimmen, welche Variante des Konfigurationspakets bereitgestellt werden soll. Dieser Header ist optional — wenn Sie ihn nicht angeben, generiert die Laufzeit automatisch eine Sitzungs-ID. Das AgentCore Gateway verwendet dann die Sitzungs-ID (unabhängig davon, ob Sie sie angegeben haben oder von der Runtime generiert wurde), um die Anfrage einer Variante zuzuweisen, die auf Ihren konfigurierten Verkehrsgewichten basiert.

Die Sitzungszuweisung ist flexibel: Sobald einer Variante eine Sitzungs-ID zugewiesen wurde, werden alle nachfolgenden Anfragen mit derselben Sitzungs-ID an dieselbe Variante weitergeleitet. Dadurch wird ein einheitliches Erlebnis innerhalb einer Sitzung gewährleistet und gleichzeitig neue Sitzungen entsprechend Ihrer Traffic-Aufteilung auf verschiedene Varianten verteilt.

Generieren Sie Traffic zum Testen

Speichern Sie das folgende Skript unter <gateway-id> und ersetzen Sie es <target-name> mit den Werten aus Ihrer Bereitstellungsausgabe: loadgen.sh

#!/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

Führen Sie das Skript aus:

bash loadgen.sh

Schritt 9: Ergebnisse abrufen

Fragen Sie den A/B Test ab, um die Ergebnisse zu überwachen, wenn die Stichprobengröße zunimmt. Umfragen haben keinen Einfluss auf die statistische Validität.

Interpretation der Ergebnisse

Eine ausführliche Erläuterung der Ergebnisstruktur und der Felddefinitionen finden Sie im Leitfaden zum zielbasierten Routing unter Grundlegendes zu Ergebnissen.

Schritt 10: Bestätigen Sie die Ergebnisse und beenden Sie den Test A/B

Sobald der A/B Test statistische Signifikanz erreicht hat, überprüfen Sie die Ergebnisse und beenden Sie das Experiment.

Schritt 11: Setze den Gewinner ein

Nachdem Sie den A/B Test beendet haben, leiten Sie den gesamten Datenverkehr an die Version des erfolgreichen Konfigurationspakets weiter.

agentcore promote ab-test -i <ab-test-id>
agentcore deploy

promotestoppt den A/B Test (falls er noch läuft) und aktualisiert das Kontrollkonfigurationspaket, sodass es die Behandlungsversion verwendet. Führen Sie agentcore deploy den Befehl aus, um die Änderungen zu übernehmen.

Alternativ können Sie den Gewinner manuell bereitstellen, indem Sie einen der folgenden Schritte ausführen:

Nächste Schritte

Nach der Bereitstellung des Gewinners:

Beispiel: Beschreibungen A/B von Testtools

Sie können dasselbe Konfigurationspaketmuster verwenden, um optimierte Werkzeugbeschreibungen zu testen. Im Gegensatz zu A/B Tests mit Systemaufforderung, bei denen der Agent das Bundle direkt liest, werden Überschreibungen der Toolbeschreibung vom AgentCore Gateway angewendet. Wenn der Agent tools/list über das Gateway anruft, liest das Gateway das Konfigurationspaket und gibt Toolbeschreibungen mit angewendeten Überschreibungen zurück. Es sind keine Änderungen am Agentencode erforderlich.

Einzelheiten dazu, wie das Gateway Überschreibungen von Toolbeschreibungen anwendet, finden Sie unter Verhalten auf MCP-Zielen.

Konfigurationspakete

Kontrollpaket — aktuelle Toolbeschreibungen:

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

Behandlungspaket — optimierte Werkzeugbeschreibungen anhand einer Empfehlung:

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

Funktionsweise

Erstellen Sie den 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

Die verbleibenden Schritte (Datenverkehr senden, Ergebnisse abrufen, Gewinner bereitstellen) sind identisch mit dem vorherigen Beispiel für eine Systemaufforderung.

Fehlerbehebung

Informationen zur Behebung von A/B Testproblemen (z. B. fehlende Ergebnisse nach dem Senden von Datenverkehr) finden Sie im Leitfaden zur zielbasierten Weiterleitung unter Problembehandlung.