使用組態套件執行 A/B 測試

當您測試的變更純為組態時，請使用組態套件模式：不同的系統提示、不同的模型 ID 或不同的工具描述。這兩個變體都以不同的組態套件版本在相同的 AgentCore 執行期上執行。AgentCore Gateway 透過 W3C 套件標頭將正確的套件參考注入每個請求，您的代理程式會在執行時間讀取。這表示您部署一個 AgentCore 執行期和一個線上評估組態。

組態套件 A/B 測試的金鑰組態：

如果您要測試的變更涉及程式碼變更、架構升級或完全不同的客服人員實作，請改用目標型路由。請參閱使用目標型路由執行 A/B 測試。

本演練使用客戶支援客服人員做為範例。客服人員會處理訂單查詢、傳回和折扣請求。您將部署代理程式、使用不同的系統提示 （控制和處理） 建立兩個組態套件、建立 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：建立組態套件

建立兩個組態套件：一個用於控制 （目前提示），另一個用於處理 （最佳化提示）。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 測試

建立 A/B 測試，將控制和處理提示之間的流量分割為 80/20。這兩個變體都參考相同 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 指派給變體後，所有具有相同工作階段 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 測試問題進行故障診斷 （例如傳送流量後遺失結果），請參閱 目標型路由指南中的故障診斷。