구성 번들을 사용하여 A/B 테스트 실행

테스트하는 변경 사항이 다른 시스템 프롬프트, 다른 모델 ID 또는 다른 도구 설명과 같은 순전히 구성인 경우 구성 번들 패턴을 사용합니다. 두 변형 모두 서로 다른 구성 번들 버전으로 동일한 AgentCore 런타임에서 실행됩니다. AgentCore Gateway는 W3C 파티커 헤더를 통해 각 요청에 올바른 번들 참조를 주입하고 에이전트는 런타임에 이를 읽습니다. 즉, AgentCore 런타임 하나와 온라인 평가 구성 하나를 배포합니다.

구성 번들 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 수수료 헤더를 통해 해당 번들 참조를 전파합니다. 런타임을 사용하면를 통해이 기능을 사용할 수 있으므로 제어 세션은 번들 v1BedrockAgentCoreContext을 수신하고 처리 세션은 번들 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 테스트 생성

제어 프롬프트와 처리 프롬프트 간에 트래픽을 80/20으로 분할하는 A/B 테스트를 생성합니다. 두 변형 모두 동일한 AgentCore 런타임에서 구성 번들을 참조하고 점수를 매기기 위한 단일 온라인 평가 구성을 공유합니다.

8단계: AgentCore 게이트웨이를 통해 트래픽 전송

A/B 테스트를 실행한 후 AgentCore Gateway HTTP 엔드포인트를 통해 트래픽을 전송합니다. AgentCore Gateway는 런타임 세션 ID를 기반으로 변형(제어 또는 처리)에 각 요청을 할당합니다.

변형 할당 작동 방식

AgentCore Gateway는 X-Amzn-Bedrock-AgentCore-Runtime-Session-Id 헤더를 사용하여 제공할 구성 번들 변형을 결정합니다. 이 헤더는 선택 사항입니다. 제공하지 않으면 런타임이 세션 ID를 자동으로 생성합니다. 그런 다음 AgentCore Gateway는 세션 ID(제공했는지 또는 런타임에서 생성했는지 여부)를 사용하여 구성된 트래픽 가중치를 기반으로 변형에 요청을 할당합니다.

세션 할당은 고정됩니다. 세션 ID가 변형에 할당되면 동일한 세션 ID를 가진 모든 후속 요청이 동일한 변형으로 라우팅됩니다. 이렇게 하면 트래픽 분할에 따라 변형 간에 새 세션을 분산하면서 세션 내에서 일관된 경험을 보장할 수 있습니다.

테스트를 위한 트래픽 생성

다음 스크립트를 로 저장하여 <gateway-id> 및 <target-name>를 배포 출력의 값으로 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

스크립트를 실행합니다.

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 테스트 문제(예: 트래픽 전송 후 결과 누락)를 해결하려면 대상 기반 라우팅 가이드의 문제 해결을 참조하세요.