本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 集成基于 API 的人工智能代理产品 ## 基于 API 的人工智能代理产品指南 AWS Marketplace 为所有基于软件即服务 (SaaS) API 的人工智能代理产品提供指南。这些指南旨在为客户提供安全可靠的使用体验。 **Topics** + [产品审核流程](#product-review-process) + [维护合规性](#maintaining-compliance) ### 产品审核流程 提交产品时，请查看 AWS Marketplace 该产品及其元数据以验证其是否符合当前指南。我们会定期更新这些指南，以适应不断变化的安全需求。 ### 维护合规性 AWS Marketplace 持续监控产品以验证合规性。如果您的产品不符合现行指南要求： + 在问题得到解决前，您的产品可能无法对新订阅用户开放 + 您必须更新产品以满足新的合规要求 | 类别 | 指南要求 | | --- | --- | | 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) | | 密钥管理 | 供应商应为客户提供 invalidate/rotate 密钥能力。客户取消订阅产品后，供应商还应具备密钥失效机制。 | | MCP 服务器要求（如果适用） | 对于 MCP 服务器，供应商应提供远程 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) | | 使用说明 | 使用说明应明确说明先决条件、身份验证设置、支持的端点、 request/response 架构、工具描述、错误代码和其他资源。 | ## 集成基于 API 的人工智能代理产品 ### 基于产品定价进行集成 将您的产品与集成 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 在客户的 Secrets Manager 中存储 API AWS 密钥或 OAuth 证书。 + 如果存储的是 API 密钥且仅包含一个参数，请调用 `PutDeploymentParameter` API，并将 `secretString` 参数设置为字符串。如果您存储了多个 OAuth 凭据参数，请在参数中提供一个带有键值对的 JSON 字符串，`secretString`如下所示： ``` { "Client Id": "{{12345}}", "Client Secret": "{{12345}}", "Discovery URL" : "{{https://auth.example.com/.well-known/openid-configuration}}" } ``` 在以下资源中了解有关 QuickLaunch 配送的更多信息： + 在[AWS Marketplace 部署 **PutDeploymentParameter**API 中了解 API](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 计量服务或 AWS Marketplace 授权服务集成的过程，该服务用于确保您对产品的客户使用情况的账单和报告准确无误。 + 要了解有关访问的更多信息 AWS Marketplace APIs，请参阅[访问 AWS Marketplace 计量和授权服务 APIs](saas-integration-metering-and-entitlement-apis.md)。 ### SNS 通知 订阅亚马逊简单通知服务 (Amazon SNS) Service 主题，接收有关买家订阅变更和商品合同权利的通知。 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 ``` ### 人工智能代理与代理和工具使用说明模板 以下示例演示了代理或代理工具的使用说明，包括先决条件、身份验证设置、支持的端点、 request/response 架构、错误代码和其他资源： ``` 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 ```