随着智能体生态系统的发展，找到合适的智能体或工具变得至关重要。Agent Registry 提供搜索功能，可让您在智能体、智能体技能和 Model Context Protocol (MCP) 服务器中执行高级关键字搜索、前缀搜索和语义搜索。
本文档介绍了如何构建搜索查询，以发现环境中的功能。
准备工作
在 Agent Registry 中搜索智能体、工具或技能之前，请注册智能体或 MCP 服务器。您还需要项目 ID 才能执行这些任务。
如需使用本文档中的 gcloud CLI 命令，请确保您已设置 Google Cloud CLI 环境。
所需的角色
如需获得在代理注册表中搜索代理、工具和技能所需的权限，请让管理员向您授予项目的 Agent Registry API Viewer (roles/agentregistry.viewer) IAM 角色。
如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。
搜索代理和工具
如需发现注册表中的功能，您可以搜索已注册的代理和 MCP 服务器。
搜索代理会匹配其基本元数据、说明和在代理卡片中内嵌声明的描述性 A2A 技能。搜索 MCP 服务器时，系统会匹配其说明和确定性工具。
按关键字搜索
您可以执行关键字搜索，以查找在功能方面与特定字词匹配的资源，例如智能体的 A2A 技能或 MCP 服务器的工具。 如需了解这些功能在注册表中的结构，请参阅 JSON 架构。如需查看可搜索字段的完整列表，请参阅 API 参考文档。
如需按关键字搜索，请提供 --search-string 标志。此参数接受自由文本查询，并支持逻辑运算符：AND、OR 和 NOT。
例如，搜索可以处理航班预订的智能体：
gcloud agent-registry agents search \
--project=PROJECT_ID \
--location=REGION \
--search-string="flight OR booking"
您还可以根据 MCP 服务器提供的特定工具或其说明来搜索 MCP 服务器。例如，搜索提供数据库工具的 MCP 服务器：
gcloud agent-registry mcp-servers search \
--project=PROJECT_ID \
--location=REGION \
--search-string="database"
替换以下内容：
PROJECT_ID：项目 ID。REGION：注册区域。
按前缀搜索
前缀搜索经过高度优化，可实现低延迟，让您的应用在用户输入内容时动态检索相关代理和工具。
如果您要构建编排器界面或自动补全功能，可以在 Agent Registry 中执行前缀搜索，以获取与查询字符串开头匹配的结果。前缀搜索使用后缀通配符 (*) 来匹配字词的开头。
例如，搜索显示名称以特定前缀（例如 Best_A2A_*）开头的代理：
gcloud agent-registry agents search \
--project=PROJECT_ID \
--location=REGION \
--search-string="displayName:Best_A2A_*"
同样，您也可以搜索显示名称以特定前缀（例如 Prod_Server_*）开头的 MCP 服务器：
gcloud agent-registry mcp-servers search \
--project=PROJECT_ID \
--location=REGION \
--search-string="displayName:Prod_Server_*"
替换以下内容：
PROJECT_ID：项目 ID。REGION：注册区域。
搜索独立技能
您可以搜索在 Agent Registry 中注册的独立技能。借助此功能，您可以发现可重用的功能，并将其附加到代理。
当您搜索技能时，系统会搜索默认技能修订版本。如需更新技能的默认修订版本，请参阅更新技能元数据或默认修订版本。
搜索模式
您可以根据自己的需求使用两种技能搜索模式：
- 关键字搜索：仅扫描基本元数据属性，例如显示名称、说明、名称 (URN) 和技能 ID。此模式针对低延迟搜索、匹配和名称自动补全进行了优化。如需查看示例，请参阅按关键字或表达方式搜索技能。
- 语义搜索：自动为
SKILL.md载荷的完整内容（包括自然语言指令、代码结构和资源）编制索引。此模式可匹配概念主题，并针对编排器代理根据您的意图动态发现相关功能包进行了优化。如需查看示例，请参阅按语义搜索技能。
搜索字段和语法
按元数据或关键字字符串搜索时，系统会对以下字段编制索引：
| 字段名称 | 支持请求行为 | 前缀搜索 | 全字段搜索 | 说明 |
|---|---|---|---|---|
displayName |
不区分大小写 | 是 | 是 | 技能面向用户的名称。使用此字段搜索常用名称。 |
description |
不区分大小写 | 否 | 是 | 技能的用途和功能的详细说明。使用此字段匹配关键字。 |
name |
不区分大小写 | 是 | 是 | 技能的程序化标识符。此字段用于匹配标识符字符串。 |
skillId |
不区分大小写 | 是 | 是 | 技能的逻辑统一资源名称 (URN)。
使用此字段可查找特定发布商的资源。例如，Google 创建的技能的格式为 urn:skill:PUBLISHER_ID:NAMESPACE:SKILL_ID。
|
publisher |
不区分大小写 | 是 | 否 | 与技能相关联的发布者。使用此字段按发布组织进行过滤。 |
frontmatter.name |
不区分大小写 | 否 | 否 | 在 SKILL.md 文件的前置元数据中定义的技能名称。 |
frontmatter.description |
不区分大小写 | 否 | 否 | SKILL.md 文件的前置元数据中定义的技能说明。 |
frontmatter.compatibility |
不区分大小写 | 否 | 否 | 在 SKILL.md 文件的文件头中定义的技能的兼容性。 |
frontmatter.license |
不区分大小写 | 否 | 否 | SKILL.md 文件前置元数据中定义的技能许可。 |
createTime |
不适用 | 否 | 否 | 技能创建时的时间戳。此字段仅在过滤条件中可用。支持范围运算符（例如 <、>）和精确匹配。 |
updateTime |
不适用 | 否 | 否 | 上次更新技能时的时间戳。此字段仅在过滤条件中可用。支持范围运算符（例如 <、>）和精确匹配。 |
查询字符串通过 --query 标志或 query 参数附加到命令，并且接受逻辑实参。您可以在搜索请求中使用以下元素：
- 布尔值运算符：使用
AND、OR或NOT运算符来串联要求。 - 特定于字段的过滤条件：使用
:运算符指定字段，例如displayName:database。 - 前缀匹配：使用通配符后缀
:*可查找以特定前缀开头的匹配项，例如skillId:db-*。
按关键字或表达式搜索技能
以下示例搜索与特定显示名称前缀和说明关键字匹配的技能：
gcloud alpha agent-registry skills search \
--project=PROJECT_ID \
--location=REGION \
--query="displayName:db-* AND description:sql"
替换以下内容：
PROJECT_ID：项目 ID。REGION：注册区域。
按语义搜索技能
以下示例执行语义搜索，以查找与数据库查询处理相关的技能，匹配自然语言查询中的概念主题：
gcloud alpha agent-registry skills search \
--project=PROJECT_ID \
--location=REGION \
--query="find skills to handle database queries" \
--search-type=semantic
替换以下内容：
PROJECT_ID：项目 ID。REGION：注册区域。
公开技能
Google 的公开技能可供所有项目在全球范围内发现。如需查看可用的公开技能列表，请参阅 GitHub 上的 google/skills 代码库。
当您执行搜索时，Agent Registry 会动态重写输出中公共技能的逻辑资源名称，使其看起来好像托管在您的本地项目中，从而简化集成。