Best Practices for Building Agents with Amazon Bedrock AgentCore

Introduction

What this guide covers

1. Harness

Knowing when to outgrow Harness

Forcing a specific tool call

💡 Production hardening: Export to a Strands runtime → own the  converse()  loop → set Bedrock  toolChoice  (Lever A) and a structural gate that refuses a final answer until a tool result exists (Lever B). Cleanest of all: make the computation backend-authoritative so the model never gets to skip it.

# Lever A: force the tool call (Harness cannot do this; a custom loop can)
resp = bedrock.converse(
    modelId=MODEL_ID, messages=messages,
    toolConfig={**TOOL_SPEC,
        # {"tool":{"name":...}} MUST call it | {"any":{}} some tool | {"auto":{}} model decides
        "toolChoice": {"tool": {"name": "run_computation"}}},
)

# Lever B: structural gate: no tool result => no answer (no model trust needed)
tool_use = next((c["toolUse"] for c in msg["content"] if "toolUse" in c), None)
if tool_use is None:
    raise ToolNotExecuted("model did not call the required tool")
result = run_in_sandbox(tool_use["input"])   # real tool stdout = proof it ran

Native vs custom tools & the  @  prefix

⚠️ Gotcha:  @  does NOT mean "Gateway." It means "not an AWS built-in." Custom ≠ Gateway-only: Gateway is for real backend services; inline functions are custom too and need no Gateway. A bare name that isn't a recognized built-in is silently rejected →  Unknown tool .

Custom container image

Key takeaway: Harness = "AWS wrote the loop for you" (CodeZip, no toolChoice). Need to force a tool or bake a dependency? Export to a runtime agent: that's where  toolChoice  and  BuildType: Container  live.

2. Runtime & session isolation



The session model

⚠️ The caveat to say out loud: AgentCore isolates the microVM but does not enforce session-to-user mapping. Your backend owns the  sub → sessionId  binding, so verify a requested session id belongs to the authenticated  sub  before resuming. Getting this wrong is the real multi-tenant bug, not the compute boundary.

How the backend API maintains the user → session mapping



💡 Why a persistent store: The microVM stops after ~15 min idle / 8 h max, but the  sessionId  stays valid and resumes with fresh compute, so the mapping must outlive the compute. Keeping it in the backend's own store (not in agent memory) means a returning user reconnects across stop/resume cycles, and a backend restart doesn't lose the binding.

3. Memory

Two types

Design for asynchronous extraction: Long-term extraction is event-triggered and asynchronous: it fires when an event is written, during the session, not at session end. The delay people see is async lag, not a session-close batch. To make a fact usable this turn, write it deterministically ( CreateEvent / IngestData ) and read it back, or carry it in session context.

Four strategies and when to use

Keys & namespaces: the survival lever

Namespace rules that matter: Keep  {sessionId}  out of a preferences namespace, or the user loses those preferences next visit. Always end namespaces with a trailing slash ( /actors/Alice/ ) to prevent prefix collisions. Records are not overwritten per session: long-term consolidates (merge/update), short-term expires by per-event TTL, and changing the TTL is not retroactive.

Who controls storage vs retrieval

# STORAGE (managed): the STRATEGY extracts; steer it with an extraction-prompt override
memoryStrategies=[{"userPreferenceMemoryStrategy":{
    "name":"UserCriteria",
    "namespaces":["/users/{actorId}/preferences/"],      # actor-level = survives
    "configuration":{"extraction":{"appendToPrompt":
        "Extract only durable user preferences and settings. Ignore small talk."}}}}]

# STORAGE (deterministic): guarantee an exact record
data.create_event(memoryId=mid, actorId=sub, sessionId=sid, payload=[...])

# RETRIEVAL (you decide): namespace scope + semantic query
data.retrieve_memory_records(memoryId=mid,
    namespace=f"/users/{sub}/preferences/",
    searchCriteria={"searchQuery": user_message, "topK": 5})

Security: four layers

Key takeaway: Storage = the strategy decides (managed, async; steer via override or guarantee via  CreateEvent ). Retrieval = you decide via namespace + semantic query, or let the Harness  memory  block auto-inject. Config lives on the Memory resource;  actorId  derives from the JWT  sub .

4. Identity: inbound, OBO, 3LO

Refresh inbound tokens early and mind the ~60s freshness floor. AgentCore Runtime's inbound JWT authorizer rejects a token that has less than ~60 seconds of remaining lifetime, returning HTTP 401 with JSON-RPC code  -32001 , "Ineffectual token, will expire within the next minute", even when signature,  iss ,  aud , and  exp  all otherwise validate. There is no TTL-floor field on  CustomJWTAuthorizerConfiguration , so this is not configurable. On the Gateway MCP inbound path the same near-expiry guard can surface instead as a 403  insufficient_scope , so do not key retry logic solely on the message string. Best practice: treat a token with under ~120 seconds remaining as already expired and refresh it proactively rather than letting it coast toward  exp .

OBO in one paragraph



3LO vs OBO: decide by one question



⚠️ Does 3LO become OBO? No. After first consent, 3LO keeps working via its stored refresh token (still 3LO). OBO is a separate token-exchange. 3LO establishes a grant; OBO propagates an identity. They can chain, but one never turns into the other. Add M2M (agent as itself) for the full taxonomy.

5. Gateway

Six capabilities

MCP vs A2A, keep them straight: Gateway's native ingress protocol is MCP, which is how agents call it. A2A is a Runtime protocol an agent can natively speak (HTTP/MCP/A2A), and Gateway can optionally front an A2A agent as a passthrough target. Gateway supports A2A, but A2A is not inherent to Gateway: two agents can speak A2A directly on Runtime with no Gateway in between. Set the exposed protocol on the agent's runtime spec at  agentcore configure -p MCP , persisted in  agentcore.json .

💡 Least-privilege pattern: Split read and write tools across two Gateways (e.g. a read-only Gateway and an ops Gateway) so a compromised read path can't mutate state.

6. Policy, Guardrails & Temporal

Request → Cedar (who/what) → Guardrails (forbid input) → Temporal (session history) → Tool runs
          deny-by-default · suppressOutput also filters the RESPONSE after the tool runs

Guardrails-in-policy

# Block prompt injection on the way in
forbid (principal, action == AgentCore::Action::"<Target>___POST:/invocations", resource)
when guardrails {
  BedrockGuardrails::PromptAttack(["PROMPT_INJECTION"], [context.input.prompt])
    ["PROMPT_INJECTION"].confidenceScore.greaterThan(decimal("0.6"))
};

Temporal policies (Dogwood)

# Permit a write ONLY if a matching confirmation happened in the last 5 min
permit (principal, action == AgentCore::Action::"my-target___commit_change", resource == ...gateway...)
when temporal {
  formerly within 5m AgentCore::Action::"my-target___confirm_change"::response {
    input.recordId: context.input.recordId, output.approved: true
  }
};

⚠️ Caveats: Changing a temporal policy invalidates open sessions → next reuse fails 409 ConflictException (start a new session). Same account + Region only; needs  GetWorkloadAccessToken  on the gateway role. Quotas apply (confirm current values in the docs): on the order of 20 policies per engine, 3 operators per policy, and a 24-hour max window. Temporal ≠ time-based (wall-clock  context.system.now ).

💡 Region: Guardrails-in-policy and Temporal policies are available in a subset of Regions (e.g. us-east-1, us-east-2, us-west-2 Oregon, and others) but not all, notably not us-west-1 (N. California). Always check the live Region matrix before you design around them.

Pattern: infrastructure-enforced confirmation. A temporal policy can make a human-in-the-loop confirmation gate infrastructure-enforced: permit the write only if a matching confirmation action occurred in session history within a short window, so the write is impossible without a recent approval, not merely "the prompt asks nicely."

7. Browser

💡 Acting as the user: For a login-gated site, pair Browser with Identity: obtain a per-user token (OBO in production), drive the login as the user, and read the result, so the token is injected into the tool and never enters the model's context.

8. Code Interpreter

💡 Proof-of-execution pattern: Have the result card/record render directly from the sandbox's stdout (e.g. a JSON line). Its presence is evidence the sandbox executed, and a bypass can't fabricate it.

9. Top caveats cheat-sheet

Conclusion