Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

搜尋代理、工具和技能

Agent Registry 可讓您依關鍵字、前置字元或自然語言，搜尋已註冊的代理、Agent2Agent (A2A) 技能、獨立技能和 Model Context Protocol (MCP) 伺服器。您可以在 Google Cloud 控制台、Google Cloud CLI 或 Agent Registry API 中執行搜尋。關鍵字和前置字元搜尋可協助您依名稱、ID 或中繼資料尋找資源。語意搜尋會根據意圖，在自然語言指令和說明中，找出概念相關的功能。

搜尋查詢會評估代理、MCP 伺服器和技能功能說明、工具結構定義和技能指令。您無法使用搜尋查詢來探索端點。如要依中繼資料列出及篩選端點，請參閱「依中繼資料探索端點和篩選元件」。

事前準備

設定 Agent Registry。
如果是單一專案設定，請取得已啟用 Agent Registry 的管理專案 ID。如果您為多個專案設定了管理邊界，請使用管理專案的 ID 進行邊界範圍的探索和註冊，或指定成員專案 ID 進行單一專案作業。
在 Agent Registry 中註冊代理、MCP 伺服器或技能。
如要使用本文件中的 Google Cloud CLI 指令，請設定 gcloud CLI 環境。

必要的角色

如要取得在 Agent Registry 搜尋代理、工具和技能所需的權限，請要求管理員在啟用 Agent Registry 的管理專案中，授予您下列 IAM 角色：

搜尋代理、工具和技能：Agent Registry API 檢視者 (roles/agentregistry.viewer)
搜尋及查看獨立技能：Agent Registry 使用者 (roles/agentregistry.user)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

搜尋代理和工具

如要探索登錄檔中的功能，您可以在 Google Cloud 控制台、gcloud CLI 或 Agent Registry API 中搜尋已註冊的代理和 MCP 伺服器。

視元件類型而定，您可以依下列欄位搜尋：

代理：依代理名稱、說明或代理 ID 搜尋。您也可以在代理的代理資訊卡中，依內嵌 A2A 技能的名稱、說明、標記和範例提示詞進行搜尋。
MCP 伺服器：依伺服器名稱、說明或 MCP 伺服器 ID 搜尋。您也可以依 MCP 伺服器工具的名稱和說明進行搜尋。

如要將搜尋範圍縮小至內建 Google 代理、Google 和 Google Cloud遠端 MCP 伺服器，或專案範圍元件，請參閱「依來源前置字串尋找元件」。如要依通訊協定類型尋找，或檢查代理的完整 Agent Card JSON 檔案，請依中繼資料篩選。

搜尋欄位

依關鍵字搜尋時，Agent Registry 會檢查代理元件探索資源中的所有索引欄位，包括代理上的內嵌 A2A 技能，以及 MCP 伺服器上的工具名稱和說明。如要將搜尋範圍縮小至特定欄位，請使用 : 運算子，例如 skills.tags:incident：

欄位篩選器	代理元件	支援前置字串搜尋	說明
`displayName`	代理和 MCP 伺服器	是	代理或 MCP 伺服器的顯示名稱。
`name`	代理和 MCP 伺服器	是	代理或 MCP 伺服器的資源名稱。
`agentId`	代理	是	代理 ID URN (也支援與 `=` 完全相符)。
`mcpServerId`	MCP 伺服器	是	MCP 伺服器 ID 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 專案。
在頁面頂端的「Search your registry」(搜尋登錄檔) 列中，輸入至少三個字元的關鍵字查詢 (例如 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

傳送 POST 要求至 agents:search 或 mcpServers:search 端點，並在要求主體中加入 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 伺服器的登錄檔 ID 都包含來源前置字元：

內建 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 旗標中加入 ID 前置字串：

內建 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

將 POST 要求傳送至 agents:search 或 mcpServers:search 端點，並在 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 旗標中的儲存庫 ID，依該成員專案的編號篩選。例如，搜尋特定成員專案中的代理：

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 註冊的獨立技能。這項功能可讓您探索可附加至代理的可重複使用功能。

搜尋技能時，系統會搜尋預設的技能修訂版本。如要更新技能的預設修訂版本，請參閱「更新技能中繼資料或預設修訂版本」。

Agent Registry 會根據您的 Identity and Access Management (IAM) 權限，篩選技能搜尋結果。搜尋要求只會傳回您具備 agentregistry.skills.get 權限的技能，無論是在專案層級授予，還是透過技能的資源層級 IAM 政策授予。

搜尋模式

您可以根據需求，使用兩種技能搜尋模式：

關鍵字搜尋：僅掃描基本中繼資料屬性，例如顯示名稱、說明、資源名稱和技能 ID。這個模式經過最佳化，適用於低延遲搜尋、精確查詢和名稱自動完成。如需範例，請參閱「依關鍵字或運算式搜尋技能」。
語意搜尋：自動為 SKILL.md 酬載的完整內容建立索引，包括自然語言指令、指令碼和中繼資料資產。這個模式會找出概念主題，並經過最佳化調整，可讓自動調度管理代理根據您的意圖，動態探索相關功能套件。如需範例，請參閱「依語意搜尋技能」。

搜尋欄位和語法

依中繼資料或關鍵字字串搜尋時，系統會為下列欄位建立索引：

欄位名稱	大小寫行為	前置字串搜尋	搜尋所有欄位	說明
`displayName`	不區分大小寫	是	是	技能的顯示名稱。在這個欄位搜尋常見名稱。
`description`	不區分大小寫	否	是	詳細說明技能的用途和功能。在這個欄位輸入要搜尋的關鍵字。
`name`	不區分大小寫	是	是	技能的資源名稱。使用這個欄位，依資源名稱搜尋。
`skillId`	不區分大小寫	是	是	技能的技能 ID。使用這個欄位尋找特定發布商的資產。舉例來說，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` 檔案前置資料中定義的技能授權。
`frontmatter.allowed_tools`	不區分大小寫	否	否	`SKILL.md` 檔案前置資料中定義的技能允許工具。
`frontmatter.metadata.KEY`	不區分大小寫	否	否	在 `SKILL.md` 檔案的前置資料中，`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

執行 gcloud agent-registry skills search 指令並加上 --search-type=keyword：

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

傳送 POST 要求至 skills:search 端點，並在要求主體中加入 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

執行 gcloud agent-registry skills search 指令並加上 --search-type=semantic：

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

傳送 POST 要求至 skills:search 端點，並在要求主體中加入 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 代管技能

任何專案都能找到 Google 代管技能。如要查看可用的 Google 代管技能清單，請前往 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。

探索端點，並依中繼資料篩選元件

您也可以在代理程式登錄檔中探索任何元件，包括已註冊的端點，方法是列出對應的集合，並篩選結構化中繼資料欄位：

探索端點：由於 Endpoint 資源不支援搜尋查詢，因此您必須在Google Cloud 控制台瀏覽「Endpoints」(端點) 分頁、執行 gcloud agent-registry endpoints list --filter，或呼叫 endpoints.list REST 方法，才能探索端點。如需完整操作說明，請參閱「管理及探索端點」。
篩選代理、MCP 伺服器和技能：如果您知道元件的登錄檔 ID (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 代管技能

探索端點，並依中繼資料篩選元件

搜尋代理、工具和技能