在线AI教程 / AI上云

[Amazon Bedrock] 使用 AWS Agent Registry 中的通用元数据管理和发现记录

· 转自:aws.amazon.com

Artificial Intelligence 使用 AWS Agent Registry 中的通用元数据管理和发现记录 随着组织构建越来越多的 agent、Model Conte

转载本文转自「aws.amazon.com」,版权归原作者所有,内容已摘录正文、去除外部链接。

Artificial Intelligence

使用 AWS Agent Registry 中的通用元数据管理和发现记录

随着组织构建越来越多的 agent、Model Context Protocol(MCP)server 和 skill,它们需要一种一致的方式来描述、治理和查找这些资源。AWS Agent Registry 提供了一个目录,用于注册、审批和发现这些资源以及自定义记录。每条记录都带有名称、描述、协议描述符和审批状态。然而,每个组织都有自己想跟踪的属性和事实,其中一些是该组织独有的,例如业务单元、资源负责人、风险分级和开发环境。组织希望这些属性各有一个通用定义,并希望注册表中的每个 agent、MCP server 和 skill 都携带这些事实。在此之前,组织无法在 AWS Agent Registry 中定义这些事实,也无法把它们存到每条记录上。

AWS Agent Registry 现在提供自定义元数据 schema。自定义元数据 schema 是一组由组织定义的键值对,AWS Agent Registry 中的记录会携带它们。管理员定义 schema 并将其应用到注册表,此后注册表中的所有记录都必须遵循该 schema。发布者创建或提交记录时,要为适用的 schema 中指定的字段提供值,AWS Agent Registry 会按管理员设定的 schema 校验这些值。审批者在审核记录时可以依赖这些已校验的值,消费者和 agent 则可以用它们来发现和过滤记录。管理员、发布者、安全与治理团队、审批者、消费者和 agent,都基于同一套共享事实来治理、发现和理解其 agent 舰队中的资源。

在本文中,我们跟随 AnyCompany 组织,看它如何发布一个带自定义 schema 定义的 MCP server、为这条记录补充元数据,并让它可被人类或 agent 发现。我们以 MCP server 为例,但同样的步骤也适用于其他记录类型。

自定义元数据如何工作

借助自定义元数据,组织可以使用标准化的词汇来描述自己的资源。注册表管理员定义自定义元数据 schema:字段名、类型、允许值,以及每个字段是必填还是可选。注册表会在每条记录上强制执行该 schema,因此像 environment 这样的字段,无论哪个团队发布记录,名字和允许值都相同。

schema 包含适用于所有记录类型的通用属性,你也可以添加只适用于特定记录类型的专属字段。每个字段的类型为 Text、Enum、URL 或 Boolean。

记录创建或更新时,注册表会按管理员设定的 schema 校验自定义元数据。如果一条记录是在不带任何自定义元数据的情况下创建的,AWS Agent Registry 会把它保存为 NON_COMPLIANT。团队可以用这种方式保存进行中的工作,但在补齐必填字段和值之前,无法提交该记录等待审批。如果记录包含自定义元数据,但其中有未知字段、缺少必填字段或值无效,AWS Agent Registry 会以 ValidationException 拒绝它。 GetRegistryRecord 返回记录的自定义元数据值及其合规状态。(COMPLIANT 表示这些值符合管理员的 schema,它并不等于审批通过;审批由审批者决定。) 发现类 API 还允许按自定义属性过滤记录。

自定义元数据带来了什么

由于各团队可以用相同的字段和值描述 AWS Agent Registry 记录,注册表能够支撑治理与合规,并随规模扩展。

归属与运维

environment(prod、staging 或 dev)、businessUnit、ownerTeam、supportContact 和 costCenter 等字段记录了资源在哪里运行、由谁负责、由谁付费。配置管理数据库(CMDB)ID 把记录关联到你现有的资产清单,support-tier 字段则为所有依赖该资源的人设定了预期。

安全与合规

数据分级、合规范围(例如 Payment Card Industry(PCI)或 Health Insurance Portability and Accountability Act(HIPAA))、风险层级、扫描状态和扫描报告 URL,把一次审批变成了对结构化证据的核查。你现有的扫描器、CMDB 同步任务和分类工具会在记录提交之前通过 API 写入这些值。正如本文所示,你可以用这些值来构建记录审批流程或自动化。

更好的发现

自定义元数据值会被索引以供搜索。消费者或 agent 可以把自然语言查询与具体的元数据过滤条件组合起来,例如 environment=prod AND businessUnit=payments AND securityScanStatus=PASSED。搜索只返回已审批的记录,因此匹配过滤条件但尚未审批的记录不会出现在结果中。图 1 展示了从管理员到消费者的每个角色,如何让一条记录走完 schema 定义、注册、补充元数据、审批和发现的全过程。

图 1:按角色划分的泳道图,展示一条记录如何在 AWS Agent Registry 中流转

从注册到发现的 MCP 记录演练

AnyCompany 运营着一个不启用自动审批的 AWS Agent Registry,名为 anycompany-governed-registry。其支付团队发布了一条 MCP 记录 payments-ledger-mcp,这是一个用于账目查询的只读 server。现有的安全与资产清单系统会为这条 MCP 记录补充元数据,之后由审批函数决定消费者能否发现它。

图 2 中五个带编号的步骤与本次演练对应:定义、注册、补充元数据并提交、审核,然后发现。

图 2:自定义元数据从你现有的工具中汇集发布者上下文与取值,让审批和搜索使用同一套事实

前置条件

要跟随本次演练,你需要:

一个位于受支持的 AWS Region的 AWS 账户。 Boto3 可用的 AWS 凭证,以及 AWS Agent Registry 所需的 AWS Identity and Access Management(IAM)权限。 Python 3.11 或更高版本,以及 boto3 1.43.113 或更高版本。 示例实现位于 GitHub 仓库中。

代码片段经过精简:cp 和 dp 分别是 agent-registry-control 和 agent-registry 的 boto3 客户端。完整代码在示例仓库中。

步骤 1:AWS Agent Registry 管理员为注册表定义自定义元数据 schema

AnyCompany 的管理员创建一个注册表,并为其定义所有记录都必须遵循的自定义元数据 schema。

每条记录都必须有 environment、businessUnit 和 securityScanStatus 字段。 记录还可以携带一些可选字段,由发布者或自动化稍后填写:ownerTeam、cmdbId、dataClassification 和 securityScanReportUrl。 MCP server 还会记录其 networkEgress,该字段可选。

default_schema = {"type": "object", "properties": { "environment": {"type": "string", "enum": ["prod", "staging", "dev"]}, "businessUnit": {"type": "string"}, "ownerTeam": {"type": "string"}, "cmdbId": {"type": "string"}, "dataClassification": {"type": "string", "enum": ["public", "internal", "confidential", "restricted"]}, "securityScanStatus": {"type": "string", "enum": ["PENDING", "PASSED", "FAILED"]}, "securityScanReportUrl": {"type": "string", "format": "uri"}, }, "required": ["environment", "businessUnit", "securityScanStatus"]}

mcp_schema = {"type": "object", "properties": {"networkEgress": { "type": "string", "enum": ["none", "vpc-only", "allowlisted-internet"]}}}

cp.create_registry( name="anycompany-governed-registry", approvalConfiguration={"autoApprovalRules": []}, customMetadataSchemaConfiguration={ "defaultSchema": json.dumps(default_schema), "recordTypeSchemaOverrides": [ {"recordType": "MCP", "schema": json.dumps(mcp_schema)}]})

图 3 展示了这个 schema,以及 payments-ledger-mcp 在步骤 3 完成元数据补充后将携带的值。空的 autoApprovalRules 列表意味着注册表不会自行批准任何记录。每条提交的记录都会停留在 Pending approval,直到某个主体批准它。由你决定这是通过你构建的自动检查(步骤 4 使用 AWS Lambda 函数)、人工审批者,还是两者兼用。

图 3:展示注册表的通用属性、为 MCP 记录新增的字段,以及 payments-ledger-mcp 经过校验的 customMetadata 映射

管理员也可以在 AWS Agent Registry 控制台中查看 schema。图 4 展示了注册表详情页上显示的通用属性与 MCP 专属字段。

图 4:AWS Agent Registry 控制台中的自定义元数据 schema

步骤 2:发布者注册 server

支付团队的流水线会连同自定义元数据一起注册 payments-ledger-mcp。第一次尝试使用了 production,而管理员允许的值里没有这个。

customMetadata sent by the pipeline:

{ "environment": "production", "businessUnit": "payments", "securityScanStatus": "PENDING" }

ValidationException: Custom metadata validation failed for record type MCP: /environment: does not have a value in the enumeration ["prod", "staging", "dev"]

注册表拒绝了这条记录。在流水线改发 prod 之后,记录被创建为一份合规的草稿。schema 就是这样让每个团队都使用相同的值。

步骤 3:自动化补充更多元数据并提交

接下来,AnyCompany 的自动化会补充自己系统掌握的信息:安全扫描器的结果、CMDB 中的资产 ID,以及已批准的数据分级。然后它提交该记录等待审批。

record = cp.get_registry_record(registryId=registry_id, recordId=record_id) scan = run_security_scan(record) # Replace this stub with your scanner call. metadata = {**record["customMetadata"], "cmdbId": get_cmdb_id(record), "dataClassification": get_classification(record), "securityScanStatus": scan["status"], "securityScanReportUrl": scan["report_url"]} cp.update_registry_record(registryId=registry_id, recordId=record_id, customMetadata={"optionalValue": metadata}) wait_for_record(cp, registry_id, record_id, "DRAFT") cp.submit_registry_record_for_approval( registryId=registry_id, recordId=record_id)

更新操作会替换整个元数据映射,所以自动化会先读出当前值,加上自己的值,再一起写回。在示例中,扫描器和 CMDB 调用都是桩(stub),你需要替换成自己的工具。注册表会向 Amazon EventBridge 发送一个待审批事件。在步骤 4 中,你创建的规则会把该事件传给审批函数。

步骤 4:审批自动化根据证据做决定

当记录进入 Pending approval 状态时,AWS Agent Registry 会向 Amazon EventBridge 发送事件,而你设置的一条 Amazon EventBridge 规则会调用自定义的 AWS Lambda 函数。图 5 展示了 payments-ledger-mcp 的控制台视图,其中包含审批函数用来做检查的自定义元数据值。

图 5:记录上的自定义元数据就是审批函数要核查的证据

该函数读取记录的自定义元数据和合规状态,检查记录是否为 COMPLIANT、扫描是否为 PASSED、是否提供了 cmdbId,以及数据是 public 还是 internal。payments-ledger-mcp 四项全部通过,因此函数批准了它。未通过检查的记录会被拒绝,拒绝原因会指出是哪一项检查失败。在生产系统中,你可以选择把需要人工审核的记录(例如包含 confidential 或 restricted 数据的记录)转人工审核,而不是直接拒绝。

步骤 5:消费者用自定义元数据字段作为过滤条件,从 AWS Agent Registry 中找到记录

一位在找账目工具的开发者会搜索注册表,并用管理员定义的同一批字段做过滤。

dp = boto3.client("agent-registry") matches = dp.search_discoverable_registry_records( registryIds=[registry_id], searchQuery="ledger lookup", filters={"$and": [ {"customMetadata.environment": {"$eq": "prod"}}, {"customMetadata.businessUnit": {"$eq": "payments"}}, {"customMetadata.securityScanStatus": {"$eq": "PASSED"}}, ]}, )

搜索会返回 payments-ledger-mcp,因为它已审批通过,并且匹配全部三个过滤条件。agent 可以通过注册表的 MCP endpoint >.api.aws/registry//mcp 执行同样的搜索,该 endpoint 把 search、list 和 get 作为 MCP tool 提供。在 GitHub 示例中,一个 Strands agent 连接到 AWS Registry MCP endpoint,并使用 Amazon Bedrock 上的模型。它的 system prompt 列出了用于过滤记录的自定义元数据字段。该 agent 会把一句自然语言请求(例如 “a production MCP server for payments ledger lookups that passed its security scan”)转成带过滤条件的搜索,并回答 payments-ledger-mcp。

开发者和 agent 查询的是管理员定义、审批函数也核查过的同一批字段,因此两者找到的都只是满足你治理规则的 server。

为长期使用设计 schema

把 schema 当作组织的共享词汇表:

先就词汇表达成一致。在创建 schema 之前,与发布和审批记录的团队确定字段名与允许值。schema 的变更是增量式的:你可以新增字段、新增允许值,或把可选字段改为必填,但不能重命名、删除或改变字段类型。 要预料到,在记录加入注册表之后所做的 schema 变更,会落后于现有记录。现有记录不会被改写。不再匹配 schema 的记录会被报告为 NON_COMPLIANT,并保留其审批状态。该记录仍处于已审批状态,但它的下一次更新必须满足新 schema。编辑一条已审批的记录会创建一个草稿,该草稿必须重新提交审批;在所有必填字段都有值之前,提交会失败。在新修订版获批之前,消费者看到的仍是已审批的那个版本。 把每个字段放在合适的层级。适用于所有记录类型的问题用通用属性,记录类型专属的事实(例如 agent 的自主级别)用记录类型字段。 选择适合该字段的类型。需要拼写一致的决策字段用 Enum,外部标识符用 Text,存放在源系统访问控制之后的证据用 URL。 只有当发布者在注册时就能赋值时,才把字段设为必填。对于由持续集成(CI)或自动化在记录发布之后提供的值,允许使用中间值,例如 PENDING。在本文中,扫描在注册之后运行,因此 securityScanStatus 有三个值:PENDING、PASSED 和 FAILED。发布者写入 PENDING,由补充元数据的自动化替换它。 不要把敏感细节放进去。密钥、内部 endpoint 和详细的发现结果,都不要放进可被广泛读取的元数据。

结论

在本文中,我们展示了如何在 AWS Agent Registry 中添加自定义元数据,让每条记录都拥有一套通用的事实,例如运行环境、所属业务单元、数据分级和安全扫描状态。以一个 MCP server 为例,我们展示了管理员定义 schema、发布者与现有自动化填写取值、你在 AWS Lambda 中构建的审批函数做出审批决定,以及消费者用元数据过滤条件找到已审批的 server。由于 schema 归管理员所有,每个团队都使用相同的字段和值,而正是这种一致性,让 AWS Agent Registry 中的审批与搜索变得可靠。

动手试试: 使用 GitHub 仓库中的示例。 深入了解: 阅读 AWS Agent Registry 开发者指南和自定义元数据 API 参考。 可用性: 参见受支持的 AWS Regions。

关于作者