註冊技能

您可以使用 Agent Registry 封裝及手動註冊獨立技能。獨立技能會將代理指令與相關聯的中繼資料資產和選用指令碼組合在一起，藉此擴充代理的推論和工作流程。在 Agent Registry 註冊獨立技能後，您就能集中管理、建立版本及共用可重複使用的功能，以及設定 Agent Registry 時可用的 Google 代管技能。

事前準備

  1. 設定 Agent Registry。

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

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

必要的角色

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

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

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

其他代理程式註冊資料庫角色可能也包含註冊及管理技能和技能修訂版本所需的權限。詳情請參閱「Agent Registry 角色和權限」。

擷取酬載限制

如要註冊技能，您必須將技能的來源檔案封裝成 ZIP 封存檔。封存檔的根目錄必須包含 SKILL.md 指令檔案。在技能註冊程序的擷取階段，Agent Registry 會驗證酬載是否符合下列限制：

  • ZIP 封存檔大小：壓縮封存檔大小上限為 500 KB。
  • 未壓縮酬載總大小：未壓縮大小上限為 10 MB。
  • 個別檔案大小：每個檔案未壓縮的大小上限為 1 MB。
  • 深層巢狀結構：目錄巢狀結構深度上限為 8 層。
  • 符合規格：SKILL.md 檔案必須包含有效的 YAML front matter 區段，定義代理技能規格中定義的名稱、說明和中繼資料。

註冊技能

您可以在 Agent Registry 手動註冊自己的技能。如要瞭解技能的定價和功能費用，請參閱「Agent Registry 定價」。

如要註冊技能，請按照下列步驟操作：

控制台

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

    前往 Agent Registry

  2. 在專案挑選器中，選取 Google Cloud 專案。

  3. 選取「技能」分頁標籤。

  4. 在「Skills」分頁中，「Add skill」按鈕會顯示兩個選項，可建立技能容器並匯入初始技能套件。請選擇下列其中一項：

    • 新增技能：在儲存庫建立新的技能容器。您也可以上傳技能套件，建立第一個修訂版本。
    • 匯入技能：上傳內含 SKILL.md 指令檔案和選用指令碼的 ZIP 套件，註冊新的自訂技能套件。

  5. 在「Create skill」(建立技能) 或「Import skill」(匯入技能) 面板中，指定下列詳細資料：

    • 顯示名稱：輸入容易使用的技能名稱。
    • 說明：輸入簡短摘要，說明技能功能。
    • 位置：選取地理區域，例如 global、us 或 eu。

  6. 在「Payload source」(酬載來源) 部分，選擇下列其中一項：

    • File：拖曳封裝的技能 ZIP 檔案，或瀏覽本機目錄。

    • 「Bucket」：輸入儲存在 Cloud Storage bucket 中的 ZIP 封存檔路徑，格式為 gs://BUCKET_NAME/SKILL_PACKAGE.zip。

  7. 點選「建立」。

    建立的技能會處於「已停用」 (DISABLED) 狀態。對於所有後續技能作業，請參照Google Cloud 控制台顯示的技能名稱private-SKILL_ID。

  8. 如要讓代理探索技能，請設定預設修訂版本，並將目標狀態更新為「Active」。如需操作說明，請參閱「管理技能生命週期狀態」。

gcloud

  1. 使用 gcloud alpha agent-registry skills create 指令建立技能容器，並上傳初始修訂版本酬載。您可以上傳本機 ZIP 檔案，或匯入儲存在 Cloud Storage 中的套件：

    • 上傳本機 ZIP 檔案：使用本機 ZIP 酬載註冊技能：

      gcloud alpha agent-registry skills create SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --display-name="DISPLAY_NAME" \
    --description="DESCRIPTION" \
    --target-state=disabled \
    --payload="LOCAL_ZIP_PATH"

      將 LOCAL_ZIP_PATH 替換為本機電腦上封裝技能封存檔的路徑，例如 ./workspace-docs-skill.zip。

    • 從 Cloud Storage bucket 匯入：使用託管於 Cloud Storage bucket 的 ZIP 封存檔註冊技能：

      gcloud alpha agent-registry skills create SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --display-name="DISPLAY_NAME" \
    --description="DESCRIPTION" \
    --target-state=disabled \
    --gcs-source-uri="gs://BUCKET_NAME/SKILL_PACKAGE.zip"

      更改下列內容：

      • BUCKET_NAME：包含 ZIP 組合的 Cloud Storage bucket 名稱。
      • SKILL_PACKAGE：包含技能酬載的技能套件名稱。

    在任一指令中替換下列項目：

    • SKILL_ID：技能的資源 ID，例如 workspace-docs-skill。建立後，登錄檔會自動在前面加上 private- 前置字串。在後續的所有技能指令中，您必須使用加上前置字元的 ID，例如 private-workspace-docs-skill。
    • PROJECT_ID：專案 ID。
    • LOCATION：地理區域，例如 global、us 或 eu。
    • DISPLAY_NAME：容易使用的技能名稱。
    • DESCRIPTION：簡短摘要，說明技能功能。

  2. 新建立的技能一開始會處於「已停用」 (DISABLED) 狀態。如要讓代理探索技能，請設定預設修訂版本，並將目標狀態更新為「有效」。如需操作說明，請參閱「管理技能生命週期狀態」。

REST

  1. 建立技能容器，並內嵌初始修訂版本：

    HTTP 方法和網址

    POST https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills?skillId=SKILL_ID

    更改下列內容：

    • PROJECT_ID：專案 ID。
    • LOCATION：登錄檔位置。
    • SKILL_ID：技能容器的專屬 ID。

    JSON 要求主體 (上傳本機檔案)

    如要直接上傳本機 ZIP 封存檔位元組來建立技能，請使用 archiveUploadSource 酬載。建立時，targetState 必須設為 TARGET_STATE_DISABLED：

    {
  "displayName": "DISPLAY_NAME",
  "description": "DESCRIPTION",
  "type": "SIMPLE",
  "targetState": "TARGET_STATE_DISABLED",
  "initialRevision": {
    "archiveUploadSource": {
      "archiveContent": "BASE64_ZIP_BYTES"
    }
  }
}

    更改下列內容：

    • DISPLAY_NAME：容易使用的技能名稱。
    • DESCRIPTION：簡短摘要，說明技能功能。
    • BASE64_ZIP_BYTES：本機 ZIP 封存檔的 base64 編碼字串表示法。

    JSON 要求主體 (從 Cloud Storage 匯入)

    或者，如要使用儲存在 Cloud Storage bucket 中的封存檔建立技能，請使用 gcsSource：

    {
  "displayName": "DISPLAY_NAME",
  "description": "DESCRIPTION",
  "type": "SIMPLE",
  "targetState": "TARGET_STATE_DISABLED",
  "initialRevision": {
    "gcsSource": {
      "uri": "gs://BUCKET_NAME/SKILL_PACKAGE.zip"
    }
  }
}

    更改下列內容：

    • DISPLAY_NAME：容易使用的技能名稱。
    • DESCRIPTION：簡短摘要，說明技能功能。
    • BUCKET_NAME：包含 ZIP 組合的 Cloud Storage bucket 名稱。
    • SKILL_PACKAGE：包含技能酬載的技能套件名稱。

    curl 指令 (上傳本機檔案)

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
      "displayName": "DISPLAY_NAME",
      "description": "DESCRIPTION",
      "type": "SIMPLE",
      "targetState": "TARGET_STATE_DISABLED",
      "initialRevision": {
        "archiveUploadSource": {
          "archiveContent": "'"$(base64 -w0 local_skill.zip)"'"
        }
      }
    }' \
    "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills?skillId=SKILL_ID"

    更改下列內容：

    • DISPLAY_NAME：容易使用的技能名稱。
    • DESCRIPTION：簡短摘要，說明技能功能。
    • PROJECT_ID：專案 ID。
    • LOCATION：登錄檔位置。
    • SKILL_ID：技能容器的專屬 ID。

    如要上傳 Cloud Storage bucket 檔案，請將要求 JSON 主體替換為對應的欄位和值。

  2. 新建立的技能一開始會處於「已停用」 (DISABLED) 狀態。如要讓代理探索技能，請設定預設修訂版本，並將目標狀態更新為「有效」。如需操作說明，請參閱「管理技能生命週期狀態」。

您或其他使用者建立的技能會自動指派給預設的 private 發布者，避免與 Google 代管技能名稱衝突。因此，特定技能的發布 ID 會變成 private-SKILL_ID。建立技能時，無法指定自訂發布者。

舉例來說，如果您建立 ID 為 workspace-tools 的技能，系統會建立資源名稱 projects/PROJECT_NUMBER/locations/LOCATION/skills/private-workspace-tools。技能 ID 會指派為 urn:skill:projects-PROJECT_NUMBER:locations:LOCATION:private-workspace-tools。所有後續技能作業都必須使用 private-workspace-tools 發布商 ID。

後續步驟