보균자 헤더 전파 BedrockAgentCoreContext 통합 BeforeModelCallEvent 후크가 있는 Strands 에이전트 요청당 구성으로 에이전트를 스트랜드합니다.LangGraph 에이전트 Google ADK 에이전트 OpenAI SDK 에이전트 유예 폴백

런타임 시 구성 번들 사용

에이전트는 런타임에 번들에서 구성을 읽어 코드를 재배포하지 않고 동적 설정을 적용합니다. 게이트웨이와 런타임은 W3C 헤더를 통해 번들 참조를 전파하므로 에이전트 코드는 어떤 버전이 활성 상태인지 알 필요가 없으며 현재 요청 컨텍스트에 있는 구성을 읽습니다.

참고

구성 번들 통합에는 bedrock-agentcore-sdk-python 버전 1.8 이상이 필요합니다. 의 get_config_bundle() 메서드는이 버전부터 BedrockAgentCoreContext 사용할 수 있습니다.

게이트웨이는 번들 ARN을 주입하고 수신 트래픽을 다른 번들 버전으로 분할합니다. 동일한 런타임에서 실행되는 동일한 에이전트 코드는 수신하는 번들 버전에 따라 다르게 작동합니다.

보균자 헤더 전파

A/B 테스트가 활성화되면 AgentCore Gateway는 각 세션을 변형에 할당하고 해당 구성 번들 참조를 요청에 W3C 헤더로 주입합니다. 런타임은이 헤더를 자동으로 구문 분석하고를 통해 에이전트 코드에서 번들 구성을 사용할 수 있도록 합니다BedrockAgentCoreContext.

웨이저에는 두 개의 키가 있습니다.

aws.agentcore.configbundle_arn - 구성 번들의 전체 ARN
aws.agentcore.configbundle_version - 번들의 버전 ID

에이전트를 직접 호출할 때(예: 테스트 중) 수동으로 웨이터를 전달할 수도 있습니다.


import boto3
import json
import uuid

rt_client = boto3.client("bedrock-agentcore", region_name="us-west-2")

BUNDLE_ARN = "arn:aws:bedrock-agentcore:us-west-2:123456789012:configuration-bundle/myAgentConfig-a1b2c3d4e5"
BUNDLE_VERSION = "12345678-1234-1234-1234-123456789012"

baggage = (
    f"aws.agentcore.configbundle_arn={BUNDLE_ARN},"
    f"aws.agentcore.configbundle_version={BUNDLE_VERSION}"
)

response = rt_client.invoke_agent_runtime(
    agentRuntimeArn="arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/MyAgent-abc123",
    runtimeSessionId=str(uuid.uuid4()),
    payload=json.dumps({"prompt": "What is the status of order ORD-1001?"}).encode(),
    baggage=baggage,
)

print(response["response"].read().decode("utf-8"))

프로덕션 환경에서는 수작업할 필요가 없습니다. 게이트웨이는 A/B 테스트 중에 이를 자동으로 처리합니다.

BedrockAgentCoreContext 통합

BedrockAgentCoreContext 클래스(bedrock-agentcoreSDK에서)는 현재 요청에 대한 구성을 반환하는 get_config_bundle() 메서드를 제공합니다. 는 BedrockAgentCoreApp 자동으로 헤더를 구문 분석하고 컨트롤 플레인 API에서 번들 버전을 확인하며 결과를 캐싱합니다.


from bedrock_agentcore.runtime import BedrockAgentCoreContext

# Returns the configuration dict for your component, or {} if no bundle is in context
config = BedrockAgentCoreContext.get_config_bundle()

system_prompt = config.get("system_prompt", "You are a helpful assistant.")
model_id = config.get("model_id", "global.anthropic.claude-sonnet-4-5-20250929-v1:0")

get_config_bundle()는 런타임 ARN과 일치하는 구성 요소의 configuration 객체를 반환합니다. 요청에 번들 참조가 없는 경우(예: A/B 테스트가 활성 상태가 아니고 웨이터링이 통과되지 않은 경우) 빈 dict를 반환합니다.

원시 번들 참조를 검사할 수도 있습니다.


ref = BedrockAgentCoreContext.get_config_bundle_ref()
if ref:
    print(f"Bundle ID: {ref.bundle_id}")
    print(f"Bundle ARN: {ref.bundle_arn}")
    print(f"Version: {ref.bundle_version}")

BeforeModelCallEvent 후크가 있는 Strands 에이전트

Strands 에이전트에 권장되는 패턴은 모든 모델 호출 전에 에이전트의 시스템 프롬프트를 동적으로 업데이트하는 BeforeModelCallEvent 후크를 사용하는 것입니다. 에이전트는 모듈 수준에서 한 번 생성되며 후크는 요청당 에이전트를 수정합니다.


from strands import Agent
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 assistant."


def dynamic_config_hook(event: BeforeModelCallEvent):
    """Read config bundle and apply system prompt before every model call."""
    config_bundle = BedrockAgentCoreContext.get_config_bundle()
    event.agent.system_prompt = config_bundle.get("system_prompt", DEFAULT_SYSTEM_PROMPT)


agent = Agent(
    model=BedrockModel(model_id=DEFAULT_MODEL_ID),
    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": str(result)}


if __name__ == "__main__":
    app.run()

BeforeModelCallEvent 후크는 모든 LLM 호출 전에 실행되므로 런타임을 다시 시작하지 않고 구성 번들 변경 사항이 즉시 적용됩니다.

요청당 구성으로 에이전트를 스트랜드합니다.

더 많은 구성 필드(모델 ID, 온도, 도구)를 적용해야 하는 경우 후크를 사용하는 대신 요청당 새 에이전트를 빌드합니다.


from strands import Agent
from strands.models.bedrock import BedrockModel
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 assistant."


def build_agent() -> Agent:
    """Build a fresh agent per request with config bundle applied."""
    config = BedrockAgentCoreContext.get_config_bundle()
    model_id = config.get("model_id", DEFAULT_MODEL_ID)
    system_prompt = config.get("system_prompt", DEFAULT_SYSTEM_PROMPT)

    model_kwargs = {"model_id": model_id}
    temperature = config.get("temperature")
    if temperature is not None:
        model_kwargs["temperature"] = temperature

    return Agent(
        model=BedrockModel(**model_kwargs),
        system_prompt=system_prompt,
    )


@app.entrypoint
def invoke(payload, context):
    agent = build_agent()
    result = agent(payload.get("prompt", "Hello"))
    return {"response": str(result)}


if __name__ == "__main__":
    app.run()

LangGraph 에이전트

LangGraph 에이전트의 경우 각 호출 시작 시 구성 번들을 읽고 값을 그래프에 전달합니다.


from langchain_aws import ChatBedrock
from langgraph.graph import StateGraph, MessagesState, START, END
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 assistant."


def build_graph():
    """Build a LangGraph graph with config bundle applied."""
    config = BedrockAgentCoreContext.get_config_bundle()
    model_id = config.get("model_id", DEFAULT_MODEL_ID)
    system_prompt = config.get("system_prompt", DEFAULT_SYSTEM_PROMPT)

    model = ChatBedrock(model_id=model_id)

    def call_model(state: MessagesState):
        messages = [{"role": "system", "content": system_prompt}] + state["messages"]
        response = model.invoke(messages)
        return {"messages": [response]}

    graph = StateGraph(MessagesState)
    graph.add_node("model", call_model)
    graph.add_edge(START, "model")
    graph.add_edge("model", END)
    return graph.compile()


@app.entrypoint
def invoke(payload, context):
    graph = build_graph()
    result = graph.invoke({"messages": [{"role": "user", "content": payload.get("prompt", "Hello")}]})
    return {"response": result["messages"][-1].content}


if __name__ == "__main__":
    app.run()

Google ADK 에이전트

Google의 에이전트 개발 키트(ADK)로 빌드된 에이전트의 경우 에이전트를 구성할 때 구성 번들을 읽습니다.


from google.adk.agents import LlmAgent
from google.adk.models.lite_llm import LiteLlm
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 assistant."


def build_agent() -> LlmAgent:
    """Build an ADK agent with config bundle applied."""
    config = BedrockAgentCoreContext.get_config_bundle()
    model_id = config.get("model_id", DEFAULT_MODEL_ID)
    system_prompt = config.get("system_prompt", DEFAULT_SYSTEM_PROMPT)

    return LlmAgent(
        name="my_agent",
        model=LiteLlm(model=f"bedrock/{model_id}"),
        instruction=system_prompt,
    )


@app.entrypoint
def invoke(payload, context):
    agent = build_agent()
    # ADK agent invocation logic
    result = agent.invoke(payload.get("prompt", "Hello"))
    return {"response": str(result)}


if __name__ == "__main__":
    app.run()

OpenAI SDK 에이전트

Amazon Bedrock에서 OpenAI SDK를 사용하는 에이전트의 경우 구성 번들을 읽고 모델 및 시스템 프롬프트를 설정합니다.


from openai import OpenAI
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 assistant."

client = OpenAI()


@app.entrypoint
def invoke(payload, context):
    config = BedrockAgentCoreContext.get_config_bundle()
    model_id = config.get("model_id", DEFAULT_MODEL_ID)
    system_prompt = config.get("system_prompt", DEFAULT_SYSTEM_PROMPT)

    response = client.chat.completions.create(
        model=model_id,
        messages=[
            {"role": "system", "content": system_prompt},
            {"role": "user", "content": payload.get("prompt", "Hello")},
        ],
    )
    return {"response": response.choices[0].message.content}


if __name__ == "__main__":
    app.run()

유예 폴백

번들 구성에서 읽을 때는 항상 기본값을 제공합니다. 이렇게 하면 활성 A/B 테스트가 없거나 번들 가져오기가 실패하거나 번들에 예상 키가 포함되지 않은 경우에도 에이전트가 올바르게 작동합니다.

get_config_bundle()는 번들 참조가 없는 경우 빈 dict를 반환합니다. 기본 API 호출이 실패하면 예외가 전파됩니다. 호출을 시도로 래핑하거나 정상적인 성능 저하를 제외합니다.


from bedrock_agentcore.runtime import BedrockAgentCoreContext

DEFAULT_SYSTEM_PROMPT = "You are a helpful customer support assistant."
DEFAULT_MODEL_ID = "global.anthropic.claude-sonnet-4-5-20250929-v1:0"


def get_config_with_fallback():
    """Read config bundle with graceful fallback to defaults."""
    try:
        config = BedrockAgentCoreContext.get_config_bundle()
        if not config:
            return {"system_prompt": DEFAULT_SYSTEM_PROMPT, "model_id": DEFAULT_MODEL_ID}
        return config
    except Exception:
        return {"system_prompt": DEFAULT_SYSTEM_PROMPT, "model_id": DEFAULT_MODEL_ID}

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

번들 삭제

구성 번들 암호화