Utilice paquetes de configuración en tiempo de ejecución

El agente lee la configuración de un paquete en tiempo de ejecución para aplicar la configuración dinámica sin tener que volver a implementar el código. La puerta de enlace y el motor de ejecución propagan la referencia del paquete a través de las cabeceras de equipaje del W3C, por lo que el código de su agente nunca necesitará saber qué versión está activa; lee cualquier configuración que se encuentre en el contexto de la solicitud actual.

La puerta de enlace inyecta el ARN del paquete y divide el tráfico entrante en diferentes versiones del paquete. El mismo código de agente, que se ejecuta en el mismo tiempo de ejecución, se comporta de forma diferente en función de la versión del paquete que reciba.

Propagación del encabezado del equipaje

Cuando hay una A/B prueba activa, el AgentCore Gateway asigna cada sesión a una variante e inserta la referencia del paquete de configuración correspondiente en la solicitud como encabezado de equipaje del W3C. El motor de ejecución analiza este encabezado automáticamente y pone la configuración del paquete a disposición del código de su agente a través de. BedrockAgentCoreContext

El equipaje contiene dos llaves:

También puede pasar el equipaje manualmente llamando directamente al agente (por ejemplo, durante las pruebas):

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 la fase de producción, no es necesario armar el equipaje manualmente. La pasarela lo gestiona automáticamente durante A/B las pruebas.

BedrockAgentCoreContext integración

La BedrockAgentCoreContext clase (del bedrock-agentcore SDK) proporciona un get_config_bundle() método que devuelve la configuración de la solicitud actual. Analiza BedrockAgentCoreApp automáticamente los encabezados del equipaje, resuelve la versión del paquete desde la API del plano de control y almacena en caché el resultado.

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()devuelve el configuration objeto del componente que coincide con su ARN de ejecución. Si no hay ninguna referencia de paquete en la solicitud (por ejemplo, cuando no hay ninguna A/B prueba activa y no se ha superado ningún equipaje), devuelve un dictado vacío.

También puedes inspeccionar la referencia del paquete sin procesar:

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 de hebras con BeforeModelCallEvent gancho

El patrón recomendado para los agentes de Strands es utilizar un BeforeModelCallEvent gancho que actualice dinámicamente el indicador del sistema del agente antes de cada llamada del modelo. El agente se crea una vez a nivel de módulo y el gancho lo modifica según la solicitud:

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

El BeforeModelCallEvent enlace se activa antes de cada llamada a LLM, por lo que los cambios en el paquete de configuración se aplican inmediatamente sin reiniciar el tiempo de ejecución.

Strand Agent con una construcción por solicitud

Si necesita aplicar más campos de configuración (ID de modelo, temperatura, herramientas), cree un agente nuevo por solicitud en lugar de utilizar un enlace:

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

En el caso de los LangGraph agentes, lee el paquete de configuración al principio de cada invocación y pasa los valores al gráfico:

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 ADK de Google

En el caso de los agentes creados con el kit de desarrollo de agentes (ADK) de Google, lee el paquete de configuración al crear el 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 de SDK para OpenAI

Para los agentes que utilizan el SDK OpenAI con Amazon Bedrock, lean el paquete de configuración para establecer el modelo y la línea de comandos del 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()

Una alternativa elegante

Indique siempre los valores predeterminados al leer la configuración del paquete. Esto garantiza que el agente funcione correctamente incluso cuando no haya ninguna A/B prueba activa, la búsqueda del paquete falle o el paquete no contenga la clave esperada.

get_config_bundle()devuelve un diccionario vacío cuando no hay ninguna referencia de paquete. Si se produce un error en la llamada a la API subyacente, la excepción se propaga. Incluya la llamada en una forma try/except para degradarla de forma elegante:

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}