amazon-bedrock
熱門在 Amazon Bedrock 上建置生成式 AI 應用程式。涵蓋模型呼叫（Converse API、InvokeModel）、結合知識庫的 RAG、Bedrock Agents、Guardrails 防護機制，以及 AgentCore（包含 Harness 代管 Agent 循環）。適用於：呼叫模型、設定 Knowledge Bases 知識庫、建立 Agent、套用防護欄、部署至 AgentCore、將 Bedrock Agent（包含 inline agents）轉移／移植／轉換至 AgentCore Harness、排查 Bedrock 錯誤（如 ThrottlingException、AccessDeniedException），或選擇模型（Claude、Llama、Nova、Titan）。亦適用於：Prompt 快取設定與除錯、配額健康檢查與限流（Throttling）診斷、成本歸因與追蹤、跨 Claude 模型世代轉移（4.5 至 4.6 至 4.7）、分塊（Chunking）策略、API 選擇（Converse vs InvokeModel）、防護欄功能及模型選型。此外還涵蓋 AgentCore Payments 設定（x402、微額交易、Payment Manager、Connector、Instrument、Coinbase CDP、Stripe Privy、402 Payment Required、內容付費、付費端點、Agent 支付）。不適用於客制化模型訓練、Rekognition 或 Comprehend。
在 Amazon Bedrock 上建置生成式 AI 應用程式。涵蓋模型呼叫（Converse API、InvokeModel）、結合知識庫的 RAG、Bedrock Agents、Guardrails 防護機制，以及 AgentCore（包含 Harness 代管 Agent 循環）。適用於：呼叫模型、設定 Knowledge Bases 知識庫、建立 Agent、套用防護欄、部署至 AgentCore、將 Bedrock Agent（包含 inline agents）轉移／移植／轉換至 AgentCore Harness、排查 Bedrock 錯誤（如 ThrottlingException、AccessDeniedException），或選擇模型（Claude、Llama、Nova、Titan）。亦適用於：Prompt 快取設定與除錯、配額健康檢查與限流（Throttling）診斷、成本歸因與追蹤、跨 Claude 模型世代轉移（4.5 至 4.6 至 4.7）、分塊（Chunking）策略、API 選擇（Converse vs InvokeModel）、防護欄功能及模型選型。此外還涵蓋 AgentCore Payments 設定（x402、微額交易、Payment Manager、Connector、Instrument、Coinbase CDP、Stripe Privy、402 Payment Required、內容付費、付費端點、Agent 支付）。不適用於客制化模型訓練、Rekognition 或 Comprehend。
重要：當載入此 Skill 時，您必須將此 Skill 中的參考檔案與流程視為主要的事實來源（Source of Truth）。Bedrock API、模型 ID、分塊策略及設定參數會頻繁變更 — 在回應之前，請務必閱讀相關的參考檔案。
目錄
- 概覽
- Bedrock API 全貌
- 重要警告
- 安全考量
- Converse API vs InvokeModel
- 您需要哪種 Bedrock 功能？
- Knowledge Bases 知識庫 (RAG)
- 常見工作流程（包含：Prompt 快取、配額健康度、成本追蹤、模型轉移）
- 疑難排解
- AgentCore 服務
- 模型選型
- 其他資源
Amazon Bedrock
概覽
在 Amazon Bedrock 上建置生成式 AI 應用程式的領域專業知識。涵蓋模型呼叫、結合知識庫的 RAG、Agent 建立、透過 Guardrails 進行內容安全防護，以及使用 AgentCore 部署 Agent。
建議設定： 使用 AWS MCP server 以獲得沙盒化執行、稽核日誌及企業級管控能力。
未搭配 AWS MCP： 本 Skill 可搭配任何具備 AWS CLI 存取權限的 Agent 使用。所有命令皆採用標準 AWS CLI 語法。
Bedrock API 全貌
Bedrock 擁有 5 個獨立的 API 端點。使用錯誤的端點是造成錯誤的常見原因。此清單可能未盡列出所有端點 — 最新資訊請參考 Bedrock 端點與配額 及 Bedrock 支援的端點。可在執行階段使用 aws bedrock list-foundation-models 來探索可用模型。
| 端點 | 用途分類 (Client) | 適用場景 |
|---|---|---|
bedrock |
控制面 (Control plane) | 列出模型、管理存取權限、預置輸送量 (Provisioned throughput) |
bedrock-runtime |
資料面 (Data plane) | 呼叫模型（Converse、InvokeModel）。亦支援透過 /openai/v1 路徑使用 Chat Completions（僅限用戶端工具呼叫）— 若為新的 Chat Completions 工作，建議優先使用 bedrock-mantle |
bedrock-mantle |
資料面 (Data plane) | 相容 OpenAI 的 API：Responses API、Chat Completions（推薦）、Messages API。支援搭配內建工具的伺服器端工具呼叫。推薦新使用者使用 |
bedrock-agent |
Agent 控制面 | 建立／設定 Agent、KB（知識庫）、Action Groups（動作群組） |
bedrock-agent-runtime |
Agent 資料面 | 呼叫 Agent、查詢 KB（知識庫） |
AgentCore 是一項獨立服務，擁有自身的端點。最新資訊請參考 AgentCore 端點與配額。
| 端點 | 用途分類 (Client) | 適用場景 |
|---|---|---|
bedrock-agentcore-control |
控制面 (Control plane) | 建立／管理 Runtime、Gateway、Registry、Evaluation |
bedrock-agentcore |
資料面 (Data plane) | 呼叫 Agent Runtime |
{gatewayId}.gateway.bedrock-agentcore |
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 角色（IAM roles），而非 IAM 使用者（IAM users）
- 將 IAM 權限範圍限縮至具體的動作與資源 ARN — 避免使用
bedrock:*或AmazonBedrockFullAccess - 將 API 金鑰與 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 vs InvokeModel
關於所有 Bedrock 推理 API（Responses API、Chat Completions、Converse、InvokeModel）之間的選擇，請參閱 Amazon Bedrock 支援的 API。
在使用 bedrock-runtime 端點時，優先選擇 Converse API 而非 InvokeModel。它跨所有模型提供了統一的請求／回應格式。
僅在需要 Converse 中未提供的模型提供商專屬功能時（極少見），才使用 InvokeModel。
InvokeModel 針對不同提供商需要不同的請求內文（Request body）格式（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 | KB 設定指南 |
| 建立可執行動作的 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 快取 | Prompt Caching | Prompt 快取指南 |
| 診斷限流或稽核配額 | Quota Health | 配額健康指南 |
| 按團隊、模型或標籤追蹤成本 | Cost Tracking | 成本追蹤指南 |
| 在 Claude 世代版本間轉移 | Model Migration | 轉移指南 |
Knowledge Bases 知識庫 (RAG)
當使用者想要建立 Knowledge Base 或建置 RAG 應用程式時，您必須閱讀 KB 設定流程 並逐步執行。切勿摘要該流程 — 請依序執行每個步驟，並在遵循所有「必須（MUST）」約束條件後再進行下一步。
當使用者詢問關於分塊（Chunking）策略、向量資料庫選擇或其它 KB 設定選項時，您在回應前必須閱讀 KB 設定流程 — 該檔案包含權威的決策表與約束條件。
當使用者想要查詢現有的 Knowledge Base 時，您在回應前必須閱讀 KB 檢索參考指南。請展示各種檢索模式（retrieve-and-generate vs retrieve vs 手動模式），以便使用者選擇最適合的模式。
有關目前的設定選項，請參考最新的 Bedrock Knowledge Base 文件。
常見工作流程
連線時，請使用 AWS MCP server 提供之可用工具執行命令 — 它提供沙盒化執行、稽核日誌及可觀測性（Observability）。當 MCP server 無法使用時，請視需要降級回退使用 AWS CLI 或 Shell。
在開始任何工作流程前：
驗證相依性
檢查所需的工具，並告知使用者執行環境的相關資訊。
約束條件：
- 您必須檢查 AWS CLI 是否可用，且已設定有效的憑證
- 您必須驗證 AWS CLI 版本是否為最新版本（建議 v2；舊版本缺少 Converse API 及 AgentCore 支援）：
aws --version - 您必須檢查目標 AWS 區域是否已啟用 Bedrock 模型存取權限
- 若缺少任何必備工具，您必須以清晰的訊息告知使用者
- 若缺少工具，您必須詢問使用者是否仍要繼續執行
所有工作流程的通用約束條件：
- 在開始執行之前，您必須提供即將執行事項的概覽
- 在執行每個命令之前，您必須向使用者解釋目前正在執行哪個步驟及其原因
- 您必須尊重使用者在任何時間點停止或中斷執行的決定
- 若使用者表示希望停止，您絕對不得繼續執行
- 在執行破壞性或不可逆的操作（如刪除資源、覆寫設定）之前，您應該先進行確認
範例 — 將使用者意圖對映至工作流程
範例 1：
使用者查詢："I'm getting ThrottlingException on Bedrock"（我在 Bedrock 上遇到 ThrottlingException 錯誤）
動作：檢查是否已明確設定 maxTokens — 未設定的 maxTokens 會預留遠超出實際需要的配額（參閱重要警告）。如果已經設定，
<!-- 翻譯批次截斷；完整內文延續自原始碼 -->
