Gunakan bundel konfigurasi saat runtime

Agen Anda membaca konfigurasi dari bundel saat runtime untuk menerapkan pengaturan dinamis tanpa menerapkan ulang kode. Gateway dan runtime menyebarkan referensi bundel melalui header bagasi W3C, sehingga kode agen Anda tidak perlu mengetahui versi mana yang aktif; ia membaca konfigurasi apa pun yang ada dalam konteks permintaan saat ini.

Gateway menyuntikkan bundel ARN dan membagi lalu lintas masuk dengan versi bundel yang berbeda. Kode agen yang sama, berjalan di runtime yang sama, berperilaku berbeda berdasarkan versi bundel yang diterimanya.

Perbanyakan header bagasi

Saat A/B pengujian aktif, AgentCore Gateway menetapkan setiap sesi ke varian dan menyuntikkan referensi bundel konfigurasi yang sesuai ke dalam permintaan sebagai header Baggage W3C. Runtime mem-parsing header ini secara otomatis dan membuat konfigurasi bundel tersedia untuk kode agen Anda melalui. BedrockAgentCoreContext

Bagasi berisi dua kunci:

Anda juga dapat melewati bagasi secara manual saat memanggil agen secara langsung (misalnya, selama pengujian):

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"))

Dalam produksi, Anda tidak perlu membuat bagasi secara manual. Gateway menangani ini secara otomatis selama A/B pengujian.

BedrockAgentCoreContext integrasi

BedrockAgentCoreContextKelas (dari bedrock-agentcore SDK) menyediakan get_config_bundle() metode yang mengembalikan konfigurasi untuk permintaan saat ini. BedrockAgentCoreAppSecara otomatis mem-parsing header bagasi, menyelesaikan versi bundel dari API bidang kontrol, dan menyimpan hasilnya.

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()mengembalikan configuration objek untuk komponen yang cocok dengan ARN runtime Anda. Jika tidak ada referensi bundel yang ada dalam permintaan (misalnya, ketika tidak ada A/B tes yang aktif dan tidak ada bagasi yang dilewati), ia mengembalikan dikte kosong.

Anda juga dapat memeriksa referensi bundel mentah:

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}")

Agen helai dengan BeforeModelCallEvent kait

Pola yang direkomendasikan untuk agen Strands adalah menggunakan BeforeModelCallEvent hook yang secara dinamis memperbarui prompt sistem agen sebelum setiap panggilan model. Agen dibuat sekali di tingkat modul, dan hook memodifikasinya per permintaan:

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()

BeforeModelCallEventKait diaktifkan sebelum setiap panggilan LLM, jadi perubahan bundel konfigurasi segera berlaku tanpa memulai ulang runtime.

Agen helai dengan konstruksi per permintaan

Jika Anda perlu menerapkan lebih banyak bidang konfigurasi (ID model, suhu, alat), buat agen baru per permintaan alih-alih menggunakan kait:

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 agen

Untuk LangGraph agen, baca bundel konfigurasi di awal setiap pemanggilan dan teruskan nilai ke grafik Anda:

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()

Agen Google ADK

Untuk agen yang dibuat dengan Kit Pengembangan Agen (ADK) Google, baca bundel konfigurasi saat membuat agen:

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()

Agen SDK OpenAI

Untuk agen yang menggunakan OpenAI SDK dengan Amazon Bedrock, baca bundel konfigurasi untuk menyetel model dan prompt sistem:

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()

Fallback yang anggun

Selalu berikan nilai default saat membaca dari konfigurasi bundel. Ini memastikan agen Anda bekerja dengan benar bahkan ketika tidak ada A/B pengujian yang aktif, pengambilan bundel gagal, atau bundel tidak berisi kunci yang diharapkan.

get_config_bundle()mengembalikan dict kosong ketika tidak ada referensi bundel hadir. Jika panggilan API yang mendasarinya gagal, pengecualian akan menyebar. Bungkus panggilan dalam a try/except untuk degradasi yang anggun:

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}