View a markdown version of this page

搜索注册记录 - 亚马逊基岩 AgentCore
请求参数元数据过滤器控制台AWS CLI（使用基于 IAM 的入站授权的注册表）AWS SDK（具有基于 IAM 的入站授权的注册表）HTTP 客户端（使用基于 OAuth 的入站授权的注册表）最终一致性为 AWS 代理注册表搜索记录属性如何影响搜索相关性

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

搜索注册记录

迁移现已开放

AWS 代理注册表已在新agent-registry命名空间下启动。对公共预览bedrock-agentcore命名空间的支持将于 2026 年 9 月 17 日停止。有关迁移说明，请参阅综合注册表迁移指南。

作为消费者，您可以使用SearchDiscoverableRegistryRecords数据平面 API 搜索注册机构的批准记录。该 API 接受自然语言查询，应用混合搜索，将语义理解与关键字匹配相结合，并返回仅限于最新修订状态为 “已批准” 的记录的排名结果。处于 “草稿” 、“待批准” 、“已拒绝” 或 “已弃用” 状态的记录不会返回。要在不进行查询的情况下浏览目录，请BatchGetDiscoverableRegistryRecord改用ListDiscoverableRegistryRecords和，请参阅浏览批准的记录。

您还可以使用任何 MCP-compatible 客户端通过注册表的 MCP 端点 (InvokeRegistryMcp) 调用发现数据平面 API。该端点以 M SearchDiscoverableRegistryRecords CP 工具的BatchGetDiscoverableRegistryRecord形式公开，您可以直接调用。ListDiscoverableRegistryRecords

请求参数

  • searchQuery（必填）：可以是 1—256 个字符的任何自然语言查询

  • registryIds（必填）：在哪个注册管理机构中进行搜索。仅支持一个注册表 ARN 或 ID

  • maxR esults（可选）：搜索响应中返回了多少条记录。可以取介于 1—20 之间的任何值，默认为 10

  • 过滤器（可选）-元数据筛选器表达式

元数据过滤器

运算符：$eq、$ne、$in。合乎逻辑：$and，$or。字段:name,recordType, recordVersion。

示例：{"recordType": {"$eq": "MCP"}}

组合：{"$and": [{"recordType": {"$eq": "MCP"}}, {"recordVersion": {"$eq": "1.0"}}]}

控制台

例
AWS Agent Registry namespace

  1. 打开AWS 代理注册表控制台。

  2. 在导航窗格中，选择 “录制目录” 。

  3. 选择要搜索的注册表。该页面会自动调用ListDiscoverableRegistryRecords并显示注册表中的批准记录。

  4. 在搜索栏中，输入您的搜索查询。这将触发SearchDiscoverableRegistryRecords并显示排名结果。

  5. （可选）要按特定属性筛选结果，请选择搜索字段展开 “属性” 菜单，然后选择筛选器：名称、记录类型或版本。

  6. 从结果中选择一条记录以查看其完整描述符内容。

Amazon Bedrock AgentCore namespace (to be deprecated)

  1. 在Bedrock-AgentCore 控制台中打开 AWS 代理注册表页面。

  2. 在导航窗格中，选择注册表，然后选择注册表名称。

  3. 选择 “搜索记录” 选项卡。

  4. 输入您的搜索查询并查看结果。

注意

控制台搜索仅适用于使用 IAM-based 入站授权的注册表。对于 JWT-authorized 注册表，直接将搜索 API 与 HTTP 客户端（例如curl）和有效的 JWT 持有者令牌一起使用，或者通过 MCP 客户端使用注册表的 MCP 端点。

AWS CLI（使用基于 IAM 的入站授权的注册表）

例
AWS Agent Registry namespace
aws agent-registry search-discoverable-registry-records \
  --search-query "weather" \
  --registry-ids "<registryARN>" \
  --region us-east-1
Amazon Bedrock AgentCore namespace (to be deprecated)
aws bedrock-agentcore search-registry-records \
  --search-query "weather" \
  --registry-ids "<registryARN>" \
  --region us-east-1

AWS SDK（具有基于 IAM 的入站授权的注册表）

例
AWS Agent Registry namespace
import boto3

client = boto3.client('agent-registry')

response = client.search_discoverable_registry_records(
    registryIds=['<registryARN>'],
    searchQuery='weather',
    maxResults=10
)
for record in response['registryRecords']:
    print(f"{record['displayName']} ({record['name']}) - {record['recordType']} - {record['status']}")
Amazon Bedrock AgentCore namespace (to be deprecated)
import boto3

client = boto3.client('bedrock-agentcore')

response = client.search_registry_records(
    registryIds=['<registryARN>'],
    searchQuery='weather',
    maxResults=10
)
for record in response['registryRecords']:
    print(f"{record['name']} - {record['descriptorType']} - {record['status']}")

HTTP 客户端（使用基于 OAuth 的入站授权的注册表）

首先获取持有者代币：

SECRET_HASH=$(echo -n "<username><appClientId>" | openssl dgst -sha256 -hmac "<appClientSecret>" -binary | base64)

aws cognito-idp initiate-auth \
  --client-id "<appClientId>" \
  --auth-flow USER_PASSWORD_AUTH \
  --auth-parameters USERNAME="<username>",PASSWORD='<password>',SECRET_HASH="$SECRET_HASH" \
  --region us-east-1 | jq -r '.AuthenticationResult.AccessToken'

然后使用持有者代币进行搜索：

例
AWS Agent Registry namespace
curl -X POST "https://agent-registry.<region>.api.aws/discoverable-records-search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <accessToken>" \
  -d '{"registryIds": ["<registryARN>"], "searchQuery": "weather", "maxResults": 10}'
Amazon Bedrock AgentCore namespace (to be deprecated)
curl -X POST "https://bedrock-agentcore.<region>.amazonaws.com/registry-records/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <accessToken>" \
  -d '{"registryIds": ["<registryARN>"], "searchQuery": "weather", "maxResults": 10}'

最终一致性为 AWS 代理注册表搜索

AWS 代理注册表使用最终一致的模型进行搜索索引。当您通过调用UpdateRegistryRecordStatus或通过控制台批准注册表记录时，该记录不会立即显示SearchDiscoverableRegistryRecords或生InvokeRegistryMcp效。通常需要几秒钟才能将批准的记录编入索引并变得可发现，但在某些情况下，可能需要长达几分钟。

在此期间，您可能会观察到以下行为：

  • SearchDiscoverableRegistryRecords查询不会返回刚刚获得批准的记录。

  • ListDiscoverableRegistryRecords或BatchGetDiscoverableRegistryRecord通话不包括记录。

  • 注册表 MCP 端点 (InvokeRegistryMcp) 在工具结果中不包含最近批准的记录。

  • 相比之下，控制平面API（GetRegistryRecord和ListRegistryRecords）在完成后UpdateRegistryRecordStatus立即返回新批准的记录。最终一致性仅适用于发现数据平面 API 和注册表 MCP 端点。

只有处于 “已批准” 状态的记录才包含在可发现的结果中。处于 “草稿”、“待批准”、“已拒绝” 或 “已弃用” 状态的记录绝不会由可发现的数据平面 API 或 InvokeRegistryMcp 您可以通过调用来验证记录的当前状态GetRegistryRecord，无论索引状态如何，调用都会返回最新版本。

为了处理应用程序的最终一致性，我们建议以下几点：

  • 批准记录后，通过调SearchDiscoverableRegistryRecords用包含指数退避的重试策略来确认该记录可被发现。

  • 如果某项记录在批准后没有立即出现在结果中，则不要假设注册表中缺失了该记录。致电GetRegistryRecord以验证记录的状态。

  • 如果您要通过亚马逊 EventBridge 和整合审批工作流程UpdateRegistryRecordStatus，请在下游系统查询可发现的 API 以获取新批准的记录之前，再延长一段时间。

注意

SearchDiscoverableRegistryRecords是在命名bedrock-agentcore空间SearchRegistryRecords中命名的。

有关在 AWS SDK 中配置重试行为的一般指导，请参阅《软件开发工具包和 AWS 工具参考指南》中的重试行为。

记录属性如何影响搜索相关性

AWS 代理注册表使用混合搜索，将语义理解与关键字匹配相结合，返回相关结果。如果您希望查找的记录未出现在搜索结果中，了解哪些记录属性会影响搜索会有所帮助。

哪些记录属性用于搜索

您的注册记录中的以下属性用于确定搜索相关性：

  • 名称 — 用于关键字匹配。反映资源内容的清晰描述性名称可提高精确和部分名称查询的可发现性。

  • 描述 — 用于关键字和语义匹配。用自然语言编写的解释资源用途和常见用例的描述比简洁的技术标签更容易被发现。

  • 描述符 — 协议定义的全部内容（MCP 服务器定义、代理卡、技能文档或自定义 JSON）用于语义匹配。这包括工具名称、工具描述、输入参数名称和功能摘要。

  • 记录类型和版本 -可用作可筛选字段。您可以使用name、recordType和的元数据筛选器缩小结果范围recordVersion。

如何处理搜索查询

当您致电时SearchDiscoverableRegistryRecords， AWS Agent Registry 会针对同一组索引记录并行运行两次搜索并合并结果：

  • 语义搜索 -您的查询将转换为矢量表示形式，并与索引记录的矢量表示形式进行比较。即使查询中的确切单词未出现在记录中，它也会找到与概念相关的记录。例如，“预订航班” 的查询可以匹配名为 “旅行预订服务” 的记录。

  • 关键字搜索 -使用传统的关键字相关性将您的查询与记录字段的文本内容进行匹配。这对于确切的名称查询和特定的技术术语有效。例如，对 “weather-api-v2” 的查询会匹配包含该精确文本的记录。

如果您在请求中包含元数据过滤器，则在对结果进行评分和排名之前，过滤器将应用于两个搜索。这意味着过滤器会减少语义搜索和关键字搜索所依据的候选集合，而不是在排名之后筛选结果。

结果是如何排名的

语义搜索和关键字搜索的结果合并为一个排名列表，并按相关性顺序返回，最相关的记录排在第一位。每个结果的最终位置取决于其在两个搜索中的相关性——在语义和关键字结果中排名靠前的记录将高于仅在一个搜索中排名靠前的记录。在关键字搜索中，记录名称对排名的影响最大，其次是描述和描述内容，它们的贡献相同。由于两种搜索模式始终运行并对最终排名做出贡献，因此您编写查询的方式会影响哪些记录的出现。以下指南可以帮助您根据自己的意图获得更好的结果。

撰写有效的搜索查询

当您知道确切的名称或标识符时，请使用简短的特定查询。关键字搜索将精确的文本与记录名称、描述和描述符内容进行匹配。像 “weather-api-v2” 或 “pdf 处理” 这样的简短查询对于按名称查找记录是有效的。

当你按能力或用例进行探索时，使用自然语言描述你的需求。语义搜索理解概念意图，因此，诸如 “查找可以预订航班的工具” 或 “从 PDF 文档中提取结构化数据” 之类的查询可以匹配相关记录，即使这些确切的词语没有出现在记录元数据中。

避免在同一个查询中将类似过滤器的约束条件与描述性意图混为一谈。像 “查找所有用于天气预报的MCP服务器” 这样的查询通过语义和关键字搜索发送整个句子。语义部分将整句解释为概念意图，它可以显示在概念上相关但与你打算限制的特定属性不匹配的记录。取而代之的是，使用元数据过滤器来限制基于属性的约束，并将查询重点放在主题上。请参阅何时使用元数据筛选器与查询文本。

写入可发现的记录

  • 撰写描述来解释该资源的作用及其解决的问题。语义搜索可以理解意图，因此 “帮助客户跟踪包裹交付” 比 “交付状态终端” 更容易被发现。

  • 为 MCP 服务器提供完整的工具定义。工具描述和输入参数描述都有助于提高搜索相关性。

  • 在您的姓名和描述中包含相关的关键字。关键字搜索与精确的文本相匹配，因此，如果消费者可能搜索特定术语，请确保这些术语出现在您的记录中。

何时使用元数据筛选器与查询文本

当您的意图是通过记录类型、名称或版本等已知属性限制结果时，请使用元数据过滤器。不要在查询文本本身中嵌入类似过滤器的约束。例如，如果您想查找与天气相关的所有 MCP 服务器，请对记录类型使用元数据筛选器，对主题使用查询：

{
  "searchQuery": "weather forecast",
  "filters": {
    "recordType": { "$eq": "MCP" }
  }
}

避免在查询文本中添加限制条件，例如 “查找所有 MCP 服务器以进行天气预报”。由于较长的查询倾向于语义匹配，因此 “MCP 服务器” 一词被解释为概念意图的一部分，而不是精确的过滤器。这可能会导致语义组件返回的记录在概念上与整句相关，但与您打算筛选的特定属性不匹配，例如，返回有关天气的代理记录以及 MCP 服务器记录。这同样适用于任何基于属性的约束。如果您想要具有特定名称、版本或类型的记录，请使用相应的元数据筛选器，而不是在查询中包含这些术语。

您可以筛选以下字段：

  • name— 按确切名称匹配记录。

  • recordType— 按语义类型 (AGENT、、MCPSKILL、CUSTOM) 匹配记录。

  • recordVersion— 按版本字符串匹配记录。

过滤器支持$eq（等于）、$ne（不等于）和$in（匹配列表中的任何值）运算符，并且可以使用$and和$or逻辑进行组合。

例如，要仅搜索与天气有关的 MCP 服务器：

{
  "searchQuery": "weather forecast",
  "filters": {
    "recordType": { "$eq": "MCP" }
  }
}

要排除特定的资源类型，请执行以下操作：

{
  "searchQuery": "<your query>",
  "filters": {
    "recordType": { "$ne": "CUSTOM" }
  }
}

要匹配多个版本中的任何一个，请执行以下操作：

{
  "filters": {
    "recordVersion": { "$in": ["1.0", "1.1", "2.0"] }
  }
}

搜索仅返回批准的记录

只有处于 “已批准” 状态的记录才会出现在搜索结果中并通过 MCP 端点显示。不返回处于 “草稿”、“待批准”、“已拒绝” 或 “已弃用” 状态的记录。如果最近批准的记录未出现在结果中，请参阅 AWS 代理注册表搜索中的 “最终一致性” 。