荷物ヘッダーの伝播 BedrockAgentCoreContext 統合 BeforeModelCallEvent フックを使用してエージェントをストランドするリクエストごとの構成でエージェントをストランドする LangGraph エージェント Google ADK エージェント OpenAI SDK エージェントグレースフルフォールバック

実行時に設定バンドルを使用する

エージェントは実行時にバンドルから設定を読み取り、コードを再デプロイせずに動的設定を適用します。ゲートウェイとランタイムはW3C バゲージヘッダーを介してバンドルリファレンスを伝達するため、エージェントコードはアクティブなバージョンを知る必要はなく、現在のリクエストコンテキストにある設定を読み取ります。

注記

設定バンドルの統合には、bedrock-agentcore-sdk-pythonバージョン 1.8 以降が必要です。の get_config_bundle()メソッドBedrockAgentCoreContextは、このバージョン以降から使用できます。

ゲートウェイはバンドル ARN を挿入し、受信トラフィックを異なるバンドルバージョンで分割します。同じランタイムで実行される同じエージェントコードは、受信したバンドルバージョンに応じて動作が異なります。

荷物ヘッダーの伝播

A/B テストがアクティブな場合、AgentCore Gateway は各セッションをバリアントに割り当て、対応する設定バンドルリファレンスを W3C ヘッダーとしてリクエストに挿入します。ランタイムは、このヘッダーを自動的に解析し、バンドル設定を経由でエージェントコードで使用できるようにしますBedrockAgentCoreContext。

荷物には 2 つのキーが含まれています。

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 テストがアクティブではなく、バランサーに合格しなかった場合）、空のディクトが返されます。

raw バンドルリファレンスを検査することもできます。


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 エージェントに推奨されるパターンは、モデル呼び出しの前にエージェントのシステムプロンプトを動的に更新するBeforeModelCallEventフックを使用することです。エージェントはモジュールレベルで 1 回作成され、フックはリクエストごとに変更します。


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 の Agent Development Kit (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 を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

バンドルを削除する

設定バンドルの暗号化