Use pacotes de configuração em tempo de execução

Seu agente lê a configuração de um pacote em tempo de execução para aplicar configurações dinâmicas sem reimplantar o código. O gateway e o tempo de execução propagam a referência do pacote por meio dos cabeçalhos de bagagem do W3C, para que seu código de agente nunca precise saber qual versão está ativa; ele lê qualquer configuração que esteja no contexto de solicitação atual.

O gateway injeta o ARN do pacote e divide o tráfego de entrada em diferentes versões do pacote. O mesmo código do agente, executado no mesmo tempo de execução, se comporta de forma diferente com base na versão do pacote que ele recebe.

Propagação do cabeçalho da bagagem

Quando um A/B teste está ativo, o AgentCore Gateway atribui cada sessão a uma variante e injeta a referência do pacote de configuração correspondente na solicitação como um cabeçalho de bagagem do W3C. O tempo de execução analisa esse cabeçalho automaticamente e disponibiliza a configuração do pacote para o código do seu agente via. BedrockAgentCoreContext

A bagagem contém duas chaves:

Você também pode passar a bagagem manualmente ao chamar diretamente o agente (por exemplo, durante o teste):

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

Na produção, você não precisa construir a bagagem manualmente. O gateway lida com isso automaticamente durante o A/B teste.

BedrockAgentCoreContext integração

A BedrockAgentCoreContext classe (do bedrock-agentcore SDK) fornece um get_config_bundle() método que retorna a configuração da solicitação atual. O analisa BedrockAgentCoreApp automaticamente os cabeçalhos de bagagem, resolve a versão do pacote a partir da API do plano de controle e armazena em cache o 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()retorna o configuration objeto do componente correspondente ao ARN do seu tempo de execução. Se nenhuma referência de pacote estiver presente na solicitação (por exemplo, quando nenhum A/B teste está ativo e nenhuma bagagem foi aprovada), ela retornará um ditado vazio.

Você também pode inspecionar a referência bruta do pacote:

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 fios com BeforeModelCallEvent gancho

O padrão recomendado para agentes Strands é usar um BeforeModelCallEvent gancho que atualiza dinamicamente o prompt do sistema do agente antes de cada chamada de modelo. O agente é criado uma vez no nível do módulo e o gancho o modifica por solicitação:

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

O BeforeModelCallEvent gancho é acionado antes de cada chamada do LLM, então as alterações do pacote de configuração entram em vigor imediatamente sem reiniciar o tempo de execução.

Agente Strands com construção por solicitação

Se você precisar aplicar mais campos de configuração (ID do modelo, temperatura, ferramentas), crie um novo agente por solicitação em vez de usar um gancho:

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

Para LangGraph agentes, leia o pacote de configuração no início de cada invocação e transmita os valores para seu 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 do Google ADK

Para agentes criados com o Agent Development Kit (ADK) do Google, leia o pacote de configuração ao criar o 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

Para agentes que usam o SDK do OpenAI com o Amazon Bedrock, leia o pacote de configuração para definir o modelo e o prompt do 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()

Recuo gracioso

Sempre forneça valores padrão ao ler a configuração do pacote. Isso garante que seu agente funcione corretamente mesmo quando nenhum A/B teste está ativo, a busca do pacote falha ou o pacote não contém a chave esperada.

get_config_bundle()retorna um dicionário vazio quando nenhuma referência de pacote está presente. Se a chamada de API subjacente falhar, a exceção se propagará. Envolva a chamada em um try/except para uma degradação 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}