Propagasi header bagasi BedrockAgentCoreContext integrasi Agen helai dengan BeforeModelCallEvent kait Agen helai dengan konstruksi per permintaan LangGraph agen Agen Google ADK Agen OpenAI SDK Fallback yang anggun

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; kode tersebut membaca konfigurasi apa pun yang ada dalam konteks permintaan saat ini.

catatan

Integrasi bundel konfigurasi memerlukan bedrock-agentcore-sdk-python versi 1.8 atau yang lebih baru. get_config_bundle()Metode aktif BedrockAgentCoreContext tersedia mulai versi ini dan seterusnya.

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 mana yang diterimanya.

Propagasi header bagasi

Ketika A/B pengujian aktif, AgentCore Gateway menetapkan setiap sesi ke varian dan menyuntikkan referensi bundel konfigurasi yang sesuai ke dalam permintaan sebagai header Bagasi W3C. Runtime mengurai header ini secara otomatis dan membuat konfigurasi bundel tersedia untuk kode agen Anda melaluiBedrockAgentCoreContext.

Bagasi berisi dua kunci:

aws.agentcore.configbundle_arn— ARN penuh dari bundel konfigurasi
aws.agentcore.configbundle_version— ID versi bundel

Anda juga dapat meneruskan 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

Kel BedrockAgentCoreContext as (dari bedrock-agentcore SDK) menyediakan get_config_bundle() metode yang mengembalikan konfigurasi untuk permintaan saat ini. Secara BedrockAgentCoreApp otomatis mengurai header bagasi, menyelesaikan versi bundel dari API pesawat 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), itu mengembalikan dict 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 disarankan 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(str(payload.get("prompt", "Hello")))
    return {"response": str(result)}


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

H BeforeModelCallEvent ook diaktifkan sebelum setiap panggilan LLM, sehingga 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 hook:


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(str(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 berikan 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": str(payload.get("prompt", "Hello"))}]})
    return {"response": result["messages"][-1].content}


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

Agen Google ADK

Untuk agen yang dibuat dengan Google Agent Development Kit (ADK), 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(str(payload.get("prompt", "Hello")))
    return {"response": str(result)}


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

Agen OpenAI SDK

Untuk agen yang menggunakan OpenAI SDK dengan Amazon Bedrock, baca bundel konfigurasi untuk mengatur 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": str(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 yang ada. Jika panggilan API yang mendasarinya gagal, pengecualian menyebar. Bungkus panggilan dengan degrad try/except asi 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}

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Hapus paket

Enkripsi bundel konfigurasi