人工智能
在 AWS Agent Registry 中使用通用元数据治理和发现记录随着组织构建越来越多的 agent、Model Context Protocol(MCP)服务器和技能,它们需要一种一致的方式来描述、治理和查找这些资源。 AWS Agent Registry 提供了一个目录,用于注册、审批和发现这些资源及自定义记录。每条记录都包含名称、描述、协议描述符和审批状态。然而,每个组织都有希望跟踪的属性和事实,其中一些是该组织独有的,例如其业务单元、资源所有者、风险分类和开发环境。组织希望为这些属性中的每一个都建立统一的定义,并希望注册表中的每个 agent、MCP 服务器和技能都携带这些事实。在此之前,组织无法在 AWS Agent Registry 中定义这些事实并将其存储到每条记录上。
自定义元数据 schema 现已在 AWS Agent Registry 中提供。自定义元数据 schema 是一组由组织定义的键值对,AWS Agent Registry 中的记录会携带这些键值对。管理员定义 schema 并将其应用到注册表,注册表中的所有记录随后都必须遵循该 schema。当发布者创建或提交记录时,他们为适用 schema 中指定的字段提供值,AWS Agent Registry 会根据管理员设置的 schema 验证这些值。审批者在审核记录时可以依赖这些经过验证的值,使用者和 agent 则可以利用它们来发现和筛选记录。管理员、发布者、安全与治理团队、审批者、使用者和 agent 都基于同一套共享事实来治理、发现和理解其 agent 资产中的资源。
在本文中,我们以 AnyCompany 组织为例,介绍其发布带有自定义 schema 定义的 MCP 服务器、丰富该记录,并使其可供人类或 agent 发现的过程。我们以 MCP 服务器为例,但相同的步骤也适用于其他记录类型。
自定义元数据的工作原理
借助自定义元数据,组织可以使用标准化词汇来描述其资源。注册表管理员定义 自定义元数据 schema:字段名称、类型、允许值,以及每个字段是必填还是可选。注册表对每条记录强制执行该 schema,因此诸如 environment 这样的字段,无论由哪个团队发布记录,都具有相同的名称和相同的允许值。
该 schema 包含适用于所有记录类型的通用属性,你还可以添加仅适用于特定记录类型的专用字段。每个字段的类型为 Text、Enum、URL 或 Boolean。
-
创建或更新记录时,注册表会根据管理员设置的 schema 验证自定义元数据。
-
如果创建记录时 未提供任何自定义元数据, AWS Agent Registry 会将其保存为
NON_COMPLIANT。团队可以通过这种方式保存进行中的工作,但在具备必填字段和值之前,无法将记录提交审批。 -
如果记录 包含自定义元数据 ,且其中存在未知字段、缺失必填字段或无效值,AWS Agent Registry 会以
ValidationException.
-
-
GetRegistryRecord返回记录的自定义元数据值及其合规状态。(COMPLIANT表示这些值与管理员的 schema 匹配。这并不代表审批通过。审批决定由审批者做出。) -
Discovery API 还允许根据自定义属性筛选记录。
自定义元数据带来的可能性
由于团队可以用相同的字段和值来描述 AWS Agent Registry 记录,注册表能够支持并扩展治理与合规能力。
归属与运营
诸如 environment (prod, staging、 dev), businessUnit, ownerTeam, supportContact以及 costCenter 等字段记录资源的运行位置、由谁负责以及由谁承担费用。配置管理数据库(CMDB)ID 将记录关联到现有清单,支持层级字段则为依赖该资源的任何人设定预期。
安全与合规
数据分类、合规范围(如支付卡行业(PCI)或《健康保险流通与责任法案》(HIPAA))、风险层级、扫描状态以及扫描报告 URL,可将审批转变为对结构化证据的核查。你现有的扫描器、CMDB 同步作业和分类工具会在记录提交之前通过 API 写入这些值。如本文所示,你可以使用这些值构建记录审批流程或自动化。
更好的发现
自定义元数据值会被索引以供搜索。消费者或 agent 可以将自然语言查询与特定的元数据筛选条件结合使用,例如 environment=prod AND businessUnit=payments AND securityScanStatus=PASSED。系统只返回已批准的记录,因此即使某条记录符合筛选条件但尚未获批,也不会出现在结果中。 图 1 展示了从管理员到消费者的每个角色如何让记录依次经过 schema 定义、注册、丰富、审批和发现。
图 1:泳道图,展示记录如何按角色在 AWS Agent Registry 中流转
MCP 记录从注册到发现的完整流程
AnyCompany 运营着 anycompany-governed-registry,这是一个没有自动审批的 AWS Agent Registry。其支付团队发布了一条 MCP 记录, payments-ledger-mcp,这是一个用于账本查询的只读服务器。现有的安全和清单系统会在审批函数决定消费者能否发现该记录之前,先丰富这条 MCP 记录。
图 2 中五个带编号的步骤 图 2 与演练流程一致:定义、注册、丰富并提交、审核,然后发现。
图 2:自定义元数据从你现有的工具中收集发布者上下文和值,因此审批和搜索可以使用相同的事实
先决条件
要跟随本演练操作,你需要:
-
一个位于 受支持的 AWS 区域.
-
的 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,每条记录都必须遵循该 schema。
-
每条记录都必须包含 其
environment,businessUnit, 和securityScanStatus字段。 -
记录还可以携带发布者或自动化流程稍后填充的可选字段:
ownerTeam,cmdbId,dataClassification, 和securityScanReportUrl. -
MCP 服务器还会记录其
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 步:发布者注册服务器
支付团队的流水线注册 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 调用是占位实现,你需要将其替换为自己的工具。注册表会发送一个 待审批事件 发送到 Amazon EventBridge。在第 4 步中,你创建的规则会将事件传递给你的审批函数。
第 4 步:审批自动化流程根据证据做出决定
当记录进入“待审批”状态时,AWS Agent Registry 会向 Amazon EventBridge 发送一个事件,并设置一条 Amazon EventBridge 规则来调用自定义的 AWS Lambda 函数。 图 5 展示了控制台视图,其中包含 payments-ledger-mcp以及审批函数为执行检查而读取的自定义元数据值。
图 5:记录上的自定义元数据是审批函数执行检查时所依据的证据
该函数会读取记录的自定义元数据和合规状态,以检查该记录是否 COMPLIANT,该扫描 PASSED,一个 cmdbId 存在,并且数据是公开或内部的。 payments-ledger-mcp 四项检查全部通过,因此该函数予以批准。未通过某项检查的记录会被拒绝,拒绝原因会指明未通过的检查项。在生产系统中,你可以选择将需要人工审核的记录(例如包含机密或受限数据的记录)转交人工审核,而不是直接拒绝。
第 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 端点运行相同的搜索, https://agentregistry.<region>.api.aws/registry/<registryId>/mcp该端点提供 search、list 和 get 作为 MCP 工具。在 GitHub 示例中,一个 Strands agent 连接到 AWS Registry MCP 端点,并使用 Amazon Bedrock 上的模型。其系统提示列出了用于筛选记录的自定义元数据字段。该 agent 将一句自然语言请求(例如“一个用于支付账本查询、已通过安全扫描的生产 MCP 服务器”)转换为带筛选条件的搜索。它回答时给出 payments-ledger-mcp.
开发者和 agent 查询管理员定义的相同字段,审批函数也检查这些字段,因此双方都只会找到符合你治理规则的服务器。
将 schema 设计为可长期使用
将 schema 视为你所在组织的共享词汇:
-
先就词汇表达成一致。在创建 schema 之前,先与负责发布和审批记录的团队确定字段名称和允许值。 Schema 变更采用增量方式:你可以添加字段、添加允许值,或将可选字段设为必填,但不能重命名、删除或更改字段类型。
-
请注意,已有记录会滞后于在记录添加到注册表之后所做的 schema 变更。已有记录不会被重写。不再符合 schema 的记录会被报告为“
NON_COMPLIANT并保留其批准状态。该记录仍保持已批准状态,但其下一次更新必须符合新的 schema。编辑已批准的记录会创建一个草稿,该草稿必须再次提交审批;在每一个必填字段都有值之前,提交会失败。在管理员批准新修订之前,消费者仍会看到已批准的版本。 -
将每个字段放在正确的层级。对于适用于所有记录类型的问题,使用通用属性;对于特定于记录类型的事实(例如 自主性级别 ,供 agent 使用。
-
选择适合该字段的类型。对于需要拼写一致的决策字段使用 Enum,对于外部标识符使用 Text,对于存储在源系统访问控制之后的证据使用 URL。
-
仅当发布者能在注册时分配值时,才将字段设为必填。对于由持续集成(CI)或自动化在记录发布后提供的值,允许使用临时值,例如
PENDING在本文中,扫描在注册之后运行,因此securityScanStatus有三个值:PENDING,PASSED,以及FAILED发布者写道:PENDING,而富化自动化会将其替换。 -
不要包含敏感细节。请将机密信息、内部端点和详细发现排除在可广泛读取的元数据之外。
结论
在本文中,我们展示了如何在 AWS Agent Registry 中添加自定义元数据,为每条记录提供一组通用事实,例如其环境、所属业务部门、数据分类和安全扫描状态。我们使用一个 MCP 服务器,展示了管理员定义 schema、发布者和现有自动化填充值、你在 AWS Lambda 中构建的审批函数决定是否批准,以及消费者通过元数据筛选条件找到已批准的服务器。由于管理员拥有该 schema,每个团队都使用相同的字段和值,而这种一致性正是 AWS Agent Registry 中审批和搜索可靠的原因。
-
自己动手试试: 使用 GitHub 仓库中的示例.
-
深入了解: 阅读 AWS Agent Registry 开发者指南 以及 自定义元数据 API 参考.
-
可用性: 请参阅 支持的 AWS 区域.
AI 热点