搜索注册记录

请求参数

元数据过滤器

运算符：$eq、$ne、$in。合乎逻辑：$and，$or。字段：名称、描述符类型、版本。

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

合并：{"$and": [{"descriptorType": {"$eq": "MCP"}}, {"version": {"$eq": "1.0"}}]}

控制台

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

aws bedrock-agentcore search-registry-records \
  --search-query "weather" \
  --registry-ids "<registryARN>" \
  --region us-east-1

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

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'

然后使用不记名令牌进行搜索：

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 Agent Registry 使用最终一致的模型进行搜索索引。当您通过调用UpdateRegistryRecordStatus或通过控制台批准注册表记录时，该记录不会出现在SearchRegistryRecords或立即生InvokeRegistryMcp效。通常需要几秒钟才能将已批准的记录编入索引并可供发现，但在某些情况下，可能需要几分钟。

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

只有处于 “已批准” 状态的记录才会包含在搜索结果中。或永远不会返回处于 “草稿”、“待批准”、“已拒绝” 或 “已弃用” 状态的SearchRegistryRecords记录。InvokeRegistryMcp您可以通过调用来验证记录的当前状态GetRegistryRecord，无论索引状态如何，调用都会返回最新的修订版。

为了处理应用程序的最终一致性，我们建议采取以下措施：

有关在 AWS SDK 中配置重试行为的一般指南，请参阅 S AWS DK 和工具参考指南中的重试行为。

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

AWS Agent Registry 使用混合搜索来返回相关结果，该搜索将语义理解与关键字匹配相结合。如果您期望找到的记录未出现在搜索结果中，那么了解哪些记录属性会影响搜索会有所帮助。

哪些记录属性用于搜索

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

如何处理搜索查询

当您调用时SearchRegistryRecords， AWS Agent Registry 会对同一组已编入索引的记录并行运行两个搜索并合并结果：

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

如何对结果进行排名

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

撰写有效的搜索查询

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

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

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

撰写可发现的记录

何时使用元数据筛选器而不是查询文本

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

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

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

您可以筛选以下字段：

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

例如，要仅搜索与天气相关的 MCP 服务器，请执行以下操作：

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

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

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

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

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

搜索仅返回已批准的记录

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