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

搜索智能体、工具和技能

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

搜索查询会评估智能体、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 或 REST API 中搜索已注册的智能体和 MCP 服务器。

搜索智能体或 MCP 服务器时，您可以按显示名称、说明或功能关键字进行查询：

智能体：搜索查询会检查智能体的显示名称、说明、智能体标识符，以及其智能体卡片中声明的内嵌 A2A 技能的名称、说明和标签，以查找匹配项。
MCP 服务器：搜索查询会检查服务器的显示名称、说明、MCP 服务器标识符以及其工具的名称和说明，以查找匹配项。

按关键字搜索

您可以执行关键字搜索，查找功能中包含特定字词的资源，例如智能体的 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"

搜索提供数据库工具的 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 服务器：

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

替换以下内容：

MANAGEMENT_PROJECT_ID：管理项目的 ID。
LOCATION：要在管理边界内搜索的位置，例如区域（如 us-central1）、多区域（如 us 或 eu）或 global。Agent Registry 会汇总管理项目和边界内所有成员项目中同一位置的资源。

如需将管理项目的结果范围缩小到特定成员项目，请传递设置为 "project_id=MEMBER_PROJECT_ID" 的 --filter 标志。如需仅在单个成员项目中搜索，而不进行跨项目汇总，请改为在 --project 标志中指定该成员项目的 ID。

从管理项目进行搜索时：

汇总的自动发现资源：Agent Registry 会在管理边界内所有成员项目的指定位置搜索自动发现的智能体和 MCP 服务器，以及在管理项目的该位置创建的所有已注册 Service 资源。
请求范围内的资源名称：在搜索结果中，每个返回的 Agent 或 McpServer 资源的 name 字段都会保留组件的 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 代码库。

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

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

发现端点：由于 Endpoint 资源不支持 :search 查询，因此您可以通过以下方式发现端点：在Google Cloud 控制台中浏览端点标签页、运行 gcloud agent-registry endpoints list --filter 或调用 endpoints.list REST 方法。如需查看完整说明，请参阅管理和发现端点。
过滤智能体、MCP 服务器和技能：如果您知道组件的注册表标识符 (URN)、显示名称或属性，请在Google Cloud 控制台中过滤集合，或将 --filter 传递给 gcloud agent-registry agents list、gcloud agent-registry mcp-servers list 或 gcloud agent-registry skills list。如需了解详情，请参阅管理代理、管理 MCP 服务器和工具以及管理技能。

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

准备工作

所需的角色

搜索智能体和工具

按关键字搜索

控制台

gcloud

REST

按前缀搜索

gcloud

REST

跨管理边界搜索

搜索独立技能

搜索模式

搜索字段和语法

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

gcloud

REST

按语义搜索技能

gcloud

REST

Google 管理的 skill

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

搜索智能体、工具和技能