Usa i pacchetti di configurazione in fase di esecuzione

L'agente legge la configurazione da un pacchetto in fase di esecuzione per applicare le impostazioni dinamiche senza ridistribuire il codice. Il gateway e il runtime propagano il riferimento al pacchetto tramite le intestazioni baggage di W3C, quindi il codice dell'agente non deve mai sapere quale versione è attiva; legge qualsiasi configurazione sia presente nel contesto della richiesta corrente.

Il gateway inserisce l'ARN del pacchetto e suddivide il traffico in entrata con diverse versioni del pacchetto. Lo stesso codice agente, eseguito nello stesso runtime, si comporta in modo diverso in base alla versione del bundle che riceve.

Propagazione dell'intestazione del bagaglio

Quando un A/B test è attivo, il AgentCore Gateway assegna ogni sessione a una variante e inserisce il riferimento al pacchetto di configurazione corrispondente nella richiesta come intestazione W3C Baggage. Il runtime analizza automaticamente questa intestazione e rende disponibile la configurazione del pacchetto al codice dell'agente tramite. BedrockAgentCoreContext

Il bagaglio contiene due chiavi:

Puoi anche far passare il bagaglio manualmente invocando direttamente l'agente (ad esempio, durante i test):

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 produzione, non è necessario costruire il bagaglio manualmente. Il gateway lo gestisce automaticamente durante A/B i test.

BedrockAgentCoreContext integrazione

La BedrockAgentCoreContext classe (dall'bedrock-agentcoreSDK) fornisce un get_config_bundle() metodo che restituisce la configurazione per la richiesta corrente. Analizza BedrockAgentCoreApp automaticamente le intestazioni dei bagagli, risolve la versione del pacchetto dall'API Control Plane e memorizza il risultato nella 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()restituisce l'configurationoggetto per il componente corrispondente all'ARN del runtime. Se nella richiesta non è presente alcun riferimento al pacchetto (ad esempio, quando nessun A/B test è attivo e nessun bagaglio è stato superato), restituisce un dict vuoto.

Puoi anche controllare il riferimento non elaborato al pacchetto:

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 con gancio BeforeModelCallEvent

Lo schema consigliato per gli agenti Strands consiste nell'utilizzare un BeforeModelCallEvent hook che aggiorni dinamicamente il prompt di sistema dell'agente prima di ogni chiamata del modello. L'agente viene creato una volta a livello di modulo e l'hook lo modifica per richiesta:

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

L'BeforeModelCallEventhook viene attivato prima di ogni chiamata LLM, quindi le modifiche al pacchetto di configurazione hanno effetto immediato senza riavviare il runtime.

Agente Strands con costruzione per richiesta

Se devi applicare più campi di configurazione (ID modello, temperatura, strumenti), crea un nuovo agente per richiesta invece di usare 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 agente

Per LangGraph gli agenti, leggi il pacchetto di configurazione all'inizio di ogni chiamata e passa i valori al tuo grafico:

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

Agente Google ADK

Per gli agenti creati con l'Agent Development Kit (ADK) di Google, leggi il pacchetto di configurazione durante la creazione dell'agente:

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

Agente OpenAI SDK

Per gli agenti che utilizzano l'SDK OpenAI con Amazon Bedrock, leggi il pacchetto di configurazione per impostare il modello e il prompt di sistema:

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

Elegante ripiego

Fornisci sempre i valori predefiniti durante la lettura dalla configurazione del pacchetto. Ciò garantisce il corretto funzionamento dell'agente anche quando non è attivo alcun A/B test, il recupero del pacchetto fallisce o il pacchetto non contiene la chiave prevista.

get_config_bundle()restituisce un dict vuoto quando non è presente alcun riferimento al bundle. Se la chiamata API sottostante fallisce, l'eccezione si propaga. Includi la chiamata in uno try/except per una degradazione graduale:

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}