使用 Gemini API 建立受管理代理：完整開發者指南

以往，要建立能夠推理、寫入及執行程式碼、瀏覽網頁，以及管理檔案的自主代理，通常需要花上數星期做基礎設施工作。隨著 Gemini API 的 Managed Agents 推出，Google 已將整套設定濃縮成一次 API 呼叫。單次請求就會啟動一個由 Google 托管的安全、短暫存在的 Linux 沙箱，並在當中啟動一個可即時投入工作的代理。

本指南涵蓋開發者需要知道的一切：Antigravity 代理如何運作、如何建立及部署自訂代理、如何分叉環境以重現執行結果、如何鎖定網絡及憑證，以及全新的 Gemini CLI 如何融入以代理為核心的工作流程。

什麼是 Gemini API Managed Agents？

Managed Agents 是 Google 為 Gemini API 上的自主 AI 代理推出的新開發者原語（developer primitive）。你不再需要自行拼接協調邏輯、程式碼執行環境、工具呼叫基礎設施及安全控制，API 會處理全部內容。

一次 Interactions API 呼叫就會建立一個沙箱化 Linux 環境、啟動一個由 Gemini 驅動的代理，並端到端執行你的任務。代理可以推理及規劃、呼叫工具、執行程式碼、管理檔案，以及瀏覽網頁——全部都在 Google 為你管理的安全執行環境內完成。

要實現這一點，有兩個介面：

• Interactions API — 執行時介面。傳送任務，回傳一個會推理並執行動作的代理。
• Agents API — 控制平面。定義、註冊及管理具名代理，並加入自訂指令、工具、技能及環境設定。

Antigravity 代理：即用型通用代理

Gemini API 上首個通用受管理代理是 Antigravity。它由 Gemini 3.5 Flash 驅動，並運行於 Antigravity IDE 及其他 Google 第一方代理產品背後的同一套執行架構。Antigravity 推出之前，Deep Research 是唯一可用的受管理代理——一個專為多步研究工作流程而設的專用代理。

Antigravity 是通用版對應方案：只需一次 API 呼叫，即可建立遠端 Linux 環境並開始工作。

Antigravity 可以做什麼

在其受管理沙箱內，Antigravity 代理可以：

• 使用 Gemini 代理執行架構進行推理及規劃
• 在安全的 Linux 環境中執行程式碼及管理檔案
• 瀏覽網頁以擷取及處理即時資料
• 使用包括網頁搜尋、程式碼執行及檔案 I/O 在內的工具

你的第一個 Antigravity API 呼叫

以下是最簡單的 Antigravity 調用方式——一次 API 呼叫就會建立遠端環境、執行代理，並回傳輸出：

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Research the top 10 AI stories today and create a PDF briefing with summaries",
    environment="remote",  # Remote Linux environment hosted by Google
)

print(interaction.output_text)

就是這樣。無需容器設定。無需沙箱程式碼。無需工具呼叫支援層。Google 會全部處理。

持久化環境：具狀態的多輪代理

環境會在多次呼叫之間保留。第一次互動會建立一個沙箱並回傳 environment_id。在後續請求中傳入該 ID，代理就會在完全延續上一輪狀態的情況下繼續執行，所有檔案、套件及狀態都會保持在前一次呼叫結束時的樣子。

# First call — provisions a new remote environment
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    environment="remote",
    input="Research the top 10 AI stories today and create a PDF briefing with summaries",
)

# Second call — resumes in the same environment with full state intact
interaction_2 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    environment=interaction.environment_id,
    previous_interaction_id=interaction.id,
    input="Now create a landing page using javascript and html",
)

print(interaction_2.output_text)

這種具狀態特性正是多步工作流程得以實際落地的原因。某個代理若在一次呼叫中安裝套件、寫入檔案及執行分析，便可將所有成果無縫交接到下一次呼叫——無需重新設定、無需重新下載、無需重新執行。

環境亦支援在啟動時載入外部資料：Git 倉庫、Google Cloud Storage 物件或內嵌內容，都可以在代理開始工作前掛載到沙箱內。

建立自訂受管理代理

Antigravity 代理可妥善處理一般用途任務。不過，生產環境幾乎總是需要自訂行為——特定指令、領域技能、專有工具或整理過的資料來源。這正是 Agents API 的用途。

Gemini Managed Agents 讓你可以把指令、技能、工具與環境打包成一個具名代理，並透過 ID 呼叫。你不需要撰寫複雜的協調程式碼，只需以宣告式方式定義一切——例如在 AGENTS.md 和 SKILL.md 這類 markdown 檔案中——然後一次性註冊即可。

從來源定義代理

透過指定系統指令及來源，從零開始建立代理。來源可以是 GitHub 倉庫、Google Cloud Storage 路徑，或內嵌內容。平台會在每次調用時為你建立全新的沙箱，並載入你的檔案。

agent = client.agents.create(
    name="data-analyst",
    base_agent="antigravity-preview-05-2026",
    base_environment={
        "sources": [
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": "You are a data analyst agent..."
            },
            {
                "type": "inline",
                "target": ".agents/slide-maker/SKILL.md",
                "content": "Instructions for creating slides..."
            },
            {
                "type": "github",
                "source": "https://github.com/my-org/data-templates.git",
                "target": "/workspace/"
            },
            {
                "type": "gcs",
                "source": "gs://my-bucket/analysis-skills/",
                "target": "/.agents/skills/"
            },
        ]
    }
)

result = client.interactions.create(
    agent="data-analyst",
    input="Analyze Q1 revenue data and create a slide deck.",
    environment="remote",
)

print(result.output_text)

一旦註冊完成，data-analyst 就會成為一個可按名稱調用的持久代理。每次執行都會以你精確設定好的內容建立乾淨環境——不同調用之間不會互相污染狀態。

分叉既有環境

有時候，建立自訂代理最快的方法就是反覆迭代。你可以先用基礎 Antigravity 代理互動式地工作——安裝套件、建立範本、設定環境——然後把該環境快照分叉成一個可重用的具名代理。

# Step 1: Iterate with the base agent in a remote environment
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Install pandas and matplotlib. Create an analysis template.",
    environment="remote"
)

# Step 2: Create a new agent from the existing environment snapshot
agent = client.agents.create(
    name="my-data-analyst",
    base_agent="antigravity-preview-05-2026",
    instructions="You are a data analyst that creates slide presentations.",
    base_environment=interaction.environment_id,
)

儲存後，每次再調用 my-data-analyst 時，都會從該基礎快照分叉——每次都從乾淨、已預配置的狀態開始。

result = client.interactions.create(
    agent="my-data-analyst",
    input="Analyze Q1 revenue data and create a slide deck.",
    environment="remote"
)

print(result.output_text)

對於依賴大量前置設定的代理，例如複雜的相依關係圖、龐大的模型資產，或每次調用都要太長時間重新建立的預編譯範本，這種「分叉再註冊」模式尤其有效。

安全網絡與憑證代理

生產代理幾乎都需要連接外部服務——GitHub、內部 API、套件註冊庫——而且通常要在不把敏感憑證暴露到沙箱內的情況下完成。Managed Agents 透過可配置的 egress proxy（出口代理） 同時處理這兩件事。

網絡設定有兩個用途：

1. Allowlist（允許清單） 會將出站連線限制在明確允許的網域，防止代理連到非預期的外部服務。
2. Header transforms（標頭轉換） 會在伺服器端注入憑證，令 API token 和密鑰從不會直接進入沙箱環境本身。

agent = client.agents.create(
    id="issue-resolver",
    base_agent="antigravity-preview-05-2026",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/my-org/backend",
                "target": "/workspace/repo",
            }
        ],
        "network": {
            "allowlist": [
                {
                    "domain": "api.github.com",
                    "transform": {
                        "Authorization": "Bearer ghp_your_github_token"
                    },
                },
                {"domain": "pypi.org"},
            ]
        },
    },
)

在此設定下，代理只能連接 api.github.com 和 pypi.org。任何嘗試連接其他網域的行為都會被封鎖。GitHub 請求會自動轉換以加入 Authorization 標頭——沙箱程式碼從不會直接看到 token。

這種架構對於部署到內部程式碼倉庫、專有 API，或任何需要符合憑證管理規範的環境而言，都是不可或缺的。

Gemini API CLI：以代理為核心的開發者體驗

除了 API 之外，Google 還推出了實驗性的開源 Gemini API CLI，專為編碼代理以結構化、對代理友善的方式與 Gemini API 互動而設計。

# Run a prompt against any model
gemini-api run "What is the capital of France?"

# Image generation
gemini-api run "A cat in space" --model gemini-3.1-flash-image-preview --output cat.png

# Text-to-speech
gemini-api run "Hello from Gemini" --model gemini-3.1-flash-tts-preview --voice Kore --output hello.wav

# Scaffold, test, and deploy an agent
gemini-api agents init my-agent
gemini-api agents test --prompt "Analyze the Q1 revenue data"
gemini-api agents create

# Run against a deployed agent
gemini-api run "Summarize this quarter" --agent my-agent

agents init / agents test / agents create 這套流程反映了 Google 對開發者如何在 Gemini API 上構建產品的預期轉變：把代理行為定義在檔案中、先在本機測試、再部署成具名受管理代理——這與基礎設施即程式碼（infrastructure-as-code）工具的常見模式非常相似。

相輔相成的工具

除了 CLI 之外，還有兩項新增功能可讓編碼代理保持與 Gemini API 的最新狀態同步：

• Gemini API Docs MCP server — 透過 MCP 提供對 Gemini 文件、SDK 及模型資訊的即時存取。編碼代理可以直接查詢文件，而不必依賴過時的訓練資料。
• gemini-interactions-api Skill — 自動把 Interactions API 模式及最佳實務注入代理的上下文，讓以 Gemini Managed Agents 建立的代理從一開始就能撰寫符合慣例的互動程式碼。

為何 Managed Agents 對生產場景如此重要

Managed Agents 背後的核心判斷是：代理開發中最困難的部分通常不是模型本身，而是包圍模型的基礎設施。沙箱化、工具整合、憑證管理、環境可重現性及網絡安全，都是每個要部署代理的團隊都必須各自解決的問題。Managed Agents 讓這些問題都變成 Google 的責任。

這種轉變對生產部署帶來實際影響：

可重現的執行結果。 分叉環境可保證每次代理呼叫都從完全一致的基線開始——沒有相依套件漂移，也不會有不同執行之間的狀態污染。

更小的攻擊面。 憑證不會進入沙箱。網絡出站設有允許清單。執行環境是短暫存在且隔離的。這些都不是額外加上的加固步驟，而是預設行為。

更快的迭代。 分叉再註冊的工作流程代表團隊可以先互動式地試驗，穩定設定，再將其升級為具名代理——無需在原型與生產之間重寫基礎設施。

框架相容性。 Managed Agents 可配合團隊已在使用的協調框架。首批合作夥伴包括 Vercel AI SDK、LiteLLM、Agno、Eigent 及 LlamaIndex——因此現有工作流程無需徹底重寫，也能享受受管理基礎設施的優勢。

企業級 Managed Agents

對於需要大規模運行自訂受管理代理的企業，Google 提供 Gemini Enterprise Agent Platform——同一套 API，再加上治理功能、集中式可視化及組織層級的政策控制。

Gemini API 的 Managed Agents 目前以預覽版形式提供。企業團隊可透過 Enterprise Agent Platform 使用相同的受管理代理原語，並獲得額外的審計、DLP（資料外洩防護）執行及多團隊治理控制。

重點總結

Gemini API Managed Agents 的推出，為開發者帶來三樣過去很難同時擁有的東西：一個開箱即用、功能完善的通用代理（Antigravity）；一個清晰的 API，可用生產級安全性去定義及部署自訂代理；以及一套為代理建立代理而設的開發者體驗——CLI、MCP server、Skills。

基礎設施的設計方向相當合理：持久化環境、環境分叉、出站允許清單，以及伺服器端憑證注入，都是生產代理部署的正確原語。開源 CLI 和 Skill 亦反映 Google 的認知：代理的開發者體驗，與其底層模型能力同樣重要。

對於在 Eigent 的模型無關平台上開發的團隊而言，Gemini Managed Agents 是一個極具吸引力的部署目標——它可與 Eigent 智能地在不同模型供應商之間路由任務的能力相得益彰，而由 Google 負責沙箱化執行層。

想開始使用的話，可以先在 AI Studio Playground 試用 Antigravity 代理，閱讀 Managed Agents 文件，並安裝 Python SDK 或 JavaScript SDK。

常見問題

什麼是 Gemini API Managed Agents？

Gemini API Managed Agents 是運行於 Google 托管、沙箱化 Linux 環境中的自主 AI 代理。只需一次 Interactions API 呼叫，就能建立沙箱、啟動一個由 Gemini 驅動的代理，並執行你的任務——包括程式碼執行、網頁瀏覽及檔案管理——而你無需自行設定任何基礎設施。

什麼是 Antigravity 代理？

Antigravity 是 Google 在 Gemini API 上推出的通用受管理代理，由 Gemini 3.5 Flash 驅動。它可以在安全的遠端 Linux 環境中推理及規劃、執行程式碼、管理檔案，以及瀏覽網頁。它使用的正是支援 Antigravity IDE 及其他 Google 第一方代理產品的同一套代理執行架構。

持久化環境如何運作？

第一次以 environment="remote" 進行互動呼叫時，系統會建立一個新的沙箱並回傳 environment_id。在後續呼叫中傳入該 ID，代理就會在同一環境中繼續執行——所有檔案、已安裝套件及狀態都會保留。這讓具狀態的多輪工作流程得以實現，而無需在每次呼叫之間重新設定。

如何建立自訂受管理代理？

使用 Agents API，透過指定基礎代理、指令及來源（GitHub 倉庫、GCS 物件或內嵌內容）來定義一個具名代理。一旦註冊完成，就可以透過 Interactions API 按名稱調用你的代理。或者，你也可以先用 Antigravity 互動式迭代，然後使用 client.agents.create() 並把 base_environment 指向既有的 environment_id，將結果分叉成具名代理。

憑證代理如何運作？

受管理代理的 egress proxy 位於沙箱與互聯網之間。你可以設定一份允許的網域 allowlist，並可選擇為每個網域設定標頭 transform 規則。代理會自動把標頭（例如 Authorization: Bearer <token>）注入相符的出站請求——因此沙箱程式碼永遠無法直接存取 token 值。

哪些框架與 Gemini Managed Agents 相容？

Gemini Managed Agents 在推出時可即用地配合 Vercel AI SDK、LiteLLM、Agno、Eigent 及 LlamaIndex。Interactions API 採用 REST 架構，因此任何可使用 HTTP 的協調框架都能整合。

什麼是 Gemini API CLI？

Gemini API CLI 是一個實驗性的開源工具，專為編碼代理與 Gemini API 互動而設。它支援執行提示、生成圖片及音訊，並可從命令列管理完整的受管理代理生命週期——init、test、create 及 run。

Gemini Managed Agents 可以用於企業用途嗎？

可以。同一套 Managed Agents API 可透過 Gemini Enterprise Agent Platform 使用，並附帶額外的治理控制、集中式可視化、DLP 執行及組織政策管理。Gemini API 的 Managed Agents 目前以預覽版形式提供。