本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # AI 代理程式產品 ## 什麼是 AI 代理器產品？ AI 代理器是利用人工智慧代表人類或系統推理、規劃和完成任務的軟體系統。與遵循固定規則的傳統軟體不同，AI 代理器會獨立運作，透過多步驟程序進行調整以達成特定目標。 AI 代理器結合用於推理和規劃的基礎模型與離散代理工具 （例如護欄、知識庫和商業邏輯），以處理請求、擷取資訊和執行任務。他們可以搜尋知識庫、呼叫 APIs、更新系統，並根據使用者需求和環境內容做出決策。 代理程式工具是特殊元件，可增強 AI 代理程式功能，包括： + 網域特定資訊的知識庫 + 安全與合規的護欄 + 整合通訊協定 like AWS MCP 伺服器 (MCP) + 專用 APIs 和微服務 + 商業邏輯元件和工作流程 ## 適用於 的 AI 代理器和工具類型 AWS Marketplace AWS Marketplace 支援跨不同產業和使用案例的各種 AI 代理器和工具。常見類型包括下列項目，但這不是詳盡的清單： **內容建立代理程式** 產生、編輯或最佳化內容的代理程式，包括文字、影像、影片和多媒體。範例包括撰寫助理、社交媒體內容產生器和行銷自動化代理程式。 **資料分析代理程式** 處理、分析和衍生資料洞見的代理程式。範例包括商業智慧代理程式、財務分析工具和預測分析系統。 **客戶服務客服人員** 處理客戶互動、支援請求和服務自動化的客服人員。範例包括聊天機器人、票證路由系統和客戶體驗最佳化工具。 **Business-process-automation代理程式** 自動化複雜業務工作流程和程序的代理程式。範例包括文件處理代理程式、核准工作流程系統和合規自動化工具。 **安全與合規代理程式** 監控、偵測和回應安全威脅或合規要求的代理程式。範例包括威脅偵測系統、稽核自動化工具和風險評估代理程式。 **開發人員工具代理程式** 協助軟體開發、測試和部署的代理程式。範例包括程式碼產生助理、測試自動化代理程式和部署最佳化工具。 **代理工具** 增強其他 AI 代理器的特殊元件，包括知識庫、護欄和整合通訊協定，例如 AWS MCP 伺服器 (MCP)。 ## AI 代理器產品的部署選項 AWS Marketplace 支援 AI 代理器的多個部署選項，可讓您選擇最適合您的架構和客戶需求的方法： + **API 部署選項** – API 部署選項可讓客戶透過廠商託管的端點存取 AI 代理程式。此選項非常適合需要特殊基礎設施或專屬模型的客服人員和客服人員工具，而您想要保留在您自己的環境中。 + **容器部署** – 將您的 AI 代理程式和代理程式工具封裝為容器化應用程式，客戶可以在自己的 AWS 環境中執行。此選項可讓客戶更好地控制其資料和基礎設施。 ## 選擇正確的部署選項 選擇 AI 代理器或工具的部署選項時，請考慮下列因素： + **資料敏感** – 如果您的客戶使用無法離開環境的高度敏感資料，容器部署可能是最佳選項。 + **模型複雜性** – 對於需要專用硬體的大型或複雜模型，API 部署可能更實際。 + **營運開銷** – 考慮在不同部署模型中維護和更新解決方案所需的資源。 以下是部署選項之間的快速功能比較： | 功能 | API 部署 | 容器部署 | | --- | --- | --- | | 託管 | 廠商託管端點 | 客戶自己的 AWS 環境 | | 資料控制 | 在廠商伺服器上處理的資料 | 加強客戶對資料的控制 | | 基礎設施需求 | 最小 - 使用廠商基礎設施 | 要求客戶管理基礎設施 | | 可擴展性 | 由廠商管理 | 客戶控制，可能更具彈性 | | 自訂 | 有限 - 以 API 功能為基礎 | 高 - 完全控制環境 | | Maintenance (維護) | 由廠商處理 | 負責更新和維護的客戶 | | 安全 | 取決於廠商的安全措施 | 根據客戶需求自訂安全性 | | 更新和改進 | 由廠商自動提供 | 需要手動更新，但依照客戶的排程 | | 法規合規 | 可能受到廠商憑證的限制 | 更輕鬆地適應特定法規要求 | # 列出 SaaS API 型 AI 代理器產品 身為 AWS Marketplace 賣方，您可以將軟體新增為服務 (SaaS) API 型 AI 代理程式或工具產品 AWS Marketplace。這包括根據您的帳單模型建立您的產品，並將其與適當的 AWS Marketplace API 操作整合。 若要在 中以 SaaS API 型 AI 代理器或工具產品的形式銷售軟體 AWS Marketplace，請遵循下列步驟： + 在其中建立 SaaS API 型 AI 代理器或工具產品 AWS Marketplace。 + AWS Marketplace 根據您的定價模式，將您的 產品與 整合： + 如需訂閱型產品的相關資訊，請參閱 [將您的 SaaS 訂閱或Pay-As-You-Go產品與 整合 AWS Marketplace](saas-integrate-subscription.md)。 + 如需有關以合約為基礎的產品的資訊，請參閱 [將您的 SaaS 合約產品與 整合 AWS Marketplace](saas-integrate-contract.md)。 + 如需與 pay-as-you-go 產品簽訂合約的相關資訊，請參閱 [將您的 SaaS 合約型產品與 整合 AWS Marketplace](saas-integrate-contract-with-pay.md)。 + 測試您產品的整合： + 如需測試訂閱型產品的相關資訊，請參閱 [測試您的 SaaS 訂閱產品整合](saas-integrate-subscription.md#saas-subscription-integration-testing)。 + 如需有關測試以合約為基礎的產品的資訊，請參閱 [測試您的 SaaS 合約產品整合](saas-integrate-contract.md#saas-contract-integration-testing)。 + 如需使用pay-as-you-go產品測試合約的相關資訊，請參閱 [使用隨需pay-as-you-go整合測試您的 SaaS 合約](saas-integrate-contract-with-pay.md#saas-contract-consumption-integration-testing)。 + 提交您的產品以啟動。 ## 先決條件 開始之前，請確定您有下列項目： + 清楚了解您的 AI 代理器功能和目標使用案例 + 適當的安全措施和合規認證 + 整合和部署的技術文件 + 與您的商業模式一致的定價策略 + 如需定價策略的詳細資訊，請參閱 [中的 SaaS 產品定價 AWS Marketplace](saas-pricing-models.md)。 ## 管理 SaaS API 型 AI 代理器和工具 所有以 SaaS API 為基礎的 AI 代理器和工具都可以透過統一 **AI 代理器和工具**產品頁面或 AWS Marketplace 管理主控台中的 **SaaS** 產品頁面進行管理。 ## 啟動清單精靈 1. 登入 [AWS Marketplace 管理入口網站](https://aws.amazon.com/marketplace/management/)。 1. 在導覽列中，選取**產品**，然後選擇 **AI 代理器和工具**。 1. 從**建立 AI 代理程式和工具產品**功能表中，選擇 **API 型 AI 代理程式和工具**。 1. 輸入產品標題。 1. 選擇**產生產品 ID 和產品代碼**。 1. （選用） 新增標籤以支援標籤型授權。 1. 選擇**繼續精靈**。 **注意** 如需標籤型授權的相關資訊，請參閱《[AWS Identity and Access Management 使用者指南》中的使用標籤控制](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_tags.html#access_tags_control-resources)AWS Identity and Access Management 資源的存取。 ## 步驟 1：提供產品資訊 您在此步驟中提供的資訊會傳達產品的價值主張。 1. 提供產品資訊索引標籤的詳細資訊： + **產品標題** + **SKU** （選用） + **產品標誌 S3 URL** + **簡短描述** + **長描述** + **產品影片 URL** （選用） + **反白 **(1-3) 1. 透過選擇新增資源，輸入支援詳細資訊並新增選用的學習**資源**。 1. 在**產品類別**功能表中，選擇 1-3 個類別。 + 我們建議您從 **AI Agents & Tools** 商業類別中至少選擇一個類別。 1. 輸入關鍵字以改善搜尋可探索性。 1. （選用） 根據準則新增影片和影像資產。 1. 選擇**下一步**。 ## 步驟 2：設定履行選項 1. 選擇履行方法： + **快速啟動** （建議） - 賣方與[AWS Marketplace 部署 API](https://docs.aws.amazon.com/marketplace/latest/APIReference/API_Operations_AWS_Marketplace_Deployment_Service.html) 整合，並在訂閱時將 API 金鑰直接提供給客戶的 AWS 帳戶。 + **重新導向至您的網站** - 客戶將重新導向至您的網站，以取得 API 金鑰或 OAuth 權杖。 **注意** 您無法在發佈產品後變更履行方法。 1. 輸入履行 URL。這是使用者登入或建立 帳戶的 URL。 1. 選擇您的 AI 代理器或工具詳細資訊： + **AI 代理程式** - 使用 AI 透過推理和決策處理請求並完成任務的軟體。 + **AI 工具**： + **MCP 伺服器** - 管理 AI 模型和應用程式之間的通訊和內容交換的伺服器。 + **知識庫** - AI 代理器用於通知決策和回應的結構化資訊集合。 + **護欄** - 定義 AI 代理器行為和操作界限的規則和控制項。 + **其他** - 增強 AI 代理器功能的其他工具。 1. 輸入端點 URL。這是您的 API 接收請求的 URL。對於 MCP 伺服器，列出 MCP 端點。 1. 新增使用說明： + 提供買方使用您的 API 的詳細指示，例如 API 結構描述、速率限制和用量範例。 + 您也可以提供 文件的其他連結。 1. 選擇授權方法： + **API 金鑰** – 客戶使用您提供的 API 金鑰進行身分驗證。 + **OAuth** – 客戶使用 OAuth 2.0 授權流程進行身分驗證。如果您選擇 OAuth，請為客戶提供明確的使用說明，包括： + OAuth 授權 URL 和字符端點 + 必要的範圍和許可 + Step-by-step身分驗證流程說明 + 具有適當身分驗證標頭的範例 API 呼叫 + 針對常見的身分驗證問題進行故障診斷 1. （選用） Amazon Bedrock AgentCore 整合 + 如果您列出支援兩邊 OAuth 身分驗證的 MCP 伺服器，您可以使用 MCP 伺服器端點做為目標，啟用與 Amazon Bedrock AgentCore Gateway 的整合。如需詳細資訊，請參閱 [MCP 伺服器目標](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-target-MCPservers.html)。在此情況下，不需要 OpenAPI 規格。 + 如果您使用 API 金鑰身分驗證列出任何其他 API 型產品或 MCP 伺服器，您可以提供 OpenAPI 規格來啟用與 Amazon Bedrock AgentCore 的整合。 + 若要進一步了解 AgentCore 部署和擴展 AI 代理器的功能，請參閱[什麼是 Amazon Bedrock AgentCore？](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/what-is-bedrock-agentcore.html) 1. （選用） - 選擇 API 整合通訊協定並提供使用說明： + **MCP** - 模型內容通訊協定 (MCP) 標準化對外部工具、資料和服務的存取，以增強功能。 + **A2A** - Agent2Agent (A2A) 可啟用跨不同平台的直接通訊和任務委派。 1. 如果您選擇 AI 代理器工具類型，請確認您的代理器使用推理 LLMs並示範自動功能。這些要求有助於確保 AWS Marketplace 上提供的代理程式符合高品質標準。如果您的代理程式不符合這兩個要求，請選擇不同的工具類型。 ## 步驟 3：設定產品定價 若要提供您的產品 AWS Marketplace，請決定定價模式並定義產品的定價維度。如需可用定價選項的詳細資訊，請參閱 [中的 SaaS 產品定價 AWS Marketplace](saas-pricing-models.md)。 每個維度都是產品的特徵、服務或其他方面，您可以為其設定每單位價格。 1. 選擇定價模型。 1. 選擇**下一步**。 ## 步驟 4：檢閱價格 1. 檢閱產品定價。 1. 選擇**下一步**。 **注意** 基於測試目的，我們會將價格設定為 \$10.001 或 \$10.00000001。您現在不需要變更價格。這可讓您的團隊和 AWS Marketplace 賣方營運團隊以較低的價格測試產品，而不會產生測試的大型帳單。當您請求產品公開的產品可見性時，您將提供實際定價。 ## 步驟 5：指定退款政策 1. 輸入您產品的退款政策。 1. 選擇**下一步**。 ## 步驟 6：設定最終使用者授權合約 (EULA) 1. 選擇**適用於 的標準合約 AWS Marketplace**，或為您的**自訂 EULA** 提供 S3 URL。 + 如需使用標準合約的詳細資訊，請參閱 [在 中使用標準化合約 AWS Marketplace](standardized-license-terms.md)。 1. 選擇**下一步**。 ## 步驟 7：設定優惠可用性 根據預設，列出的產品 AWS Marketplace 可在 AWS 支援的所有國家/地區購買。您可以選擇透過識別買方可以或無法購買您產品的國家/地區，來啟用國家/地區特定的可用性。 1. 依國家/地區選擇您的優惠可用性。 1. 選擇**下一步**。 ## （選用） 步驟 8：設定允許清單 發佈的所有新產品清單都會以有限的可見性 AWS Marketplace 啟動。您可以將選取 AWS 帳戶 IDs 新增至允許清單，以控制哪些帳戶可以存取您的有限產品，包括產品的有限版本。 若要將 AWS 帳戶新增至允許清單： 1. 輸入您需要新增至允許清單的逗號分隔 AWS 帳戶 IDs。 1. 選擇**提交**。 **注意** 僅將測試帳戶新增至允許清單以進行測試。 ## 在 中修改 SaaS API 型 AI 代理器產品設定 AWS Marketplace 在 中建立 **SaaS API 型代理程式和工具產品**之後 AWS Marketplace，您可以修改許多產品設定。如需提交變更請求和修改產品設定的相關資訊，請參閱下列主題： ### 產品變更和請求 + 如需管理變更請求的資訊，請參閱 [管理變更請求](saas-product-settings.md#create-change-request)。 + 如需更新產品資訊的資訊，請參閱 [更新產品資訊](saas-product-settings.md#update-product-information)。 + 如需更新架構詳細資訊的詳細資訊，請參閱 [更新架構詳細資訊](saas-product-settings.md#updating-architecture-details)。 ### 存取和可見性 + 如需更新允許清單的資訊，請參閱 [更新 AWS 帳戶 IDs的允許清單](saas-product-settings.md#update-allowlist)。 + 如需變更產品可見性的資訊，請參閱 [更新產品可見性](saas-product-settings.md#saas-update-visibility)。 + 如需管理買方存取權的資訊，請參閱 [更新定價條款](saas-product-settings.md#saas-update-pricing-terms)。 + 如需國家/地區可用性的詳細資訊，請參閱 [依國家/地區更新可用性](saas-product-settings.md#saas-availability-by-country)。 ### 定價和條款 + 如需更新定價條款的詳細資訊，請參閱 [更新定價條款](saas-product-settings.md#saas-update-pricing-terms)。 + 如需新增定價維度的詳細資訊，請參閱 [新增定價維度](saas-product-settings.md#saas-add-pricing-dimensions)。 + 如需更新定價維度的詳細資訊，請參閱 [更新定價維度](saas-product-settings.md#saas-update-dimension)。 + 如需限制定價維度的資訊，請參閱 [限制定價維度](saas-product-settings.md#restrict-pricing-dimensions)。 ### 法律和授權 + 如需更新退款政策的詳細資訊，請參閱 [更新產品的退款政策](saas-product-settings.md#update-refund-policy)。 + 如需更新 EULA 的資訊，請參閱 [更新最終使用者授權合約 (EULA)](saas-product-settings.md#saas-update-eula)。 ### 提供免費產品 如果您的產品可見性有限： + 提交請求，將可見性從限制變更為公有。 + 輸入所有定價維度的 0 美元。 如果您的產品已公開： + 提交**更新定價條款**變更請求。 + 輸入所有定價維度的 0 美元。 **注意** 將產品設定為免費之後，您就無法將其轉換為付費產品。 # 整合 API 型 AI 代理器產品 ## API 型 AI 代理器產品準則 AWS Marketplace 提供所有軟體即服務 (SaaS) API 型 AI 代理器產品的指導方針。這些準則可確保為客戶提供安全且值得信賴的體驗。 **Topics** + [產品審核程序](#product-review-process) + [維持合規](#maintaining-compliance) ### 產品審核程序 當您提交產品時， 會 AWS Marketplace 檢閱產品及其中繼資料，以確認其符合目前的準則。我們會定期更新這些準則，以因應不斷變化的安全需求。 ### 維持合規 AWS Marketplace 會持續監控產品以驗證合規性。如果您的產品不符合目前的準則： + 在您解決問題之前，您的產品可能無法供新訂閱用戶使用 + 您必須更新產品以符合新的需求 | Category | 指導方針 | | --- | --- | | API 和代理程式功能 | 所有 APIs都應正常運作並適當回應。如果您要列出 代理程式，解決方案必須透過在沒有明確外部命令或常式人工輸入的情況下操作來示範自主功能。 | | API 存取和身分驗證 | 客戶應該能夠訂閱您的清單並擷取 API 金鑰，或依照步驟產生 OAuth 權杖。 | | 架構準則 | [如需詳細資訊，請遵循架構準則。](https://docs.aws.amazon.com/marketplace/latest/userguide/saas-guidelines.html#saas-architecture) | | 客戶資訊要求 | [如需詳細資訊，請遵循客戶資訊需求。](https://docs.aws.amazon.com/marketplace/latest/userguide/saas-guidelines.html#saas-customer-information) | | 金鑰管理 | 供應商應讓客戶能夠使金鑰失效/輪換。一旦客戶取消訂閱清單，廠商也應該有使金鑰失效的機制。 | | MCP 伺服器需求 （如適用） | 對於 MCP Server，廠商應該提供遠端 MCP 組態詳細資訊，以及要設定的任何先決條件或環境變數。 | | 產品設定 | [如需詳細資訊，請遵循產品設定準則。](https://docs.aws.amazon.com/marketplace/latest/userguide/saas-guidelines.html#saas-guidelines-setup) | | 產品用量 | [如需詳細資訊，請遵循產品使用準則。](https://docs.aws.amazon.com/marketplace/latest/userguide/saas-guidelines.html#saas-product-usage) | | 使用說明 | 使用說明應清楚說明先決條件、身分驗證設定、支援的端點、請求/回應結構描述、工具描述、錯誤碼和其他資源。 | ## 整合 API 型 AI 代理器產品 ### 根據產品定價進行整合 將您的產品與 整合， AWS Marketplace 是列出 API 型 AI 代理器產品的一個步驟。若要將 API 型 AI 代理器產品與 整合 AWS Marketplace，您必須撰寫程式碼，並示範它可以成功回應數個客戶案例。 如需根據不同定價模型整合產品的相關資訊，請參閱下列主題： + 如需訂閱型產品的相關資訊，請參閱 [將您的 SaaS 訂閱或Pay-As-You-Go產品與 整合 AWS Marketplace](saas-integrate-subscription.md)。 + 如需有關以合約為基礎的產品的資訊，請參閱 [將您的 SaaS 合約產品與 整合 AWS Marketplace](saas-integrate-contract.md)。 + 如需與pay-as-you-go產品簽訂合約的相關資訊，請參閱 [將您的 SaaS 合約型產品與 整合 AWS Marketplace](saas-integrate-contract-with-pay.md)。 ### 客戶加入 #### 重新導向至網站履行 當客戶透過 訂閱您的產品時 AWS Marketplace，他們會存取您 AWS 環境中的產品。訂閱後，我們會引導客戶前往您的產品網站，註冊其帳戶並設定產品。 + 了解如何在 中使用重新導向至網站履行來加入客戶[透過 將客戶加入您的 SaaS 產品 AWS Marketplace](saas-product-customer-setup.md)。 #### QuickLaunch 履行 客戶透過 訂閱您的產品時 AWS Marketplace，會收到 API 金鑰或 OAuth 登入資料，以呼叫您的 API 端點或 MCP 伺服器。程序的運作方式如下： + 客戶訂閱產品。 + 客戶在您的網站上註冊或登入 帳戶。 + 您可以使用 **PutDeploymentParameter** API，將 API 金鑰或 OAuth 登入資料存放在客戶的 AWS Secrets Manager 中。 + 如果您在 API 金鑰的情況下存放一個參數，請呼叫 `secretString` 參數為字串的 `PutDeploymentParameter` API。如果您在 OAuth 登入資料的情況下存放多個參數，請在 `secretString` 參數中提供 JSON 字串，其中包含索引鍵/值對，如下所示： ``` { "Client Id": "12345", "Client Secret": "12345", "Discovery URL" : "https://auth.example.com/.well-known/openid-configuration" } ``` 進一步了解這些資源中的 QuickLaunch 履行： + 了解部署 API 中的 **PutDeploymentParameter** API [AWS Marketplace](https://docs.aws.amazon.com/marketplace/latest/APIReference/API_Operations_AWS_Marketplace_Deployment_Service.html) + 在 中尋找客戶加入指示 [透過 將客戶加入您的 SaaS 產品 AWS Marketplace](saas-product-customer-setup.md) ### 存取 AWS Marketplace APIs 下一節概述了與 AWS Marketplace Metering Service 或 AWS Marketplace Entitlement Service 整合的程序，用於確保您產品的帳單和客戶用量報告的準確性。 + 若要進一步了解存取 AWS Marketplace APIs，請參閱 [存取 AWS Marketplace 計量和權利服務 APIs](saas-integration-metering-and-entitlement-apis.md)。 ### SNS 通知 訂閱 Amazon Simple Notification Service (Amazon SNS) 主題，以接收有關產品的客戶訂閱變更和合約權利的通知。 會在產品建立期間 AWS Marketplace 提供這些主題，協助您管理客戶存取權。 下列 Amazon SNS 主題適用於 SaaS API 型產品： + [Amazon SNS 主題： `aws-mp-entitlement-notification`](saas-notification.md#saas-sns-message-body) – 在客戶建立、升級或續約合約時，或合約過期時通知您。這僅適用於定價模型包含合約的產品。 + [Amazon SNS 主題： `aws-mp-subscription-notification`](saas-notification.md#saas-sns-subscription-message-body) – 當客戶訂閱或取消訂閱您的產品時通知您，並包含`offer-identifier`適用於私有優惠的 和適用於 SaaS 免費試用的免費試用旗標。這適用於所有定價模式，包括合約和訂閱。 ## 使用說明範本 ### MCP 伺服器使用說明範本 下列範例示範 MCP 伺服器的使用說明，包括工具描述、先決條件、身分驗證設定、熱門用戶端的組態、速率限制和其他資源： ``` To get started using the remove MCP server, follow the instructions below: **Availble Tools** This MCP server support the following tools: - Search - Performs a web search - Summarize Website - Summarizes a webpage **Prerequisites** - Install **Node.js** and **npm** **Authentication** Replace `YOUR_API_KEY` with your actual key below. **Claude Desktop** Edit the configuration file at: - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - Windows: %APPDATA%\Claude\claude_desktop_config.json Add the below code: ``` { "mcpServers": { "demo-example": { "command": "npx", "args": [ "mcp-remote", "https://remote.mcp.server/sse", "--header", "Authorization: Bearer " ] }, } } ``` **Cline** Cline stores MCP server configurations in a JSON file that can be modified. In the "Installed" tab, click "Configure MCP Servers" to access the settings file. Add the following: ``` { "mcpServers": { "demoServer": { "url": "https://remote.mcp.server/sse", "disabled": false, "autoApprove": ["searchWeb", "summarizeWebsite"], "timeout": 30 } } } ``` **Rate Limits** - 60 requests per minute per API key. - Exceeding returns HTTP 429 Too Many Requests. - Use retry and exponential backoff to handle limits. **Learn More** MCP Docs: https://mcp.search.demoproduct.com ``` ### AI Agent 和 Agent & Tools 使用說明範本 下列範例示範客服人員或客服人員工具的使用說明，包括先決條件、身分驗證設定、支援的端點、請求/回應結構描述、錯誤碼和其他資源： ``` To get started follow the instructions below: **Authentication** All API requests require this HTTP header: Authorization: Bearer `YOUR_API_KEY` Replace `YOUR_API_KEY` with your actual key. **Search Endpoint** **Endpoint:** `GET /web/search` Performs a web search. **Query Parameters:** | Param | Type | Description | |------------|--------|-------------------------------------| | `q` | string | Your search query (required) | | `count` | int | Number of results (default: 10) | | `offset` | int | Offset for pagination | | `country` | string | Country code (e.g. `us`, `de`) | | `safesearch` | string | `off`, `moderate`, or `strict` | **Example Request:** ```bash curl -X GET "https://api.search.demo.com/res/v1/web/search?q=searchtool" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Response Schema:** ``` { "results": [{ "title": "string", "url": "string", "description": "string" }], "query" :"string", "total" :"number" } ``` **Example Response:** ``` { "results": [ { "title": "DemoProductAPI", "url": "https://demo.com", "description": "Demo Product API is a search tool for..." } ], "query": "searchtool", "total": 1 } ``` **Additional Search Types** DemoProduct also supports: - `GET /news/search – News articles` - `GET /images/search – Image results` - `GET /videos/search – Video results` These endpoints follow the same format as /web/search. **Summarize Endpoint** **Endpoint:** `POST /summarize` Summarizes a webpage **Request Headers:** Content Type: application/json **Request Body:** ``` { "input": "string" // URL or plain text } ``` **Example Request:** ``` { "input": "https://example.com/article" } ``` **Response Schema** ``` { "summary": "string" } ``` **Example Response** ``` { "summary": "This article explains our commitment to user privacy." } ``` **Error Codes** | Status | Meaning | | ------ | ------------------------------ | | `401` | Unauthorized (check your key) | | `429` | Too many requests (rate limit) | | `500` | Server error | All error responses follow this structure: ``` { "error": { "code": 401, "message": "Unauthorized" } } ``` **Rate Limits** - 60 requests per minute per API key. - Exceeding returns HTTP 429 Too Many Requests. - Use retry and exponential backoff to handle limits. **Learn More** API Docs: https://api.search.demoproduct.com ``` # Amazon Bedrock AgentCore Gateway 本文件為想要列出可與 Amazon Bedrock AgentCore Gateway 整合之 API 型 AI 代理程式產品或工具的 AWS Marketplace 賣方提供資訊。 **Topics** + [概觀](#agentcore-overview) + [與 Bedrock AgentCore Gateway 整合](#bedrock-agentcore-integration) ## 概觀 Amazon Bedrock AgentCore Gateway 可協助開發人員大規模建置、部署、探索和連線至工具。服務可讓您： + 將 APIs、Lambda 函數和現有服務轉換為與模型內容通訊協定 (MCP) 相容的工具 + 透過閘道端點為客服人員提供工具 + 在全受管服務中使用全面的輸入和輸出身分驗證 AI 代理器使用這些工具來執行任務，例如： + 查詢資料庫 + 傳送訊息 + 分析文件 如需詳細資訊，請參閱 [Amazon Bedrock AgentCore 開發人員指南](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway.html)。 ## 與 Bedrock AgentCore Gateway 整合 視您的產品而定，您可以透過下列其中一種方式為您的 SaaS API AI 代理程式產品啟用 Amazon Bedrock AgentCore Gateway 整合： + 如果您列出支援兩邊 OAuth 身分驗證的 MCP 伺服器，您可以選擇加入，為買方提供整合，無需額外的要求。您在列出程序中提供的 MCP 伺服器端點將用於整合。不過，您必須確保您的 MCP 伺服器符合下列要求。如需詳細資訊，請參閱 [MCP 伺服器目標](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-target-MCPservers.html)。 + 對於所有其他代理程式或工具，您可以提供 OpenAPI 規格來啟用整合。 ### MCP 伺服器需求 您的 MCP 伺服器必須符合下列要求： + 使用下列其中一個組態的雙邊 OAuth 身分驗證： + 用戶端 ID、用戶端秘密和探索 URL + 用戶端 ID、用戶端秘密、發行者、授權端點和字符端點。 + MCP 伺服器必須具有工具功能。 + 支援的 MCP 通訊協定版本：**2025-06-18** 和 **2025-03-26**。 + 對於提供的 URL 或伺服器的端點，應該對 URL 進行編碼。Gateway 使用相同的 URL 來叫用伺服器。 ### OpenAPI 規格要求 您的 OpenAPI 規格必須： + 包含所有操作`operationId`的欄位 + 避免語意錯誤 + 在伺服器屬性中包含有效的安全 (https) 端點 URL 下表顯示支援和不支援的 OpenAPI 功能： | Category | 支援 | 不支援 | | --- | --- | --- | | 版本 | 3.0 和 3.1 | 2 | | 結構描述定義 | 基本資料類型 （字串、數字、布林值等） | oneOf 規格 | | | 必要欄位驗證 | anyOf 規格 | | | 巢狀物件 | | | | 具有項目規格的陣列 | | | | 標準 HTTP 方法 | | | 媒體類型 | application/json | 自訂媒體類型 | | | application/xml | 二進位媒體類型 | | | 分段/表單資料 | | | | x-www-form-urlencoded | | | Parameters | 簡單路徑參數和基本查詢參數，例如 string/number/boolean 類型 | 複雜路徑參數序列化 | | | | 複雜的查詢參數陣列 | | | | 標頭參數序列化 | | | | Cookie 參數序列化 | | 請求與回應 | JSON 內文 | | | | XML 內文 | | | | 標準 HTTP 狀態碼 | | | 驗證 | 基本欄位驗證 | Regex 模式驗證 | | | | 最小/最大值驗證 | | 安全 | N/A | 規格層級的安全機制 | | | | 多個安全機制 | | | | OAuth 2.0 在規格層級 | | | | 指定層級的 API 金鑰 | | | | 指定層級的 HTTP 基本身分驗證 | | 伺服器組態 | 基本 URL | | | | 具有預留位置的 URL | | ### 啟用 Bedrock AgentCore Gateway 啟用閘道整合之前，請先完成下列任務，以 Amazon Bedrock AgentCore Gateway 測試您的 OpenAPI 規格或 MCP 伺服器： + [建立閘道](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-building.html) + [連接目標](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-building-adding-targets.html) + [測試您的閘道](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-building-testing.html) **啟用閘道整合** 1. 登入 [AWS Marketplace 管理入口網站](https://aws.amazon.com/marketplace/management)。 1. 開啟 [AI 代理器和工具](https://aws.amazon.com/marketplace/management/products/aiagents)頁面。 1. 在 **AI 代理器和工具產品**索引標籤上，選取要修改的產品。 1. 從**請求變更**下拉式清單中，選取**更新履行選項**。 1. 選擇**啟用 Amazon Bedrock AgentCore 整合的工具**。 1. 上傳您的 OpenAPI 規格。對於啟用雙邊 OAuth 的 MCP 伺服器產品，這並非必要項目，而且只需要 MCP 端點。 1. 選擇**提交**。 提交後，請求狀態會在**請求**索引標籤中顯示為**審核中**。處理完成時，狀態會變更為**成功**。 # 列出容器型 AI 代理器產品 ## 管理容器型 AI 代理器和工具 在 Amazon Bedrock AgentCore 執行期上執行的容器型 AI 代理程式和工具，可以透過統一 **AI 代理程式和工具**產品頁面或 AWS Marketplace 管理主控台中的**伺服器**產品頁面進行管理。只有支援 Amazon Bedrock AgentCore 執行期版本的產品會顯示在 **AI 代理器和工具**產品頁面中。 ## 啟動清單精靈 1. 使用您的 AWS 賣方帳戶登入 [AWS Marketplace 管理入口網站](https://aws.amazon.com/marketplace/management/homepage/)。 1. 選取**產品**，然後在導覽列中選取 **AI 代理程式和工具**。 1. 選取**建立 AI 代理程式和工具產品**選單，然後選擇**容器型 AI 代理程式和工具**。 1. 選取**產生產品 ID 和產品代碼**。 1. （選用） 新增標籤以支援標籤型授權。 1. 選取**繼續**。 ## 步驟 1：提供產品資訊 1. 在**產品資訊**中，輸入： + **產品標題** + **產品標誌 S3 URL** + **簡短描述** + **長描述** + **反白 (1-3)** 1. 透過選擇新增資源，輸入支援詳細資訊並新增選用的學習資源。 1. 在**產品類別**功能表中，選擇 1-3 個類別。我們建議您從 **AI Agents & Tools** 商業類別中至少選擇一個類別。 1. 輸入關鍵字以改善搜尋可探索性。 1. （選用） 根據準則新增影片和影像資產。 1. 選擇**下一步**。 ## 步驟 2：設定 AI Agent Container 定價 1. 選擇定價模型。 **AgentCore 定價限制** 如果容器映像使用 AgentCore，則不支援具有長期合約定價模型**的每小時**和用量。 ****若要進一步了解合約定價，請參閱 [使用 的容器產品的合約定價 AWS License Manager](container-license-manager-integration.md)。若要進一步了解以用量為基礎的定價自訂計量，請參閱 [使用 AWS Marketplace Metering Service 設定容器產品的自訂計量](container-metering-meterusage.md)。 1. 選取**下一步**。 1. 在**設定價格**中。 1. 選取**下一步**。 ## 步驟 3：指定退款政策 1. 輸入退款政策。 1. 選取**下一步**。 **注意** 如果您選擇免費產品定價模式，則不需要輸入退款政策。 ## 步驟 4：設定 EULA 1. 選擇**適用於 的標準合約 AWS Marketplace**或**自訂 EULA**。 **注意** 如果您選擇自訂 EULA，請輸入最終使用者授權合約的 URL。 1. 選取**下一步**。 ## 步驟 5：新增儲存庫 1. 為您的容器產品新增初始儲存庫。 **注意** 儲存庫名稱在您賣方帳戶的所有產品中必須是唯一的。每個產品最多可以建立 50 個儲存庫。 1. 選取**下一步**。 ## 步驟 6：設定優惠可用性/允許清單 1. 在**設定優惠可用性**中，選擇您的地理可用性設定。 1. 選取**下一步**。 1. 在**設定允許清單中**，列出在有限狀態時應可存取清單的任何 AWS 帳戶。 1. 選取**提交**，為有限可見性測試建立新的變更請求。 等待 10-15 分鐘，直到您的請求狀態處於*成功*狀態。 ## 步驟 7：將容器映像和成品上傳至儲存庫 **注意** [的 Amazon Bedrock AgentCore 執行期 AWS Marketplace](bedrock-agentcore-runtime.md) 請參閱如何將 AgentCore 與您的容器映像整合。 1. 找到 ECR 儲存庫的 URL： + 在 AWS Marketplace Management Portal 中開啟伺服器產品頁面。 + 選取您的容器產品以檢視詳細資訊。 + 選取儲存庫索引標籤以複製儲存庫的 URL。 1. 選取**檢視推送命令**以開啟指示清單，包括可用來將 Docker 容器映像和 Helm Chart 推送至該儲存庫的命令。如需如何將容器映像和其他成品推送至儲存庫的一般資訊，請參閱《Amazon Elastic Container Registry 使用者指南》中的[推送映像](https://docs.aws.amazon.com/AmazonECR/latest/userguide/docker-push-ecr-image.html)。 **注意** 您可以在呼叫 docker pull 或 docker push 時使用下列 Amazon Elastic Container Registry (Amazon ECR) API 操作： DescribeImages - 用來檢閱儲存庫中影像的中繼資料。 GetAuthorizationToken - 用於在將成品上傳到儲存庫之前進行驗證，然後使用 docker pull 或 docker push 命令。 ListImages - 用來檢視您推送的映像清單。 1. 使用列出的命令，將任何必要的成品從本機儲存庫推送至您產品的 AWS Marketplace 儲存庫。 **注意** 您在推送命令中提供的標籤用於區分您上傳到儲存庫的成品版本。使用對成品所屬版本有意義的標籤。 1. 針對版本中所需的每個容器映像或成品重複此步驟。 **注意** 您的版本在每個交付選項中最多可包含 50 個容器映像或成品。如需交付選項的詳細資訊，請參閱下列程序。 1. 上傳成品之後，您就可以建立產品的版本。 **注意** 您的容器映像會自動掃描，以查看是否符合 [的容器型產品需求 AWS Marketplace](container-product-policies.md)。如需詳細資訊，請參閱[容器產品掃描安全問題](container-product-getting-started.md#container-security)。 ## 步驟 8：使用資產新增產品版本 1. 在 AWS Marketplace 管理入口網站中開啟 **AI 代理程式和工具**產品頁面。 **注意** 只有支援 Amazon Bedrock AgentCore 執行期版本的容器產品會顯示在 **AI Agents and Tools** 產品頁面中。在新增第一個版本之前，您只能在 AWS Marketplace 管理入口網站的**伺服器**產品頁面中找到您的產品。建立 Amazon Bedrock AgentCore 執行期的版本後，您可以在 **AI Agents and Tools** 產品頁面中找到您的容器產品。 1. 選取您的容器產品，然後按一下**請求變更**下拉式功能表，選取**更新版本**，然後選取**新增新版本**。 1. 在**交付選項**中，輸入： + **版本標題** + **版本備註** 1. 選取**新增交付選項**。 1. 針對**交付方法**，選取**容器映像**並填入： + **支援的服務**：選取買方可以在其中啟動軟體的環境。 + 對於 **Bedrock AgentCore** 服務，請在**類型**欄位中選取 **AI Agent、MCP Server 或 A2A Server**。 + **容器映像**：您先前指定的*儲存庫 URL *和*版本標籤*。 + **交付選項標題**和**部署選項描述**：輸入此交付選項的標題和描述。 + **使用說明**：輸入詳細資訊，協助您的買方在啟動軟體後使用您的軟體。 + **環境變數**：指定買方必須提供的環境變數，以設定代理程式的執行時間行為。這些變數可用於在啟動時將設定、登入資料或自訂旗標傳遞至容器。針對每個變數，提供容器預期的名稱、描述和選用的預設值。對於唯一的變數，例如登入資料或 API 金鑰，請勿提供預設值。您可以使用描述來指定變數的詳細資訊，以及可能的值。買方啟動您的產品時，所有提供的變數及其預設值都會預先填入。 1. 如果您選擇 **AI 代理器**或 **A2A Server** 工具類型，請確認您的代理器使用推理 LLMs並示範自動功能。這些要求有助於確保 AWS Marketplace 上提供的代理程式符合高品質標準。如果您的代理程式不符合這兩個要求，請選擇不同的工具類型。 1. 選取**新增版本**。 等待並重新整理頁面，直到請求狀態顯示*成功*為止。 新增新版本會自動掃描容器映像是否有漏洞。 ## 步驟 9：檢閱產品清單並發佈至公有 1. 在 AWS Marketplace 管理入口網站中開啟 **AI Agent and Tools** 產品頁面。 1. 在清單中選取您的容器產品。 1. 選取**檢視。 AWS Marketplace** 1. 檢閱您的產品詳細資訊頁面的準確性。確保使用說明充分引導買方完成啟動產品的必要步驟。 1. 將更新可見性請求提交至公有： + 在**伺服器產品**頁面的**目前伺服器產品**索引標籤上，選取您要修改的容器型產品。從**請求變更**下拉式清單中，選擇**更新可見性**。 ## 容器部署詳細資訊 容器部署將您的 AI 代理程式或工具封裝為容器化應用程式，客戶可以在自己的 AWS 環境中執行。此方法提供下列優勢： + 資料會保留在客戶的環境中 + 可自訂的部署組態 + 支援與 Bedrock AgentCore 執行期和客戶現有基礎設施的整合 列出容器化代理程式時，請提供明確的部署指示、資源需求和組態選項，以確保客戶成功實作。 ### Bedrock AgentCore 執行期容器的技術需求 **注意** 如需詳細資訊，請參閱[的 Amazon Bedrock AgentCore 執行期 AWS Marketplace](bedrock-agentcore-runtime.md)。 為 建立容器型 AI 代理程式產品時 AWS Marketplace，請遵循下列要求： MCP 伺服器需求 + **傳輸**：僅限無狀態可串流 http + **工作階段管理**：平台會自動新增工作階段隔離的`Mcp-Session-Id`標頭 + **主機**：容器必須接聽 `0.0.0.0` + **連接埠**：容器必須公開 MCP 伺服器通訊`8000`的連接埠 + **路徑**：`/mcp`- 用於接收 MCP RPC 訊息的 POST 端點。MCP 伺服器的 InvokeAgentRuntime 會將請求傳遞至此路徑。 + **通訊協定**：MCP 伺服器必須支援 MCP 通訊協定，包括通訊協定訊息 'tools/list' 和 'tools/call' （受 FastMCP 等常見架構支援）。 代理程式需求 + **/ping** 端點：運作狀態檢查的 GET 端點 + **/invocations** 端點：客服人員互動的 POST 端點 + **Docker 容器**：ARM64 容器化部署套件 + **連接埠**：容器必須公開連接埠`8080`以進行 HTTP 型代理程式通訊 + 沒有硬式編碼登入資料 + 沒有常見漏洞和暴露 (CVEs) A2A 伺服器需求 + **連接埠**：A2A 伺服器在連接埠 9000 上執行 （相較於 HTTP 的 8080、MCP 的 8000) + **主機**：容器必須接聽 `0.0.0.0` + **路徑**：A2A 伺服器掛載於 `/`(vs `/invocations` for HTTP， `/mcp` for MCP) + **客服人員卡**：A2A 透過位於 的客服人員卡提供內建客服人員探索 `/.well-known/agent-card.json` + **通訊協定**：使用 JSON-RPC agent-to-agent通訊 + **身分驗證**：同時支援 SigV4 和 OAuth 2.0 身分驗證機制 使用說明 確保指示徹底引導客戶啟動和設定產品。請參閱[建立 的 AMI 和容器產品使用說明 AWS Marketplace](ami-container-product-usage-instructions.md)。 ## 測試和驗證 在將 MCP 相容代理程式或工具發佈至公有之前，請徹底測試您的實作： + 驗證使用說明提供啟動和設定產品的必要資訊。 + 測試身分驗證流程和錯誤處理 + 在各種負載條件下驗證效能 + 確保與熱門 MCP 用戶端相容 + 記錄任何用戶端特定的組態需求 ## 最佳實務與建議 ### 文件需求 在 上列出與模型內容通訊協定相容的代理程式或工具時 AWS Marketplace，包含完整的文件： + 詳細的功能描述和範例 + 身分驗證和組態指示 + 常見整合案例的範例程式碼 + 故障診斷指南和錯誤參考 + 效能考量和最佳實務 ### 其他資源 如需在 AI 代理器或工具中實作模型內容通訊協定的詳細資訊，請參閱下列資源： + [Amazon Bedrock AgentCore 文件](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/what-is-bedrock-agentcore.html) + [的 Amazon Bedrock AgentCore 執行期 AWS Marketplace](bedrock-agentcore-runtime.md) + [容器技術需求](https://docs.aws.amazon.com/marketplace/latest/userguide/container-product-getting-started.html) # 的 Amazon Bedrock AgentCore 執行期 AWS Marketplace 本文件為想要列出可在 Amazon Bedrock AgentCore 執行期上部署之 AI 代理程式或工具的 AWS Marketplace 賣方提供資訊。它概述了用於準備 Bedrock AgentCore 執行期支援容器的技術要求、組態準則和最佳實務 AWS Marketplace。 **Topics** + [概觀](#agentcore-runtime-overview) + [Bedrock AgentCore 容器技術需求](#agentcore-container-requirements) + [測試 Bedrock AgentCore 執行期容器](#testing-agentcore-container) + [容器組態的最佳實務](#container-best-practices) + [AWS Marketplace 提交要求](#marketplace-submission-requirements) + [其他資源](#agentcore-additional-resources) + [在 上支援 AgentCore 執行期 AWS Marketplace](#agentcore-support) ## 概觀 Amazon Bedrock AgentCore 執行期提供安全、無伺服器和專門建置的託管環境，用於部署和執行 AI 代理器或工具。在 上列出 Bedrock AgentCore 執行期容器時 AWS Marketplace，您需要確保容器符合特定要求，才能在 Bedrock AgentCore 環境中正常運作。 **注意** 如需進一步了解，請參閱 [Amazon Bedrock AgentCore 執行期入門](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-getting-started.html)。 ## Bedrock AgentCore 容器技術需求 Amazon Bedrock AgentCore 執行期在列出 AI 代理器、MCP 伺服器和 A2A 伺服器方面有不同的技術需求。 + **客服人員需求** + **MCP 伺服器需求** + **A2A 伺服器需求** ### 客服人員需求 您的容器化代理程式必須符合下列核心需求： + **/ping** 端點：運作狀態檢查的 GET 端點 + **/invocations** 端點：客服人員互動的 POST 端點 + **Docker 容器**：ARM64 容器化部署套件 + **連接埠**：容器必須公開連接埠`8080`以進行 HTTP 型代理程式通訊 #### `/ping` - GET 此端點會驗證您的代理程式是否正常運作，並準備好處理請求。 **回應範例：** ``` { "status": "Healthy" } ``` #### `/invocations` - POST 當客戶使用 JSON 格式的承載呼叫具有 InvokeAgentRuntime 動作的客服人員時，這是主要客服人員互動端點。InvokeAgentRuntime 支援串流回應，可讓客戶在部分回應可用時收到回應。 **請求範例：** ``` Content-Type: application/json { "prompt": "What's the weather today?" } ``` **回應範例：** + JSON 回應 （非串流）： ``` Content-Type: application/json { "response": "Your agent's response here", "status": "success" } ``` + SSE 回應 （串流）： ``` Content-Type: text/event-stream data: {"event": "partial response 1"} data: {"event": "partial response 2"} data: {"event": "final response"} ``` ### MCP 伺服器需求 Amazon Bedrock AgentCore 執行期可讓您部署和執行模型內容通訊協定 (MCP) 伺服器。當您使用 MCP 通訊協定設定 Amazon Bedrock AgentCore 執行期時，服務預期 MCP 伺服器容器位於路徑 `0.0.0.0:8000/mcp`。這是大多數官方 MCP 伺服器 SDKs支援的預設路徑。 由於 Amazon Bedrock AgentCore 執行期預設提供工作階段隔離，因此需要無狀態可串流 HTTP 伺服器。執行時間會自動為不包含 的任何請求新增 `Mcp-Session-Id`標頭。這可讓 MCP 用戶端維持與相同 Amazon Bedrock AgentCore 執行期工作階段的連線持續性。 `InvokeAgentRuntime` API 會直接傳遞承載資料，以便輕鬆代理 MCP 等通訊協定的 RPC 訊息。 使用要求： + **Transport** - 必須使用無狀態可串流 - 僅限 http + **工作階段管理** - 平台會自動新增工作階段隔離的`Mcp-Session-Id`標頭 + **主機** - 容器必須接聽 `0.0.0.0` + **連接埠** - 容器必須公開 MCP 伺服器通訊`8000`的連接埠 + **路徑** - 必須公開`/mcp`為 POST 端點才能接收 MCP RPC 訊息。`InvokeAgentRuntime` API 會將請求傳遞至 MCP 伺服器的此路徑。 + **通訊協定** - MCP 伺服器必須支援 MCP 通訊協定，包括下列通訊協定訊息： + `tools/list` + `tools/call` （受 FastMCP 等常見架構支援） 若要進一步了解 MCP 伺服器需求，請參閱[在 AgentCore 執行期中部署 MCP 伺服器](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-mcp.html)。 #### `/mcp` - POST 這是客戶使用 InvokeAgentRuntime 呼叫 MCP 伺服器時的主要客服人員互動端點。 **範例清單請求：** ``` Content-Type: application/json { "jsonrpc": "2.0", "id": 1, "method": "tools/list", } ``` **範例清單回應：** JSON 回應 （非串流）： ``` Content-Type: application/json { "jsonrpc": "2.0", "id": 1, "result": { "tools": [ { "name": "get_weather", "title": "Weather Information Provider", "description": "Get current weather information for a location", "inputSchema": { "type": "object", "properties": { "location": { "type": "string", "description": "City name or zip code" } }, "required": ["location"] } } ], "nextCursor": "next-page-cursor" } } ``` **工具呼叫請求範例：** ``` Content-Type: application/json { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "get_weather", "arguments": { "location": "New York" } } } ``` **工具呼叫回應範例：** JSON 回應 （非串流）： ``` Content-Type: application/json { "jsonrpc": "2.0", "id": 2, "result": { "content": [ { "type": "text", "text": "Current weather in New York:\nTemperature: 72°F\nConditions: Partly cloudy" } ], "isError": false } } ``` ### A2A 伺服器需求 Amazon Bedrock AgentCore 執行期可讓您在 AgentCore 執行期中部署和執行 Agent-to-Agent (A2A) 伺服器。Amazon Bedrock AgentCore 的 A2A 通訊協定支援可做為透明代理層，與 A2A 伺服器無縫整合。為 A2A 設定時，Amazon Bedrock AgentCore 預期容器在根路徑 (`0.0.0.0:9000/`) `9000`的連接埠上執行無狀態、可串流的 HTTP 伺服器，這符合預設的 A2A 伺服器組態。 此服務提供企業級工作階段隔離，同時維持通訊協定透明度 - 來自 InvokeAgentRuntime API 的 JSON-RPC 承載會直接傳遞至 A2A 容器，無需修改。此架構會保留標準 A2A 通訊協定功能，例如透過 的代理程式卡`/.well-known/agent-card.json`和 JSON-RPC 通訊的內建代理程式探索，同時新增企業身分驗證 (SigV4/OAuth 2.0) 和可擴展性。 與其他通訊協定的主要區別在於連接埠 (9000 vs 8080 for HTTP)、掛載路徑 (`/` vs `/invocations`) 和標準化代理程式探索機制，使得 Amazon Bedrock AgentCore 成為生產環境中 A2A 代理程式的理想部署平台。 使用要求： + **連接埠** - A2A 伺服器在連接埠 9000 上執行 （相較於 HTTP 的 8080、MCP 的 8000) + **主機** - 容器必須接聽 `0.0.0.0` + **路徑** + A2A 伺服器掛載於 `/`(vs `/invocations` for HTTP， `/mcp` for MCP) + `/ping` 使用 GET 進行 的運作狀態檢查 + **客服人員卡** - A2A 透過位於 的客服人員卡提供內建客服人員探索 `/.well-known/agent-card.json` + **Protocol** - 使用 JSON-RPC agent-to-agent通訊 + **身分驗證** - 同時支援 SigV4 和 OAuth 2.0 身分驗證機制 若要進一步了解 A2A 伺服器需求，請參閱在 [ AgentCore 執行期中部署 A2A 伺服器](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-a2a.html)。 #### `/` - POST 這是客戶使用 InvokeAgentRuntime 呼叫 A2A 伺服器時的主要客服人員互動端點。 **客服人員調用請求範例：** ``` Content-Type: application/json { "jsonrpc": "2.0", "id": "req-001", "method": "message/send", "params": { "message": { "role": "user", "parts": [ { "kind": "text", "text": "what is 101 * 11?" } ], "messageId": "12345678-1234-1234-1234-123456789012" } } } ``` **客服人員叫用回應範例：** JSON 回應 （非串流）： ``` Content-Type: application/json { "jsonrpc": "2.0", "id": "req-001", "result": { "artifacts": [ { "parts": [ { "kind": "text", "text": "101 * 11 is 1111" } ] } ] } } ``` **客服人員卡擷取範例：** ``` curl https://bedrock-agentcore..amazonaws.com/runtimes/{escaped_agent_arn}/invocations/.well-known/agent-card.json ``` #### `/ping` - GET 這是執行運作狀態檢查的端點。 ## 測試 Bedrock AgentCore 執行期容器 將容器提交至 之前 AWS Marketplace，請徹底進行測試： ### 本機代理程式測試 使用 Docker 在本機測試您的代理程式 ``` docker run -p 8080:8080 # Test ping endpoint curl http://localhost:8080/ping # Test agent invocation endpoint curl -X POST http://localhost:8080/invocations \ -H "Content-Type: application/json" \ -d '{"prompt": "Hello world!"}' ``` ### 本機 MCP 伺服器測試 使用 Docker 在本機測試 MCP 伺服器 ``` docker run -p 8000:8000 # Test ping endpoint curl http://localhost:8000/ping # Test MCP endpoint with tools/list curl -X POST http://localhost:8000/mcp \ -H "Content-Type: application/json" \ -d '{"jsonrpc": "2.0","id": 1,"method": "tools/list"}' # Test MCP endpoint with tools/call curl -X POST http://localhost:8000/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "get_weather", "arguments": {"location": "New York"}}}' ``` ### 本機 A2A 伺服器測試 使用 Docker 在本機測試您的 A2A 伺服器 ``` docker run -p 9000:9000 # Test ping endpoint curl http://localhost:9000/ping # Retrieve agent card curl http://localhost:9000/.well-known/agent-card.json # Test A2A endpoint with message/send curl -X POST http://localhost:9000/ \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": "req-001", "method": "message/send", "params": { "message": { "role": "user", "parts": [ { "kind": "text", "text": "what is 101 * 11?"}],"messageId": "12345678-1234-1234-1234-123456789012" }}}' ``` ### 在 Bedrock AgentCore 執行期上測試 在本機測試容器之後，請將其上傳至 Amazon Elastic Container Registry (Amazon ECR)，並將其部署至 Amazon Bedrock AgentCore 執行期。您可以使用 Amazon Bedrock AgentCore 執行期主控台或 AWS Command Line Interface (AWS CLI) 部署。 ## 容器組態的最佳實務 ### 安全考量 + **隔離** - 請勿在調用之間存放敏感資料 + **身分驗證** - 驗證所有傳入的請求 + **記錄** - 記錄適當的資訊，但避免包含敏感資料 + **相依性** - 保持所有相依性為最新狀態，以防止安全漏洞 ### 效能最佳化 + **冷啟動** - 針對快速冷啟動最佳化您的容器 + **記憶體使用**量 - 將記憶體使用量降至最低，以改善效能 + **並行** - 設計您的代理程式以有效率地處理並行請求 + **逾時** - 實作適當的逾時處理 ### 錯誤處理 + **緩和降級** - 在服務無法使用時實作備用機制 + **結構化錯誤** - 傳回具有適當 HTTP 狀態碼的良好結構化錯誤回應 + **重試邏輯** - 針對暫時性失敗實作適當的重試邏輯 ## AWS Marketplace 提交要求 當您將 AgentCore 執行期容器提交至 時 AWS Marketplace，請包含： + **容器映像** – 您的容器映像推送至 Amazon ECR + **文件** – 有關如何使用您的代理程式或 MCP 伺服器的完整文件 + **使用範例** – 如何叫用代理程式或 MCP 伺服器的明確範例 + **支援資訊** – 支援聯絡資訊 + **定價資訊** – 清除代理程式或 MCP 伺服器的定價結構 ## 其他資源 如需詳細資訊，請參閱下列內容： + [什麼是 Amazon Bedrock AgentCore？](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/what-is-bedrock-agentcore.html) + [什麼是 AWS Marketplace？](https://docs.aws.amazon.com/marketplace/latest/userguide/what-is-marketplace.html) + [容器產品入門](container-product-getting-started.md) ## 在 上支援 AgentCore 執行期 AWS Marketplace 如需有關在 上列出 AgentCore 執行期容器的問題 AWS Marketplace，請參閱[取得 的支援 AWS Marketplace](https://docs.aws.amazon.com/marketplace/latest/buyerguide/buyer-support.html)。 如需 AgentCore 執行期的技術問題，請參閱 [AWS 支援 和客戶服務](https://console.aws.amazon.com/support/home#/case/create?issueType=technical)。 # 整合 MCP AWS MCP 伺服器 (MCP) 是一種開放標準，可實現 AI 代理器和外部工具之間的無縫通訊。當您在 AI 代理程式或工具中實作 MCP 時，客戶可以直接將您的解決方案整合到現有的代理程式工作流程中，而無需複雜的 API 整合工作。 MCP 會轉換 AI 代理器存取外部功能的方式。客服人員不使用為每個工具建置自訂整合，而是使用標準化通訊協定來探索、連線並與 MCP 相容服務互動。此方法可降低整合複雜性並啟用plug-and-play功能。 如需在 代理程式或工具 AWS MCP 伺服器 中實作 的詳細資訊，請參閱 [整合 MCP](#integrating-mcp)。 **Topics** + [AWS MCP 伺服器 整合的主要優點](#mcp-benefits) + [AWS MCP 伺服器 架構和元件](#mcp-architecture) + [AWS MCP 伺服器 實作的技術需求](#mcp-implementation) + [測試和驗證](#mcp-testing) + [文件需求](#mcp-documentation) + [其他資源](#mcp-resources) ## AWS MCP 伺服器 整合的主要優點 MCP 整合可為 AI 代理程式提供者和最終使用者提供優勢。 ### AI 代理程式供應商的優勢 + 使用支援 MCP 的熱門 AI 開發解決方案聯絡客戶。 + 使用標準化整合減少客戶加入摩擦。 + 透過 MCP 相容用戶端應用程式啟用探索。 + 透過單一實作支援多個用戶端平台。 ### 最終使用者的優勢 + 將您的功能新增至現有的 AI 工作流程，無需自訂開發。 + 使用他們已經知道的熟悉 AWS MCP 伺服器 用戶端界面。 + 受益於自動通訊協定處理和錯誤管理。 + 透過多個 AI 平台和應用程式存取您的工具。 + 維持跨已啟用 AWS MCP 伺服器服務的一致身分驗證。 ## AWS MCP 伺服器 架構和元件 AWS MCP 伺服器 使用用戶端-伺服器架構，其中您的 AI 代理器或工具充當 AWS MCP 伺服器 伺服器。客戶應用程式 (AWS MCP 伺服器 用戶端） 會連線至您的伺服器以存取您的 功能。 通訊協定定義下列三種主要功能類型： + **工具** – 客服人員可以呼叫以執行動作的函數。 + **資源** – 客服人員可以讀取或查詢的資料來源。 + **提示** – 客服人員可以使用的預先定義提示範本。 ## AWS MCP 伺服器 實作的技術需求 您的 AWS MCP 伺服器 伺服器必須實作下列核心通訊協定規格： + JSON-RPC 2.0 通訊協定 + 標準 AWS MCP 伺服器 訊息類型和格式 + 功能公告和探索 + 身分驗證和工作階段管理 + 錯誤處理和狀態報告 ### 實作步驟 1. 定義您的功能 （工具、資源或提示）。 1. 實作 AWS MCP 伺服器 伺服器界面。 1. 使用 JSON 結構描述建立功能結構描述。 1. 實作身分驗證和授權。 1. 新增錯誤處理和記錄。 1. 使用 AWS MCP 伺服器相容的用戶端進行測試。 1. 為客戶記錄您的功能。 ### 功能定義範例 ``` { "name": "search_knowledge_base", "description": "Search the knowledge base for relevant information", "parameters": { "type": "object", "properties": { "query": { "type": "string", "description": "The search query" }, "max_results": { "type": "integer", "description": "Maximum number of results to return", "default": 5 } }, "required": ["query"] } } ``` ## 測試和驗證 在列出相容的 AWS MCP 伺服器代理程式或工具之前 AWS Marketplace，請徹底測試您的實作： + 驗證功能探索和結構描述驗證 + 測試身分驗證流程和錯誤處理 + 在各種負載條件下驗證效能 + 確保與熱門 AWS MCP 伺服器 用戶端的相容性 + 記錄任何用戶端特定的組態需求 ## 文件需求 在 上列出 AWS MCP 伺服器相容的代理程式或工具時 AWS Marketplace，請包含完整的文件： + 詳細的功能描述和範例 + 身分驗證和組態指示 + 常見整合案例的範例程式碼 + 故障診斷指南和錯誤參考 + 效能考量和最佳實務 ## 其他資源 如需在 AI 代理器或工具 AWS MCP 伺服器 中實作 的詳細資訊，請參閱下列資源： + [模型內容通訊協定規格](https://modelcontextprotocol.github.io/) + [MCP GitHub 儲存庫](https://github.com/modelcontextprotocol/mcp) + AWS MCP 伺服器 整合支援的[AWS Marketplace 賣方營運團隊](https://aws.amazon.com/marketplace/management/contact-us/)