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

能夠自主推理、撰寫與執行程式碼、瀏覽網路並管理檔案的代理，過去往往需要花上數週來建置基礎架構。隨著 Gemini API 上的 Managed Agents 上線，Google 已將這套設置濃縮成單一 API 呼叫。一次請求就能啟動由 Google 託管的安全、短暫 Linux 沙箱——以及一個已準備好在其中實際工作的代理。

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

什麼是 Gemini API Managed Agents？

Managed Agents 是 Google 在 Gemini API 上推出的新一代開發者原語，用於建立自主 AI 代理。你不必自行拼湊協調邏輯、程式碼執行環境、工具呼叫基礎架構與安全控制，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",  # Google 託管的遠端 Linux 環境
)

print(interaction.output_text)

就這麼簡單。不需要容器設定。不需要沙箱化程式碼。不需要工具呼叫骨架。Google 會幫你處理一切。

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

環境會跨呼叫持續保留。第一次互動會配置一個沙箱並回傳 environment_id。在後續請求中傳入該 ID，代理就會從上次結束的地方繼續，所有檔案、套件與狀態都會維持不變。

# 第一次呼叫 — 配置新的遠端環境
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",
)

# 第二次呼叫 — 在同一個環境中繼續，完整狀態保持不變
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 代理進行互動式工作——安裝套件、建立範本、設定環境——再把那個環境快照分支成可重複使用的具名代理。

# 步驟 1：在遠端環境中與基礎代理反覆迭代
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Install pandas and matplotlib. Create an analysis template.",
    environment="remote"
)

# 步驟 2：根據現有環境快照建立新代理
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)

分支並註冊的模式，對依賴大量前置設定的代理特別有效：例如複雜的依賴圖、龐大的模型資產，或每次呼叫重新建置都太耗時的預編譯範本。

安全網路與憑證 Proxy

生產環境中的代理幾乎總是需要連線到外部服務——GitHub、內部 API、套件註冊庫——而且幾乎總是需要在不把敏感憑證暴露到沙箱內的前提下完成。Managed Agents 透過可設定的 egress proxy 同時解決了這兩個問題。

網路設定有兩個用途：

1. Allowlist（允許清單） 限制出站連線只可前往明確允許的網域，避免代理連到不該接觸的外部服務。
2. Header transform（標頭轉換） 在伺服器端注入憑證，讓 API token 與 secret 永遠不會進入沙箱環境本身。

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 互動而設計。

# 對任何模型執行提示
gemini-api run "What is the capital of France?"

# 影像生成
gemini-api run "A cat in space" --model gemini-3.1-flash-image-preview --output cat.png

# 文字轉語音
gemini-api run "Hello from Gemini" --model gemini-3.1-flash-tts-preview --voice Kore --output hello.wav

# 生成、測試並部署代理骨架
gemini-api agents init my-agent
gemini-api agents test --prompt "Analyze the Q1 revenue data"
gemini-api agents create

# 針對已部署代理執行
gemini-api run "Summarize this quarter" --agent my-agent

agents init / agents test / agents create 工作流程反映出 Google 對 Gemini API 的開發方式正在轉變：把代理行為定義在檔案中、在本地測試、再以具名受管代理部署——這與基礎架構即程式碼工具的思維十分相似。

相輔相成的工具

除了 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 的 model-agnostic 平台上開發的團隊來說，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 進行互動式迭代，再用指向既有 environment_id 的 base_environment 透過 client.agents.create() 將結果環境分支成具名代理。

憑證 proxy 是如何運作的？

受管代理的 egress proxy 位於沙箱與網際網路之間。你可以設定一份允許的網域 allowlist，並且可選擇為每個網域設定標頭 transform 規則。proxy 會自動把標頭（例如 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 目前仍為預覽版。