建立及管理代理程式

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

事前準備

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

  1. In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance 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

  2. Verify that billing is enabled for your Cloud de Confiance project.

  3. Enable the Agent Platform API, if it is not already enabled.

    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

  4. 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 Cloud de Confiance 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 Cloud de Confiance 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 identifier for a user in a workforce identity pool. For details, see Represent workforce pool users in IAM policies, or contact your administrator.

    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.
  5. 如果打算在代理使用 Cloud de Confiance by S3NS 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： Cloud de Confiance by S3NS 專案 ID。
  • LOCATION：代理的區域位置。僅支援 global 區域。

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

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

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

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

  • INSTRUCTIONS：要為代理設定的系統指令或角色。

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

  • 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 application-default 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： Cloud de Confiance by S3NS 專案 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 application-default 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 要求遠端 MCP 伺服器必須是可串流的 HTTP 伺服器。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://bigquery.googleapis.com/mcp",
      "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： Cloud de Confiance by S3NS 專案 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 application-default 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 中安裝專門技能，以程式輔助方式管理代理和互動：

從 Skill Registry 附加技能

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

REST

要求變數

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

  • PROJECT_ID： Cloud de Confiance by S3NS 專案 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 application-default 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 掛接技能時，請注意下列規定：

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

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

REST

要求變數

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

  • PROJECT_ID： Cloud de Confiance by S3NS 專案 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 application-default 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： Cloud de Confiance by S3NS 專案 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： Cloud de Confiance by S3NS 專案 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 application-default 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： Cloud de Confiance by S3NS 專案 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 application-default 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： Cloud de Confiance by S3NS 專案 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 application-default print-access-token)" \
  -d '{
      "name": "AGENT_ID",
      "tools": [
          {
              "type": "google_search"
          },
          {
              "type": "url_context"
          }
      ]
  }'

使用 MCP 設定更新代理

如要修改附加至代理的 MCP 工具，請傳送含有 update_mask=tools 的 PATCH 要求：

REST

要求變數

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

  • PROJECT_ID： Cloud de Confiance by S3NS 專案 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 application-default 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 附加技能

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

REST

要求變數

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

  • PROJECT_ID： Cloud de Confiance by S3NS 專案 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 application-default 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 掛接技能時，請注意下列規定：

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

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

REST

要求變數

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

  • PROJECT_ID： Cloud de Confiance by S3NS 專案 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 application-default 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 要求。這項長時間執行的作業會永久刪除設定。刪除 Agent Runtime 後，Agent Identity 就會失效。任何向該主體授予權限的 IAM 統一存取政策 (UAP)，都會在規則中保留已停用的主體。此外，政策繫結仍會保持有效。如要移除失效的主體，請更新 UAP，從規則中移除該主體。如果政策不再包含任何有效主體，請刪除政策繫結。

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

REST

要求變數

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

  • PROJECT_ID： Cloud de Confiance by S3NS 專案 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 application-default 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： Cloud de Confiance by S3NS 專案 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 application-default 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": "*"}]
    }
}

後續步驟

指南

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