Propagazione dell'intestazione del bagaglio BedrockAgentCoreContext integrazione Agente per fili con gancio BeforeModelCallEvent Agente Strands con costruzione per richiesta LangGraph agente Agente Google ADK Agente OpenAI SDK Elegante soluzione alternativa

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 del pacchetto tramite le intestazioni dei bagagli W3C, quindi il codice dell'agente non deve mai sapere quale versione è attiva; legge qualsiasi configurazione si trovi nel contesto corrente della richiesta.

Nota

L'integrazione del pacchetto di configurazione richiede la versione 1.8 o successiva. bedrock-agentcore-sdk-python Il get_config_bundle() metodo attivo BedrockAgentCoreContext è disponibile a partire da questa versione.

Il gateway inietta l'ARN del bundle e divide 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 pacchetto 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 del pacchetto di configurazione corrispondente nella richiesta come intestazione W3C Baggage. https://www.w3.org/TR/baggage/ Il runtime analizza automaticamente questa intestazione e rende la configurazione del pacchetto disponibile al codice dell'agente tramite. BedrockAgentCoreContext

Il bagaglio contiene due chiavi:

aws.agentcore.configbundle_arn— ARN completo del pacchetto di configurazione
aws.agentcore.configbundle_version— ID della versione del pacchetto

Puoi anche trasferire il bagaglio manualmente quando invoci 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 del piano di controllo e memorizza nella cache il risultato.


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 di 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 grezzo del 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}")

Agente per fili 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 al modello. L'agente viene creato una volta a livello di modulo e l'hook lo modifica su 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(str(payload.get("prompt", "Hello")))
    return {"response": str(result)}


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

L'BeforeModelCallEventhook si attiva prima di ogni chiamata LLM, quindi le modifiche al bundle di configurazione hanno effetto immediato senza riavviare il runtime.

Agente Strands con costruzione per richiesta

Se hai bisogno di 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(str(payload.get("prompt", "Hello")))
    return {"response": str(result)}


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

LangGraph agente

Per LangGraph gli agenti, leggete il pacchetto di configurazione all'inizio di ogni chiamata e passate i valori al 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": str(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(str(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": str(payload.get("prompt", "Hello"))},
        ],
    )
    return {"response": response.choices[0].message.content}


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

Elegante soluzione alternativa

Fornisci sempre valori predefiniti durante la lettura dalla configurazione del pacchetto. Ciò garantisce che l'agente funzioni correttamente anche quando nessun A/B test è attivo, il recupero del bundle fallisce o il bundle non contiene la chiave prevista.

get_config_bundle()restituisce un dict vuoto quando non è presente alcun riferimento al pacchetto. Se la chiamata API sottostante fallisce, l'eccezione si propaga. Confeziona la chiamata in un try/except ordine decrescente:


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}

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Eliminazione di un bundle

Crittografia del pacchetto di configurazione