註冊技能

在 Agent Registry 中，技能代表代理程式可執行的獨立功能。其中包含 SKILL.md 檔案中的操作說明、程式碼指令碼，以及擴充代理程式推論能力的資產。在 Agent Registry 中註冊獨立技能，即可集中管理、版本化及分享整個機構 AI 代理的功能。

設定 Agent Registry 後，系統會立即顯示 Google 建立的技能。本文說明如何在 Agent Registry 中手動註冊自己的獨立技能。

事前準備

開始之前，請先設定代理程式登錄。您需要專案 ID 才能執行這些工作。

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

必要的角色

如要取得在 Agent Registry 中註冊技能所需的權限，請要求管理員授予您專案的「Agent Registry 使用者」 (roles/agentregistry.user) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

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

擷取酬載限制

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

  • ZIP 壓縮檔大小：壓縮檔大小上限為 500 KB。
  • 未壓縮酬載總大小：未壓縮大小上限為 10 MB。
  • 個別檔案大小：每個檔案的未壓縮大小上限為 1 MB。
  • 巢狀結構深度：目錄巢狀結構深度上限為 8 層。
  • 規格相容性：SKILL.md 檔案必須包含有效的 YAML 前置事項部分，定義名稱、說明和中繼資料，如代理程式技能規格中所定義。

註冊技能

設定 Agent Registry 後，系統會立即顯示 Google 建立的技能。不過，您也可以手動註冊自己的技能。每個技能都有預設修訂版本，且可包含多個版本化的技能修訂版本。

如要註冊自己的技能，請建立邏輯技能容器，並在單一作業中上傳初始修訂版本酬載。之後，您可以管理已註冊的技能，以及後續的技能修訂內容。

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

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

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

控制台

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

    前往 Agent Registry

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

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

  4. 在「技能」分頁中，「新增技能」按鈕會顯示兩個選項。你可以選擇下列其中一種做法：

    • 新增技能：在登錄檔中建立新的技能容器。您也可以上傳技能套件，建立第一個修訂版本。
    • 匯入技能：上傳內含程式碼或提示詞指令 (SKILL.md) 檔案的 ZIP 套件，即可匯入新的自訂技能套件。

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

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

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

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

    • 值區：以 gs://BUCKET_NAME/SKILL_PACKAGE.zip 格式輸入儲存在 Cloud Storage 值區中的 ZIP 封存檔路徑。

  7. 點選「建立」。

技能已建立。在後續所有技能作業中，請將技能稱為 private-SKILL_ID，如Google Cloud 控制台所示。

gcloud

如要註冊技能並上傳初始酬載，您可以上傳本機 ZIP 檔，或匯入儲存在 Cloud Storage 中的套件。

更改下列內容：

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

  • DESCRIPTION：簡短摘要，說明技能功能。

  • 上傳本機 ZIP 檔案：如要使用本機 ZIP 酬載註冊技能，請按照下列步驟操作：

    gcloud alpha agent-registry skills create SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --display-name="DISPLAY_NAME" \
  --description="DESCRIPTION" \
  --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" \
  --gcs-source-uri="gs://BUCKET_NAME/SKILL_PACKAGE.zip"

    更改下列內容：

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

REST

如要建立技能並內嵌初始修訂版本，請按照下列步驟操作：

HTTP 方法和網址

POST https://agentregistry.googleapis.com/v1alpha/projects/{project}/locations/{location}/skills?skillId={skillId}

JSON 要求內文 (上傳本機檔案)

如要直接上傳本機 ZIP 封存位元組來建立技能，請使用 archiveUploadSource 酬載：

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

將 BASE64_ZIP_BYTES 替換為本機 ZIP 封存檔的 base64 編碼字串表示法。

JSON 要求內文 (從 Cloud Storage 匯入)

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

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

更改下列內容：

  • 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_ACTIVE",
        "initialRevision": {
          "archiveUploadSource": {
            "archiveContent": "$(base64 -w0 local_skill.zip)"
          }
        }
      }' \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills?skillId=SKILL_ID"

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

後續步驟