設定バンドルを使用して A/B テストを実行する

テストする変更が純粋な設定である場合は、設定バンドルパターンを使用します。異なるシステムプロンプト、異なるモデル ID、または異なるツールの説明です。両方のバリアントは、異なる設定バンドルバージョンを持つ同じ AgentCore ランタイムで実行されます。AgentCore Gateway はW3C ヘッダーを介して各リクエストに正しいバンドルリファレンスを挿入し、エージェントが実行時に読み取ります。つまり、1 つの AgentCore ランタイムと 1 つのオンライン評価設定をデプロイします。

設定バンドル A/B テストのキー設定:

テストする変更にコード変更、フレームワークのアップグレード、またはまったく異なるエージェントの実装が含まれる場合は、代わりにターゲットベースのルーティングを使用します。「ターゲットベースのルーティングで A/B テストを実行する」を参照してください。

このチュートリアルでは、例としてカスタマーサポートエージェントを使用します。エージェントは、注文検索、返品、割引リクエストを処理します。エージェントをデプロイし、異なるシステムプロンプト (制御と処理) を使用して 2 つの設定バンドルを作成し、A/B テストを作成し、トラフィックを送信し、結果を確認して、勝者をデプロイします。

ステップ 1: プロジェクトを作成する

AgentCore CLI を使用してプロジェクトを作成します。

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

ステップ 2: ランタイムを追加する

エージェントランタイムを追加します。

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

プロジェクト構造:

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

ステップ 3: エージェントコードを更新してデプロイする

を以下app/csAgent/main.pyに置き換えます。キーの追加は、実行時にアクティブな設定バンドルを読み取るBeforeModelCallEventフックです。

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

カスタマーサポートエージェントを AgentCore ランタイムにデプロイします。

agentcore deploy

デプロイ後、出力のランタイム ARN を書き留めます (例: arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/csAgent-abc123)。設定バンドルを作成するには、これが必要です。

エージェントが実行されていることを確認します。

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

BeforeModelCallEvent フックは LLM 呼び出しの前に起動し、リクエストコンテキストからアクティブな設定バンドルを読み取ります。A/B テスト中、AgentCore Gateway は各セッションをバリアントに割り当て、対応するバンドルリファレンスを W3C バゲージヘッダーを介して伝播します。ランタイムはこれを を通じて利用可能にするためBedrockAgentCoreContext、コントロールセッションはバンドル v1 を受信し、処理セッションはバンドル v2 を受信します。エージェントは受信したバンドル内のどのシステムプロンプトも適用します。

詳細については、「実行時に設定バンドルを使用する」を参照してください。

ステップ 4: 設定バンドルを作成する

2 つの設定バンドルを作成します。1 つは制御用 (現在のプロンプト）、もう 1 つは処理用 (最適化されたプロンプト) です。A/B テストでは、これらの間でトラフィックを分割して、どのプロンプトがより良い評価者スコアを生成するかを測定します。

コントロールバンドル — 現在のシステムプロンプト:

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

処理バンドル — よりプロアクティブにするようエージェントに指示する最適化されたシステムプロンプト。

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

デプロイのたびに、出力のバンドル ARN とバージョン ID を書き留めます。A/B テストを作成するときに必要になります。

ステップ 5: オンライン評価設定を作成する

A/B テストでは、両方のバリアントのセッションをスコアリングするためのオンライン評価設定が必要です。オンライン評価は、ライブトラフィックに対して評価者を実行し、A/B テストの統計エンジンにスコアをフィードします。

設定バンドルバリアントの場合は、共有 AgentCore ランタイムをモニタリングする単一のオンライン評価設定を作成します。

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

agentcore deploy

デプロイ後、出力からオンライン評価設定 ARN を書き留めます。A/B テストを作成するときに必要になります。

評価者のオプションと設定の詳細については、「オンライン評価の作成」を参照してください。

ステップ 6: ゲートウェイとターゲットを作成する

config-bundle A/B テストは AgentCore Gateway を介してトラフィックをルーティングするため、テストを開始する前にゲートウェイとそのターゲットがすでにデプロイされている必要があります。ランタイムをhttp-runtimeターゲットとするゲートウェイを追加し、以下をデプロイします。

agentcore add gateway --name csGateway

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

agentcore deploy

ステップ 7: A/B テストを作成する

コントロールプロンプトと処理プロンプトの間でトラフィックを 80/20 に分割する A/B テストを作成します。どちらのバリアントも、同じ AgentCore ランタイムの設定バンドルを参照し、スコアリング用に単一のオンライン評価設定を共有します。

ステップ 8: AgentCore Gateway 経由でトラフィックを送信する

A/B テストの実行後、AgentCore Gateway HTTP エンドポイントを介してトラフィックを送信します。AgentCore Gateway は、ランタイムセッション ID に基づいて各リクエストをバリアント (コントロールまたは処理) に割り当てます。

バリアント割り当ての仕組み

AgentCore Gateway は、 X-Amzn-Bedrock-AgentCore-Runtime-Session-Idヘッダーを使用して、提供する設定バンドルバリアントを決定します。このヘッダーはオプションです。指定しない場合、ランタイムはセッション ID を自動的に生成します。次に、AgentCore Gateway はセッション ID (指定したかランタイムで生成されたかにかかわらず) を使用して、設定されたトラフィックの重みに基づいてリクエストをバリアントに割り当てます。

セッション割り当てはスティッキーです。セッション ID がバリアントに割り当てられると、同じセッション ID を持つ後続のすべてのリクエストは同じバリアントにルーティングされます。これにより、トラフィックの分割に応じてバリアント間で新しいセッションを分散しながら、セッション内で一貫したエクスペリエンスを確保できます。

テスト用のトラフィックを生成する

次のスクリプトを として保存しloadgen.sh、 <gateway-id>と をデプロイ出力の値<target-name>に置き換えます。

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

スクリプトを実行します。

bash loadgen.sh

ステップ 9: 結果を取得する

A/B テストをポーリングして、サンプルサイズの増加に応じて結果をモニタリングします。ポーリングは統計的有効性には影響しません。

結果の解釈

結果構造とフィールド定義の詳細な説明については、「ターゲットベースのルーティングガイド」の「結果を理解する」を参照してください。

ステップ 10: 結果を確認し、A/B テストを停止する

A/B テストが統計的有意性に達したら、結果を確認し、実験を停止します。

ステップ 11: 勝者をデプロイする

A/B テストを停止した後、すべてのトラフィックを優先設定バンドルバージョンにルーティングします。

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

promote は A/B テストを停止し (まだ実行中の場合）、コントロール設定バンドルを更新して処理バージョンを使用します。agentcore deploy を実行して変更を適用します。

または、次のいずれかを実行して、勝者を手動でデプロイすることもできます。

次の手順

勝者をデプロイした後:

例: A/B テストツールの説明

同じ設定バンドルパターンを使用して、最適化されたツールの説明をテストできます。エージェントがバンドルを直接読み取るシステムプロンプト A/B テストとは異なり、ツールの説明の上書きは AgentCore Gateway によって適用されます。エージェントがゲートウェイtools/list経由で を呼び出すと、ゲートウェイは設定バンドルを読み取り、オーバーライドが適用されたツールの説明を返します。エージェントコードの変更は必要ありません。

ゲートウェイがツールの説明オーバーライドを適用する方法の詳細については、「MCP ターゲットの動作」を参照してください。

設定バンドル

コントロールバンドル — 現在のツールの説明:

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

治療バンドル — レコメンデーションから最適化されたツールの説明:

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

仕組み

A/B テストを作成する

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

残りのステップ (トラフィックの送信、結果の取得、勝者のデプロイ) は、前述のシステムプロンプトの例と同じです。

トラブルシューティング

A/B テストの問題 (トラフィック送信後の結果の欠落など) のトラブルシューティングについては、「ターゲットベースのルーティングガイド」の「トラブルシューティング」を参照してください。