Models & Guardrails

AgentCore Runtime hosts a container that speaks a known protocol — it does not care which LLM your agent calls. That decision lives inside your agent code, as a model object you construct and hand to your framework. Change the object, change the model; the @app.entrypoint, the deploy flow, and the HTTP contract stay identical.

For Bedrock-hosted models, Strands gives you BedrockModel. The three arguments you'll set on day one are the model ID, the region, and the sampling temperature:

from strands import Agent
from strands.models.bedrock import BedrockModel

model = BedrockModel(
    model_id="us.anthropic.claude-sonnet-4-5-20250929-v1:0",  # see note on volatility
    region_name="us-west-2",
    temperature=0.3,
)

agent = Agent(model=model, tools=[...])

That us. prefix is not cosmetic. It marks a cross-region inference profile: Bedrock routes the request across a set of regions in a geography to absorb load and improve availability, rather than pinning you to a single region's capacity. AgentCore-supported prefixes you'll see are:

Nova, Claude, Llama, and Mistral are all reachable this way. The point to internalize: picking a model is editing one constructor call, not reconfiguring the platform.

Because the model is just an object, you are not locked into Bedrock. Strands ships provider classes that all satisfy the same interface, so the only line that changes is which class you instantiate:

For example, the same agent on OpenAI or on Gemini-via-LiteLLM:

from strands import Agent
from strands.models.openai import OpenAIModel
from strands.models.litellm import LiteLLMModel

# OpenAI directly
openai_model = OpenAIModel(model_id="gpt-4o", client_args={"api_key": OPENAI_API_KEY})

# Gemini (and 100+ others) through LiteLLM
gemini_model = LiteLLMModel(model_id="gemini/gemini-1.5-pro")

agent = Agent(model=openai_model, tools=[...])   # swap to gemini_model freely

LiteLLMModel is the escape hatch: it fronts 100+ providers, including Google Gemini, behind one class, so you can reach a model Strands doesn't have a dedicated class for. OllamaModel points at a local Ollama server, which is handy for offline development against an open-weights model before you commit to a hosted one.

The architectural payoff is that model choice and agent logic are decoupled. Your tools, prompt, and entrypoint are written once; the provider is a swappable dependency.

The single most common stumble on a brand-new agent is an AccessDeniedException on the very first model call. It looks like an IAM or code bug, but it usually is not.

Bedrock model access is granted per-model and per-region. Even with a valid execution role, a specific foundation model in a specific region is off until you explicitly enable access to it in that account/region. A model that works in us-east-1 may be denied in eu-central-1 because access was never enabled there.

The error surfaces from the SDK roughly like this:

AccessDeniedException: An error occurred (AccessDeniedException) when calling
the Converse operation: You don't have access to the model with the specified
model ID.

Resolution checklist, in order:

1. Enable model access for that exact model in that exact region (Bedrock console → Model access, or the equivalent API), and wait for it to show as granted.
2. Confirm the model ID is current, not a legacy ID like claude-sonnet-4-20250514. A retired ID can also read as denied.
3. Check the prefix matches your intent — a us. inference profile must be enabled for the regions it routes across, not just your home region.
4. Only after the above, look at the execution role's Bedrock permissions.

Getting this ordering right saves hours: reach for model access before you start rewriting IAM policies.

Once a model is wired up, you want safety: content filters, denied topics, word filters, PII detection/redaction, and contextual grounding. Bedrock Guardrails provide all of these, and when your model is a Bedrock model, you attach a guardrail directly to the BedrockModel.

You create the guardrail once (in the Bedrock console or via API), which yields a guardrail_id and a guardrail_version. Then you pass those — plus optional trace and redaction controls — into the model object:

from strands import Agent
from strands.models.bedrock import BedrockModel

model = BedrockModel(
    model_id="us.anthropic.claude-sonnet-4-5-20250929-v1:0",
    region_name="us-west-2",
    guardrail_id="abcd1234efgh",
    guardrail_version="1",
    guardrail_trace="enabled",   # include guardrail assessment in the trace
)

agent = Agent(model=model)
result = agent("...user prompt...")

Now Bedrock evaluates every request and response against the guardrail inline with the model call. When a guardrail blocks the interaction, the model does not return normal content — it returns a distinct stop reason. Detect it by inspecting stop_reason:

if result.stop_reason == "guardrail_intervened":
    # the guardrail blocked input or output; serve a safe fallback,
    # log the event, and do NOT treat the (empty/blocked) content as an answer
    return {"result": "I can't help with that request."}

This is the clean path: the guardrail is part of the model's own request/response cycle, so there's no extra API call. The catch is that it only works because the model lives in Bedrock — which is exactly the limitation the next section removes.

Native attachment only works on Bedrock models. But you may be running OpenAI, Gemini, or a self-hosted model — and you still want the same guardrail policy. The answer is the standalone ApplyGuardrail API, which moderates text without invoking a Bedrock foundation model at all. It's just a content-moderation call you can place around any provider's input and output.

import boto3

bedrock_runtime = boto3.client("bedrock-runtime", region_name="us-west-2")

# Moderate the user's INPUT before sending it to OpenAI/Gemini/etc.
resp = bedrock_runtime.apply_guardrail(
    guardrailIdentifier="abcd1234efgh",
    guardrailVersion="1",
    source="INPUT",                       # or "OUTPUT" for the model's response
    content=[{"text": {"text": user_prompt}}],
)

if resp["action"] == "GUARDRAIL_INTERVENED":
    # blocked: substitute a safe message instead of calling the model
    ...

Because ApplyGuardrail is a separate call, the pattern is: moderate the input → call your non-Bedrock model → moderate the output. The same guardrail (same content filters, denied topics, word filters, PII redaction, contextual grounding) now spans every provider you use.

Shadow mode lets you deploy a guardrail without enforcing it yet. Using Strands Hooks on MessageAddedEvent and AfterInvocationEvent, you call ApplyGuardrail and log what would have been blocked — without actually blocking it. You watch the would-be-block rate in production traffic, tune the policy, and only then flip to enforcement.

from strands.hooks import HookProvider, HookRegistry
from strands.hooks.events import MessageAddedEvent, AfterInvocationEvent

class ShadowGuardrail(HookProvider):
    def register_hooks(self, registry: HookRegistry) -> None:
        registry.add_callback(MessageAddedEvent, self._check_input)
        registry.add_callback(AfterInvocationEvent, self._check_output)

    def _check_input(self, event: MessageAddedEvent) -> None:
        # call apply_guardrail(source="INPUT", ...) and LOG would-be blocks;
        # do not raise / do not block in shadow mode
        ...

    def _check_output(self, event: AfterInvocationEvent) -> None:
        # call apply_guardrail(source="OUTPUT", ...) and LOG would-be blocks
        ...

Non-Bedrock providers need credentials — an OpenAI key, a Gemini key. The wrong move is baking them into the container image or passing them through the LLM context where they can leak. Keys belong in AgentCore Identity, injected at call time.

Instead of hardcoding, you register the key once with CreateApiKeyCredentialProvider (which stores it in AWS Secrets Manager — you can also reference an existing secret you already manage), then pull it in with a decorator at the moment of use. The raw key never touches your business logic or the model's prompt:

from bedrock_agentcore.identity.auth import requires_api_key

@requires_api_key(provider_name="openai-provider", into="api_key")
async def call_openai(prompt: str, *, api_key: str):
    model = OpenAIModel(model_id="gpt-4o", client_args={"api_key": api_key})
    agent = Agent(model=model)
    return agent(prompt)

For OAuth-protected resources (not just static keys), the sibling decorator @requires_access_token(provider_name, scopes, auth_flow, into=...) runs the full workload-identity → token-vault → consent flow and injects an access_token kwarg the same way. Both decorators live in bedrock_agentcore.identity.auth.

The deep mechanics of the token vault, OAuth 2LO/3LO, and per-provider refresh config are a later lesson on AgentCore Identity. For now, the rule is simple: secrets are injected, never embedded. If you find yourself reading an env var holding a provider key inside your image, route it through Identity instead.