Propagación del encabezado del equipaje BedrockAgentCoreContext integración Agente Strands con BeforeModelCallEvent gancho Agente de Strands con construcción por solicitud LangGraph agente Agente ADK de Google Agente OpenAI SDK Una alternativa elegante

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

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

nota

La integración del paquete de configuración requiere la bedrock-agentcore-sdk-python versión 1.8 o posterior. El get_config_bundle() método on BedrockAgentCoreContext está disponible a partir de esta versión.

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 según la versión del paquete que reciba.

Propagación del encabezado del equipaje

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

El equipaje contiene dos llaves:

aws.agentcore.configbundle_arn— ARN completo del paquete de configuración
aws.agentcore.configbundle_version— ID de versión del paquete

También puedes repartir el equipaje manualmente llamando directamente al agente (por ejemplo, durante la prueba):


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

Durante la producción, no es necesario fabricar el equipaje manualmente. La pasarela gestiona esto 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 las cabeceras 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 en tiempo de ejecución. Si no hay ninguna referencia al 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 Strands con BeforeModelCallEvent gancho

El patrón recomendado para los agentes de Strands es utilizar un BeforeModelCallEvent enlace que actualice dinámicamente el indicador del sistema del agente antes de cada llamada al modelo. El agente se crea una vez a nivel de módulo y el enlace lo modifica en cada 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(str(payload.get("prompt", "Hello")))
    return {"response": str(result)}


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

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

Agente de Strands con construcción por solicitud

Si necesitas aplicar más campos de configuración (ID de modelo, temperatura, herramientas), crea un agente nuevo por solicitud en lugar de usar 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(str(payload.get("prompt", "Hello")))
    return {"response": str(result)}


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

LangGraph agente

En el caso de los LangGraph agentes, lea el paquete de configuración al principio de cada invocación y pase los valores a su 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": str(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(str(payload.get("prompt", "Hello")))
    return {"response": str(result)}


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

Agente OpenAI SDK

Para los agentes que utilizan el SDK de OpenAI con Amazon Bedrock, lea el paquete de configuración para configurar el modelo y el indicador 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": str(payload.get("prompt", "Hello"))},
        ],
    )
    return {"response": response.choices[0].message.content}


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

Una alternativa elegante

Proporcione 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, se produzca un error en la búsqueda del paquete o el paquete no contenga la clave esperada.

get_config_bundle()devuelve un diccionario vacío cuando no hay ninguna referencia al paquete. Si la llamada a la API subyacente falla, la excepción se propaga. Envuelva la llamada en un try/except para que se degrade sin problemas:


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}

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Elimine un paquete

Cifrado del paquete de configuración