Making Amazon Quick enterprise-ready: Automated, auditable cross-account resource promotion

使 Amazon Quick 企业就绪：自动化、可审计的跨账户资源推广 | 人工智能

使 Amazon Quick 企业就绪：自动化、可审计的跨账户资源推广

Amazon Quick 是 Amazon 为工作场景打造的智能代理 AI 助手。您可以通过构建代理来分析数据、调用操作连接器并完成多步骤任务。将这些资源（聊天代理、操作连接器、知识库、流程和空间）从开发环境推广到生产环境的 AWS 账户，与推广其他应用程序的方式相同，这一过程此前一直是手动且容易出错的繁琐工作。本文将展示如何通过 Amazon Bedrock AgentCore 上的幂等、可审计的模型上下文协议（MCP）服务器实现自动化。

智能代理解决方案的核心组件包括代理、操作连接器、知识库和空间：配置了自定义指令的聊天代理、连接到 Slack、Jira 等集成系统的连接器、基于您自身文档的知识库，以及将这些组件整合在一起的空间。团队可以在开发账户中快速构建并迭代这些组件。

大多数企业会为开发和生产环境分别设置独立的 AWS 账户，有时还会在中间设置质量保证（QA）账户。当代理、操作连接器和知识库在开发账户中验证通过后，目前没有原生的一键式方法将其推广到下一账户。团队需要手动重新构建每个资源：重新创建每个代理并设置相同的指令和初始提示，重新附加代理的操作连接器，重新授予资源权限，并重新配置每个知识库背后的 Amazon 简单存储服务（Amazon S3）存储桶、存储桶策略和数据源。这项工作耗时且难以审计，容易因细微错误而影响企业所需的治理流程。

通过 API 管理 Amazon Quick 资源

Amazon Quick 资源可通过编程方式管理。空间、代理、操作连接器、知识库和流程均通过 Amazon Quick API（属于 Amazon Quick Sight API 的一部分）进行管理，该接口提供完整的资源生命周期操作，包括创建、读取、更新、删除和列表。任何业务用户在 Amazon Quick 中配置的内容——无论是带有指令和初始提示的代理、连接器、知识库还是流程——我们都可以通过编程方式检查、重新创建、更新和管理，包括权限设置。

这种可编程的接口使受控推广成为可能。我们不再需要手动重新创建每个资源，而是通过 API 读取资源及其权限，并在另一个账户中精确地重新应用这些设置。本文中的迁移工具将创建、读取、更新和列表操作组合成一个可重复的工作流，且永远不会对目标账户执行删除操作，因此每次运行仅执行添加或更新操作。

在本文中，我们将介绍 Quick Resource Migrator（快速资源迁移器），这是一个托管在 Amazon Bedrock AgentCore 运行时上的示例 MCP 服务器，属于 Amazon Bedrock AgentCore 的一项功能，它可以通过单次工具调用自动化 Amazon Quick 资源的跨账户推广。该工具以资源为中心：您可以选择资源类型（代理、连接器、知识库、流程或空间），并按 ID、名称或全部进行选择。该工具具有幂等性（可安全重复运行），并且通过描述源并重放相同操作，能够忠实地复制权限。完整的源代码可在 aws-samples 代码库中获取。

解决方案概述

迁移器通过单次调用可批量提升选定资源集。该操作为插入或更新（upsert）：目标环境中不存在的资源将被创建，已存在的资源则会就地更新。每次更新操作前都会通过版本化备份写入Amazon S3进行保护，因此每个资源都会保留完整的操作历史记录，可随时查看并回滚。只读预览功能可在提交前准确报告运行将创建或更新的内容，迁移过程本身运行于Amazon Bedrock AgentCore，因此可通过Amazon Quick或任何MCP兼容客户端进行驱动。

迁移内容范围

• 选择模型：选择资源类型（代理、连接器、知识库、流程或空间），通过ID、名称或全部方式选择资源。选择过程以资源为中心。可直接迁移特定资源类型，或迁移空间以同步其关联资源。

• 聊天代理：将根据自定义指令、身份、语气、初始提示和欢迎信息重新创建，其操作连接器会重新附加（映射到目标账户）。当空间被迁移时，其代理会自动重新链接到该空间。

• 操作连接器：根据配置重新创建。不会从源端读取密钥值。连接器会使用占位符凭证创建，并在目标端重新认证。

• 知识库：在目标账户中注册知识库，重新创建其数据源并复制权限。对于基于S3的知识库，迁移器还会在目标端创建存储桶及其存储桶策略（这是迁移的独立输出）。文档（S3对象）本身不会被复制。

• 流程：根据定义在目标账户中重新创建。由于流程ID在不同账户中可能不同，流程通过名称匹配：同名的目标流程会被更新，否则会创建新流程。流程权限会被复制。

• 空间：在目标账户中重新创建，并重新链接到其代理、连接器和知识库（资源Amazon资源名称（ARN）映射到目标账户）。请先迁移关联资源以确保目标ARN能正确解析。空间权限会被复制。

核心设计原则

• 资源驱动选择：每次迁移一种资源类型（代理、连接器、知识库、流程或空间），可通过ID、名称或全部方式选择。代理会根据其操作连接器重新附加。空间会在目标账户中重新创建，并重新链接到其代理、连接器和知识库，ARN映射到目标账户。

• 权限保真度：权限不会硬编码。服务器会对每个源资源调用相应的Describe*Permissions API，并在目标端重放完全相同的权限列表，将主体映射到目标账户中已注册的用户。

• 幂等性：每个资源都会被创建或更新。服务器会先描述目标状态，再决定是创建还是更新，因此重新运行迁移会收敛到相同状态，而不会产生重复或失败。

• 最小权限与隔离：源端角色仅具有只读权限。目标角色仅包含迁移所需的操作权限。运行时通过Cognito JSON Web Token（JWT）对调用者进行身份验证，并可运行在虚拟私有云（VPC）网络模式下。

• 安全且可逆的更新。在迁移器更新任何现有目标资源之前，会先将该资源及其依赖项的版本化快照写入专用的备份存储桶。如果无法写入备份，更新操作将被中止。每个创建或更新的资源也会被快照记录，且恢复工具可将任何资源回滚到早期版本。

架构

该解决方案采用三账户模型。中央运行账户在 Amazon Bedrock AgentCore 运行时上托管 MCP 服务器。服务器通过 AWS Security Token Service (AWS STS) 在源账户中担任只读角色，在目标账户中担任读写角色，因此任何地方都不会存储长期凭证。

图 1：Amazon Quick Resource Migrator MCP 服务器架构

组件职责

| 组件 | 职责 | |------|------| | AgentCore 运行时（运行账户） | 托管 MCP 服务器（server.py）。在源账户和目标账户中担任角色并协调迁移。以 VPC 网络模式运行，使用 Cognito JWT 授权器。 | | Amazon Cognito（运行账户） | 用户池、资源服务器和一个机器到机器的应用客户端。颁发 JWT（客户端凭证授权，范围 invoke），调用者将其呈现给 AgentCore。 | | 运行程序执行角色 | AgentCore 执行角色：Amazon CloudWatch Logs、遥测数据以及 sts:AssumeRole 进入源和目标角色。 | | 迁移器角色（源账户） | 只读 Quick Sight 描述/列表权限，以及知识库读取权限。 | | 迁移器角色（目标账户） | 读写 Quick Sight 创建/更新权限，知识库和 S3 写入权限，以及用于主体解析的 ListUsers。 | | 备份存储桶（运行账户） | 加密的 S3 存储桶，用于存储目标资源的版本化预更新和迁移后快照。运行时直接写入该存储桶。恢复操作从该存储桶读取。可选（未设置时禁用）。 |

表 1：架构组件

迁移流程

• 解析资源：根据资源类型和选择器（ID、名称或全部），在源账户中解析具体的资源 ID。
• 描述源资源：描述每个选定资源以捕获其配置和权限。
• 连接器：重新创建每个连接器。认证配置被清理为创建（写入）模型，使用占位符密钥，然后在目标环境中重新认证。复制权限。
• 知识库：创建目标存储桶（knowledge-base-<env>-<account>）、存储桶策略、数据源和知识库，然后复制知识库权限。不复制 S3 对象。
• 代理：在目标账户中重新创建每个代理（其操作连接器已重新映射），然后复制代理权限。当空间本身被迁移时，代理与空间的关联关系将被恢复（参见空间步骤）。
• 流程：根据定义重新创建每个流程，通过名称匹配（不同账户中的流程 ID 不同）：更新同名的目标流程或创建新流程，然后复制流程权限。
• 空间：重新创建每个空间，并重新链接其代理、连接器和知识库（ARN 已重新映射到目标账户，需先迁移这些资源），然后复制空间权限。
• 报告：返回创建或更新的资源、存储桶、备份、跳过权限以及任何错误的 JSON 报告。

MCP 服务器暴露的工具

服务器暴露了五个工具，所有工具均在 server.py 中定义。

preview_migration（只读）

preview_migration 接收源账号 ID、资源类型（agent、connector、knowledge base、flow、space 或 all）、选择器（id、name 或 all）和 AWS 区域。它会返回待迁移的代理、操作连接器、知识库和流程的清单，包含名称和类型，但不会进行任何实际更改。可将其作为预演步骤，用于确认范围并支持在推广前的变更管理审批流程。当同时传递目标账号 ID 时，响应结果会增加源到目标的映射关系，标记每个资源的 CREATE 或 UPDATE 操作，让您在执行迁移前清楚了解具体变更内容。

migrate_resources（完整迁移）

migrate_resources 接收源和目标账号 ID、资源类型（agent、connector、knowledge base、flow 或 space）、选择器（id、name 或 all）、区域、源和目标环境名称（用于知识库存储桶名称）、以及 Quick Sight 服务角色名称。它执行上述完整的创建或更新迁移操作，并返回所有创建、更新和授权内容的结构化报告，同时包含任何错误信息。由于其具备幂等性，您可以重复运行该操作（例如每次发布时运行），最终都会收敛到相同的目标状态。

list_backups（只读）

list_backups 搜索备份目录并列出每个资产的可用版本。备份是迁移器在更新前写入备份存储桶的快照，每个更新对应一个版本化对象，因此您可以查看任何迁移资源的完整历史记录。

get_backup（只读）

get_backup 返回指定资产和版本（默认为最新版本）的完整备份数据，包括捕获的资源配置及其依赖项。

restore_backup

restore_backup 将存储的备份版本重新应用到目标资源上，直接在原位置更新资源，或在资源不存在时重新创建。操作前会先创建一个新鲜的预恢复备份，因此该回滚操作本身也可以被再次回滚。

部署解决方案

完整的源代码和逐步部署说明位于 aws-samples 仓库的 README 文件中。总体而言，您需要部署三个 AWS CloudFormation 堆栈：跨账号的 AWS Identity and Access Management（IAM）角色、VPC 网络，以及托管 MCP 服务器的 Cognito 认证 AgentCore 运行时环境，然后将该运行时注册为 Amazon Quick 的操作连接器。

通过 Quick App 使用迁移工具

通过将运行时注册为操作连接器，您可以使用自然语言在 Amazon Quick 中驱动迁移工具，也可以构建 Quick App：一种基于相同 MCP 工具的点选式网页体验。您无需手动构建该界面。仓库中包含一个即用型的 app-builder 提示，您将其粘贴到 Amazon Quick 应用构建器中，替换占位符连接器和操作 ID 为自己的 ID 即可生成应用。该应用将工作流程转化为引导式流程：选择源账号和目标账号、要推广的资源、预览将要创建或更新的内容、执行迁移，并查看所有历史迁移记录，每次迁移都由服务器写入的版本化 S3 快照作为支持。以下屏幕截图展示了该体验。

Quick App 示例

（此处应插入图片链接）

• 由于应用是根据提示生成的，每次构建都会有所不同。以下屏幕显示了一个示例。在此示例中，登录页面会提示输入源账户 ID、目标账户 ID、资源类型（代理、连接器、知识库、流程或空间）、选择器（ID、名称或全部），并根据需要提供其他选项。

图3：登录页面上可用的其他迁移选项

• 选择“Confirm & migrate”后，您将看到类似以下的响应：

图4：选择“Confirm and migrate”后的确认响应

• 确认并迁移后，您应该看到来自MCP服务器的响应，显示已创建/更新的资源。

图5：MCP服务器响应，列出已创建或更新的资源

• 打开“History”标签页，可以查看所有过去的迁移记录。每条记录都基于迁移到Amazon S3的版本快照，因此您可以获得完整且可审计的记录，了解哪些内容已被推广以及时间，还可以检查任何早期版本。

图6：“History”标签页显示过去迁移的可审计记录

• 要回滚，请选择资源的备份版本并选择“Restore”。应用会将保存的版本重新应用到目标。由于在恢复之前会先捕获一个新鲜备份，因此回滚本身也可以撤销。

图7：将资源回滚到早期备份版本

结论

跨账户推广是企业软件的基本预期，直到现在，它一直是Amazon Quick缺少的关键部分。Quick Resource Migrator将原本缓慢、手动且难以审计的任务转变为快速、可重复且受控的任务：单次工具调用即可在目标账户中重新创建代理、连接器和知识库，并忠实地复制权限，所有操作均以幂等性方式执行，因此您可以在每次发布时运行。

克隆示例仓库，将其部署到运行账户中，尝试将代理或知识库从开发环境推广到生产环境。然后根据自己的治理和加固需求调整此模式。

作者简介

'"` /think