管理技能

Agent Registry 可讓您檢查、更新及管理獨立技能,控管代理可使用的技能版本和生命週期狀態。註冊獨立技能後,您可以查看詳細資料、更新說明或預設修訂版本、轉換生命週期狀態、管理資源層級存取權政策,或從代理程式註冊資料庫中刪除。您也可以列出及查看 Google 代管技能,設定代理登錄檔後即可使用。

事前準備

  1. 設定 Agent Registry。
  2. 如果是單一專案設定,請取得已啟用 Agent Registry 的管理專案 ID。如果您為多個專案設定了管理邊界,請使用管理專案的 ID 進行邊界範圍的探索和註冊,或指定成員專案 ID 進行單一專案作業。

  3. 註冊獨立技能。

  4. 如要使用本文件中的 Google Cloud CLI 指令,請設定 gcloud CLI 環境。

必要的角色

如要取得在 Agent Registry 管理技能所需的權限,請要求管理員在已啟用 Agent Registry 的管理專案中,授予您下列 IAM 角色:

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

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

其他 Agent Registry 角色也可能包含查看、更新和刪除技能所需的權限。詳情請參閱「Agent Registry 角色和權限」。

列出及查看技能

您可以瀏覽所有已註冊的技能,或搜尋特定功能:

控制台

  1. 前往 Google Cloud 控制台的「Agent Registry」頁面:

    前往 Agent Registry

  2. 選取「技能」分頁標籤。
  3. 查看技能清單。您可以使用「Location」(位置) 或「Status」(狀態) 選單篩選顯示內容。
  4. 按一下任何技能名稱,即可開啟「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。啟用或更新技能掃描功能後,系統只會掃描變更後建立的版本,不會回溯掃描現有版本。詳情請參閱「掃描技能中的安全性問題」。如要建立新的技能修訂版本,請參閱「管理技能修訂版本」。

如要更新技能中繼資料或特定技能的預設修訂版本,請按照下列步驟操作:

控制台

  1. 前往 Google Cloud 控制台的「Agent Registry」頁面:

    前往 Agent Registry

  2. 選取「技能」分頁標籤。
  3. 查看技能清單。您可以使用「Location」(位置) 或「Status」(狀態) 選單篩選顯示內容。
  4. 按一下任何技能名稱,即可開啟「Skill Details」(技能詳細資料) 頁面,其中會顯示名稱、說明、有效版本、技能 ID、上次更新時間、自訂中繼資料和修訂版本記錄。
  5. 選擇下列其中一個選項:

    • 更新技能中繼資料:

      1. 按一下「Edit」(編輯)。
      2. 在「Edit skill」(編輯技能) 面板中,更新技能的顯示名稱或說明。
      3. 按一下「儲存」。
    • 更新預設修訂版本:

      1. 找出「版本記錄」表格。
      2. 找出要設為使用中的修訂版本。
      3. 在「動作」欄中,按一下「啟用版本」。

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。

管理技能生命週期狀態

如要控管技能在執行階段的提供方式,您可以變更技能的目標狀態,以便轉換生命週期。

如要轉換技能的生命週期狀態,請按照下列步驟操作:

控制台

  1. 前往 Google Cloud 控制台的「Agent Registry」頁面:

    前往 Agent Registry

  2. 選取「技能」分頁標籤。
  3. 查看技能清單。您可以使用「Location」(位置) 或「Status」(狀態) 選單篩選顯示內容。
  4. 按一下任何技能名稱,即可開啟「Skill Details」(技能詳細資料) 頁面,其中會顯示名稱、說明、有效版本、技能 ID、上次更新時間、自訂中繼資料和修訂版本記錄。
  5. 使用狀態控制按鈕轉換目標狀態。頁面顯示的按鈕取決於技能目前的狀態,例如「啟用」、「停用」、「淘汰」或「停用」。

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:登錄檔位置。

目標狀態的允許值如下:

  • DRAFT
  • ACTIVE
  • DISABLED
  • DEPRECATED
  • DECOMMISSIONED

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_DRAFT
  • TARGET_STATE_ACTIVE
  • TARGET_STATE_DISABLED
  • TARGET_STATE_DEPRECATED
  • TARGET_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,會在執行階段失敗。

控制台

  1. 前往 Google Cloud 控制台的「Agent Registry」頁面:

    前往 Agent Registry

  2. 選取「技能」分頁標籤。
  3. 查看技能清單。您可以使用「Location」(位置) 或「Status」(狀態) 選單篩選顯示內容。
  4. 按一下要刪除的技能名稱。
  5. 在「Skill Details」頁面中,按一下 「Delete」。
  6. 在確認對話方塊中輸入 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。

後續步驟