本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 搜索注册表记录 **迁移现已开放** Amazon 代理注册表已在新`agent-registry`命名空间下启动。2026 年 10 月 30 日将停止对公共预览版`bedrock-agentcore`命名空间的支持。有关迁移说明，请参阅[注册表迁移综合指南](registry-faq.md)。 作为消费者，您可以使用`SearchDiscoverableRegistryRecords`数据平面 API 搜索注册机构批准的记录。API 接受自然语言查询，应用将语义理解与关键字匹配相结合的混合搜索，并返回的排名结果仅限于最新修订版本处于 “已**批准**” 状态的记录。不返回处于 “**草稿**”、“**待批准**”、“已**拒绝**” 或 “**已弃用**” 状态的记录。要在不进行查询的情况下浏览目录，请`BatchGetDiscoverableRegistryRecord`改用`ListDiscoverableRegistryRecords`和，请参阅[浏览已批准的记录](registry-browse-records.md)。 您也可以使用任何 MCP-compatible 客户端通过注册表的 MCP 端点 (`InvokeRegistryMcp`) 调用发现数据平面 API。端点将`SearchDiscoverableRegistryRecords``ListDiscoverableRegistryRecords`、和显示`BatchGetDiscoverableRegistryRecord`为 MCP 工具，您可以直接调用。 ## 请求参数 + **SearchQuery**（必填）：可以是 1 到 256 个字符之间的任何自然语言查询 + Re@@ **gistryIds**（必填）：在哪个注册机构中进行搜索。只支持一个注册表 ARN 或 ID + **MaxRes** ults（可选）：搜索响应中返回了多少条记录。可以取介于 1—20 之间的任何值，默认为 10 + **过滤器**（可选）-元数据筛选表达式 ## 元数据过滤器 运算符：`$eq`、`$ne`、`$in`。合乎逻辑：`$and`，`$or`。字段：`name``recordType`、`recordVersion`、和`customMetadata.{fieldName}`用于注册表的自定义元数据架构中定义的任何字段。有关更多信息，请参阅[定义自定义元数据架构](registry-custom-metadata-schema.md)。 示例：`{"recordType": {"$eq": "MCP"}}` 合并：`{"$and": [{"recordType": {"$eq": "MCP"}}, {"recordVersion": {"$eq": "1.0"}}]}` 自定义元数据示例：`{"customMetadata.owner": {"$eq": "search-team"}}` ## 控制台 **Example** 1. 打开[Amazon 代理注册表控制台](https://console.amazonaws.cn/agent-registry/home?region=us-east-1#)。 1. 在导航窗格中，选择 “**录制目录**”。 1. 选择要搜索的注册表。该页面会自动调用`ListDiscoverableRegistryRecords`并显示注册表中已批准的记录。 1. 在搜索栏中，输入您的搜索查询。这会触发`SearchDiscoverableRegistryRecords`并显示排名结果。 1. （可选）要按特定属性筛选结果，请选择搜索字段以展开 “**属性**” 菜单，然后选择筛选器：**名称**、**记录类型**或**版本**。如果注册表具有自定义元数据架构，则其字段将分组显示在**自定义元数据**下。 1. 从结果中选择一条记录以查看其完整描述符内容。 1. 在[Bedrock-AgentCore 控制台](https://console.amazonaws.cn/bedrock-agentcore/home?region=us-east-1#)中打开 “ Amazon 代理注册表” 页面。 1. 在导航窗格中，选择**注册表**，然后选择注册表名称。 1. 选择 “**搜索记录**” 选项卡。 1. 输入您的搜索查询并查看结果。 **注意** 控制台搜索仅适用于使用 IAM-based 入站授权的注册机构。对于 JWT-authorized 注册管理机构，请直接使用 HTTP 客户端（例如`curl`）和有效的 JWT 不记名令牌使用搜索 API，或者通过 MCP 客户端使用注册表的 MCP 端点。 ## Amazon CLI（使用基于 IAM 的入站授权的注册表） **Example** ``` aws agent-registry search-discoverable-registry-records \ --search-query "weather" \ --registry-ids "" \ --region us-east-1 ``` ``` aws bedrock-agentcore search-registry-records \ --search-query "weather" \ --registry-ids "" \ --region us-east-1 ``` ## Amazon SDK（具有基于 IAM 的入站授权的注册表） **Example** ``` import boto3 client = boto3.client('agent-registry') response = client.search_discoverable_registry_records( registryIds=[''], searchQuery='weather', maxResults=10 ) for record in response['registryRecords']: print(f"{record.get('displayName', record['name'])} ({record['name']}) - {record['recordType']} - {record['status']}") ``` ``` import boto3 client = boto3.client('bedrock-agentcore') response = client.search_registry_records( registryIds=[''], searchQuery='weather', maxResults=10 ) for record in response['registryRecords']: print(f"{record['name']} - {record['descriptorType']} - {record['status']}") ``` ## HTTP 客户端（使用基于 OAuth 的入站授权的注册表） 首先获取不记名代币： ``` SECRET_HASH=$(echo -n "" | openssl dgst -sha256 -hmac "" -binary | base64) aws cognito-idp initiate-auth \ --client-id "" \ --auth-flow USER_PASSWORD_AUTH \ --auth-parameters USERNAME="",PASSWORD='',SECRET_HASH="$SECRET_HASH" \ --region us-east-1 | jq -r '.AuthenticationResult.AccessToken' ``` 然后使用不记名令牌进行搜索： **Example** ``` curl -X POST "https://agent-registry..api.aws/discoverable-records-search" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -d '{"registryIds": [""], "searchQuery": "weather", "maxResults": 10}' ``` ``` curl -X POST "https://bedrock-agentcore..amazonaws.com/registry-records/search" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -d '{"registryIds": [""], "searchQuery": "weather", "maxResults": 10}' ``` ## 最终一致性 Amazon 代理注册表搜索 Amazon Agent Registry 使用最终一致的模型进行搜索索引。当您通过调用`UpdateRegistryRecordStatus`或通过控制台批准注册表记录时，该记录不会出现在`SearchDiscoverableRegistryRecords`或立即生`InvokeRegistryMcp`效。通常需要几秒钟才能将已批准的记录编入索引并可供发现，但在某些情况下，可能需要几分钟。 在此期间，您可能会观察到以下行为： + `SearchDiscoverableRegistryRecords`查询不会返回刚刚批准的记录。 + `ListDiscoverableRegistryRecords`或`BatchGetDiscoverableRegistryRecord`呼叫不包括记录。 + 注册表 MCP 端点 (`InvokeRegistryMcp`) 在工具结果中不包含最近批准的记录。 + 相比之下，控制平面 API（`GetRegistryRecord`和`ListRegistryRecords`）在完成后`UpdateRegistryRecordStatus`立即返回新批准的记录。最终一致性仅适用于发现数据平面 API 和注册表 MCP 端点。 只有处于 “**已批准**” 状态的记录才会包含在可发现的结果中。处于草稿、待批准、已拒绝或已弃用状态的记录永远不会由可发现的数据平面 API 或由返回。`InvokeRegistryMcp`您可以通过调用来验证记录的当前状态`GetRegistryRecord`，无论索引状态如何，调用都会返回最新的修订版。 为了处理应用程序的最终一致性，我们建议采取以下措施： + 批准记录后，通过调`SearchDiscoverableRegistryRecords`用包含指数退避的重试策略，确认该记录可以被发现。 + 如果记录在批准后没有立即出现在结果中，请不要假设注册表中缺少该记录。致电`GetRegistryRecord`以验证记录的状态。 + 如果您要通过 Amazon EventBridge 和集成审批工作流程`UpdateRegistryRecordStatus`，请在下游系统查询可发现 API 以获取新批准的记录之前稍作延迟。 **注意** `SearchDiscoverableRegistryRecords`是在命名`bedrock-agentcore`空间`SearchRegistryRecords`中命名的。 有关在 Amazon SDK 中配置重试行为的一般指南，请参阅 S * Amazon DK 和*工具参考指南中的[重试行为](https://docs.amazonaws.cn/sdkref/latest/guide/feature-retry-behavior.html)。 ## 记录属性如何影响搜索相关性 Amazon Agent Registry 使用混合搜索来返回相关结果，该搜索将语义理解与关键字匹配相结合。如果您希望找到的记录未出现在搜索结果中，那么了解哪些记录属性会影响搜索会有所帮助。 ### 哪些记录属性用于搜索 注册表记录中的以下属性用于确定搜索的相关性： + **名称**-用于关键字匹配。反映资源内容的清晰描述性名称可以提高精确和部分名称查询的可发现性。 + **描述**-用于关键字和语义匹配。用自然语言编写的说明资源用途和常见用例的描述比简洁的技术标签更容易被发现。 + **描述符** — 协议定义的全部内容（MCP 服务器定义、代理卡、技能文档或自定义 JSON）用于语义匹配。这包括工具名称、工具描述、输入参数名称和功能摘要。 + **记录类型和版本**-可用作可筛选字段。您可以在`name`、`recordType`和上使用元数据筛选器缩小结果范围`recordVersion`。 + **自定义元数据**-如果注册表具有自定义元数据架构，则其字段可用作下方的可筛选字段。`customMetadata.{fieldName}`自定义元数据值包含在搜索索引中。`customMetadata.{fieldName}`过滤器语法提供精确匹配的筛选，而这些值也有助于通过参数对关键字和语义搜索进行排名。`searchQuery` ### 如何处理搜索查询 当您调用时`SearchDiscoverableRegistryRecords`， Amazon Agent Registry 会对同一组索引记录并行运行两个搜索并合并结果： + **语义搜索**-将您的查询转换为向量表示形式，并与索引记录的矢量表示进行比较。即使查询中的确切单词未出现在记录中，这也会找到概念上相关的记录。例如，“预订航班” 的查询可以匹配名为 “旅行预订服务” 的记录。 + **关键字搜索**-使用传统的关键字相关性将您的查询与记录字段的文本内容进行匹配。这对于确切的名称查询和特定的技术术语有效。例如，查询 “weather-api-v2” 会匹配包含该精确文本的记录。 如果您在请求中包含元数据过滤器，则在对结果进行评分和排名之前，过滤器将应用于两个搜索。这意味着过滤器会减少语义搜索和关键字搜索同时使用的候选集，而不是在排名之后筛选结果。 ### 如何对结果进行排名 语义搜索和关键字搜索的结果合并到一个排名列表中，并按相关性顺序返回，最相关的记录在前。每个结果的最终位置由其在两次搜索中的相关性决定——在语义和关键字结果中排名较高的记录将高于仅在一个搜索中排名靠前的记录。在关键字搜索中，记录名称对排名的影响最大，其次是描述和描述符内容，它们的贡献相同。由于两种搜索模式始终运行并影响最终排名，因此您编写查询的方式会影响显示哪些记录。以下指导可以帮助您根据自己的意图获得更好的结果。 ### 撰写有效的搜索查询 **当您知道确切的名称或标识符**时，请使用简短的特定查询。关键字搜索将精确的文本与记录名称、描述和描述符内容进行匹配。诸如 “weather-api-v2” 或 “pdf 处理” 之类的简短查询对于按名称查找记录非常有效。 **当您按功能或用例进行探索**时，请使用自然语言描述您的需求。语义搜索可以理解概念意图，因此 “查找可以预订航班的工具” 或 “从 PDF 文档中提取结构化数据” 之类的查询可以匹配相关记录，即使这些确切的单词没有出现在记录元数据中。 **避免在同一个查询中将类似过滤器的约束与描述性意图混为一谈。**诸如 “查找所有用于天气预报的MCP服务器” 之类的查询通过语义和关键字搜索发送整句话。语义组件将整句解释为概念意图，它可以显示在概念上相关但与你打算限制的特定属性不匹配的记录。相反，对基于属性的约束使用元数据过滤器，并将查询重点放在主题上。请参阅[何时使用元数据筛选器而不是查询文本](#registry-search-filters-vs-query)。 ### 撰写可发现的记录 + 撰写描述来解释资源的作用及其解决的问题。语义搜索可以理解意图，因此 “帮助客户跟踪包裹配送” 比 “配送状态端点” 更容易被发现。 + 为 MCP 服务器提供完整的工具定义。工具描述和输入参数描述都有助于提高搜索的相关性。 + 在您的姓名和描述中加入相关的关键词。关键字搜索与文本完全匹配，因此，如果消费者可能搜索特定字词，请确保这些词出现在您的记录中。 ### 何时使用元数据筛选器而不是查询文本 如果您的意图是通过记录类型、名称或版本等已知属性限制结果，请使用元数据过滤器。不要在查询文本本身中嵌入类似过滤器的约束。例如，如果要查找与天气相关的所有 MCP 服务器，请对记录类型使用元数据筛选器，对主题使用查询： ``` { "searchQuery": "weather forecast", "filters": { "recordType": { "$eq": "MCP" } } } ``` 避免在查询文本中加入限制，例如 “查找所有用于天气预报的 MCP 服务器”。由于较长的查询倾向于语义匹配，因此 “MCP 服务器” 一词被解释为概念意图的一部分，而不是精确的过滤器。这可能会导致语义组件返回在概念上与完整句子相关但与您要筛选的特定属性不匹配的记录，例如，将有关天气的代理记录与 MCP 服务器记录一起返回。这同样适用于任何基于属性的约束。如果您想要具有特定名称、版本或类型的记录，请使用相应的元数据筛选器，而不是在查询中包含这些术语。 您可以筛选以下字段： + `name`— 按确切名称匹配记录。 + `recordType`— 按语义类型 (`AGENT`、、、`MCP``SKILL``GATEWAY`、`CUSTOM`) 匹配记录。 + `recordVersion`— 按版本字符串匹配记录。 + `customMetadata.{fieldName}`— 按注册表的自定义元数据架构中的值匹配记录，其中`{fieldName}`是您定义的字段名（例如`customMetadata.owner`）。请参见[定义自定义元数据架构](registry-custom-metadata-schema.md)。 过滤器支持`$eq`（等于）、`$ne`（不等于）和`$in`（匹配列表中的任何值）运算符，并且可以使用和逻辑进行`$and`组合。`$or` 例如，要仅搜索与天气相关的 MCP 服务器，请执行以下操作： ``` { "searchQuery": "weather forecast", "filters": { "recordType": { "$eq": "MCP" } } } ``` 要排除特定资源类型，请执行以下操作： ``` { "searchQuery": "", "filters": { "recordType": { "$ne": "CUSTOM" } } } ``` 要匹配多个版本中的任何一个，请执行以下操作： ``` { "filters": { "recordVersion": { "$in": ["1.0", "1.1", "2.0"] } } } ``` 要按自定义元数据字段匹配记录，请执行以下操作： ``` { "filters": { "customMetadata.humanInLoop": { "$eq": true } } } ``` 要将自定义元数据筛选器与基本字段筛选器结合使用，请执行以下操作： ``` { "filters": { "$and": [ { "recordType": { "$eq": "MCP" } }, { "customMetadata.tier": { "$eq": "internal" } } ] } } ``` **注意** 的筛选值`customMetadata.{fieldName}`是字符串或本机布尔值。对于**布尔型**字段，请使用字符串`"true"`或或`"false"`原生 JSON 布尔值 (`true`/`false`)。对于 E **num** 字段，请使用架构允许的值之一。字段上的筛选器会匹配包含该字段的每种记录类型的记录。 ### 搜索仅返回已批准的记录 只有处于 “**已批准**” 状态的记录才会显示在搜索结果中并通过 MCP 端点。不返回处于 “草稿”、“待批准”、“已拒绝” 或 “已弃用” 状态的记录。如果最近批准的记录未出现在结果中，请参阅[Amazon 代理注册表搜索的最终一致性](#registry-search-eventual-consistency)。