Verwenden Sie zur Laufzeit Konfigurationspakete

Ihr Agent liest zur Laufzeit die Konfiguration aus einem Paket, um dynamische Einstellungen anzuwenden, ohne Code erneut bereitzustellen. Das Gateway und die Runtime geben die Paketreferenz über die W3C-Baggack-Header weiter, sodass Ihr Agentencode nie wissen muss, welche Version aktiv ist. Er liest die Konfiguration, die sich im aktuellen Anforderungskontext befindet.

Das Gateway injiziert den Bundle-ARN und teilt den eingehenden Verkehr auf verschiedene Bundle-Versionen auf. Derselbe Agentencode, der in derselben Laufzeit ausgeführt wird, verhält sich je nachdem, welche Bundle-Version er empfängt, unterschiedlich.

Weitergabe von Baggage Headern

Wenn ein A/B Test aktiv ist, weist das AgentCore Gateway jede Sitzung einer Variante zu und fügt die entsprechende Referenz für das Konfigurationspaket als W3C-Baggage-Header in die Anfrage ein. Die Runtime analysiert diesen Header automatisch und stellt die Bundle-Konfiguration Ihrem Agentencode über zur Verfügung. BedrockAgentCoreContext

Das Gepäck enthält zwei Schlüssel:

Sie können Gepäck auch manuell übergeben, wenn Sie den Agenten direkt anrufen (z. B. beim Testen):

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

In der Produktion müssen Sie Gepäck nicht manuell zusammenstellen. Das Gateway erledigt dies während des A/B Tests automatisch.

BedrockAgentCoreContext Integration

Die BedrockAgentCoreContext Klasse (aus dem bedrock-agentcore SDK) stellt eine get_config_bundle() Methode bereit, die die Konfiguration für die aktuelle Anfrage zurückgibt. Der analysiert BedrockAgentCoreApp automatisch die Baggage-Header, löst die Bundle-Version aus der API der Kontrollebene auf und speichert das Ergebnis im Cache.

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()gibt das configuration Objekt für die Komponente zurück, die Ihrem Runtime-ARN entspricht. Wenn die Anfrage keine Paketreferenz enthält (z. B. wenn kein A/B Test aktiv ist und kein Paket bestanden wurde), wird ein leeres Diktat zurückgegeben.

Sie können sich auch die unformatierte Bundle-Referenz ansehen:

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

Strands Agent mit BeforeModelCallEvent Haken

Das empfohlene Muster für Strings-Agenten besteht darin, einen BeforeModelCallEvent Hook zu verwenden, der die Systemaufforderung des Agenten vor jedem Modellaufruf dynamisch aktualisiert. Der Agent wird einmal auf Modulebene erstellt, und der Hook ändert ihn pro Anfrage:

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

Der BeforeModelCallEvent Hook wird vor jedem LLM-Aufruf ausgelöst, sodass Änderungen am Konfigurationspaket sofort wirksam werden, ohne dass die Laufzeit neu gestartet werden muss.

Strands Agent mit Erstellung auf Anfrage

Wenn Sie mehr Konfigurationsfelder (Modell-ID, Temperatur, Tools) anwenden müssen, erstellen Sie pro Anfrage einen neuen Agenten, anstatt einen Hook zu verwenden:

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 Agent

Für LangGraph Agenten lesen Sie das Konfigurationspaket zu Beginn jedes Aufrufs und übergeben die Werte an Ihr Diagramm:

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-Agent

Für Agenten, die mit dem Agent Development Kit (ADK) von Google erstellt wurden, lesen Sie bei der Erstellung des Agenten das Konfigurationspaket:

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-Agent

Für Agenten, die das OpenAI SDK mit Amazon Bedrock verwenden, lesen Sie das Konfigurationspaket, um das Modell und die Systemaufforderung festzulegen:

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

Anmutiger Fallback

Geben Sie beim Lesen aus der Bundle-Konfiguration immer Standardwerte an. Dadurch wird sichergestellt, dass Ihr Agent auch dann ordnungsgemäß funktioniert, wenn kein A/B Test aktiv ist, der Bundle-Abruf fehlschlägt oder das Bundle nicht den erwarteten Schlüssel enthält.

get_config_bundle()gibt ein leeres Diktat zurück, wenn keine Bundle-Referenz vorhanden ist. Wenn der zugrunde liegende API-Aufruf fehlschlägt, wird die Ausnahme weitergegeben. Verpacken Sie den Aufruf in ein, um eine ordentliche try/except Degradierung zu erzielen:

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}