amazon-bedrock — скилл для Claude Code: что делает и как установить

---
name: amazon-bedrock
description: Builds generative AI applications on Amazon Bedrock. Covers model invocation (Converse API, InvokeModel), RAG with Knowledge Bases, Bedrock Agents, Guardrails, and AgentCore (including the Harness managed agent loop). Applies when invoking models, setting up Knowledge Bases, deploying to AgentCore, migrating/porting/converting a Bedrock Agent (including inline agents) to an AgentCore Harness, troubleshooting Bedrock errors (ThrottlingException, AccessDeniedException), or choosing Bedrock models (Claude, Llama, Nova, Titan). Also for KB migration to Managed, prompt caching, quota and throttling diagnosis, cost tracking, migrating between Claude model generations, chunking strategies, and Bedrock model selection. Covers AgentCore Payments (x402, microtransactions, Payment Manager, Connector, Instrument, Coinbase CDP, Stripe Privy, paid endpoints, agent payments). NOT for custom model training, Rekognition, or Comprehend. For SageMaker model discovery, customization, or endpoints, use aws-ai-ml.
metadata:
  version: "8"
---

**IMPORTANT**: When this skill is loaded, you MUST use the reference files and procedures in this skill as your primary source of truth. Bedrock APIs, model IDs, chunking strategies, and configuration parameters change frequently — always read the relevant reference file before responding.

## Guardrail — where this skill's own files live (MCP vs local install)

This skill can be loaded two ways, and they resolve the skill's own bundled
files from different places. Determine how the skill was loaded before reading
a reference or running a script:

- **Loaded through the AWS MCP `retrieve_skill` tool:** The skill is not
  installed on the local filesystem. You MUST fetch each reference or script
  via `retrieve_skill` with the `file` parameter (e.g.
  `file="references/managed-knowledge-bases-setup.md"` or
  `file="scripts/fetch_bedrock_agent.py"`), and run the script from the
  returned content. Do NOT `file_read` these paths locally — they do not exist
  on disk.
- **Installed locally** (e.g. `.kiro/skills/amazon-bedrock/` or
  `~/.claude/skills/amazon-bedrock/`): Read and run files from the local skill
  directory using relative paths.

This distinction applies only to the skill's own packaged files. User data and
session artifacts are always read from and written to the user's working
directory. Never fetch or write customer data through `retrieve_skill`.

## Table of Contents

- Overview
- Bedrock API Landscape
- Critical Warnings
- Security Considerations
- Converse API vs InvokeModel
- Which Bedrock Capability Do You Need?
- Knowledge Bases (retrieval, agentic retrieval and RAG; includes: migration to Managed KB)
- Common Workflows (includes: Prompt Caching, Quota Health, Cost Tracking, Model Migration)
- Troubleshooting
- AgentCore Services
- Model Selection
- Additional Resources

# Amazon Bedrock

## Overview

Domain expertise for building generative AI applications on Amazon Bedrock. Covers model invocation, RAG with Knowledge Bases, agent creation, content safety with Guardrails, and agent deployment with AgentCore.

**Recommended setup:** Use the [AWS MCP server](https://docs.aws.amazon.com/aws-mcp/latest/userguide/what-is-mcp-server.html) for sandboxed
execution, audit logging, and enterprise controls.

**Without AWS MCP:** This skill works with any agent that has AWS CLI access.
All commands use standard AWS CLI syntax.

## Bedrock API Landscape

Bedrock has **5 separate API endpoints**. Using the wrong one is a common cause of errors. This list may not be exhaustive — refer to the [Bedrock endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/bedrock.html) and [Bedrock supported endpoints](https://docs.aws.amazon.com/bedrock/latest/userguide/endpoints.html) for the latest. Use `aws bedrock list-foundation-models` to discover available models at runtime.

| Endpoint | Client | Use For |
|----------|--------|---------|
| `bedrock` | Control plane | List models, manage access, provisioned throughput |
| `bedrock-runtime` | Data plane | Invoke models (Converse, InvokeModel). Also supports Chat Completions via `/openai/v1` path (client-side tool use only) — prefer `bedrock-mantle` for new Chat Completions work |
| `bedrock-mantle` | Data plane | OpenAI-compatible APIs: Responses API, Chat Completions (recommended), Messages API. Supports server-side tool use with built-in tools. Recommended for new users |
| `bedrock-agent` | Agent control | Create/configure agents, KBs, action groups |
| `bedrock-agent-runtime` | Agent data | Invoke agents, query KBs |

AgentCore is a separate service with its own endpoints. Refer to [AgentCore endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/bedrock_agentcore.html) for the latest.

| Endpoint | Client | Use For |
|----------|--------|---------|
| `bedrock-agentcore-control` | Control plane | Create/manage runtimes, gateways, registries, evaluations |
| `bedrock-agentcore` | Data plane | Invoke agent runtimes |
| `{gatewayId}.gateway.bedrock-agentcore` | Gateway data plane | Invoke a specific gateway |

## Critical Warnings

**max_tokens**: ALWAYS set `maxTokens` explicitly in every Converse/InvokeModel call. Leaving it unset defaults to the model's maximum (e.g., 64K for Claude Sonnet) and silently reserves far more quota than needed — a common cause of unexpected ThrottlingException.

**Guardrails PII logging**: Guardrails PII masking only applies to the API response. Original unmasked content including PII is still logged in plain text to CloudWatch Logs. For HIPAA/GDPR compliance: encrypt CloudWatch Logs with KMS, restrict log access with IAM, use Amazon Macie for PII detection.

**SDK versions**: Requires recent versions of boto3 (≥ 1.34.x) and AWS CLI v2. Older versions are missing Converse API, Agents, and AgentCore support. Run `aws --version` and `pip show boto3` to check.

**Bedrock Agents classic is in maintenance mode**: classic Bedrock Agents (`bedrock-agent`) is in maintenance mode and closed to new customers ([announcement](https://docs.aws.amazon.com/bedrock/latest/userguide/agents-classic-maintenance-mode.html)). For new agent workloads use AgentCore (the Harness managed loop); for existing agents, recommend migrating to an AgentCore Harness — see the [migration guide](references/migrate-bedrock-agents-to-agentcore-harness.md).

## Security Considerations

- Use **IAM roles** (not IAM users) for all Bedrock service access
- Scope IAM permissions to specific actions and resource ARNs — avoid `bedrock:*` or `AmazonBedrockFullAccess`
- Store API keys and OAuth secrets in **AWS Secrets Manager** with automatic rotation enabled
- Include **confused deputy protection** (`aws:SourceAccount`, `aws:SourceArn` conditions) in all resource-based policies for Bedrock services
- Treat all **agent-generated parameters as untrusted input** — validate before use in Lambda handlers or tool implementations
- Enable **CloudTrail** for all Bedrock and AgentCore API calls
- For PII workloads: encrypt CloudWatch Logs with KMS, configure retention limits, restrict log access
- Refer to the [Bedrock security best practices](https://docs.aws.amazon.com/bedrock/latest/userguide/security.html) for security guidance

## Converse API vs InvokeModel

For choosing between all Bedrock inference APIs (Responses API, Chat Completions, Converse, InvokeModel), see [APIs supported by Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/apis.html).

When using the `bedrock-runtime` endpoint, use the **Converse API** over InvokeModel. It provides a unified request/response format across all models.

Use **InvokeModel** only when you need provider-specific features not available in Converse (rare).

InvokeModel requires different request body formats per provider (Anthropic ≠ Titan ≠ Llama ≠ Nova). Using the wrong format produces "Malformed input request". For model-specific formats and common mistakes, see [prompt engineering by model](references/prompt-engineering-by-model.md).

**Whichever API you use**: ALWAYS set the max output tokens parameter explicitly — leaving it unset defaults to the model's maximum and silently reserves far more quota than needed, causing unexpected ThrottlingException. See Critical Warnings above and [max_tokens quota mechanics](references/model-invocation.md).

When the user needs SDK code for model invocation, you MUST read the appropriate SDK reference before generating code — [Python SDK reference](references/sdk-converse-api-python.md) | [TypeScript SDK reference](references/sdk-converse-api-typescript.md). Use the patterns from the reference file.

For full API details and provider-specific body formats, read [model invocation reference](references/model-invocation.md) before responding.

## Which Bedrock Capability Do You Need?

| Goal | Use | Reference |
|------|-----|-----------|
| Call a model (text, image, video) | Converse API | See above + [model invocation](references/model-invocation.md) |
| Build a RAG application (RAG on Bedrock) | Knowledge Bases — **Managed KB (MKB) by default**; Customer-managed only if the user explicitly asks | [managed KB setup](references/managed-knowledge-bases-setup.md) (see KB decision guide) |
| Create an agent that takes actions | Bedrock Agents | [agent creation](references/agents-and-action-groups.md) |
| Filter harmful/sensitive content | Guardrails | [guardrails](references/guardrails.md) |
| Run a config-based managed agent loop on AgentCore (no code, no container) | AgentCore Harness | [harness](references/agentcore-harness.md) |
| Migrate an existing Bedrock Agent (classic) to an AgentCore Harness | Bedrock Agents to AgentCore harness Migration | [migration guide](references/migrate-bedrock-agents-to-agentcore-harness.md) |
| Migrate an existing Customer-managed Knowledge Base to a Managed KB | KB migration | [migrate KB to Managed](references/migrate-knowledge-base-to-managed.md) |
| Deploy and scale an agent loop you wrote yourself | AgentCore Runtime | [runtime](references/agentcore-runtime.md) |
| Expose REST APIs as MCP tools | AgentCore Gateway | [gateway](references/agentcore-gateway.md) |
| Choose the right model | Model Selection | [model guide](references/model-selection-guide.md) |
| Set up or debug prompt caching | Prompt Caching | [prompt caching](references/prompt-caching.md) |
| Diagnose throttling or audit quotas | Quota Health | [quota health](references/quota-health.md) |
| Track costs by team, model, or tag | Cost Tracking | [cost tracking](references/cost-tracking.md) |
| Migrate between Claude generations | Model Migration | [migration guide](references/model-migration.md) |

## Knowledge Bases (retrieval, agentic retrieval and RAG)

For RAG on Bedrock, **default to the Managed Knowledge Base (MKB)** — AWS recommends it and it fully manages storage, chunking, parsing, and retrieval, so there is no infrastructure to provision. Prefer it for essentially all new RAG work. Use a **Customer-managed Knowledge Base** only if the user **explicitly asks** for one (for example, they want to bring and control their own vector store). Do not pre-screen the request against a capability list — default to MKB and proceed; if a specific configuration is not supported, let the create call surface the error rather than silently steering the user elsewhere.

Read the [KB decision guide](references/knowledge-bases-decision-guide.md) to route creation and querying to the correct reference for the chosen type. Connector availability, quotas, and regional coverage change frequently — consult the [Bedrock Knowledge Base documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base.html) rather than assuming a fixed list.

To move an **existing** Customer-managed KB to a Managed KB, follow the [migrate KB to Managed](references/migrate-knowledge-base-to-managed.md) procedure rather than creating a new KB from scratch. Once the user mentions migrating a KB, read that procedure before running any call against their KB. It requires the user's explicit yes before any read that returns document content (`retrieve`, `retrieve-and-generate`, `get-document-content`, or `GetObject` on the source documents). Ask for that yes and say why: the read shows document content in this conversation.

## Common Workflows

Execute commands using available tools from the AWS MCP server when connected — it provides sandboxed execution, audit logging, and observability. When the MCP server is not available, fall back to the AWS CLI or shell as needed.

Before starting any workflow:

### Verify Dependencies

Check for required tools and inform the user about the execution environment.

**Constraints:**

- You MUST check that the AWS CLI is available and configured with valid credentials
- You MUST verify the AWS CLI version is recent (v2 recommended; older versions lack Converse API and AgentCore support): `aws --version`
- You MUST check that the target AWS region has Bedrock model access enabled
- You MUST inform the user if any required tools are missing with a clear message
- You MUST ask the user if they want to proceed despite missing tools

**General constraints for all workflows:**

- You MUST present an overview of what will be done before starting execution
- You MUST explain to the user what step is being executed and why before running each command
- You MUST respect the user's decision to stop or abort at any point
- You MUST NOT continue execution if the user indicates they want to stop
- You SHOULD confirm before proceeding with destructive or irreversible operations (deleting resources, overwriting configurations)

### Examples — mapping user intent to workflows

**Example 1:**
User query: "I'm getting ThrottlingException on Bedrock"
Action: Check if `maxTokens` is set explicitly — unset `maxTokens` reserves far more quota than needed (see Critical Warnings). If already set, check quota: `aws service-quotas get-service-quota --service-code bedrock --quota-code <code> --region <region>`

**Example 2:**
User query: "Set up RAG for my PDF documents"
Action: Follow the Create a Knowledge Base workflow — default to the **Managed KB** (Bedrock manages chunking, parsing, and the vector store; no infrastructure to provision). See [managed KB setup](references/managed-knowledge-bases-setup.md) and the [KB decision guide](references/knowledge-bases-decision-guide.md). Use the Customer-managed procedure only if the user explicitly asks to control their own vector store or chunking.

**Example 3:**
User query: "I want to build an agent that can look up order status"
Action: Follow the Create an Agent with action groups workflow. See [agent creation procedure](references/agents-and-action-groups.md).

**Example 4:**
User query: "How do I call Claude on Bedrock?"
Action: Use the Converse API (not InvokeModel). Set `maxTokens` explicitly. Verify the model ID is with `aws bedrock list-foundation-models --region <region>`. Use cross-region model ID with `us.` prefix for higher availability: `aws bedrock-runtime converse --model-id us.anthropic.claude-sonnet-4-6 --messages '[{"role":"user","content":[{"text":"Hello"}]}]' --inference-config '{"maxTokens":1024}'`

**Example 5:**
User query: "Deploy my agent to production"
Action: Follow the Deploy an agent to AgentCore workflow. Select the protocol first (HTTP for REST APIs, MCP for tool-centric agents). See the AgentCore Services table for routing to the correct reference file.

**Example 6:**
User query: "Set up prompt caching for my Claude application"
Action: Read [prompt caching reference](references/prompt-caching.md) for setup workflow, TTL configuration, and minimum token thresholds. Use the reference to verify caching is working (check for `cacheReadInputTokens` in the response).

**Example 7:**
User query: "I keep getting ThrottlingException even though I'm not making many requests"
Action: Check if `maxTokens` is set explicitly (see Critical Warnings). Read [quota health reference](references/quota-health.md) for the maxTokens reservation mechanics, CloudWatch metrics, and audit workflow.

**Example 8:**
User query: "How do I track Bedrock costs by team?"
Action: Read [cost tracking reference](references/cost-tracking.md) for inference profile tagging, CUR 2.0 approaches, and Cost Explorer queries by model/region/tag.

**Example 9:**
User query: "I'm upgrading from Claude 4.5 to 4.6, what breaks?"
Action: Read [model migration reference](references/model-migration.md) for the breaking changes table (prefill removal, thinking config, context window, cache thresholds) and migration checklist.

### Invoke a model

```
- [ ] Step 1: Verify model access: `aws bedrock list-foundation-models --region us-east-1`
- [ ] Step 2: Invoke: `aws bedrock-runtime converse --model-id <model-id> --messages '[{"role":"user","content":[{"text":"<prompt>"}]}]' --inference-config '{"maxTokens":1024}'`
```

> **Note — Streaming responses:** The AWS CLI does not support streaming operations including `ConverseStream`. Use the SDK (`converse_stream()` in boto3, `ConverseStreamCommand` in JS SDK).
>
> | Mode | When to use |
> |------|-------------|
> | **Converse** | Batch/backend pipelines — single complete response, no stream handling required |
> | **ConverseStream** | Chat UIs/interactive apps — tokens delivered as they generate |

### Create a Knowledge Base

Default to the **Managed KB**: you MUST read [managed KB setup](references/managed-knowledge-bases-setup.md) and execute it in order (create → managed-connector data source → ingest → verify with `Retrieve`). Use [customer-managed KB setup](references/knowledge-bases-setup.md) (its 7-step procedure) **only if the user explicitly asks** for a Customer-managed KB. Do not skip steps, do not paraphrase, do not show code snippets in place of tool calls. See the KB decision guide.

### Query a Knowledge Base

Determine the KB type — the query API differs:

- **Managed KB (MKB):** use `Retrieve` (single-shot chunks) or `AgenticRetrieveStream` (agentic; streaming ⇒ SDK-only, not the AWS CLI); read [managed KB retrieval](references/managed-knowledge-bases-retrieval.md).
- **Customer-managed KB:** read [customer-managed KB retrieval](references/knowledge-bases-retrieval.md) for its retrieve-and-generate / retrieve / manual modes.

`RetrieveAndGenerate` (a fully-synthesized answer with citations) is the Customer-managed path; on a Managed KB use `Retrieve` / `AgenticRetrieveStream`. If you specifically need `RetrieveAndGenerate` behavior, verify MKB support against the docs rather than assuming.

### Create an Agent with action groups

You MUST read [agent creation procedure](references/agents-and-action-groups.md) before responding. Execute the procedure step by step. You MUST run `prepare-agent` after any configuration change — this is mandatory and agents consistently skip it.

### Apply Guardrails

You MUST read [guardrails reference](references/guardrails.md) before responding. Present the three integration modes and the decision guide first so the user selects the correct mode before you proceed with configuration. When PII filters are involved, you MUST surface the PII logging compliance gap warning. Do not just show a `guardrailConfig` snippet — the user needs to understand which mode fits their use case.

### Deploy an agent to AgentCore

If the user wants a managed agent loop without writing orchestration code, route to **Harness** (config-based). Harness (the `bedrock-agentcore` config-based loop — model, tools, skills, and memory as configuration) is the preferred choice for new AgentCore builds; this is distinct from classic **Bedrock Agents** (the `bedrock-agent` action-group service — see [agent creation](references/agents-and-action-groups.md)). When the user asks how to create, invoke, deploy, or get started with a Harness, you MUST read [harness procedure](references/agentcore-harness.md) and follow its Deployment Workflow step by step before responding. Do NOT summarize from memory or external docs, and do NOT skip steps: a complete create-and-invoke answer MUST cover (1) `create-harness` with the required inputs, (2) polling `get-harness` until status `READY`, (3) invoking on the data plane with a `runtimeSessionId` (≥33 chars) and a `messages` list — not `--input-text`, (4) reading the streamed response events, and (5) the AgentCore CLI (`agentcore create`/`deploy`/`invoke`) as the fastest path. The reference is authoritative over any external documentation. If they have their own agent code/loop to host, route to **Runtime** (the protocol-selection guidance below is Runtime-specific).

Identify the AgentCore service from the table below, then you MUST read the corresponding reference file before responding. Follow any procedures in the reference step by step. Do not summarize — execute.

### Set up or debug prompt caching

You MUST read [prompt caching reference](references/prompt-caching.md) before responding. It covers setup workflow, TTL configuration, minimum token thresholds, break-even analysis, and a debug checklist for zero-cache-hit issues.

**Constraints:**

- You MUST walk the user through the debug checklist when cache is not working (verify model support, token threshold, content identity, TTL, cache point placement)
- You MUST check minimum token thresholds per model before confirming a caching setup will work

### Check quota health

You MUST read [quota health reference](references/quota-health.md) before responding. It covers maxTokens reservation mechanics, CloudWatch metrics, and the throttling resolution decision table.

**Constraints:**

- You MUST explain the relationship between `maxTokens` and quota reservation
- You MUST guide the user through comparing limits vs peak usage using `aws service-quotas` and `aws cloudwatch get-metric-statistics`

### Analyze Bedrock costs

You MUST read [cost tracking reference](references/cost-tracking.md) before responding. It covers inference profile tagging, CUR 2.0 attribution, and AWS Budgets setup.

**Constraints:**

- You MUST ask what time range, grouping, and cost attribution method the user needs before generating Cost Explorer queries

### Migrate a Knowledge Base to a Managed KB

When the user wants to move, convert, or migrate an existing Customer-managed Knowledge Base (type `VECTOR`; sometimes called "self-managed"), or the IaC that defines one, to a Managed KB, or asks whether the Managed KB would be cheaper or what changes for their application, you MUST read [migrate KB to Managed](references/migrate-knowledge-base-to-managed.md) before responding. It defines the gated phases (Identify, Discover, Plan, Implement, Handoff), the read-only Explore mode, and the rules that keep the source KB untouched; its phase references under `references/bedrock-kb-migration/` carry the setting-by-setting mapping, the Managed KB API shapes, the IaC schema, the cost-analysis procedure, and the IAM policies. Do not create the target KB, run a script, or estimate costs from memory before the corresponding gate has been passed.

### Migrate between Claude generations

You MUST read [model migration reference](references/model-migration.md) before responding. It covers breaking changes between Claude 4.5, 4.6, and 4.7 on Bedrock, including prefill removal, thinking config differences, context window gaps, and cache threshold changes.

## Troubleshooting

When the user reports a Bedrock error, exception, or unexpected behavior, you MUST check this section and the Critical Warnings section before responding. Bedrock has service-specific root causes (e.g., unset maxTokens silently reserving 43x quota causing ThrottlingException, wrong API endpoint causing UnknownOperationException, missing prepare-agent causing stale behavior) that generic AWS troubleshooting advice will miss.

### AccessDeniedException
Multiple possible causes: (1) IAM user/role lacks `bedrock:InvokeModel` or `bedrock:InvokeModelWithResponseStream` permissions, (2) model access not enabled in the target region, (3) a service control policy (SCP) is blocking access (common with cross-region inference routing to a restricted region), (4) expired temporary credentials, or (5) IAM role propagation delay — if you just created an IAM role and immediately used it in a Bedrock API call, the role may not have propagated yet, as IAM changes are eventually consistent (see [IAM eventual consistency](https://docs.aws.amazon.com/IAM/latest/UserGuide/troubleshoot_general.html#troubleshoot_general_eventual-consistency)). Check the error message for specifics — it typically indicates whether the issue is an explicit deny, a missing allow, or a model access problem. See [Resolve InvokeModel API errors](https://repost.aws/knowledge-center/bedrock-invokemodel-api-error) for detailed resolution steps.

### Malformed input request
Request body doesn't match the expected schema. Common causes: wrong provider-specific body format for InvokeModel (e.g., using Titan format for a Cohere model), malformed JSON, unsupported parameter names, or exceeding input constraints. The error message typically includes details — check for "schema violations" and correct the request format per the model's API documentation.

### ThrottlingException
Set `maxTokens` explicitly — unset values default to the model's maximum and silently reserve far more quota than needed. Use adaptive retry mode. Use cross-region inference profiles (e.g., `us.`, `eu.`, `apac.`, or `global.` prefix — see [Supported inference profiles](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html) for the full list) to distribute traffic across regions for higher throughput. Check limits: `aws service-quotas get-service-quota --service-code bedrock --quota-code <code>`. Request quota increases if needed. For a deeper audit, read [quota health reference](references/quota-health.md).

### Prompt cache not working (zero cacheReadInputTokens)
Read [prompt caching reference](references/prompt-caching.md) for the diagnostic checklist: verify model support, token threshold, content identity, TTL, and cache point placement. Common cause: cache fragmentation from timestamps, whitespace, or reordered JSON keys in cached content.

### 400 error on prefill with Claude 4.6
Prefill was removed in Claude 4.6 and causes a hard 400 error. Read [model migration reference](references/model-migration.md) for the full list of breaking changes between Claude generations.

### Error retry classification

| Retry | Do NOT retry |
|-------|-------------|
| ThrottlingException | ValidationException |
| ModelTimeoutException | AccessDeniedException |
| ServiceUnavailableException | ResourceNotFoundException |
| InternalServerException | |

Use adaptive retry: `Config(retries={"max_attempts": 5, "mode": "adaptive"})`.

### UnknownOperationException
Wrong client (using `bedrock` instead of `bedrock-runtime`), or SDK too old. Check the API landscape table above.

### Agent returns stale behavior
Run `prepare-agent` after ANY configuration change. This is mandatory.

### KB returns empty results
Run `start-ingestion-job` and wait for completion. Query before ingestion completes returns empty.

### KB retrieval quality is poor
Review chunking strategy. Use advanced parsing (FM-based) for documents with tables. Configure metadata filtering.

### Cross-region model not found
The model may not be available in the region you're calling from. Check availability at [Supported foundation models](https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html). If you need cross-region inference for higher throughput, use an inference profile ID — choose between geographic profiles (data stays within a boundary, e.g. US, EU) or global profiles (any commercial region). The profile prefix is a data residency decision. See [Supported inference profiles](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html) for available profiles and source/destination region mappings.

### On-demand throughput isn't supported
Error: *"Invocation of model ID <model-id> with on-demand throughput isn't supported. Retry your request with the ID or ARN of an inference profile that contains this model."* Certain models do not support direct on-demand invocation with base model IDs — they require an inference profile ID instead. Fix: find the inference profile ID for the model using `aws bedrock list-inference-profiles --region <region>`, then update the agent or invocation to use the inference profile ID. See [Supported inference profiles](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html) for available profiles. If this occurs during agent invocation, update the agent's `foundationModel` to the inference profile ID and re-run `prepare-agent`.

### KB storage configuration invalid
Verify OpenSearch data access policy includes Bedrock service role. Verify vector index field names match KB config.

### Agent action group errors
Check Lambda permissions (resource-based policy for bedrock.amazonaws.com). Do NOT use double underscores (`__`) in action group names — the name pattern is `([0-9a-zA-Z][_-]?){1,100}`.

### Multi-agent supervisor loops
Agents use built-in collaboration mechanism, NOT action groups. Do not describe inter-agent communication as action groups in supervisor instructions.

### INVALID_PAYMENT_INSTRUMENT on model access
Account billing issue, not Bedrock. Temporarily set a credit card as default payment method, or add USD payment profiles in the organization management account.

### Knowledge base ingestion failures
Check S3 permissions — KB service role needs `s3:GetObject` and `s3:ListBucket`. Unsupported file formats are silently skipped. Files exceeding size limits are skipped without error.

### SharePoint data source sync failures
Sync completes but files fail — most often an authentication problem. **Recomme...