As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

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 da solicitação atual.

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

Propagação do cabeçalho de 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 por meio de. BedrockAgentCoreContext

A bagagem contém duas chaves:

Você também pode passar a bagagem manualmente ao chamar o agente diretamente (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 trata 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 da bagagem, resolve a versão do pacote da API do plano de controle e armazena o resultado em 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()retorna o configuration objeto do componente correspondente ao seu ARN de tempo de execução. Se nenhuma referência de pacote estiver presente na solicitação (por exemplo, quando nenhum A/B teste estiver ativo e nenhuma bagagem tiver sido 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 atualize 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(str(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(str(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 passe 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": str(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(str(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": str(payload.get("prompt", "Hello"))},
        ],
    )
    return {"response": response.choices[0].message.content}


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

Recurso 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 estiver ativo, a busca do pacote falhar ou o pacote não conter a chave esperada.

get_config_bundle()retorna um ditado vazio quando nenhuma referência de pacote está presente. Se a chamada da API subjacente falhar, a exceção se propagará. Encerre a chamada em uma forma try/except de degradação graciosa:

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}