前言¶

在 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。