AgentCore via SDK Best Practices

Tool-scoping, guardrail design, and cost controls for autonomous agents.

This is the checklist to run before and after putting an AgentCore-hosted agent into production. Each item is a rule stated positively with a one-line rationale, grouped from deployment hygiene outward through tool scoping, harness/prompt design, guardrails, and cost/scaling. Work top to bottom - the early groups keep your deployment correct and verifiable; the later ones keep it safe and cheap.

Because AgentCore is a 2026 preview capability, several items below double as a reminder to verify a specific name or mechanic against current AWS documentation rather than trusting any cached example, including the ones elsewhere in this section.

How to Use This List

Treat each box as an audit question against your own AgentCore deployment.
Groups run roughly in order of foundation: get deployment and tool-scoping right first, then harness design, guardrails, and cost.
Most rules apply whether you use the managed harness or a hand-written orchestration loop on AgentCore Runtime.
Revisit the list whenever you add a new Gateway target, a new built-in tool, or scale up traffic.

A - Runtime & Deployment Hygiene

Treat CLI subcommands and SDK operation names as unstable. AgentCore's preview surface changes; re-check current AWS docs before scripting automation around a specific name.
Test entrypoints locally before deploying. A local dev-server loop catches obvious errors faster than a deploy-and-invoke cycle against a live runtime.
Pin your CLI/toolkit version in CI. A fast-moving preview tool can change behavior between versions; upgrade deliberately, not implicitly.
Confirm a deploy actually landed before routing traffic to it. Poll runtime/target status via the control-plane client rather than trusting a CLI's exit code alone.
Review scaffolded/template code before production use. A starter template optimizes for "gets you started," not for your specific security posture.

B - Tool Scoping & Gateway Security

Scope every Gateway target's IAM role tightly. An agent inherits whatever its tools can reach - grant exactly the functions/APIs a target should expose, nothing wider.
Write specific tool/target descriptions. If a model reads descriptions to pick tools, a vague one causes wrong or missed calls - write it like documentation, not a code comment.
Group unrelated tools across separate gateways. Tool-selection quality degrades as one gateway's tool list grows; split by domain rather than registering everything on one gateway.
Verify network reachability, not just schema validity, for API targets. An OpenAPI schema that parses fine still needs a real, authenticated path to the underlying API.
Reserve built-in tools (like managed web search) for genuinely generic needs. Route internal/private data access through your own Gateway targets instead.

C - Harness & Prompt Design

Write the same disciplined system prompt you would for any tool-using agent. A managed harness runs the loop for you; it does not fix a vague or underspecified prompt.
Instruct the agent to disclose when it used a tool. Especially for search - users should be able to tell a grounded answer from a training-data-only one.
Confirm which tools are actually in scope for a given deployment. Don't assume every registered Gateway tool or built-in is automatically enabled for every agent.
Evaluate tool-calling behavior per model, not just per prompt. Tool-use quality varies by model family the same way it does on plain Bedrock Converse.
Keep session and actor identifiers straight when using Memory. Conflating "this conversation" with "this user" leaks context between sessions or loses continuity between them.

Verify a guardrail is actually attached before treating a deployment as production-ready.

# --- Python (boto3) --- guardrail attachment on a Converse call; verify AgentCore-specific wiring separately
import boto3
 
brt = boto3.client("bedrock-runtime", region_name="us-east-1")
resp = brt.converse(
    modelId="amazon.nova-lite-v1:0",
    messages=[{"role": "user", "content": [{"text": "Draft a customer-facing reply."}]}],
    guardrailConfig={
        "guardrailIdentifier": "arn:aws:bedrock:us-east-1:111122223333:guardrail/gr-abc123",
        "guardrailVersion": "1",
    },
)
print(resp.get("stopReason"))

// --- TypeScript (AWS SDK v3) --- guardrail attachment on a Converse call; verify AgentCore-specific wiring separately
import { BedrockRuntimeClient, ConverseCommand } from "@aws-sdk/client-bedrock-runtime";
 
const brt = new BedrockRuntimeClient({ region: "us-east-1" });
const resp = await brt.send(new ConverseCommand({
  modelId: "amazon.nova-lite-v1:0",
  messages: [{ role: "user", content: [{ text: "Draft a customer-facing reply." }] }],
  guardrailConfig: {
    guardrailIdentifier: "arn:aws:bedrock:us-east-1:111122223333:guardrail/gr-abc123",
    guardrailVersion: "1",
  },
}));
console.log(resp.stopReason);

D - Guardrails & Safety

Attach a guardrail to every model call inside the agent, not just the final response. Depending on harness internals, intermediate reasoning calls may need their own coverage.
Branch on guardrail intervention distinctly from generic errors. A blocked or redacted response is a policy decision, not a failure - handle it separately.
Cap tool-use loop iterations with a hard limit. An uncapped loop can run (and cost) far longer than expected before a guardrail or the model itself decides to stop.
Don't store sensitive data in long-term memory unreviewed. Extracted facts persist across sessions - apply the same data-handling care you would to any durable user data store.
Avoid logging raw prompt/response content by default. Log token counts, request/session ids, and stop reasons; log full content only with a clear data-handling policy.

E - Cost, Scaling & Observability

Set concurrency and iteration limits before traffic ramps up. An agent's cost ceiling isn't a single maxTokens cap the way a plain model call's is - a tool-use loop can multiply it.
Set budget/cost alarms specifically for agent workloads. A looping agent can spend fast; surface it before the invoice does, the same discipline as any Bedrock inference workload.
Wire logging and tracing in from the start, not after an incident. Retrofitting observability into a hard-to-inspect hosted agent is much harder than building it in during initial development.
Confirm CloudWatch log groups/metrics before building dashboards. AgentCore's observability surface is newer than the rest of Bedrock's - verify names rather than guessing.
Re-audit this whole list whenever you add a tool, model, or scale up traffic. Tool scoping, guardrail coverage, and cost controls that were fine at low volume may not hold at higher volume.

FAQs

What's the single most important security habit for an AgentCore agent?

Scoping every Gateway target's IAM role tightly. An agent can reach whatever its tools can reach, so an overly broad execution role is a bigger blast radius than the agent itself needs.

What's the biggest cost risk specific to agents versus plain model calls?

An uncapped tool-use loop. A single Converse call has a natural ceiling via maxTokens; a looping agent does not, unless you set a hard iteration cap and monitor it.

Do guardrails cover an agent's internal reasoning calls automatically?

Not necessarily - depending on harness internals, intermediate model calls inside the loop may need their own guardrail attachment, not just the final user-facing response. Verify coverage explicitly.

How stable are the exact AgentCore names used across this section?

Treat them as illustrative. AgentCore is a 2026 preview capability, and CLI subcommands, control-plane operation names, and CloudWatch resource names are all worth re-checking against current AWS docs before production use.

Should observability be added before or after launch?

Before. A hard-to-inspect hosted agent is much harder to debug retroactively once it's already handling production traffic than if logging and tracing were built in from the start.

How do session and actor ids relate to security?

Conflating them can leak one user's or conversation's context into another's. Keep them distinct in Memory calls even when they happen to map one-to-one in a simple deployment.

Is a starter-template scaffold safe to deploy as-is?

No - review its generated IAM roles, guardrail wiring, and tool registrations before promoting past a development environment. Templates optimize for a fast start, not your specific production posture.

AgentCore Gateway & Tool Registration - the tool-scoping rules in group B, in depth.
Observability & Guardrails for Production Agents - the guardrail and cost-control rules in groups D and E.
Agent Memory & Session State - the session/actor id discipline in group C.
AgentCore CLI & Skills for Coding Assistants - the deployment hygiene rules in group A.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+). Amazon Bedrock AgentCore is a fast-moving 2026 preview capability - verify exact API/CLI surface against current AWS docs before relying on specific method names.

AgentCore via SDK Best Practices

Tool-scoping, guardrail design, and cost controls for autonomous agents.

How to Use This List

Treat each box as an audit question against your own AgentCore deployment.
Groups run roughly in order of foundation: get deployment and tool-scoping right first, then harness design, guardrails, and cost.
Most rules apply whether you use the managed harness or a hand-written orchestration loop on AgentCore Runtime.
Revisit the list whenever you add a new Gateway target, a new built-in tool, or scale up traffic.

A - Runtime & Deployment Hygiene

Treat CLI subcommands and SDK operation names as unstable. AgentCore's preview surface changes; re-check current AWS docs before scripting automation around a specific name.
Test entrypoints locally before deploying. A local dev-server loop catches obvious errors faster than a deploy-and-invoke cycle against a live runtime.
Pin your CLI/toolkit version in CI. A fast-moving preview tool can change behavior between versions; upgrade deliberately, not implicitly.
Confirm a deploy actually landed before routing traffic to it. Poll runtime/target status via the control-plane client rather than trusting a CLI's exit code alone.
Review scaffolded/template code before production use. A starter template optimizes for "gets you started," not for your specific security posture.

B - Tool Scoping & Gateway Security

Scope every Gateway target's IAM role tightly. An agent inherits whatever its tools can reach - grant exactly the functions/APIs a target should expose, nothing wider.
Write specific tool/target descriptions. If a model reads descriptions to pick tools, a vague one causes wrong or missed calls - write it like documentation, not a code comment.
Group unrelated tools across separate gateways. Tool-selection quality degrades as one gateway's tool list grows; split by domain rather than registering everything on one gateway.
Verify network reachability, not just schema validity, for API targets. An OpenAPI schema that parses fine still needs a real, authenticated path to the underlying API.
Reserve built-in tools (like managed web search) for genuinely generic needs. Route internal/private data access through your own Gateway targets instead.

C - Harness & Prompt Design

Write the same disciplined system prompt you would for any tool-using agent. A managed harness runs the loop for you; it does not fix a vague or underspecified prompt.
Instruct the agent to disclose when it used a tool. Especially for search - users should be able to tell a grounded answer from a training-data-only one.
Confirm which tools are actually in scope for a given deployment. Don't assume every registered Gateway tool or built-in is automatically enabled for every agent.
Evaluate tool-calling behavior per model, not just per prompt. Tool-use quality varies by model family the same way it does on plain Bedrock Converse.
Keep session and actor identifiers straight when using Memory. Conflating "this conversation" with "this user" leaks context between sessions or loses continuity between them.

Verify a guardrail is actually attached before treating a deployment as production-ready.

# --- Python (boto3) --- guardrail attachment on a Converse call; verify AgentCore-specific wiring separately
import boto3
 
brt = boto3.client("bedrock-runtime", region_name="us-east-1")
resp = brt.converse(
    modelId="amazon.nova-lite-v1:0",
    messages=[{"role": "user", "content": [{"text": "Draft a customer-facing reply."}]}],
    guardrailConfig={
        "guardrailIdentifier": "arn:aws:bedrock:us-east-1:111122223333:guardrail/gr-abc123",
        "guardrailVersion": "1",
    },
)
print(resp.get("stopReason"))

// --- TypeScript (AWS SDK v3) --- guardrail attachment on a Converse call; verify AgentCore-specific wiring separately
import { BedrockRuntimeClient, ConverseCommand } from "@aws-sdk/client-bedrock-runtime";
 
const brt = new BedrockRuntimeClient({ region: "us-east-1" });
const resp = await brt.send(new ConverseCommand({
  modelId: "amazon.nova-lite-v1:0",
  messages: [{ role: "user", content: [{ text: "Draft a customer-facing reply." }] }],
  guardrailConfig: {
    guardrailIdentifier: "arn:aws:bedrock:us-east-1:111122223333:guardrail/gr-abc123",
    guardrailVersion: "1",
  },
}));
console.log(resp.stopReason);

D - Guardrails & Safety

Attach a guardrail to every model call inside the agent, not just the final response. Depending on harness internals, intermediate reasoning calls may need their own coverage.
Branch on guardrail intervention distinctly from generic errors. A blocked or redacted response is a policy decision, not a failure - handle it separately.
Cap tool-use loop iterations with a hard limit. An uncapped loop can run (and cost) far longer than expected before a guardrail or the model itself decides to stop.
Don't store sensitive data in long-term memory unreviewed. Extracted facts persist across sessions - apply the same data-handling care you would to any durable user data store.
Avoid logging raw prompt/response content by default. Log token counts, request/session ids, and stop reasons; log full content only with a clear data-handling policy.

E - Cost, Scaling & Observability

Set concurrency and iteration limits before traffic ramps up. An agent's cost ceiling isn't a single maxTokens cap the way a plain model call's is - a tool-use loop can multiply it.
Set budget/cost alarms specifically for agent workloads. A looping agent can spend fast; surface it before the invoice does, the same discipline as any Bedrock inference workload.
Wire logging and tracing in from the start, not after an incident. Retrofitting observability into a hard-to-inspect hosted agent is much harder than building it in during initial development.
Confirm CloudWatch log groups/metrics before building dashboards. AgentCore's observability surface is newer than the rest of Bedrock's - verify names rather than guessing.
Re-audit this whole list whenever you add a tool, model, or scale up traffic. Tool scoping, guardrail coverage, and cost controls that were fine at low volume may not hold at higher volume.

FAQs

What's the single most important security habit for an AgentCore agent?

Scoping every Gateway target's IAM role tightly. An agent can reach whatever its tools can reach, so an overly broad execution role is a bigger blast radius than the agent itself needs.

What's the biggest cost risk specific to agents versus plain model calls?

An uncapped tool-use loop. A single Converse call has a natural ceiling via maxTokens; a looping agent does not, unless you set a hard iteration cap and monitor it.

Do guardrails cover an agent's internal reasoning calls automatically?

How stable are the exact AgentCore names used across this section?

Should observability be added before or after launch?

Before. A hard-to-inspect hosted agent is much harder to debug retroactively once it's already handling production traffic than if logging and tracing were built in from the start.

How do session and actor ids relate to security?

Conflating them can leak one user's or conversation's context into another's. Keep them distinct in Memory calls even when they happen to map one-to-one in a simple deployment.

Is a starter-template scaffold safe to deploy as-is?

AgentCore Gateway & Tool Registration - the tool-scoping rules in group B, in depth.
Observability & Guardrails for Production Agents - the guardrail and cost-control rules in groups D and E.
Agent Memory & Session State - the session/actor id discipline in group C.
AgentCore CLI & Skills for Coding Assistants - the deployment hygiene rules in group A.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+). Amazon Bedrock AgentCore is a fast-moving 2026 preview capability - verify exact API/CLI surface against current AWS docs before relying on specific method names.

AgentCore via SDK Best Practices

Search Documentation

AgentCore via SDK Best Practices