使用 Gemini API 构建托管代理：完整开发者指南

曾经需要花费数周基础设施工作才能实现的自主代理——能够推理、编写并执行代码、浏览网页以及管理文件——如今随着 Gemini API 上的 Managed Agents 发布，Google 已将这套配置压缩为一次 API 调用。一次请求就会启动一个由 Google 托管的安全、临时 Linux 沙箱——以及一个已经准备好在其中执行真实工作的代理。

本指南涵盖开发者需要了解的一切：Antigravity 代理如何工作、如何构建和部署自定义代理、如何为可复现运行分叉环境、如何锁定网络和凭证，以及全新的 Gemini CLI 如何融入 agent-first 工作流。

什么是 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 第一方代理产品背后的同一套 harness 上。在 Antigravity 之前，Deep Research 是唯一可用的托管代理——一个专门用于多步骤研究工作流的特定代理。

Antigravity 是通用型对应方案：一次 API 调用即可创建远程 Linux 环境并开始工作。

Antigravity 可以做什么

在其托管沙箱中，Antigravity 代理可以：

• 使用 Gemini agent harness 进行推理和规划
• 在安全的 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)

这种“分叉并注册”的模式对依赖重型准备工作的代理尤其有效：复杂的依赖图、大型模型工件，或每次调用时都重建会耗时过长的预编译模板。

安全网络与凭证代理

生产代理几乎总是需要访问外部服务——GitHub、内部 API、包仓库——而且几乎总是需要在不把敏感凭证暴露到沙箱中的前提下完成。Managed Agents 通过可配置的 egress proxy（出站代理） 同时解决了这两个问题。

网络配置有两个目的：

1. Allowlist（允许列表） 限制出站连接只能访问明确允许的域，防止代理访问意外的外部服务。
2. Header transform（请求头转换） 在服务器端注入凭证，因此 API 令牌和密钥永远不会进入沙箱环境本身。

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 请求头——沙箱代码永远不会直接看到令牌。

对于部署到内部代码仓库、专有 API，或任何把凭证卫生作为合规要求的环境，这种架构都至关重要。

Gemini API CLI：面向代理优先的开发者体验

除了 API 之外，Google 还发布了一个实验性的开源 Gemini API CLI，专为编码代理以结构化、适合 agent 的方式与 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 的模型无关平台上构建的团队来说，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 第一方代理产品的同一套 agent harness。

持久化环境是如何工作的？

首次使用 environment="remote" 调用 Interactions API 时，会创建一个新沙箱并返回一个 environment_id。在后续调用中传入该 ID，代理就会在同一环境中继续运行——所有文件、已安装包和状态都会被保留。这使得有状态的多轮工作流成为可能，而无需在每次调用之间重新设置。

我该如何构建自定义托管代理？

使用 Agents API 通过指定基础代理、指令和源（GitHub 仓库、GCS 对象或内联内容）来定义一个具名代理。注册后，你可以通过 Interactions API 按名称调用该代理。或者，你也可以先与 Antigravity 交互式迭代，然后使用带有指向现有 environment_id 的 base_environment 的 client.agents.create() 将生成的环境分叉为一个具名代理。

凭证代理是如何工作的？

托管代理的出站代理位于沙箱和互联网之间。你可以配置一个允许域名的 allowlist，并可选地为每个域名设置 transform 请求头规则。代理会自动将请求头（例如 Authorization: Bearer <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 目前处于预览阶段。