Agent Registry 可讓您檢查、更新及管理獨立技能,控管代理可使用的技能版本和生命週期狀態。註冊獨立技能後,您可以查看詳細資料、更新說明或預設修訂版本、轉換生命週期狀態、管理資源層級存取權政策,或從代理程式註冊資料庫中刪除。您也可以列出及查看 Google 代管技能,設定代理登錄檔後即可使用。
事前準備
- 設定 Agent Registry。
如果是單一專案設定,請取得已啟用 Agent Registry 的管理專案 ID。如果您為多個專案設定了管理邊界,請使用管理專案的 ID 進行邊界範圍的探索和註冊,或指定成員專案 ID 進行單一專案作業。
如要使用本文件中的 Google Cloud CLI 指令,請設定 gcloud CLI 環境。
必要的角色
如要取得在 Agent Registry 管理技能所需的權限,請要求管理員在已啟用 Agent Registry 的管理專案中,授予您下列 IAM 角色:
-
列出及查看技能:Agent Registry API 檢視者 (
roles/agentregistry.viewer) -
更新、轉換生命週期狀態及刪除技能:代理程式註冊資料庫使用者 (
roles/agentregistry.user) -
管理技能和其他 Agent Registry 資源:Agent Registry API 編輯者 (
roles/agentregistry.editor) -
管理技能的身分與存取權管理 (IAM) 政策:Agent Registry API 管理員 (
roles/agentregistry.admin)
如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和組織的存取權」。
其他 Agent Registry 角色也可能包含查看、更新和刪除技能所需的權限。詳情請參閱「Agent Registry 角色和權限」。
列出及查看技能
您可以瀏覽所有已註冊的技能,或搜尋特定功能:
控制台
- 前往 Google Cloud 控制台的「Agent Registry」頁面:
- 選取「技能」分頁標籤。
- 查看技能清單。您可以使用「Location」(位置) 或「Status」(狀態) 選單篩選顯示內容。
- 按一下任何技能名稱,即可開啟「Skill Details」(技能詳細資料) 頁面,其中會顯示名稱、說明、有效版本、技能 ID、上次更新時間、自訂中繼資料和修訂版本記錄。
gcloud
如要列出某個位置的所有技能,請使用 gcloud agent-registry skills list 指令:
gcloud agent-registry skills list \
--project=PROJECT_ID \
--location=LOCATION
如要查看特定技能的詳細資料,請使用 gcloud agent-registry skills describe 指令:
gcloud agent-registry skills describe SKILL_ID \
--project=PROJECT_ID \
--location=LOCATION
更改下列內容:
SKILL_ID:要查看的技能 ID。如果是手動註冊的技能,請加入private-前置字元,例如private-my-skill。PROJECT_ID:專案 ID。LOCATION:登錄檔位置。
REST
如要擷取所有技能的清單,請傳送 GET 要求:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/skills"
如要擷取單一技能容器,請傳送 GET 要求:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID"
更改下列內容:
PROJECT_ID:專案 ID。LOCATION:登錄檔位置。SKILL_ID:要查看的技能 ID。如果是手動註冊的技能,請加入private-前置字元,例如private-my-skill。
更新技能中繼資料或預設修訂版本
您可以修改技能的顯示名稱、說明、掃描設定,或手動變更預設修訂版本指標,部署其他版本。
如果技能設有 ENABLED_BLOCKING 掃描政策,嘗試將預設修訂版本設為有安全性發現項目或掃描結果待處理的修訂版本時,會失敗並顯示 FAILED_PRECONDITION 錯誤。同樣地,如果技能目前的預設修訂版本有安全性發現項目或待處理的掃描結果,您就無法將技能的掃描政策更新為 ENABLED_BLOCKING。啟用或更新技能掃描功能後,系統只會掃描變更後建立的版本,不會回溯掃描現有版本。詳情請參閱「掃描技能中的安全性問題」。如要建立新的技能修訂版本,請參閱「管理技能修訂版本」。
如要更新技能中繼資料或特定技能的預設修訂版本,請按照下列步驟操作:
控制台
- 前往 Google Cloud 控制台的「Agent Registry」頁面:
- 選取「技能」分頁標籤。
- 查看技能清單。您可以使用「Location」(位置) 或「Status」(狀態) 選單篩選顯示內容。
- 按一下任何技能名稱,即可開啟「Skill Details」(技能詳細資料) 頁面,其中會顯示名稱、說明、有效版本、技能 ID、上次更新時間、自訂中繼資料和修訂版本記錄。
選擇下列其中一個選項:
更新技能中繼資料:
- 按一下「Edit」(編輯)。
- 在「Edit skill」(編輯技能) 面板中,更新技能的顯示名稱或說明。
- 按一下「儲存」。
更新預設修訂版本:
- 找出「版本記錄」表格。
- 找出要設為使用中的修訂版本。
- 在「動作」欄中,按一下「啟用版本」。
gcloud
如要更新技能的中繼資料,請使用
gcloud agent-registry skills update指令:gcloud agent-registry skills update SKILL_ID \ --project=PROJECT_ID \ --location=LOCATION \ --display-name="DISPLAY_NAME" \ --description="DESCRIPTION"如要更新技能的預設服務修訂版本,請使用
gcloud agent-registry skills update指令,並指定目標修訂版本的資源名稱:gcloud agent-registry skills update SKILL_ID \ --project=PROJECT_ID \ --location=LOCATION \ --default-revision="projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID"
更改下列內容:
SKILL_ID:要更新的技能 ID。如果是手動註冊的技能,請加入private-前置字元,例如private-my-skill。PROJECT_ID:專案 ID。LOCATION:登錄檔位置。DISPLAY_NAME:更新後的顯示名稱。DESCRIPTION:更新後的說明。REVISION_ID:要設為預設值的技能修訂版本 ID。
REST
傳送 PATCH 要求,並指定要更新的欄位:
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{
"displayName": "DISPLAY_NAME",
"description": "DESCRIPTION",
"defaultRevision": "projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID"
}' \
"https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID?updateMask=displayName,description,defaultRevision"
更改下列內容:
DISPLAY_NAME:技能的更新顯示名稱。DESCRIPTION:技能的更新說明。PROJECT_ID:專案 ID。LOCATION:登錄檔位置。SKILL_ID:要更新的技能 ID。如果是手動註冊的技能,請加入private-前置字元,例如private-my-skill。REVISION_ID:要啟用的技能修訂版本 ID。
管理技能生命週期狀態
如要控管技能在執行階段的提供方式,您可以變更技能的目標狀態,以便轉換生命週期。
如要轉換技能的生命週期狀態,請按照下列步驟操作:
控制台
- 前往 Google Cloud 控制台的「Agent Registry」頁面:
- 選取「技能」分頁標籤。
- 查看技能清單。您可以使用「Location」(位置) 或「Status」(狀態) 選單篩選顯示內容。
- 按一下任何技能名稱,即可開啟「Skill Details」(技能詳細資料) 頁面,其中會顯示名稱、說明、有效版本、技能 ID、上次更新時間、自訂中繼資料和修訂版本記錄。
- 使用狀態控制按鈕轉換目標狀態。頁面顯示的按鈕取決於技能目前的狀態,例如「啟用」、「停用」、「淘汰」或「停用」。
gcloud
使用 gcloud agent-registry skills update 指令和 --target-state 旗標更新技能容器:
gcloud agent-registry skills update SKILL_ID \
--project=PROJECT_ID \
--location=LOCATION \
--target-state=DISABLED
更改下列內容:
SKILL_ID:要更新的技能 ID。如果是手動註冊的技能,請加入private-前置字元,例如private-my-skill。PROJECT_ID:專案 ID。LOCATION:登錄檔位置。
目標狀態的允許值如下:
DRAFTACTIVEDISABLEDDEPRECATEDDECOMMISSIONED
REST
傳送 PATCH 要求,並在主體和更新遮罩中指定 targetState:
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{
"targetState": "TARGET_STATE_DISABLED"
}' \
"https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID?updateMask=targetState"
更改下列內容:
PROJECT_ID:專案 ID。LOCATION:登錄檔位置。SKILL_ID:要更新的技能 ID。如果是手動註冊的技能,請加入private-前置字元,例如private-my-skill。
目標狀態的允許值如下:
TARGET_STATE_DRAFTTARGET_STATE_ACTIVETARGET_STATE_DISABLEDTARGET_STATE_DEPRECATEDTARGET_STATE_DECOMMISSIONED
管理技能存取權
註冊技能時,Agent Registry 會自動在 Skill 資源上設定資源層級 IAM 許可政策,授予主體 Agent Registry API 管理員 (roles/agentregistry.admin) 角色。如果專案屬於組織,Agent Registry 也會將 Agent Registry API 檢視者 (roles/agentregistry.viewer) 角色授予專案中的代理工作負載。
如要與其他使用者、群組、服務帳戶或代理身分共用技能,但不想授予專案層級存取權,可以管理 Skill 資源的資源層級 IAM 政策。舉例來說,您可以授予 Agent Registry API 檢視者角色,讓主體查看、搜尋及下載技能,或授予 Agent Registry API 編輯者角色,讓主體更新技能及上傳新修訂版本。您也可以在專案層級的 IAM 繫結上設定 IAM 條件,限制特定 Skill 和 SkillRevision 資源的存取權。
如要查看或更新技能的 IAM 政策,請按照下列步驟操作:
gcloud
如要查看技能目前的 IAM 政策,請執行
gcloud agent-registry skills get-iam-policy指令:gcloud agent-registry skills get-iam-policy SKILL_ID \ --project=PROJECT_ID \ --location=LOCATION如要將技能角色授予主體,請執行
gcloud agent-registry skills add-iam-policy-binding指令:gcloud agent-registry skills add-iam-policy-binding SKILL_ID \ --project=PROJECT_ID \ --location=LOCATION \ --member="PRINCIPAL" \ --role="ROLE"如要撤銷主體的技能角色,請執行
gcloud agent-registry skills remove-iam-policy-binding指令:gcloud agent-registry skills remove-iam-policy-binding SKILL_ID \ --project=PROJECT_ID \ --location=LOCATION \ --member="PRINCIPAL" \ --role="ROLE"如要使用本機 JSON 或 YAML 政策檔案,取代技能的 IAM 政策,請執行
gcloud agent-registry skills set-iam-policy指令:gcloud agent-registry skills set-iam-policy SKILL_ID POLICY_FILE \ --project=PROJECT_ID \ --location=LOCATION
更改下列內容:
SKILL_ID:技能 ID,包括private-前置字串,例如private-my-skill。PROJECT_ID:專案 ID。LOCATION:登錄檔位置。PRINCIPAL:主體 ID,例如user:user@example.com或serviceAccount:my-sa@example-project.iam.gserviceaccount.com。ROLE:要授予或撤銷的代理程式登錄檔角色,例如roles/agentregistry.viewer或roles/agentregistry.editor。POLICY_FILE:JSON 或 YAML 檔案的路徑,其中包含 IAM 政策定義。
REST
如要擷取技能目前的 IAM 政策,請向
skills:getIamPolicy端點傳送GET要求:curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID:getIamPolicy"如要更新技能的 IAM 政策,請將
POST要求傳送至skills:setIamPolicy端點,並附上現有政策的etag:curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -d '{ "policy": { "bindings": [ { "role": "ROLE", "members": [ "PRINCIPAL" ] } ], "etag": "ETAG" } }' \ "https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID:setIamPolicy"
更改下列內容:
PROJECT_ID:專案 ID。LOCATION:登錄檔位置。SKILL_ID:技能 ID,包括private-前置字串,例如private-my-skill。ROLE:要授予的 Agent Registry 角色,例如roles/agentregistry.viewer或roles/agentregistry.editor。PRINCIPAL:主體 ID,例如user:user@example.com或serviceAccount:my-sa@example-project.iam.gserviceaccount.com。ETAG:skills:getIamPolicy傳回的etag字串。
刪除技能
刪除技能容器會永久刪除 Skill 資源,以及所有相關聯的不可變更 SkillRevision 資源。如果代理嘗試解析已刪除的技能 ID,會在執行階段失敗。
控制台
- 前往 Google Cloud 控制台的「Agent Registry」頁面:
- 選取「技能」分頁標籤。
- 查看技能清單。您可以使用「Location」(位置) 或「Status」(狀態) 選單篩選顯示內容。
- 按一下要刪除的技能名稱。
- 在「Skill Details」頁面中,按一下 「Delete」。
- 在確認對話方塊中輸入
DELETE,然後按一下「Delete」(刪除)。
gcloud
如要刪除技能,請使用 gcloud agent-registry skills delete 指令:
gcloud agent-registry skills delete SKILL_ID \
--project=PROJECT_ID \
--location=LOCATION
更改下列內容:
SKILL_ID:要刪除的技能 ID。如果是手動註冊的技能,請加入private-前置字元,例如private-my-skill。PROJECT_ID:專案 ID。LOCATION:登錄檔位置。
REST
如要刪除技能,請傳送 DELETE 要求:
curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID?force=true"
更改下列內容:
PROJECT_ID:專案 ID。LOCATION:登錄檔位置。SKILL_ID:要刪除的技能 ID。如果是手動註冊的技能,請加入private-前置字元,例如private-my-skill。
後續步驟
- 瞭解如何上傳新修訂版本及下載套件。
- 瞭解如何掃描技能,找出安全性問題。
- 瞭解管理技能的角色和權限。