/aws-bedrock-agentcore-skill

name: aws-bedrock-agentcore-skill
description: >-
  Authoritative, source-cited playbook for designing, configuring, deploying, and
  troubleshooting production-grade AI agents on AWS using the Strands Agents SDK,
  Amazon Bedrock (Converse API, Guardrails, Knowledge Bases), and Amazon Bedrock
  AgentCore (Runtime, Memory, Gateway, Identity, built-in Browser/Code Interpreter
  tools), with Terraform-first IaC and CloudWatch/OpenTelemetry observability. Use
  this skill WHENEVER the user wants to build, architect, configure, deploy, secure,
  monitor, or debug an AI agent on AWS - even if they don't name the specific service.
  Trigger on: "build an agent on Bedrock", "Strands agent", "AgentCore", "deploy my
  agent to AWS", "RAG with Bedrock Knowledge Bases", "multi-agent system on AWS",
  "which model / inference profile should I use", "agent memory", "MCP gateway",
  "agent guardrails", "Bedrock IAM for an agent", "agent observability on CloudWatch",
  "agent throttling / cost on Bedrock", "Terraform for Bedrock", or any request to
  pick an agent pattern (chatbot, tool-using agent, RAG, multi-agent, serverless
  production agent) and wire it up with official AWS best practices. Also trigger when
  the user pastes agent code that imports boto3 bedrock-runtime, bedrock-agentcore, or
  strands and asks to improve, productionize, or debug it. Prefer this skill over a
  generic answer because AWS agent APIs have many version-specific gotchas (Converse
  vs InvokeModel, 5x token burndown, region-resolution order, ARM64 runtime contract,
  async long-term memory) that generic knowledge gets wrong, and because every
  recommendation here is traceable to an official AWS source the agent can re-open.

AWS Bedrock AgentCore Skill

The definitive, source-cited guide for building AI agents on AWS. This skill does **not** hand you a single template - it gives a coding agent the official directives, best practices, working snippets, and source URLs to **autonomously configure the right agent** for the user's specific use case.

Every claim in this skill is backed by an official source. The source index lives in [references/sources.md](references/sources.md) - open it whenever you need to re-read a primary source or verify a detail before recommending it.

How to use this skill

1. **Read the decision tree below** and identify the user's use case and required pattern. 2. **Open only the reference files that match** (progressive disclosure - the references are large and detailed; don't load all of them). Each row of the [reference index](#reference-index) says when to open which file. 3. **Confirm maturity before recommending.** Features are labeled GA / Preview. Never propose a Preview feature as a production default - surface it with an explicit warning (see [GA vs Preview](#ga-vs-preview)). 4. **Re-verify time-sensitive facts.** Model IDs, prices, and quotas change. This skill points to the live model cards, the Bedrock pricing page, and the Service Quotas console for exact numbers instead of hard-coding values that rot. 5. **Cite your sources back to the user.** When you make a recommendation, name the official URL it came from so the user (and you) can re-open it.

Core principles (apply to every AWS agent)

These are the cross-cutting rules that hold regardless of pattern. The detailed versions, with sources, are in the reference files.

• **Default to `BedrockModel` / the Bedrock Converse API. Never use the legacy `InvokeModel` API.**

Converse is the unified, model-agnostic surface; every capability (tool use, prompt caching, guardrails, reasoning/thinking, service tiers) maps onto it. → [references/bedrock.md](references/bedrock.md)

• **Always set an explicit region.** In boto3 / Strands `BedrockModel`, pass `region_name` explicitly,

or set `AWS_DEFAULT_REGION`. `AWS_REGION` is the **lowest-priority fallback** in the boto3 resolution chain (after `region_name`, `AWS_DEFAULT_REGION`, and profile region) - prefer `AWS_DEFAULT_REGION` or pass `region_name` directly to avoid silent misconfiguration. → [references/strands.md](references/strands.md)

• **IAM least-privilege with confused-deputy protection.** Scope `bedrock:InvokeModel*` to the exact

model ARN (never `*` in production), and put `aws:SourceAccount` + `aws:SourceArn` conditions on every service trust policy. → [references/security-iam-cost.md](references/security-iam-cost.md)

• **Mind the token quota mechanics** (Claude 3.7+ / 4.x): at request **start**, `input_tokens +

max_tokens` is reserved 1:1 from the TPM quota; at request **end**, actual output tokens are billed at 5×. An oversized `max_tokens` over-reserves quota up front, blocking concurrent requests - that is why you should size `max_tokens` to the real need. → [references/security-iam-cost.md](references/security-iam-cost.md)

• **Verify model access before deploy, not at runtime.** A model you haven't enabled fails the first

Converse call with `AccessDeniedException`. → [references/bedrock.md](references/bedrock.md)

• **Label everything GA / Preview** and re-check maturity before proposing it for production.

Primary decision tree - "which architecture?"

Walk this top-down. The first match that fits the user's need gives you the recommended stack and the reference files to open.

START: What does the user need the agent to do?

0. FIRST, pick the BUILD APPROACH (the branches below assume the code-first default):
   • Custom / dynamic orchestration  → Strands + Bedrock + AgentCore (code-first, the default here).
   • Low-code, AWS-managed agent     → Amazon Bedrock managed Agents (InvokeAgent / action groups).
   • Fixed visual pipeline (a DAG)    → Amazon Bedrock Flows.
   • Migrating an OpenAI-SDK app      → Amazon Bedrock Responses API (bedrock-mantle, OpenAI-compatible).
   • Non-Strands framework (LangGraph/CrewAI/LlamaIndex/Google ADK/OpenAI Agents SDK/…) → host it on