Jalankan A/B pengujian dengan bundel konfigurasi

Gunakan pola bundel konfigurasi saat perubahan yang Anda uji murni konfigurasi — prompt sistem yang berbeda, ID model yang berbeda, atau deskripsi alat yang berbeda. Kedua varian berjalan pada AgentCore Runtime yang sama dengan versi bundel konfigurasi yang berbeda. AgentCore Gateway menyuntikkan referensi bundel yang benar ke setiap permintaan melalui header bagasi W3C, dan agen Anda membacanya saat runtime. Ini berarti Anda menerapkan satu AgentCore Runtime dan satu konfigurasi evaluasi online.

Konfigurasi kunci untuk A/B pengujian bundel konfigurasi:

Jika perubahan yang Anda uji melibatkan perubahan kode, peningkatan kerangka kerja, atau implementasi agen yang sama sekali berbeda, gunakan perutean berbasis target sebagai gantinya. Lihat Menjalankan A/B pengujian dengan perutean berbasis target.

Panduan ini menggunakan agen dukungan pelanggan sebagai contoh. Agen menangani pencarian pesanan, pengembalian, dan permintaan diskon. Anda akan menyebarkan agen, membuat dua bundel konfigurasi dengan prompt sistem yang berbeda (kontrol dan perawatan), membuat A/B tes, mengirim lalu lintas, meninjau hasil, dan menyebarkan pemenang.

Langkah 1: Buat proyek

Buat proyek dengan AgentCore CLI:

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

Langkah 2: Tambahkan runtime

Tambahkan runtime agen:

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

Struktur proyek:

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

Langkah 3: Perbarui kode agen dan terapkan

Ganti app/csAgent/main.py dengan yang berikut ini. Penambahan kuncinya adalah BeforeModelCallEvent hook yang membaca bundel konfigurasi aktif saat runtime:

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

Perbarui app/csAgent/pyproject.toml dependensi:

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

Menyebarkan agen dukungan pelanggan ke AgentCore Runtime:

agentcore deploy

Setelah penerapan, perhatikan ARN runtime dari output (misalnya,). arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/csAgent-abc123 Anda akan membutuhkannya untuk membuat bundel konfigurasi.

Verifikasi agen sedang berjalan:

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

BeforeModelCallEventHook diaktifkan sebelum setiap panggilan LLM, membaca bundel konfigurasi aktif dari konteks permintaan. Selama A/B pengujian, AgentCore Gateway menetapkan setiap sesi ke varian dan menyebarkan referensi bundel yang sesuai melalui header bagasi W3C. Runtime membuat ini tersediaBedrockAgentCoreContext, jadi sesi kontrol menerima bundel v1 dan sesi perawatan menerima bundel v2 — agen menerapkan prompt sistem mana pun yang ada dalam bundel yang diterimanya.

Untuk detail selengkapnya, lihat Menggunakan bundel konfigurasi saat runtime.

Langkah 4: Buat bundel konfigurasi

Buat dua bundel konfigurasi - satu untuk kontrol (prompt saat ini) dan satu untuk perawatan (prompt yang dioptimalkan). A/B Tes akan membagi lalu lintas di antara ini untuk mengukur prompt mana yang menghasilkan skor evaluator yang lebih baik.

Bundel kontrol - prompt sistem saat ini:

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

Bundel perawatan — prompt sistem yang dioptimalkan yang menginstruksikan agen untuk lebih proaktif:

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

Setelah setiap penerapan, catat bundel ARN dan ID versi dari output - Anda akan memerlukannya saat membuat A/B pengujian.

Langkah 5: Buat konfigurasi evaluasi online

A/B Tes memerlukan konfigurasi evaluasi online untuk menilai sesi dari kedua varian. Evaluasi online menjalankan evaluator terhadap lalu lintas langsung dan memberi skor umpan ke mesin statistik A/B tes.

Untuk varian bundel konfigurasi, buat konfigurasi evaluasi online tunggal yang memantau AgentCore Runtime bersama:

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

agentcore deploy

Setelah penerapan, perhatikan konfigurasi evaluasi online ARN dari output — Anda akan membutuhkannya saat membuat pengujian. A/B

Untuk detail selengkapnya tentang opsi dan konfigurasi evaluator, lihat Membuat evaluasi online.

Langkah 6: Buat gateway dan target

A/B Tes config-bundle merutekan lalu lintas melalui AgentCore Gateway, jadi gateway dan targetnya harus sudah digunakan sebelum Anda memulai pengujian. Tambahkan gateway dengan runtime sebagai http-runtime target, lalu terapkan:

agentcore add gateway --name csGateway

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

agentcore deploy

Langkah 7: Buat A/B tes

Buat A/B tes yang membagi lalu lintas 80/20 antara petunjuk kontrol dan perawatan. Kedua varian mereferensikan bundel konfigurasi pada AgentCore Runtime yang sama dan berbagi satu konfigurasi evaluasi online untuk penilaian.

Langkah 8: Kirim lalu lintas melalui AgentCore Gateway

Setelah A/B pengujian berjalan, kirim lalu lintas melalui titik akhir HTTP AgentCore Gateway. AgentCore Gateway menetapkan setiap permintaan ke varian (kontrol atau perlakuan) berdasarkan ID sesi runtime.

Cara kerja penugasan varian

AgentCore Gateway menggunakan X-Amzn-Bedrock-AgentCore-Runtime-Session-Id header untuk menentukan varian bundel konfigurasi mana yang akan disajikan. Header ini opsional — jika Anda tidak menyediakannya, runtime akan menghasilkan ID sesi secara otomatis. AgentCore Gateway kemudian menggunakan ID sesi (apakah Anda menyediakannya atau runtime yang dihasilkannya) untuk menetapkan permintaan ke varian berdasarkan bobot lalu lintas yang dikonfigurasi.

Penetapan sesi bersifat lengket: setelah ID sesi ditetapkan ke varian, semua permintaan berikutnya dengan ID sesi yang sama merutekan ke varian yang sama. Ini memastikan pengalaman yang konsisten dalam sesi sambil tetap mendistribusikan sesi baru di seluruh varian sesuai dengan pembagian lalu lintas Anda.

Menghasilkan lalu lintas untuk pengujian

Simpan skrip berikut sebagailoadgen.sh, ganti <gateway-id> dan <target-name> dengan nilai dari keluaran penerapan Anda:

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

Jalankan skrip .

bash loadgen.sh

Langkah 9: Dapatkan hasil

Jajak pendapat A/B tes untuk memantau hasil saat ukuran sampel bertambah. Polling tidak mempengaruhi validitas statistik.

Menafsirkan hasil

Untuk penjelasan rinci tentang struktur hasil dan definisi bidang, lihat Memahami hasil dalam panduan perutean berbasis target.

Langkah 10: Konfirmasikan hasil dan hentikan A/B tes

Setelah A/B tes mencapai signifikansi statistik, tinjau hasilnya dan hentikan percobaan.

Langkah 11: Menyebarkan pemenang

Setelah menghentikan A/B pengujian, rute semua lalu lintas ke versi bundel konfigurasi pemenang.

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

promotemenghentikan A/B pengujian (jika masih berjalan) dan memperbarui bundel konfigurasi kontrol untuk menggunakan versi perawatan. Jalankan agentcore deploy untuk menerapkan perubahan.

Atau, Anda dapat menyebarkan pemenang secara manual dengan melakukan salah satu hal berikut:

Langkah selanjutnya

Setelah menyebarkan pemenang:

Contoh: deskripsi alat A/B pengujian

Anda dapat menggunakan pola bundel konfigurasi yang sama untuk menguji deskripsi alat yang dioptimalkan. Tidak seperti A/B pengujian prompt sistem di mana agen membaca bundel secara langsung, penggantian deskripsi alat diterapkan oleh Gateway. AgentCore Saat agen memanggil tools/list melalui gateway, gateway membaca bundel konfigurasi dan mengembalikan deskripsi alat dengan penggantian yang diterapkan. Tidak diperlukan perubahan kode agen.

Untuk detail tentang cara gateway menerapkan penggantian deskripsi alat, lihat Perilaku pada target MCP.

Bundel konfigurasi

Bundel kontrol - deskripsi alat saat ini:

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

Bundel perawatan - deskripsi alat yang dioptimalkan dari rekomendasi:

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

Cara kerjanya

Buat A/B tes

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

Langkah-langkah yang tersisa (mengirim lalu lintas, mendapatkan hasil, menyebarkan pemenang) identik dengan contoh prompt sistem sebelumnya.

Pemecahan masalah

Untuk mengatasi masalah A/B pengujian (seperti hasil yang hilang setelah mengirim lalu lintas), lihat Pemecahan masalah dalam panduan perutean berbasis target.