Utiliser des ensembles de configuration lors de l'exécution

Votre agent lit la configuration depuis un bundle au moment de l'exécution pour appliquer des paramètres dynamiques sans redéployer le code. La passerelle et le moteur d'exécution propagent la référence du bundle via les en-têtes de bagages du W3C, de sorte que le code de votre agent n'a jamais besoin de savoir quelle version est active ; il lit la configuration contenue dans le contexte de demande actuel.

La passerelle injecte l'ARN du bundle et divise le trafic entrant entre différentes versions du bundle. Le même code d'agent, exécuté dans le même environnement d'exécution, se comporte différemment en fonction de la version du bundle qu'il reçoit.

Propagation de l'entête

Lorsqu'un A/B test est actif, la AgentCore passerelle attribue chaque session à une variante et injecte la référence du bundle de configuration correspondante dans la demande sous forme d'en-tête W3C Baggage. Le moteur d'exécution analyse automatiquement cet en-tête et met la configuration du bundle à la disposition du code de votre agent viaBedrockAgentCoreContext.

Le bagage contient deux clés :

Vous pouvez également transmettre les bagages manuellement lorsque vous appelez directement l'agent (par exemple, pendant les tests) :

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

En production, il n'est pas nécessaire de construire les bagages manuellement. La passerelle gère cela automatiquement lors A/B des tests.

BedrockAgentCoreContext intégration

La BedrockAgentCoreContext classe (issue du bedrock-agentcore SDK) fournit une get_config_bundle() méthode qui renvoie la configuration de la demande en cours. analyse BedrockAgentCoreApp automatiquement les en-têtes des bagages, résout la version du bundle à partir de l'API du plan de contrôle et met le résultat en 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()renvoie l'configurationobjet du composant correspondant à votre ARN d'exécution. Si aucune référence de bundle n'est présente dans la demande (par exemple, lorsqu'aucun A/B test n'est actif et qu'aucun bagage n'a été réussi), elle renvoie un dict vide.

Vous pouvez également inspecter la référence brute du bundle :

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

Agent à mèches avec BeforeModelCallEvent crochet

Le modèle recommandé pour les agents Strands consiste à utiliser un BeforeModelCallEvent hook qui met à jour dynamiquement l'invite système de l'agent avant chaque appel de modèle. L'agent est créé une fois au niveau du module, et le hook le modifie par demande :

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

Le BeforeModelCallEvent hook se déclenche avant chaque appel LLM, de sorte que les modifications du bundle de configuration prennent effet immédiatement sans redémarrer le moteur d'exécution.

Agent Strands avec construction à la demande

Si vous devez appliquer davantage de champs de configuration (ID du modèle, température, outils), créez un nouvel agent par requête au lieu d'utiliser un 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(payload.get("prompt", "Hello"))
    return {"response": str(result)}


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

LangGraph agent

Pour les LangGraph agents, lisez le bundle de configuration au début de chaque appel et transmettez les valeurs à votre graphe :

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

Agent Google ADK

Pour les agents créés avec le kit de développement d'agents (ADK) de Google, lisez le bundle de configuration lors de la création de l'agent :

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

Agent du SDK OpenAI

Pour les agents utilisant le SDK OpenAI avec Amazon Bedrock, lisez le bundle de configuration pour définir le modèle et l'invite système :

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

Solution de repli gracieuse

Fournissez toujours des valeurs par défaut lors de la lecture de la configuration du bundle. Cela garantit que votre agent fonctionne correctement même lorsqu'aucun A/B test n'est actif, que la récupération du bundle échoue ou que le bundle ne contient pas la clé attendue.

get_config_bundle()renvoie un dict vide lorsqu'aucune référence de bundle n'est présente. Si l'appel d'API sous-jacent échoue, l'exception se propage. Enveloppez l'appel dans un try/except pour une dégradation gracieuse :

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}