创建和管理代理

本指南介绍了如何在 Agent Platform 中使用托管式智能体 API 创建、检索、列出、更新和删除自定义智能体资源，以及如何配置智能体环境、Model Context Protocol (MCP) 服务器工具和技能。

准备工作

在配置代理之前，请设置您的环境：

  1. 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

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

  3. 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

  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 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 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. 如果您计划将 Google Cloud 模型上下文协议 (MCP) 工具与代理搭配使用，请向您的用户账号和关联的服务账号授予 MCP Tool User (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 必须遵守以下限制：

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

    • 长度必须介于 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 Tool User (roles/mcp.toolUser) Identity and Access Management (IAM) 角色。

  • 确认配置中的 MCP 服务器通过标准 HTTP POST 进行通信，以实现工具列表和执行。Agent Platform 上的受管代理 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://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 必须遵守以下限制：

    • 长度必须介于 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 存储桶附加自定义技能。

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

CLI 技能

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

从技能注册表中附加技能

在创建智能体时，直接从技能注册表中加载可重用技能：

REST

请求变量

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

  • PROJECT_ID：您的 Google Cloud 项目 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 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：您的 Google Cloud 项目 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 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 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 搜索进行接地和网址上下文），请发送带有 update_mask=tools 的 PATCH 请求：

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 工具，请发送包含 update_mask=tools 的 PATCH 请求：

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

从技能注册表中附加技能

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

从 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 存储桶路径（例如 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": "*"}]
    }
}

后续步骤

指南

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