Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

搜索智能体、工具和技能

借助 Agent Registry，您可以按关键字、前缀或自然语言搜索已注册的智能体、Agent2Agent (A2A) 技能、独立技能和 Model Context Protocol (MCP) 服务器。您可以在 Google Cloud 控制台、Google Cloud CLI 或 Agent Registry API 中运行搜索。关键字和前缀搜索可帮助您按名称、标识符或元数据查找资源。语义搜索会根据意图，在自然语言指令和说明中查找概念上相关的功能。

搜索查询会评估智能体、MCP 服务器和技能功能说明、工具架构以及技能指令。您无法使用搜索查询来发现端点。如需按元数据列出和过滤端点，请参阅按元数据发现端点和过滤组件。

准备工作

设置 Agent Registry。
对于单项目设置，请获取已启用 Agent Registry 的治理项目的项目 ID。如果您为多个项目配置了管理边界，请使用管理项目的 ID 进行边界范围内的发现和注册，或指定成员项目 ID 进行单项目操作。
在 Agent Registry 中注册智能体、MCP 服务器或 skill。
如需使用本文档中的 Google Cloud CLI 命令，请设置 gcloud CLI 环境。

所需的角色

如需获得在 Agent Registry 中搜索智能体、工具和技能所需的权限，请让管理员为您授予已启用 Agent Registry 的治理项目的以下 IAM 角色：

搜索智能体、工具和技能：Agent Registry API Viewer (roles/agentregistry.viewer)
搜索和查看独立技能：Agent Registry User (roles/agentregistry.user)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

搜索智能体和工具

如需在注册表中发现功能，您可以在 Google Cloud 控制台、gcloud CLI 或 Agent Registry API 中搜索已注册的智能体和 MCP 服务器。

根据组件类型，您可以按以下字段进行搜索：

智能体：按智能体的名称、说明或智能体标识符搜索。您还可以通过代理的代理卡片中内嵌 A2A 技能的名称、说明、标签和示例提示进行搜索。
MCP 服务器：按服务器名称、说明或 MCP 服务器标识符搜索。您还可以按 MCP 服务器工具的名称和说明进行搜索。

如需将搜索范围缩小到内置 Google 智能体、Google 和 Google Cloud远程 MCP 服务器或项目级组件，请参阅按来源前缀查找组件。如需按协议类型查找或检查代理的完整代理卡片 JSON 文件，请按元数据过滤。

搜索字段

当您按关键字搜索时，Agent Registry 会检查智能体组件的发现资源中的所有索引字段，包括智能体上的内嵌 A2A 技能以及 MCP 服务器上的工具名称和说明。如需将搜索范围缩小到特定字段，请使用 : 运算符，例如 skills.tags:incident：

字段过滤条件	智能体组件	支持前缀搜索	说明
`displayName`	代理和 MCP 服务器	是	代理或 MCP 服务器的显示名称。
`name`	代理和 MCP 服务器	是	代理或 MCP 服务器的资源名称。
`agentId`	代理	是	代理标识符 URN（也支持与 `=` 完全匹配）。
`mcpServerId`	MCP 服务器	是	MCP 服务器标识符 URN（也支持与 `=` 完全匹配）。
`description`	代理	否	代理的说明。
`skills`	代理	否	搜索从智能体卡片中提取的所有内嵌 A2A 技能字段。
`skills.id`、`skills.name`、`skills.description`、`skills.tags`、`skills.examples`	代理	否	定位从智能体卡片中提取的特定内嵌 A2A 技能字段。

代理卡片和传输 protocols 中的自定义字段不会编入索引以供搜索。相反，您可以在列出或描述代理时使用元数据过滤条件来检查这些信息。如需了解详情，请参阅发现端点并按元数据过滤组件。

按关键字搜索

您可以执行关键字搜索，查找功能中包含特定字词的资源，例如智能体的 A2A 技能或 MCP 服务器的工具。如需了解这些功能在注册表中的结构，请参阅 JSON 架构。如需查看可搜索字段的完整列表，请参阅 API 参考文档。

关键字查询接受自由文本字符串，并支持逻辑运算符 AND、OR 和 NOT：

控制台

在 Google Cloud 控制台中，前往 Agent Registry：

前往 Agent Registry
从项目选择器中，选择您的 Google Cloud 项目。
在页面顶部的搜索您的注册表栏中，输入至少包含三个字符的关键字查询（例如 flight 或 database）或字段过滤条件（例如 Name:booking），然后按 Enter。

搜索结果表格会显示所选位置中匹配的智能体、MCP 服务器和独立技能。

gcloud

向 gcloud agent-registry agents search 或 gcloud agent-registry mcp-servers search 命令提供 --search-string 标志，例如：

搜索可处理航班预订的智能体：

gcloud agent-registry agents search \
    --project=PROJECT_ID \
    --location=REGION \
    --search-string="flight OR booking"

按 A2A 技能标签或示例提示搜索智能体：

gcloud agent-registry agents search \
    --project=PROJECT_ID \
    --location=REGION \
    --search-string='skills.tags:incident OR skills.examples:"rollout"'

搜索提供数据库工具的 MCP 服务器：

gcloud agent-registry mcp-servers search \
    --project=PROJECT_ID \
    --location=REGION \
    --search-string="database"

替换以下内容：

PROJECT_ID：项目 ID。
REGION：注册表区域或 global。

REST

向 agents:search 或 mcpServers:search 端点发送 POST 请求，并在请求正文中添加 searchString 字段。

例如，搜索可以处理航班预订的代理：

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"searchString": "flight OR booking"}' \
    "https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/agents:search"

搜索提供数据库工具的 MCP 服务器：

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"searchString": "database"}' \
    "https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/mcpServers:search"

替换以下内容：

PROJECT_ID：项目 ID。
REGION：注册表区域或 global。

按前缀搜索

前缀搜索针对低延迟进行了优化，可让您的应用在用户输入时动态检索相关智能体和工具。

如果您要构建编排器界面或自动补全功能，可以在智能体注册表中执行前缀搜索，以查找以给定字符串开头的结果。前缀搜索使用 * 后缀通配符来搜索单词的开头：

gcloud

运行带有前缀表达式的 gcloud agent-registry agents search 或 gcloud agent-registry mcp-servers search 命令。

例如，搜索显示名称以 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：注册表区域或 global。

REST

在请求正文的 searchString 字段中传递前缀表达式：

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"searchString": "displayName:Best_A2A_*"}' \
    "https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/agents:search"

替换以下内容：

PROJECT_ID：项目 ID。
REGION：注册表区域或 global。

按来源前缀查找组件

每个智能体和 MCP 服务器在其注册表标识符中都包含一个来源前缀：

内置 Google 代理以及 Google 和 Google Cloud 远程 MCP 服务器：使用 urn:agent:googleapis.com: 或 urn:mcp:googleapis.com:。
项目级组件：使用 urn:agent:projects- 或 urn:mcp:projects-，后跟项目编号，例如 urn:agent:projects-PROJECT_NUMBER:。

您可以按以下来源前缀进行搜索，以便仅查找内置 Google 智能体、Google 和 Google Cloud 远程 MCP 服务器、所有项目级组件或特定项目中的组件：

gcloud

在 gcloud agent-registry agents search 或 gcloud agent-registry mcp-servers search 命令的 --search-string 标志中添加标识符前缀：

内置 Google 智能体以及 Google 和 Google Cloud 远程 MCP 服务器：包含 urn:agent:googleapis.com:* 或 urn:mcp:googleapis.com:* 前缀：

搜索内置 Google 代理：

gcloud agent-registry agents search \
    --project=PROJECT_ID \
    --location=REGION \
    --search-string='agentId:"urn:agent:googleapis.com:*"'

搜索 Google 和 Google Cloud 远程 MCP 服务器：

gcloud agent-registry mcp-servers search \
    --project=PROJECT_ID \
    --location=REGION \
    --search-string='mcpServerId:"urn:mcp:googleapis.com:*"'

项目级组件：使用 projects-* 匹配所有项目级组件，或使用 projects-PROJECT_NUMBER:* 匹配特定项目：

例如，搜索所有项目级智能体：

gcloud agent-registry agents search \
    --project=PROJECT_ID \
    --location=REGION \
    --search-string='agentId:"urn:agent:projects-*"'

例如，搜索特定项目中的 MCP 服务器：

gcloud agent-registry mcp-servers search \
    --project=PROJECT_ID \
    --location=REGION \
    --search-string='mcpServerId:"urn:mcp:projects-PROJECT_NUMBER:*"'

替换以下内容：

PROJECT_ID：项目 ID。
REGION：注册表位置，例如区域（如 us-central1）、多区域（如 us 或 eu）或 global。
PROJECT_NUMBER：特定项目组件的项目编号。

REST

向 agents:search 或 mcpServers:search 端点发送 POST 请求，并在 searchString 中使用 googleapis.com 或 projects- 标识符前缀：

内置 Google 智能体以及 Google 和 Google Cloud 远程 MCP 服务器：包含 urn:agent:googleapis.com:* 或 urn:mcp:googleapis.com:* 前缀。例如，搜索内置 Google 代理：

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"searchString": "agentId:\"urn:agent:googleapis.com:*\""}' \
    "https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/agents:search"

项目级组件：使用 projects-* 匹配所有项目级组件，或使用 projects-PROJECT_NUMBER:* 定位到特定项目。例如，搜索项目级智能体：

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"searchString": "agentId:\"urn:agent:projects-*\""}' \
    "https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/agents:search"

替换以下内容：

PROJECT_ID：项目 ID。
REGION：注册表位置，例如区域（如 us-central1）、多区域（如 us 或 eu）或 global。

在特定项目中列出或描述已注册的智能体和 MCP 服务器时，您还可以按来源前缀过滤已注册的智能体和过滤已注册的 MCP 服务器。

跨管理边界搜索

如果您配置了管理边界，则可以从管理项目中搜索该边界内所有成员项目中某个位置的所有智能体和 MCP 服务器：

gcloud agent-registry agents search \
    --project=MANAGEMENT_PROJECT_ID \
    --location=LOCATION \
    --search-string="analytics"

如需将管理项目中的结果范围缩小到特定成员项目中的代理或 MCP 服务器，请使用 --search-string 标志中的注册表标识符，按该成员项目的编号进行过滤。例如，搜索特定成员项目中的代理：

gcloud agent-registry agents search \
    --project=MANAGEMENT_PROJECT_ID \
    --location=LOCATION \
    --search-string='agentId:"urn:agent:projects-MEMBER_PROJECT_NUMBER:*"'

替换以下内容：

MANAGEMENT_PROJECT_ID：管理项目的 ID。如需仅在单个成员项目中搜索，而不进行跨项目汇总，请改为在 --project 标志中指定该成员项目的 ID。
LOCATION：要在管理边界内搜索的位置，例如区域（如 us-central1）、多区域（如 us 或 eu）或 global。Agent Registry 会汇总管理项目和边界内所有成员项目中同一位置的资源。
MEMBER_PROJECT_NUMBER：成员项目的项目编号。

从管理项目进行搜索时：

汇总的自动发现资源：Agent Registry 会在管理边界内所有成员项目的指定位置搜索自动发现的智能体和 MCP 服务器，以及在管理项目的该位置创建的所有已注册 Service 资源。
请求范围内的资源名称：在搜索结果中，每个返回的智能体或 MCP 服务器资源名称都会保留组件的 ID，并使用请求网址中指定的项目。
项目级注册资源：在成员项目中创建的手动注册 Service 资源和 Binding 资源仍限定于该成员项目，不会显示在管理项目搜索结果中。如需使其在管理边界内可见，请在管理项目中创建它们。

搜索独立技能

您可以搜索在 Agent Registry 中注册的独立 skill。此功能可让您发现可附加到代理的可重用功能。

搜索技能时，您搜索的是默认技能修订版本。如需更新技能的默认修订版本，请参阅更新技能元数据或默认修订版本。

Agent Registry 会根据您的 Identity and Access Management (IAM) 权限过滤技能搜索结果。搜索请求仅返回您拥有 agentregistry.skills.get 权限的技能，无论该权限是在项目级层授予的，还是通过技能的资源级 IAM 政策授予的。

搜索模式

您可以根据自己的需求，使用两种技能搜索模式：

关键字搜索：仅扫描基本元数据属性，例如显示名称、说明、资源名称和技能标识符。此模式针对低延迟搜索、精确查找和名称自动补全进行了优化。如需查看示例，请参阅按关键字或表达式搜索技能。
语义搜索：自动为 SKILL.md 载荷的完整内容（包括自然语言指令、脚本和元数据资产）编制索引。此模式可识别概念主题，并针对编排器代理根据您的意图动态发现相关功能包进行了优化。如需查看示例，请参阅按语义搜索技能。

搜索字段和语法

按元数据或关键字字符串搜索时，系统会为以下字段编制索引：

字段名称	大小写行为	前缀搜索	全字段搜索	说明
`displayName`	不区分大小写	是	是	技能的显示名称。使用此字段可搜索通用名称。
`description`	不区分大小写	否	是	技能用途和功能的详细说明。使用此字段搜索关键字。
`name`	不区分大小写	是	是	技能的资源名称。使用此字段可按资源名称进行搜索。
`skillId`	不区分大小写	是	是	技能的技能标识符。使用此字段可查找特定发布商的资产。例如，Google 管理的 skill 的格式为 `urn:skill:PUBLISHER_ID:NAMESPACE:SKILL_ID`。
`publisher`	不区分大小写	是	否	与技能相关联的发布商。使用此字段可按发布组织进行过滤。
`frontmatter.name`	不区分大小写	否	否	`SKILL.md` 文件的 front matter 中定义的技能名称。
`frontmatter.description`	不区分大小写	否	否	`SKILL.md` 文件的 front matter 中定义的技能说明。
`frontmatter.compatibility`	不区分大小写	否	否	`SKILL.md` 文件前言中定义的技能兼容性。
`frontmatter.license`	不区分大小写	否	否	`SKILL.md` 文件前言中定义的技能许可。
`frontmatter.allowed_tools`	不区分大小写	否	否	在 `SKILL.md` 文件的 front matter 中定义的技能允许使用的工具。
`frontmatter.metadata.KEY`	不区分大小写	否	否	在 `SKILL.md` 文件的 front matter 中，`metadata` 内定义的自定义元数据键值对条目。支持搜索查询中的 `:` 运算符和过滤条件中的完全匹配（`=` 和 `!=`）。
`state`	不区分大小写	否	否	技能的当前生命周期状态，例如 `ACTIVE`、`DRAFT`、`DISABLED`、`DEPRECATED` 或 `DECOMMISSIONED`。此字段仅在过滤条件中可用，并且支持完全匹配（`=` 和 `!=`）。
`targetState`	不区分大小写	否	否	技能的目标生命周期状态，例如 `ACTIVE`、`DRAFT`、`DISABLED`、`DEPRECATED` 或 `DECOMMISSIONED`。此字段仅在过滤条件中可用，并且支持完全匹配（`=` 和 `!=`）。
`defaultRevisionFindingCount`	不适用	否	否	在技能的默认修订版本中检测到的安全发现结果数量。此字段仅在过滤条件中可用，并支持完全匹配（`=` 和 `!=`）和范围运算符（`<`、`<=`、`>` 和 `>=`），例如 `defaultRevisionFindingCount = 0` 或 `defaultRevisionFindingCount > 0`。
`createTime`	不适用	否	否	技能的创建时间戳。此字段仅在过滤条件中可用。支持范围运算符（例如 `<`、`>`）和完全匹配。
`updateTime`	不适用	否	否	上次更新技能时的时间戳。此字段仅在过滤条件中可用。支持范围运算符（例如 `<`、`>`）和完全匹配。

如需搜索技能，请使用 gcloud CLI 中的 --query 标志或 REST API 请求正文中的 searchString 字段提供查询字符串。您可以在搜索请求中使用以下语法元素：

布尔运算符：包含 AND、OR 或 NOT 运算符，用于串联要求。
字段专用过滤条件：使用 : 运算符定位字段，例如 displayName:database。
前缀搜索：使用 * 后缀通配符查找以特定前缀开头的值，例如 displayName:cloud-*。

按关键字或表达方式搜索技能

搜索具有特定显示名称前缀和说明关键字的技能：

gcloud

使用 --search-type=keyword 运行 gcloud agent-registry skills search 命令：

gcloud agent-registry skills search \
    --project=PROJECT_ID \
    --location=REGION \
    --query="displayName:cloud-* AND description:database" \
    --search-type=keyword

替换以下内容：

PROJECT_ID：项目 ID。
REGION：注册表区域或 global。

REST

向 skills:search 端点发送 POST 请求，并在请求正文中包含 searchString 和 searchType 字段：

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
      "searchString": "displayName:cloud-* AND description:database",
      "searchType": "KEYWORD"
    }' \
    "https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/skills:search"

替换以下内容：

PROJECT_ID：项目 ID。
REGION：注册表区域或 global。

按语义搜索技能

使用语义搜索查找与管理关系型数据库相关的技能：

gcloud

使用 --search-type=semantic 运行 gcloud agent-registry skills search 命令：

gcloud agent-registry skills search \
    --project=PROJECT_ID \
    --location=REGION \
    --query="manage and configure relational databases" \
    --search-type=semantic

替换以下内容：

PROJECT_ID：项目 ID。
REGION：注册表区域或 global。

REST

向 skills:search 端点发送 POST 请求，并在请求正文中包含 searchString 和 searchType 字段：

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
      "searchString": "manage and configure relational databases",
      "searchType": "SEMANTIC"
    }' \
    "https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/skills:search"

替换以下内容：

PROJECT_ID：项目 ID。
REGION：注册表区域或 global。

Google 管理的 skill

Google 管理的 skill 可从任何项目中发现。如需查看可用的 Google 管理的 skill 列表，请参阅 GitHub 上的 google/skills 代码库。

如需搜索来自经过验证的 Google 管理的发布商的技能，请过滤 publisher 字段：

gcloud agent-registry skills search \
    --project=PROJECT_ID \
    --location=REGION \
    --query="publisher:cloud.google.com" \
    --search-type=keyword

替换以下内容：

PROJECT_ID：项目 ID。
REGION：注册表位置，例如区域（如 us-central1）、多区域（如 us 或 eu）或 global。

发现端点并按元数据过滤组件

您还可以通过列出相应的集合并过滤结构化元数据字段，在 Agent Registry 中发现任何组件，包括已注册的端点：

发现端点：由于 Endpoint 资源不支持搜索查询，因此您可以通过浏览Google Cloud 控制台中的端点标签页、运行 gcloud agent-registry endpoints list --filter 或调用 endpoints.list REST 方法来发现端点。如需查看完整说明，请参阅管理和发现端点。
过滤智能体、MCP 服务器和技能：如果您知道组件的注册表标识符 (URN)、显示名称、协议类型或属性，则可以在 Google Cloud 控制台中过滤列表，或在 gcloud agent-registry agents list、gcloud agent-registry mcp-servers list 或 gcloud agent-registry skills list 命令中添加 --filter 标志。例如，在 gcloud agent-registry agents list 命令中添加 --filter='protocols.type="A2A_AGENT"'，以仅显示 A2A 智能体，并运行 gcloud agent-registry agents describe 以查看智能体的完整智能体卡片和 protocols 端点。如需了解详情，请参阅管理智能体、管理 MCP 服务器和工具以及管理技能。

搜索智能体、工具和技能 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

所需的角色

搜索智能体和工具

搜索字段

按关键字搜索

控制台

gcloud

REST

按前缀搜索

gcloud

REST

按来源前缀查找组件

gcloud

REST

跨管理边界搜索

搜索独立技能

搜索模式

搜索字段和语法

按关键字或表达方式搜索技能

gcloud

REST

按语义搜索技能

gcloud

REST

Google 管理的 skill

发现端点并按元数据过滤组件

搜索智能体、工具和技能