建立及管理代理程式

本指南說明如何使用 Agent Platform 上的 Managed Agents API，建立、擷取、列出、更新及刪除自訂代理資源，以及如何設定代理環境、Model Context Protocol (MCP) 伺服器工具和技能。

事前準備

設定代理程式前，請先設定環境：

  1. 登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎 建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Agent Platform API.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  5. Make sure that you have the following role or roles on the project: Agent Platform User (roles/aiplatform.user) or Agent Platform Administrator (roles/aiplatform.admin)

    Check for the roles

    1. In the Google Cloud console, go to the IAM page.

      Go to IAM
    2. Select the project.

    3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

    4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

    Grant the roles

    1. In the Google Cloud console, go to the IAM page.

      Go to IAM
    2. Select the project.
    3. Click Grant access.

    4. In the New principals field, enter your user identifier. This is typically the email address for a Google Account.

    5. Click Select a role, then search for the role.
    6. To grant additional roles, click Add another role and add each additional role.
    7. Click Save.

  6. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  7. Verify that billing is enabled for your Google Cloud project.

  8. Enable the Agent Platform API.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  9. Make sure that you have the following role or roles on the project: Agent Platform User (roles/aiplatform.user) or Agent Platform Administrator (roles/aiplatform.admin)

    Check for the roles

    1. In the Google Cloud console, go to the IAM page.

      Go to IAM
    2. Select the project.

    3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

    4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

    Grant the roles

    1. In the Google Cloud console, go to the IAM page.

      Go to IAM
    2. Select the project.
    3. Click Grant access.

    4. In the New principals field, enter your user identifier. This is typically the email address for a Google Account.

    5. Click Select a role, then search for the role.
    6. To grant additional roles, click Add another role and add each additional role.
    7. Click Save.
  10. 如果打算搭配代理程式使用 Google Cloud Model Context Protocol (MCP) 工具，請將 MCP 工具使用者 (roles/mcp.toolUser) 角色授予使用者帳戶和相關聯的服務帳戶。

建立虛擬服務專員

如要建立新的自訂代理程式，請使用 CreateAgent 方法。這是長時間執行的作業。

基礎代理程式

base_agent 是核心自動化調度管理工具，可為代理提供推論能力，並存取執行環境。這項工具可將技能和程式庫插入環境，並存取服務端工具，以執行程式碼、進行檔案系統作業，以及採用基準搜尋。

建立代理程式時，base_agent 僅支援一個值：antigravity-preview-05-2026。

建立基本虛擬服務專員

如要使用預設工具和 Google Cloud Storage 掛接目標建立基本代理程式，請傳送 POST 要求：

REST

要求變數

呼叫 API 之前，請先替換下列項目：

  • PROJECT_ID： Google Cloud 專案 ID。
  • LOCATION：代理程式的區域位置。僅支援 global 地區。

  • AGENT_ID：新代理程式的專屬自訂 ID。自訂代理程式 ID 必須遵守下列限制：

    • 長度必須介於 1 至 63 個字元之間。
    • 只能使用小寫英文字母、數字和連字號。
    • 開頭須為英文字母，結尾則須為英文字母或數字。

  • BASE_AGENT：要擴充的基礎代理程式名稱。使用 antigravity-preview-05-2026。

  • AGENT_DESCRIPTION：代理程式範圍的簡短摘要。

  • INSTRUCTIONS：要在代理程式上設定的系統指令或角色。

  • GCS_BUCKET：已掛接 Google Cloud Storage 值區的資料夾路徑區隔 (例如 gs://cymbal-bucket-name)。 注意：如要掛接其他專案的值區，請將該值區的 read 和 write 存取權授予專案的服務帳戶。

  • network：基於安全性考量，環境中的網路存取權已關閉。您必須指定 allowlist 才能啟用存取權。在 allowlist 中使用 * 做為網域，可允許連線至所有網域，提供不受限制的網路存取權。

HTTP 方法和網址

POST https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents

JSON 要求內文

{
  "id": "AGENT_ID",
  "base_agent": "BASE_AGENT",
  "description": "AGENT_DESCRIPTION",
  "system_instruction": "INSTRUCTIONS",
  "tools": [
    {"type": "code_execution"},
    {"type": "filesystem"},
    {"type": "google_search"},
    {"type": "url_context"}
  ],
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "gcs",
        "source": "GCS_BUCKET",
        "target": "/.agent"
      }
    ],
    "network": {
      "allowlist": [
        { "domain": "*" }
      ]
    }
  }
}

curl 指令

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{
      "id": "AGENT_ID",
      "base_agent": "antigravity-preview-05-2026",
      "description": "AGENT_DESCRIPTION",
      "system_instruction": "INSTRUCTIONS",
      "tools": [
          {"type": "code_execution"},
          {"type": "filesystem"},
          {"type": "google_search"},
          {"type": "url_context"}
      ],
      "base_environment": {
          "type": "remote",
          "sources": [
              {
                  "type": "gcs",
                  "source": "GCS_BUCKET",
                  "target": "/.agent"
              }
          ],
          "network": {
              "allowlist": [
                  { "domain": "*" }
              ]
          }
      }
  }'

回覆範例

{
  "name": "projects/1234567890/locations/global/agents/my-first-agent/operations/234567890123",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1beta1.CreateAgentOperationMetadata",
    "genericMetadata": {
      "createTime": "2026-05-12T23:50:16.933752Z",
      "updateTime": "2026-05-12T23:50:16.933752Z"
    }
  }
}

Python

執行這段程式碼前，請先設定「REST」分頁中說明的變數。

from google import genai

client = genai.Client(
    vertexai=True,
    project="PROJECT_ID",
    location="global",
)

agent = client.agents.create(
    id="AGENT_ID",
    base_agent="antigravity-preview-05-2026",
    description="AGENT_DESCRIPTION",
    system_instruction="INSTRUCTIONS",
    tools=[
        {"type": "code_execution"},
        {"type": "google_search"},
        {"type": "url_context"},
    ],
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "gcs",
                "source": "GCS_BUCKET",
                "target": "/.agent",
            }
        ],
        "network": {
            "allowlist": [{"domain": "*"}]
        },
    },
)

JavaScript

執行這段程式碼前，請先設定「REST」分頁中說明的變數。

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({
    vertexai: true,
    project: "PROJECT_ID",
    location: "global",
});

const agent = await client.agents.create({
    id: "AGENT_ID",
    base_agent: "antigravity-preview-05-2026",
    description: "AGENT_DESCRIPTION",
    system_instruction: "INSTRUCTIONS",
    tools: [
        { type: "code_execution" },
        { type: "google_search" },
        { type: "url_context" },
    ],
    base_environment: {
        type: "remote",
        sources: [
            {
                type: "gcs",
                source: "GCS_BUCKET",
                target: "/.agent",
            },
        ],
        network: {
            allowlist: [{ domain: "*" }],
        },
    },
});

使用 Google 第一方工具建立代理

如要使用 Google 第一方工具 (例如「透過 Google 搜尋和網址脈絡進行基礎訓練」) 建立代理程式，請將這些工具新增至代理程式設定中的 tools 清單：

REST

要求變數

呼叫 API 之前，請先替換下列項目：

  • PROJECT_ID： Google Cloud 專案 ID。
  • LOCATION：代理程式的區域位置。僅支援 global 地區。

  • AGENT_ID：新代理程式的專屬自訂 ID。自訂代理程式 ID 必須遵守下列限制：

    • 長度必須介於 1 至 63 個字元之間。
    • 只能使用小寫英文字母、數字和連字號。
    • 開頭須為英文字母，結尾則須為英文字母或數字。

  • AGENT_DESCRIPTION：代理程式範圍的簡短摘要。

JSON 要求內文

{
  "id": "AGENT_ID",
  "base_agent": "antigravity-preview-05-2026",
  "description": "AGENT_DESCRIPTION",
  "tools": [
    {
      "type": "google_search"
    },
    {
      "type": "url_context"
    }
  ],
  "base_environment": {
    "type": "remote",
    "network": {
      "allowlist": [
        { "domain": "*" }
      ]
    }
  }
}

curl 指令

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{
      "id": "AGENT_ID",
      "base_agent": "antigravity-preview-05-2026",
      "description": "AGENT_DESCRIPTION",
      "tools": [
          {
              "type": "google_search"
          },
          {
              "type": "url_context"
          }
      ],
      "base_environment": {
          "type": "remote",
          "network": {
              "allowlist": [
                  { "domain": "*" }
              ]
          }
      }
  }'

使用 MCP 設定建立代理

您可以使用 Agent Platform 的 Managed Agents API，建立具備預先設定 MCP 伺服器工具的代理。

事前準備

建立具備預先設定 MCP 伺服器工具的代理前，請先完成下列工作：

  • 將「MCP 工具使用者」 (roles/mcp.toolUser) Identity and Access Management (IAM) 角色授予使用者帳戶和相關聯的服務帳戶。

  • 確認設定中的 MCP 伺服器透過標準 HTTP POST 通訊協定，進行工具刊登和執行作業。Agent Platform 的 Managed Agents API 需要可串流的 HTTP 伺服器做為遠端 MCP 伺服器。MCP 伺服器必須實作 MCP 可串流 HTTP 傳輸，其中 tools/list 和 tools/call 會透過 HTTP POST 以 JSON-RPC 形式傳送。

    系統不支援已淘汰的雙端點 HTTP+SSE 傳輸 (獨立的長期 GET /sse 串流)。

授權 Google 代管的 MCP

如果您使用不記名權杖授權 Google 代管的 MCP 伺服器 (例如 BigQuery)，請完成下列步驟：

  1. 新增 OAuth 範圍：將必要的 OAuth 2.0 範圍附加至驗證權杖。舉例來說，如要使用 BigQuery MCP，請在要求中加入相關的 BigQuery 範圍。
  2. 驗證存取權：在 OAuth Playground 中測試授權流程，確認是否能透過新設定的範圍存取 MCP 伺服器。
  3. 使用標頭：如果是 BigQuery 等 Google MCP，您必須在 headers 對應中加入設為專案名稱的 X-Goog-User-Project 標頭。

舉例來說，用來建立使用 BigQuery MCP 的代理程式的要求 JSON 主體，看起來會類似於下列內容：

{
  "name": "projects/<projectname>/locations/global/agents/data-analyst",
  "id": "data-analyst",
  "system_instruction": "You are a data analyst. Use the provided tools and data to perform analysis.",
  "tools": [
    { "type": "code_execution" },
    { "type": "filesystem" },
    { "type": "google_search" },
    { "type": "url_context" },
    {
      "type": "mcp_server",
      "name": "bigquery-mcp",
      "url": "https://mcp-bigquery.googleapis.com/v1",
      "headers": {
        "Authorization": "Bearer ya29.a0AQyyyy",
        "X-Goog-User-Project": "project-nameyyyy"
      }
    }
  ],
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "gcs",
        "source": "gs://agents-1",
        "target": "/.agent/agents-1"
      }
    ],
    "network": {
      "allowlist": [ { "domain": "*" } ]
    }
  },
  "base_agent": "antigravity-preview-05-2026",
  "object": "agent"
}

建立代理

如要建立具備預先設定 MCP 伺服器工具的代理，請在 tools 區段下方新增詳細資料：

REST

要求變數

呼叫 API 之前，請先替換下列項目：

  • PROJECT_ID： Google Cloud 專案 ID。
  • LOCATION：代理程式的區域位置。僅支援 global 地區。

  • AGENT_ID：新代理程式的專屬自訂 ID。自訂代理程式 ID 必須遵守下列限制：

    • 長度必須介於 1 至 63 個字元之間。
    • 只能使用小寫英文字母、數字和連字號。
    • 開頭須為英文字母，結尾則須為英文字母或數字。

  • AGENT_DESCRIPTION：代理程式範圍的簡短摘要。

  • MCP_SERVER_NAME：MCP 工具的說明名稱。

  • MCP_SERVER_URL：MCP 伺服器的遠端 HTTP 閘道網址。

  • MCP_HEADER_KEY：選用。驗證標頭的名稱 (例如 Authorization)。

  • MCP_HEADER_VALUE：選用。驗證不記名權杖 (例如 Bearer <token>)。

JSON 要求內文

{
  "id": "AGENT_ID",
  "base_agent": "antigravity-preview-05-2026",
  "description": "AGENT_DESCRIPTION",
  "tools": [
    {
      "type": "mcp_server",
      "name": "MCP_SERVER_NAME",
      "url": "MCP_SERVER_URL",
      "headers": {
        "MCP_HEADER_KEY": "MCP_HEADER_VALUE"
      }
    }
  ]
}

curl 指令

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{
      "id": "AGENT_ID",
      "base_agent": "antigravity-preview-05-2026",
      "description": "AGENT_DESCRIPTION",
      "tools": [
          {
              "type": "mcp_server",
              "name": "MCP_SERVER_NAME",
              "url": "MCP_SERVER_URL",
              "headers": {
                  "MCP_HEADER_KEY": "MCP_HEADER_VALUE"
              }
          }
      ]
  }'

Python

執行這段程式碼前，請先設定「REST」分頁中說明的變數。

from google import genai

client = genai.Client(
    vertexai=True,
    project="PROJECT_ID",
    location="global",
)

agent = client.agents.create(
    id="AGENT_ID",
    base_agent="antigravity-preview-05-2026",
    description="AGENT_DESCRIPTION",
    tools=[
        {
            "type": "mcp_server",
            "name": "MCP_SERVER_NAME",
            "url": "MCP_SERVER_URL",
            "headers": {
                "MCP_HEADER_KEY": "MCP_HEADER_VALUE"
            },
        }
    ],
)

JavaScript

執行這段程式碼前，請先設定「REST」分頁中說明的變數。

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({
    vertexai: true,
    project: "PROJECT_ID",
    location: "global",
});

const agent = await client.agents.create({
    id: "AGENT_ID",
    base_agent: "antigravity-preview-05-2026",
    description: "AGENT_DESCRIPTION",
    tools: [
        {
            type: "mcp_server",
            name: "MCP_SERVER_NAME",
            url: "MCP_SERVER_URL",
            headers: {
                "MCP_HEADER_KEY": "MCP_HEADER_VALUE",
            },
        },
    ],
});

將技能附加至代理程式

如要在建立代理程式時直接載入可重複使用的技能，請在 base_environment.sources 內掛接該技能。

你可以使用下列任一方法附加技能：

  • 技能登錄：在技能登錄中，附加專案內註冊的技能。

  • Google Cloud Storage：直接從 Cloud Storage bucket 附加自訂技能。

    最佳做法是在環境的 /.agent/skills 資料夾下掛接技能，讓代理程式更容易找到這些技能。

CLI 技能

開發人員也可以在所選的 CLI 中安裝專門技能，以程式輔助方式管理代理程式和互動：

從技能登錄檔附加技能

如要在建立代理程式時直接從技能登錄檔載入可重複使用的技能，請按照下列步驟操作：

REST

要求變數

呼叫 API 之前，請先替換下列項目：

  • PROJECT_ID： Google Cloud 專案 ID。
  • LOCATION：代理程式的區域位置。僅支援 global 區域。
  • AGENT_ID：新代理程式的專屬自訂 ID。自訂代理程式 ID 必須遵守下列限制：
    • 長度必須介於 1 至 63 個字元之間。
    • 只能使用小寫英文字母、數字和連字號。
    • 開頭須為英文字母，結尾則須為英文字母或數字。
  • SKILL_RESOURCE_NAME：要掛接的技能或技能清單的資源路徑。您可以指定下列其中一種格式：
    • 技能 (預設版本)： projects/{projectID}/locations/{location}/skills/{skillName}
    • 特定版本： projects/{projectID}/locations/{location}/skills/{skillName}/skill_versions/{skill_version}
    • 技能清單： projects/{projectID}/locations/{location}/skills。這會將指定 project/location 中的最多 100 項技能掛接到沙箱環境。
    詳情請參閱「列出技能」。
JSON 要求內文
{
  "id": "AGENT_ID",
  "base_agent": "antigravity-preview-05-2026",
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "skill_registry",
        "source": "SKILL_RESOURCE_NAME",
        "target": "/.agent/skills"
      }
    ],
    "network": {
      "allowlist": [
        { "domain": "*" }
      ]
    }
  }
}
curl 指令
curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{
      "id": "AGENT_ID",
      "base_agent": "antigravity-preview-05-2026",
      "base_environment": {
          "type": "remote",
          "sources": [
              {
                  "type": "skill_registry",
                  "source": "SKILL_RESOURCE_NAME",
                  "target": "/.agent/skills"
              }
          ],
          "network": {
              "allowlist": [
                  { "domain": "*" }
              ]
          }
      }
  }'

Python

執行這段程式碼前，請先設定「REST」分頁中說明的變數。

from google import genai

client = genai.Client(
    vertexai=True,
    project="PROJECT_ID",
    location="global",
)

agent = client.agents.create(
    id="AGENT_ID",
    base_agent="antigravity-preview-05-2026",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "skill_registry",
                "source": "SKILL_RESOURCE_NAME",
                "target": "./skills",
            }
        ],
        "network": {
            "allowlist": [{"domain": "*"}]
        },
    },
)

JavaScript

執行這段程式碼前，請先設定「REST」分頁中說明的變數。

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({
    vertexai: true,
    project: "PROJECT_ID",
    location: "global",
});

const agent = await client.agents.create({
    id: "AGENT_ID",
    base_agent: "antigravity-preview-05-2026",
    base_environment: {
        type: "remote",
        sources: [
            {
                type: "skill_registry",
                source: "SKILL_RESOURCE_NAME",
                target: "./skills",
            },
        ],
        network: {
            allowlist: [{ domain: "*" }],
        },
    },
});

從 Google Cloud Storage 附加技能

或者，您也可以在建立代理程式時，直接從 Google Cloud Storage bucket 附加自訂技能。

從 Cloud Storage 掛接技能時，請注意下列規定：

  • 上傳規定：你必須將整個技能資料夾上傳至值區。
  • 不驗證內容：後端不會在掛接前驗證資料夾內容，行為與標準資料夾上傳相同。
  • 大小限制：所有附加檔案都須遵守沙箱環境的記憶體限制 (總共最多 4 GiB 的 RAM)。
  • 最佳做法：如要確保技能品質，請按照 agentskills.io/home 說明的慣例，在技能資料夾中建構及準備檔案。

建立代理程式時，如要從 Google Cloud Storage 附加技能，請按照下列步驟操作：

REST

要求變數

呼叫 API 之前，請先替換下列項目：

  • PROJECT_ID： Google Cloud 專案 ID。
  • LOCATION：代理程式的區域位置。僅支援 global 區域。
  • AGENT_ID：新代理程式的專屬自訂 ID。自訂代理程式 ID 必須遵守下列限制：
    • 長度必須介於 1 至 63 個字元之間。
    • 只能使用小寫英文字母、數字和連字號。
    • 開頭須為英文字母，結尾則須為英文字母或數字。
  • GCS_SOURCE_PATH：包含技能資料夾的 Google Cloud Storage bucket 路徑 (例如 gs://cymbal-bucket-name/my-skill-folder)。
JSON 要求內文
{
  "id": "AGENT_ID",
  "base_agent": "antigravity-preview-05-2026",
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "gcs",
        "source": "GCS_SOURCE_PATH",
        "target": "/.agent/skills"
      }
    ],
    "network": {
      "allowlist": [
        { "domain": "*" }
      ]
    }
  }
}
curl 指令
curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{
      "id": "AGENT_ID",
      "base_agent": "antigravity-preview-05-2026",
      "base_environment": {
          "type": "remote",
          "sources": [
              {
                  "type": "gcs",
                  "source": "GCS_SOURCE_PATH",
                  "target": "./skills"
              }
          ],
          "network": {
              "allowlist": [
                  { "domain": "*" }
              ]
          }
      }
  }'

Python

執行這段程式碼前，請先設定「REST」分頁中說明的變數。

from google import genai

client = genai.Client(
    vertexai=True,
    project="PROJECT_ID",
    location="global",
)

agent = client.agents.create(
    id="AGENT_ID",
    base_agent="antigravity-preview-05-2026",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "gcs",
                "source": "GCS_SOURCE_PATH",
                "target": "./skills",
            }
        ],
        "network": {
            "allowlist": [{"domain": "*"}]
        },
    },
)

JavaScript

執行這段程式碼前，請先設定「REST」分頁中說明的變數。

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({
    vertexai: true,
    project: "PROJECT_ID",
    location: "global",
});

const agent = await client.agents.create({
    id: "AGENT_ID",
    base_agent: "antigravity-preview-05-2026",
    base_environment: {
        type: "remote",
        sources: [
            {
                type: "gcs",
                source: "GCS_SOURCE_PATH",
                target: "./skills",
            },
        ],
        network: {
            allowlist: [{ domain: "*" }],
        },
    },
});

列出代理程式

如要列出專案中所有已儲存的代理程式，請傳送 GET 要求。你可以使用選用的分頁功能，控管每頁的結果數。

REST

要求變數

呼叫 API 之前，請先替換下列項目：

  • PROJECT_ID： Google Cloud 專案 ID。
  • LOCATION：列出代理商的區域位置。僅支援 global 區域。
  • PAGE_SIZE：選用。每頁要傳回的代理數量上限。預設值為 10，最大值為 100。
  • PAGE_TOKEN：選用。屬於接收自前一個 ListAgents 回應的網頁權杖。提供這個權杖即可擷取後續頁面的結果。

如要傳回的代理程式數量大於 PAGE_SIZE，ListAgents 回應會包含 nextPageToken 欄位。如要擷取下一頁的代理程式，請在下一個 ListAgents 要求中，將這個 nextPageToken 的值做為 PAGE_TOKEN 參數傳遞。重複這個程序，直到回應中不再傳回 nextPageToken 欄位為止。

HTTP 方法和網址

GET https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents?page_size=PAGE_SIZE&page_token=PAGE_TOKEN

curl 指令

curl -X GET "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents?page_size=PAGE_SIZE&page_token=PAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"

回覆範例

{
  "agents": [
    {
      "name": "projects/1234567890/locations/global/agents/my-first-agent",
      "id": "my-first-agent",
      "created": "2026-05-12T23:50:16.933Z",
      "updated": "2026-05-12T23:50:21.159Z",
      "systemInstruction": "You are a helpful assistant to user."
    }
  ],
  "nextPageToken": "ABCDEFGHIJKLMNOPQRSTUVWXYZ=="
}

Python

執行這段程式碼前，請先設定「REST」分頁中說明的變數。

from google import genai

client = genai.Client(
    vertexai=True,
    project="PROJECT_ID",
    location="global",
)

response = client.agents.list()

for agent in response.agents:
    print(agent)

JavaScript

執行這段程式碼前，請先設定「REST」分頁中說明的變數。

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({
    vertexai: true,
    project: "PROJECT_ID",
    location: "global",
});

const response = await client.agents.list();

if (response.agents) {
    for (const agent of response.agents) {
        console.log(agent);
    }
}

取得代理程式

如要擷取指定代理程式的完整設定，請使用 GET 要求。

REST

要求變數

呼叫 API 之前，請先替換下列項目：

  • PROJECT_ID： Google Cloud 專案 ID。

  • LOCATION：代理程式的區域位置。僅支援 global 區域。

  • AGENT_ID：您要求的自訂代理程式設定專屬 ID。

HTTP 方法和網址

GET https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID

curl 指令

curl -X GET "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)"

回覆範例

{
  "name": "projects/vertex-agent-fishfood/locations/global/agents/my-first-agent",
  "id": "my-first-agent",
  "created": "2026-05-12T23:50:16.933Z",
  "updated": "2026-05-12T23:50:21.159Z",
  "systemInstruction": "You are a helpful assistant to user.",
  "tools": [
    {"type": "code_execution"},
    {"type": "filesystem"},
    {"type": "google_search"},
    {"type": "url_context"}
  ],
  "description": "A demo agent showcasing Environment and Skills use case.",
  "baseEnvironment": {
    "type": "remote",
    "sources": [
      {
        "type": "gcs",
        "source": "gs://agents-api-sample-skills",
        "target": "/.agent"
      }
    ],
    "network": {
      "allowlist": [
        {"domain": "*"}
      ]
    }
  },
  "baseAgent": "antigravity-preview-05-2026",
  "object": "agent"
}

Python

執行這段程式碼前，請先設定「REST」分頁中說明的變數。

from google import genai

client = genai.Client(
    vertexai=True,
    project="PROJECT_ID",
    location="global",
)

agent = client.agents.get(id="AGENT_ID")
print(agent)

JavaScript

執行這段程式碼前，請先設定「REST」分頁中說明的變數。

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({
    vertexai: true,
    project: "PROJECT_ID",
    location: "global",
});

const agent = await client.agents.get("AGENT_ID");
console.log(agent);

更新代理程式

如要更新現有代理程式的設定，請傳送 PATCH 要求。雖然代理程式的 ID 無法變更，但您可以修改指令、工具和環境變數等參數。使用 update_mask 查詢參數，準確指定要更新的欄位。這麼做可確保只有您要變更的欄位會受到影響，其他設定則會保留。

更新基本虛擬服務專員

如要更新代理程式的系統指令，請使用 update_mask=system_instruction 傳送 PATCH 要求：

REST

要求變數

呼叫 API 之前，請先替換下列項目：

  • PROJECT_ID： Google Cloud 專案 ID。
  • LOCATION：代理程式的區域位置。僅支援 global 區域。
  • AGENT_ID：要修補更新的目標代理程式設定。
  • NEW_INSTRUCTIONS：要取代的更新版說明結構或說明。

HTTP 方法和網址

PATCH https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID?update_mask=system_instruction

JSON 要求內文

{
  "name": "AGENT_ID",
  "system_instruction": "NEW_INSTRUCTIONS"
}

curl 指令

curl -X PATCH "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID?update_mask=system_instruction" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{
      "name": "AGENT_ID",
      "system_instruction": "NEW_INSTRUCTIONS"
  }'

Python

JavaScript

使用 Google 第一方工具更新代理程式

如要更新代理，啟用 Google 第一方 (1P) 工具 (例如以 Google 搜尋強化事實基礎和網址背景資訊)，請傳送 PATCH 要求，並附上 update_mask=tools：

REST

要求變數

呼叫 API 之前，請先替換下列項目：

  • PROJECT_ID： Google Cloud 專案 ID。
  • LOCATION：代理程式的區域位置。僅支援 global 區域。
  • AGENT_ID：目標代理程式 ID。

JSON 要求內文

{
  "name": "AGENT_ID",
  "tools": [
    {
      "type": "google_search"
    },
    {
      "type": "url_context"
    }
  ]
}

curl 指令

curl -X PATCH "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID?update_mask=tools" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{
      "name": "AGENT_ID",
      "tools": [
          {
              "type": "google_search"
          },
          {
              "type": "url_context"
          }
      ]
  }'

更新代理以使用 MCP 設定

如要修改附加至代理的 MCP 工具，請傳送 PATCH 要求並指定下列欄位：update_mask=tools

REST

要求變數

呼叫 API 之前，請先替換下列項目：

  • PROJECT_ID： Google Cloud 專案 ID。
  • LOCATION：代理程式的區域位置。僅支援 global 區域。
  • AGENT_ID：目標代理程式 ID。
  • NEW_MCP_SERVER_NAME：更新後的 MCP 工具標籤。
  • NEW_MCP_SERVER_URL：伺服器的新網址端點參數。
  • NEW_MCP_HEADER_KEY：選用。驗證標頭的名稱 (例如 Authorization)。
  • NEW_MCP_HEADER_VALUE：選用。驗證持有人權杖 (例如 Bearer <token>)。

JSON 要求內文

{
  "name": "AGENT_ID",
  "tools": [
    {
      "type": "mcp_server",
      "name": "NEW_MCP_SERVER_NAME",
      "url": "NEW_MCP_SERVER_URL",
      "headers": {
        "NEW_MCP_HEADER_KEY": "NEW_MCP_HEADER_VALUE"
      }
    }
  ]
}

curl 指令

curl -X PATCH "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID?update_mask=tools" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{
      "name": "AGENT_ID",
      "tools": [
          {
              "type": "mcp_server",
              "name": "NEW_MCP_SERVER_NAME",
              "url": "NEW_MCP_SERVER_URL",
              "headers": {
                  "NEW_MCP_HEADER_KEY": "NEW_MCP_HEADER_VALUE"
              }
          }
      ]
  }'

Python

JavaScript

將技能附加至代理程式

如要在代理程式更新期間，於 base_environment.sources 中附加或修改技能，請使用 update_mask=base_environment 傳送 PATCH 要求。

你可以使用下列任一方法附加技能：

  • 技能登錄：在技能登錄中，附加專案內註冊的技能。

  • Google Cloud Storage：直接從 Cloud Storage bucket 附加自訂技能。

從技能登錄檔附加技能

如要附加在 Skill Registry 註冊的技能，請按照下列步驟操作：

REST

要求變數

呼叫 API 之前，請先替換下列項目：

  • PROJECT_ID： Google Cloud 專案 ID。
  • LOCATION：代理程式的區域位置。僅支援 global 區域。
  • AGENT_ID：目標代理程式 ID。
  • NEW_SKILL_RESOURCE_NAME：要掛接的技能或技能清單的資源路徑。您可以指定下列其中一種格式：
    • 技能 (預設版本)： projects/{projectID}/locations/{location}/skills/{skillName}
    • 技能版本 (釘選至特定版本)： projects/{projectID}/locations/{location}/skills/{skillName}/skill_versions/{skill_version}
    • ListSkills (掛接所有技能)： projects/{projectID}/locations/{location}/skills。這會在專案/位置資訊中掛接最多 100 項技能至沙箱環境。
    如要進一步瞭解如何找出 NEW_SKILL_RESOURCE_NAME 的 name 值，請參閱「列出技能」。
JSON 要求內文
{
  "name": "AGENT_ID",
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "skill_registry",
        "source": "NEW_SKILL_RESOURCE_NAME",
        "target": "/.agent/skills"
      }
    ],
    "network": {
      "allowlist": [
        { "domain": "*" }
      ]
    }
  }
}
curl 指令
curl -X PATCH "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID?update_mask=base_environment" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{
      "name": "AGENT_ID",
      "base_environment": {
          "type": "remote",
          "sources": [
              {
                  "type": "skill_registry",
                  "source": "NEW_SKILL_RESOURCE_NAME",
                  "target": "/.agent/skills"
              }
          ],
          "network": {
              "allowlist": [
                  { "domain": "*" }
              ]
          }
      }
  }'

Python

JavaScript

從 Google Cloud Storage 附加技能

或者，您也可以在建立代理程式時，直接從 Google Cloud Storage bucket 附加自訂技能。

從 Cloud Storage 掛接技能時，請注意下列規定：

  • 上傳規定：你必須將整個技能資料夾上傳至值區。
  • 不驗證內容：後端不會在掛接前驗證資料夾內容，行為與標準資料夾上傳相同。
  • 大小限制：所有附加檔案都須遵守沙箱環境的記憶體限制 (總共最多 4 GiB 的 RAM)。
  • 最佳做法：為確保技能品質，請按照 agentskills.io/home 說明的慣例，在技能資料夾中建構及準備檔案。

如要附加 Google Cloud Storage 中的技能，請按照下列步驟操作：

REST

要求變數

呼叫 API 之前，請先替換下列項目：

  • PROJECT_ID： Google Cloud 專案 ID。
  • LOCATION：代理程式的區域位置。僅支援 global 區域。
  • AGENT_ID：目標代理程式 ID。
  • NEW_GCS_SOURCE_PATH：包含技能資料夾的 Google Cloud Storage bucket 路徑 (例如 gs://cymbal-bucket-name/my-skill-folder)。
JSON 要求內文
{
  "name": "AGENT_ID",
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "gcs",
        "source": "NEW_GCS_SOURCE_PATH",
        "target": "/.agent/skills"
      }
    ],
    "network": {
      "allowlist": [
        { "domain": "*" }
      ]
    }
  }
}
curl 指令
curl -X PATCH "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID?update_mask=base_environment" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{
      "name": "AGENT_ID",
      "base_environment": {
          "type": "remote",
          "sources": [
              {
                  "type": "gcs",
                  "source": "NEW_GCS_SOURCE_PATH",
                  "target": "/.agent/skills"
              }
          ],
          "network": {
              "allowlist": [
                  { "domain": "*" }
              ]
          }
      }
  }'

Python

JavaScript

刪除代理程式

如要刪除特定自訂代理程式設定，請發出 DELETE 要求。這項長時間執行的作業會永久刪除設定。

刪除代理程式時，請在網址中提供所有必要資訊，且不要加入 JSON 要求主體。

REST

要求變數

呼叫 API 之前，請先替換下列項目：

  • PROJECT_ID： Google Cloud 專案 ID。
  • LOCATION：代理程式的區域。僅支援 global 區域。
  • AGENT_ID：要刪除的代理程式 ID。

HTTP 方法和網址

DELETE https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID

curl 指令

curl -X DELETE "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)"

回覆範例

{
  "name": "projects/1234567890/locations/global/operations/234567890123",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1beta1.DeleteOperationMetadata",
    "genericMetadata": {
      "createTime": "2026-05-13T02:15:45.936287Z",
      "updateTime": "2026-05-13T02:15:45.936287Z"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.protobuf.Empty"
  }
}

Python

執行這段程式碼前，請先設定「REST」分頁中說明的變數。

from google import genai

client = genai.Client(
    vertexai=True,
    project="PROJECT_ID",
    location="global",
)

response = client.agents.delete(id="AGENT_ID")
print(response)

JavaScript

執行這段程式碼前，請先設定「REST」分頁中說明的變數。

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({
    vertexai: true,
    project: "PROJECT_ID",
    location: "global",
});

const response = await client.agents.delete("AGENT_ID");
console.log(response);

取得長時間執行的作業詳細資料

CreateAgent、UpdateAgent 和 DeleteAgent 等作業都是非同步作業。初始 API 回應會傳回包含作業 ID 的 name 欄位。使用這個 ID 輪詢進度。GetOperation

REST

要求變數

呼叫 API 之前，請先替換下列項目：

  • PROJECT_ID： Google Cloud 專案 ID。
  • LOCATION：作業的區域位置。僅支援 global 區域。
  • OPERATION_ID：從初始 LRO 回應的 name 欄位擷取的作業 ID。

HTTP 方法和網址

GET https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID

curl 指令

curl -X GET "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)"

Python

JavaScript

設定網路存取權

根據預設，使用 Agents API 建立代理程式時，沙箱會停用網路存取權。如要允許自由存取，請使用 *。

舉例來說，在 allowlist 中使用 * (如下列程式碼所示)，即可存取所有網域：

"base_environment": {
    "type": "remote",
    "sources": [
        {
            "type": "skill_registry",
            "source": "SKILL_RESOURCE_NAME",
            "target": "./skills"
        }
    ],
    "network": {
        "allowlist": [{"domain": "*"}]
    }
}

後續步驟

指南

瞭解如何在執行階段與代理程式互動、管理工作階段狀態，以及動態覆寫設定。