创建和管理代理

本指南介绍了如何在 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 Tool User (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 必须遵循以下限制：

    • 长度必须介于 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 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 必须遵循以下限制：

    • 长度必须介于 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 Tool User (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 必须遵循以下限制：

    • 长度必须介于 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",
            },
        },
    ],
});

将 skill 附加到智能体

如需在创建智能体时直接加载可重用技能，请将其装载到 base_environment.sources 中。

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

  • Skill Registry：附加在 Skill Registry 中注册到项目内的技能。

  • Google Cloud Storage：直接从 Cloud Storage 存储桶附加自定义技能。

    作为最佳实践，我们建议将技能装载到环境中的 /.agent/skills 文件夹下，以便代理更容易发现它们。

CLI Skills

开发者还可以在所选的 CLI 中安装专业技能，以编程方式管理智能体和互动：

从技能注册表中附加技能

如需在创建智能体时直接从技能注册表中加载可重用技能，请执行以下操作：

REST

请求变量

在调用 API 之前，请先进行以下替换：

  • PROJECT_ID：您的 Cloud de Confiance by S3NS 项目 ID。
  • LOCATION：智能体的区域位置。仅支持 global 区域。
  • AGENT_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 存储桶附加自定义技能。

从 Cloud Storage 装载技能时，请注意以下要求：

  • 上传要求：您必须将整个技能文件夹上传到存储桶。
  • 无内容验证：后端在装载前不会验证文件夹内容；其行为类似于标准文件夹上传。
  • 大小限制：所有附加文件都受沙盒环境内存限制（总共最多 4 GiB RAM）。
  • 最佳实践：为确保技能质量，请按照 agentskills.io/home 上所述的惯例，在技能文件夹中整理和准备文件。

如需在创建智能体时附加 Google Cloud Storage 中的技能，请执行以下操作：

REST

请求变量

在调用 API 之前，请先进行以下替换：

  • PROJECT_ID：您的 Cloud de Confiance by S3NS 项目 ID。
  • LOCATION：智能体的区域位置。仅支持 global 区域。
  • AGENT_ID：新代理的唯一自定义标识符。自定义代理 ID 必须遵守以下限制：
    • 长度必须介于 1 到 63 个字符之间。
    • 只能包含小写字母、数字和连字符。
    • 必须以字母开头，以字母或数字结尾。
  • GCS_SOURCE_PATH：包含技能文件夹的 Google Cloud Storage 存储桶路径（例如 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 搜索进行接地和网址上下文），请发送包含 update_mask=tools 的 PATCH 请求：

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

将 skill 附加到智能体

如需在代理更新期间在 base_environment.sources 中附加或修改技能，请使用 update_mask=base_environment 发送 PATCH 请求。

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

  • Skill Registry：附加在 Skill Registry 中注册到项目内的技能。

  • Google Cloud Storage：直接从 Cloud Storage 存储桶附加自定义技能。

从技能注册表中附加技能

如需附加在 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 存储桶附加自定义技能。

从 Cloud Storage 装载技能时，请注意以下要求：

  • 上传要求：您必须将整个技能文件夹上传到存储桶。
  • 无内容验证：后端在装载前不会验证文件夹内容；其行为类似于标准文件夹上传。
  • 大小限制：所有附加文件都受沙盒环境内存限制（总共最多 4 GiB RAM）。
  • 最佳实践：为确保技能质量，请按照 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 存储桶路径（例如 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 Unified Access Policy (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": "*"}]
    }
}

后续步骤

指南

了解如何在运行时与智能体互动、管理会话状态以及动态替换配置。