ターゲットベースのルーティングで A/B テストを実行する

テストする変更にコード変更、フレームワークのアップグレード、またはまったく異なるエージェントの実装が含まれる場合は、ターゲットベースのルーティングパターンを使用します。ターゲットベースのルーティングは、同じ AgentCore ランタイム (名前付きエンドポイント) の複数のバージョン間、またはまったく異なる AgentCore ランタイム間でトラフィックをルーティングします。AgentCore Gateway は、各エンドポイントを個別のターゲットとして登録し、A/B テストのトラフィックの重みに基づいて、各セッションを 1 つのエンドポイントまたは別のエンドポイントにルーティングします。

ターゲットベースの A/B テストのキー設定:

このチュートリアルでは、2 つのバージョンのカスタマーサポートエージェントをデプロイします。1 つは Claude Sonnet (コントロール) を使用し、もう 1 つは Claude Opus (評価) を使用します。各バージョンの名前付きエンドポイントを作成し、A/B テストを作成し、トラフィックを送信し、結果を確認して、勝者をデプロイします。

A/B テストパターンの詳細な比較については、「パターンの選択」を参照してください。

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

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

agentcore create --name ABTestTargetBased --no-agent
cd ABTestTargetBased

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

エージェントランタイムを追加します。このランタイムの 2 つのバージョンをデプロイします。1 つは制御用、もう 1 つは処理用です。次に、各バージョンにエイリアスを付ける名前付きエンドポイントを作成します。

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

プロジェクト構造:

ABTestTargetBased/
├── agentcore/
│   ├── agentcore.json
│   ├── aws-targets.json
│   └── cdk/
└── app/
    └── csAgent/
        ├── main.py
        └── pyproject.toml

ステップ 3: コントロールバージョンと処理バージョンをデプロイする

をコントロールバージョンapp/csAgent/main.pyに置き換えます (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()

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

コントロールバージョンをデプロイします (これによりバージョン 1 が作成されます）。

agentcore deploy

次に、 を更新main.pyして処理バリアントに別のモデルを使用し、デプロイします (これによりバージョン 2 が作成されます）。

MODEL_ID = "global.anthropic.claude-opus-4-6-v1"

agentcore deploy

バージョンごとに名前付きエンドポイントを作成し、デプロイします。

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

これで、次のことができるようになりました。

ランタイムが動作していることを確認します。

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

これで、次のことができるようになりました。

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

各エンドポイントには独自のロググループ (ロググループ名はエンドポイント名で終わる) があるため、バリアントごとに 1 つのオンライン評価設定が必要です。

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

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

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

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

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

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

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

で A/B テストを開始しますagentcore run ab-test。各バリアントは、作成したゲートウェイターゲットの 1 つを参照し、独自のオンライン評価設定があります。コマンドは、既にデプロイされているゲートウェイに対して、サービスで直接テストを開始します。

ステップ 7: 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>に置き換えます。から完全な呼び出し URL をコピーすることもできますagentcore view ab-test <ab-test-id>。

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

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

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

結果の解釈

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

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

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

A/B テストを停止した後、すべてのトラフィックを勝者バリアントにルーティングします。

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

promote は A/B テストを停止し (まだ実行されている場合）、コントロールエンドポイントを更新して処理バージョン (バージョン 1 controlからバージョン 2 への更新など）、処理エンドポイントを削除します。agentcore deploy を実行して変更を適用します。

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

次の手順

勝者をデプロイした後:

結果について

を呼び出すとGetABTest、集約パイプラインが十分なセッションを処理すると、レスポンスに results オブジェクトが含まれます。結果には、バリアント別に分類された評価者ごとのメトリクスが含まれます。

結果構造

{
  "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
          }
        ]
      }
    ]
  }
}

フィールドリファレンス

トラブルシューティング

A/B テストでは、トラフィックの送信後に結果は表示されません

結果はすぐには表示されません。所要時間は、オンライン評価設定で設定されたセッションタイムアウトによって異なります。セッションは、タイムアウトウィンドウ内に新しいリクエストが到着しなかった場合にのみ完了したと見なされます。セッションが終了したら、約 15 分以内に結果が予想されます。

このウィンドウの後に結果が表示されない場合: