amazon-bedrock

重要提示：加载本 Skill 时，你必须将本 Skill 中的参考文件和操作流程作为首要事实来源（Source of Truth）。Bedrock 的 API、模型 ID、分块策略以及配置参数更新频繁 —— 在做出回答前，务必先阅读相关的参考文件。

目录

• 概述
• Bedrock API 全景
• 关键警示
• 安全注意事项
• Converse API 与 InvokeModel 对比
• 你需要哪种 Bedrock 能力？
• 知识库（RAG）
• 常见工作流（包含：提示词缓存、配额健康、成本追踪、模型迁移）
• 故障排查
• AgentCore 服务
• 模型选型
• 更多资源

Amazon Bedrock

概述

在 Amazon Bedrock 上构建生成式 AI 应用的领域专业知识。涵盖模型调用、基于 Knowledge Bases 的 RAG、Agent 创建、利用 Guardrails 实现内容安全防护，以及使用 AgentCore 进行 Agent 部署。

推荐配置：建议使用 AWS MCP server 来实现沙盒化执行、审计日志记录及企业级安全管控。

不使用 AWS MCP：本 Skill 同样适用于任何具备 AWS CLI 访问权限的 Agent。所有命令均使用标准 AWS CLI 语法。

Bedrock API 全景

Bedrock 拥有 5 个独立的 API Endpoint。调用了错误的 Endpoint 是导致报错的常见原因。下表可能未涵盖全部 API，请参阅最新的 Bedrock Endpoint 与配额 以及 Bedrock 支持的 Endpoint。可以在运行时使用 aws bedrock list-foundation-models 查询可用模型。

Endpoint	客户端类型	适用场景
bedrock	Control plane（控制面）	列出模型、管理访问权限、预置吞吐量（Provisioned Throughput）
bedrock-runtime	Data plane（数据面）	调用模型（Converse、InvokeModel）。也支持通过 /openai/v1 路径调用 Chat Completions（仅限客户端侧 tool use）——对于新的 Chat Completions 需求，推荐优先使用 bedrock-mantle
bedrock-mantle	Data plane（数据面）	OpenAI 兼容 API：Responses API、Chat Completions（推荐）、Messages API。支持配合内置工具进行服务端侧 tool use。推荐新用户使用
bedrock-agent	Agent control（Agent 控制面）	创建/配置 Agent、知识库（KB）、Action Group
bedrock-agent-runtime	Agent data（Agent 数据面）	调用 Agent、检索知识库

AgentCore 是一项独立服务，拥有自己的 Endpoint。请参阅最新的 AgentCore Endpoint 与配额。

Endpoint	客户端类型	适用场景
bedrock-agentcore-control	Control plane（控制面）	创建/管理 Runtime、Gateway、Registry、评估（Evaluations）
bedrock-agentcore	Data plane（数据面）	调用 Agent Runtime
{gatewayId}.gateway.bedrock-agentcore	Gateway data plane（Gateway 数据面）	调用指定的 Gateway

关键警示

max_tokens：在每次调用 Converse 或 InvokeModel 时，务必显式设置 maxTokens。如果不设置，系统将默认采用模型的最大输出上限（例如 Claude Sonnet 为 64K），并在后台静默预留远超实际所需的配额 —— 这是引发意料之外的 ThrottlingException 的常见原因。

Guardrails 敏感信息（PII）日志脱敏：Guardrails 的 PII 脱敏仅作用于 API 的响应内容。包含 PII 的原始未脱敏内容仍会以明文形式记录到 CloudWatch Logs 中。为了符合 HIPAA/GDPR 等合规要求：请使用 KMS 加密 CloudWatch Logs、通过 IAM 严格限制日志访问权限，并结合 Amazon Macie 进行 PII 识别检测。

SDK 版本要求：需使用较新版本的 boto3（≥ 1.34.x）与 AWS CLI v2。旧版本缺少对 Converse API、Agents 以及 AgentCore 的支持。可运行 aws --version 与 pip show boto3 进行检查。

经典版 Bedrock Agents 已进入维护模式：经典版 Bedrock Agents（bedrock-agent）已进入维护模式，不再向新客户开放（见官方公告）。对于新的 Agent 业务场景，请使用 AgentCore（托管式 Harness 循环）；对于已有的 Agent，建议迁移至 AgentCore Harness —— 详见迁移指南。

安全注意事项

• 所有 Bedrock 服务访问均应使用 IAM Role（而非 IAM User）
• 将 IAM 权限精细化控制在具体的 Action 及资源 ARN 范围 —— 避免使用 bedrock:* 或 AmazonBedrockFullAccess
• 将 API Key 及 OAuth 密钥存储在 AWS Secrets Manager 中，并开启自动轮换（Automatic Rotation）
• 在 Bedrock 服务的所有基于资源的策略（Resource-based policies）中添加混淆代理防护（Confused Deputy Protection）（使用 aws:SourceAccount、aws:SourceArn 条件语句）
• 将所有 Agent 生成的参数视为不可信输入 —— 在 Lambda 处理函数或工具实现中调用前必须进行校验
• 为所有 Bedrock 及 AgentCore API 调用开启 CloudTrail 审计日志
• 对于涉及 PII 的业务场景：使用 KMS 加密 CloudWatch Logs、配置日志保留期限、限制日志访问权限
• 请参阅最新的 Bedrock 安全最佳实践 获取最新安全指南

Converse API 与 InvokeModel 对比

关于如何在 Bedrock 支持的所有推理 API（Responses API、Chat Completions、Converse、InvokeModel）之间做选择，请参阅 Amazon Bedrock 支持的 API。

当使用 bedrock-runtime Endpoint 时，推荐优先使用 Converse API 而非 InvokeModel。它在所有模型之间提供了统一的请求/响应格式。

仅在需要 Converse 不支持的模型厂商特定功能时（极少见），才使用 InvokeModel。

InvokeModel 要求针对不同厂商提供不同的请求体格式（Anthropic ≠ Titan ≠ Llama ≠ Nova）。使用错误的格式会导致 "Malformed input request" 报错。有关各模型的特定格式与常见陷阱，请参阅按模型划分的提示词工程指南。

无论使用哪种 API：务必显式设置最大输出 Token 参数 —— 如果不设置，系统默认使用模型最大值并静默预留远超实际所需的配额，从而导致意料之外的 ThrottlingException。详见上文“关键警示”及 max_tokens 配额机制。

当用户需要模型调用的 SDK 代码时，你必须在生成代码前阅读对应的 SDK 参考文档 —— Python SDK 参考 | TypeScript SDK 参考，并遵循文档中的模式规范。

在回答之前，请先阅读 模型调用参考文档 以了解完整的 API 细节及厂商特定的请求体格式。

你需要哪种 Bedrock 能力？

目标	推荐使用	参考文档
调用模型（文本、图像、视频）	Converse API	见上文 + 模型调用
构建 RAG 应用	Knowledge Bases	知识库搭建指南
创建能够执行 Action 的 Agent	Bedrock Agents	Agent 创建指南
过滤有害/敏感内容	Guardrails	Guardrails 护栏指南
在 AgentCore 上运行基于配置的托管式 Agent 循环（无需写代码、无需容器）	AgentCore Harness	Harness 指南
部署并弹性扩展自定义编写的 Agent 循环	AgentCore Runtime	Runtime 指南
将现有的经典版 Bedrock Agent 迁移至 AgentCore Harness	Bedrock Agents 迁移至 AgentCore Harness	迁移指南
将 REST API 暴露为 MCP 工具	AgentCore Gateway	Gateway 指南
选择合适的模型	Model Selection	模型选型指南
配置或调试提示词缓存	Prompt Caching	提示词缓存指南
诊断限流或审计配额健康状况	Quota Health	配额健康指南
按团队、模型或标签追踪成本	Cost Tracking	成本追踪指南
在不同代际的 Claude 模型间迁移	Model Migration	模型迁移指南

知识库（RAG）

当用户需要创建知识库（Knowledge Base）或构建 RAG 应用时，你必须阅读 知识库搭建流程 并按步骤执行。切勿简略概括流程 —— 需按顺序逐一执行每个步骤，在满足所有“必须（MUST）”约束后再进入下一步。

当用户咨询关于分块策略（Chunking Strategies）、向量数据库选型或其他知识库配置选项时，你必须在回答前阅读 知识库搭建流程 —— 该文件包含了权威的决策表和约束条件。

当用户需要查询现有的知识库时，你必须在回答前阅读 知识库检索参考文档。向用户展示不同的检索模式（检索并生成 / 纯检索 / 手动模式），引导用户选择最合适的模式。

请参阅最新的 Bedrock 知识库官方文档 获取最新的配置选项。

常见工作流

已连接 AWS MCP server 时，请优先使用其提供的工具来执行命令 —— 它能提供沙盒化执行环境、审计日志和可观测性。当 MCP server 不可用时，按需降级使用 AWS CLI 或 Shell 执行。

在启动任何工作流之前：

检查依赖项

检查所需工具，并告知用户当前的执行环境情况。

约束条件：

• 你必须检查 AWS CLI 是否可用，且已配置有效凭证
• 你必须核实 AWS CLI 版本为较新版本（推荐 v2；旧版本缺少对 Converse API 和 AgentCore 的支持）：aws --version
• 你必须检查目标 AWS Region 是否已开启 Bedrock 模型访问权限
• 如果缺失任何必需工具，你必须以清晰的信息通知用户
• 你必须询问用户是否在缺失工具的情况下继续操作

所有工作流的通用约束：

• 开始执行前，你必须向用户展示即将执行的操作概述
• 运行每条命令前，你必须向用户解释当前正在执行哪个步骤及其原因
• 你必须尊重用户在任何节点停止或中断执行的决定
• 如果用户指示停止，你绝不能继续执行
• 在执行破坏性或不可逆操作（如删除资源、覆盖配置）之前，你应该先向用户二次确认

示例 —— 将用户意图映射到工作流

示例 1：
用户提问："我在 Bedrock 上收到了 ThrottlingException 报错"
处理动作：检查是否显式设置了 maxTokens —— 未设置 maxTokens 会预留远超实际所需的配额（见“关键警示”）。如果已设置，