套件標頭傳播 BedrockAgentCoreContext 整合使用 BeforeModelCallEvent 勾點的 Strands 代理程式具有每個請求建構的 Strands 代理程式 LangGraph 代理程式 Google ADK 代理程式 OpenAI SDK 代理程式優雅後援

在執行時間使用組態套件

您的代理程式會在執行時間從套件讀取組態，以套用動態設定，而無需重新部署程式碼。閘道和執行期會透過 W3C 套件標頭傳播套件參考，因此您的代理程式程式碼永遠不需要知道哪個版本處於作用中狀態；它會讀取目前請求內容中的任何組態。

注意

組態套件整合需要 1bedrock-agentcore-sdk-python.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-agentcore SDK) 提供傳回目前請求組態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 測試且未傳遞任何封包時），它會傳回空白的口號。

您也可以檢查原始套件參考：


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 呼叫之前觸發，因此組態套件變更會立即生效，而不會重新啟動執行時間。

具有每個請求建構的 Strands 代理程式

如果您需要套用更多組態欄位（模型 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 開發套件的代理程式，請閱讀組態套件以設定模型和系統提示：


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。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

刪除套件

組態套件加密