前言¶

在 Gemini Enterprise Agent Platform 上跑定制 Agent，往往不只是调一次对话接口。你需要事先定义系统指令、挂载 GCS 或 Skill Registry 里的技能目录、声明代码执行、文件系统、搜索或 MCP 等工具，并能在上线后查询和变更配置。若把这些步骤都记在内部文档里，Agent 与 Coding Agent 很难按同一套契约自动拼出正确的 REST 请求和 JSON 载荷。

下面介绍的 gemini-agents-api 是 Google 在 google/skills 仓库中发布的官方 Skill（metadata 版本 1.0.0，分类 AiAndMachineLearning）。它面向 Managed Agents API——平台 Agent 资源的控制面（Control Plane），用于在发起对话（数据面）之前，以程序化方式创建、配置、列出、更新或删除由服务端托管的有状态 Agent 资源。

这是什么¶

gemini-agents-api（全名：Gemini Enterprise Agent Platform - Managed Agents API Skill）是一份可安装到 Agent 上的操作说明：包含认证方式、REST 端点、请求体结构，以及创建 Agent 时长运行操作（LRO）的轮询方式。

与只覆盖推理或对话的 Skill（例如同仓库中的 Gemini Interactions API Skill）不同，本 Skill 聚焦资源生命周期：为开发者预置可定制的、有状态的 Agent 容器，支持系统指令、沙箱文件、自定义 Skill 注册表，以及本地或远程工具的配置说明。

官方路径：skills/cloud/gemini-agents-api。

核心功能¶

依据 Skill 正文与 frontmatter，已核实的能力包括：

1. 认证与环境：所有控制面请求使用 Application Default Credentials（ADC）衍生的 Bearer Token，并指向生产环境全局端点（LOCATION 需设为 Managed Agents API 支持的区域，例如 global）。
2. 创建 Agent（LRO）：POST 到 agents 集合；可指定 base_agent、描述、system_instruction、tools，并通过 base_environment 从 Google Cloud Storage 挂载目录到容器工作区（如 /.agent/skills），或从 Skill Registry 挂载修订版本。
3. 工具与 MCP：创建请求中的 tools 可声明平台内置类型（如 code_execution、filesystem、google_search、url_context），也可配置第三方 MCP 服务器（type: mcp，含 url 与可选 headers）；文档要求说明平台会将工具请求安全路由到指定 MCP URL，且自定义头仅发往该 URL。
4. 轮询创建结果：创建返回 operation name；对 GET https://aiplatform.googleapis.com/v1beta1/{OPERATION_NAME} 轮询直至 done: true，从 response 读取就绪的 Agent 资源。
5. 读取 Agent：GET 单个 Agent，返回完整配置（工具、环境等）。
6. 范围说明：Skill 描述还涵盖对 Agent 的列出、更新、删除；安装本 Skill 后，Agent 会按仓库内完整 SKILL 正文引用对应端点与载荷（下文示例以资料中给出的创建、轮询、Get 为主）。

安装与启用¶

Google 官方仓库通过 skills.sh 分发，安装方式为交互式选择 Skill 与目标 Agent：

npx skills add google/skills

按提示选择 gemini-agents-api（或安装全部 Cloud / AI 相关 Skill），并指定要配置的 Agent 与安装范围（项目或全局）。环境需具备 npx（通常随 Node.js 提供）。更新已安装 Skill：

npx skills update

资料未单独列出 Cursor、Codex CLI 与 Claude Code 的差异步骤；三者均遵循同一套 npx skills add 流程，以你当前使用的 Coding Agent 对 Skills 的挂载方式为准。

典型用法¶

1. 准备项目变量与访问令牌¶

控制面请求需要 PROJECT_ID、LOCATION 和 ACCESS_TOKEN：

export PROJECT_ID="your-project-id"
export LOCATION="global"
export ACCESS_TOKEN=$(gcloud auth print-access-token)

LOCATION 必须是当前区域已支持 Managed Agents API 的值（文档示例为 global 或其他可用区域端点）。

2. 控制面基础 URL¶

Agent 资源集合端点为：

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

3. 创建 Agent 并挂载 GCS 技能目录¶

下面用 curl 发起创建；平台会异步拉起容器，响应为 LRO 对象而非立即可用的 Agent：

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/agents" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "id": "my-custom-agent",
    "base_agent": "antigravity-preview-05-2026",
    "description": "A professional agent configured with remote tools and mounted Cloud Storage directories.",
    "system_instruction": "You are a helpful, domain-expert assistant.",
    "tools": [
      {"type": "code_execution"},
      {"type": "filesystem"},
      {"type": "google_search"},
      {"type": "url_context"}
    ],
    "base_environment": {
      "type": "remote",
      "sources": [
        {
          "type": "gcs",
          "source": "gs://your-agent-bucket-name/skills",
          "target": "/.agent/skills"
        }
      ],
      "network": {
        "allowlist": [
          { "domain": "*" }
        ]
      }
    }
  }'

若要从 Skill Registry 挂载而非 GCS，可将 sources 中一项改为 type: skill_registry，source 为类似 projects/your-project-id/locations/global/skills/my-math-skill/revisions/123456789012 的资源路径，target 仍为容器内路径（如 /.agent/skills）。

4. 轮询 LRO 直至 Agent 就绪¶

从创建响应的 name 字段取出 operation 路径，例如 projects/1234567890/locations/global/operations/operation-987654321-abcde：

curl -X GET "https://aiplatform.googleapis.com/v1beta1/projects/1234567890/locations/global/operations/operation-987654321-abcde" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json"

进行中仅有 metadata；成功时 done 为 true，response 内为 @type 为 google.cloud.aiplatform.v1beta1.Agent 的完整资源（含 name、base_agent、system_instruction 等）。

5. 查询已有 Agent 配置¶

curl -X GET "https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/global/agents/my-custom-agent" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json"

返回当前 Agent 的工具列表与环境设置，便于与基础设施即代码或 CI 中的期望状态对账。

6. MCP 与对话时覆盖（关联能力）¶

创建时在 tools 中加入 MCP 条目即可声明外部服务器；文档强调需向读者说明头信息与路由边界。若在交互时动态覆盖 MCP，需在数据面 interactions.create 的 tools 中使用 type: mcp_server——细节见 Gemini Interactions API Skill 与 Interactions API 文档，本 Skill 在正文中做了交叉引用。

适用场景与注意¶

适合谁：已在或计划使用 Gemini Enterprise Agent Platform、需要把 Agent 定义（指令、挂载、工具）纳入自动化流水线或让 Coding Agent 按官方契约生成 curl/客户端代码的团队。

注意点：

1. API 为 v1beta1，base_agent 等字段以平台当前可用模型/模板为准（资料示例为 antigravity-preview-05-2026）。
2. 创建是 LRO，集成侧必须实现轮询或等价异步等待，不能假设 POST 同步返回可用 Agent。
3. LOCATION 与端点区域必须一致，且需确认该区域已开放 Managed Agents API。
4. MCP 配置涉及凭据与出站网络；base_environment.network.allowlist 需按企业安全策略收紧，示例中的 "domain": "*" 仅作结构说明。
5. 控制面管资源，对话执行属于数据面；完整链路通常还需配合 gemini-interactions-api 等 Skill。

结尾¶

gemini-agents-api 把 Gemini Enterprise 上自定义有状态 Agent 的控制面 REST 流程收敛成可安装的 Agent Skill，减少手写端点与 JSON 时的遗漏。安装入口为 npx skills add google/skills，Skill 源码与完整 CRUD 说明见官方仓库：https://github.com/google/skills/tree/main/skills/cloud/gemini-agents-api。