---
url: /antigravity/managed-agents-api.md
description: >-
  一文讲清 Google 如何把 Antigravity 编程 Agent 塞进 Gemini API：Interactions API、远程 Linux
  沙箱、AGENTS.md 与 Skills 挂载、命名 Agent 持久化、真实价格与踩坑提示。
---

# 认识 Antigravity 托管 Agent（Managed Agents）

先说一件让我有点恍惚的事。

以前你要让 AI 帮你干完一整件活儿——装依赖、跑脚本、看报错、改代码、再跑一遍——标准流程是：打开一个 IDE，装插件，配环境，SSH 连机器，写 Dockerfile，部署到 Cloud Run，再祈祷它别在半夜挂掉。我数了一下，光是"让 Agent 有个地方能跑代码"这件事，就要先干掉半天的工程活。

现在 Google 说：**一行 API 调用就够了。**

```python
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="写个脚本抓 HN 首页前 5 条，整理成 PDF。",
    environment="remote",
)
```

没了。没有 Docker，没有服务器，没有部署。Google 在云端给你开一台 Ubuntu 虚拟机，Agent 自己进去装包、写代码、跑命令、上网查资料，干完把文件还给你。

2026 年 9 月，Google 把 **Antigravity** 从"一个 AI IDE"变成了 **Gemini API 里的托管 Agent（Managed Agent）**。9 月 14 日的 AI Engineer 大会上，Google DeepMind 的 Philipp Schmid 专门做了 keynote 讲这件事。

> 这事的信号意义比功能本身大：Google 不想只卖模型了，它想卖"干完活的 Agent"。模型是引擎，Agent 是整车。

## 什么是 Antigravity 托管 Agent

简单说：**Antigravity 原本是 Google 的 Agent First 编程 IDE**，你打开它，让 AI 自己规划、写代码、跑命令、开浏览器验证。

\*\*托管 Agent（Managed Agent）\*\*是它的另一种形态——**把同一个 Agent 内核，通过 Gemini API 提供给你调用**。你不用打开任何界面，一行请求就能让它干活。

技术上它跑在 **Interactions API** 上，这是 Google 在 2026 年 6 月 23 日推的统一接口，目标准确说是：以后调 Gemini 模型和调 Agent，用同一套 schema。这次 Antigravity 入驻，算是把当年埋的伏笔兑现了。

目前公开的托管 Agent 只有一个，ID 是：

```
antigravity-preview-05-2026
```

注意名字里带 `preview`——**这是预览版，会变**。生产环境请做好心理准备。

它和 Antigravity IDE 用的是**同一套 Agent 内核（harness）**：plan → act → observe 循环，自己规划、执行、看结果、继续，直到任务完成或者撞上限制。

## 它到底强在哪

* **一行调用，自带一台电脑**：`environment="remote"` 就会分配一个全新隔离的 Ubuntu 沙箱，Python 3.12、Node.js 22、git、pip、curl 预装好，规格 **4 核 CPU / 16 GB 内存**
* **工具开箱即用**：内置 `code_execution`（跑 Bash / Python / Node）、`google_search`（联网搜索）、`url_context`（抓取并阅读网页）；一旦传了 `environment`，文件系统工具 `read_file` / `write_file` / `list_files` 自动启用
* **缺什么包自己装**：Agent 可以在沙箱里 `pip install`，不用你预先打镜像
* **两个 ID，两种记忆**：`interaction_id` 管对话上下文（说过什么、推理过什么），`environment_id` 管环境状态（文件、装过的包）。想接着上次的文件继续干，传 `environment_id` 就行
* **沙箱能活 7 天**：任务跑完沙箱不关机，**7 天无活动**后自动过期。中途想回来改点东西，直接复用 `environment_id`
* **能挂载配置**：通过 `environment.sources` 把 `AGENTS.md`、`SKILL.md`、脚本文件以 inline 方式塞进沙箱，Agent 启动时自动加载
* **能存成命名 Agent**：`agents.create()` 把配置固化到 Google 侧，之后按 ID 调用，代码里再也不用背着一坨配置字符串
* **流式输出**：`stream=True` 实时看到 Agent 在想什么、调了什么工具，而不是盯着黑屏等 90 秒
* **凭证不进沙箱**：Google 用网络代理替 Agent 注入凭据，你的 API token 不会暴露在沙箱环境里（这条我很喜欢，是少见的正确设计）

| 传统做法（ADK + Cloud Run） | 托管 Agent |
| --- | --- |
| 写 Dockerfile、配 CI/CD | 不用，沙箱全托管 |
| 部署 + 扩容 Cloud Run | 每次交互自动分配，7 天无活动自动回收 |
| 自己做沙箱隔离 | 每次交互天然隔离 |
| 自定义 PDF 工具 + pip 装包 | Agent 在沙箱里自己装 |
| 自己搭 SSE 流式服务 | `stream=True` 直接返回事件流 |
| 用 Python 定义工具 | 浏览网页、执行代码、文件系统，内置 |

## 真实场景：一个能自己出 PDF 的技术日报 Agent

Google 官方 Codelab 给了一个完整例子，我觉得比任何 benchmark 都能说明问题。

需求：每天抓 Hacker News 首页，挑出 5 条值得看的，按你的文风写成日报，输出成 PDF。

传统写法：ADK + Cloud Run，写 Dockerfile、部署服务、写自定义 PDF 工具、维护流式接口。一整天。

托管 Agent 写法：**写三个配置文件 + 一次 API 调用。**

```python
from google import genai

client = genai.Client()

stream = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Generate the digest.",
    stream=True,
    environment={
        "type": "remote",
        "sources": [  # 启动时挂载进沙箱
            {"type": "inline", "target": ".agents/AGENTS.md", "content": AGENTS_MD},
            {"type": "inline", "target": ".agents/skills/digest-pdf/SKILL.md", "content": SKILL_MD},
            {"type": "inline", "target": ".agents/skills/digest-pdf/scripts/generate_pdf.py", "content": GENERATE_PDF_PY},
        ],
    },
)

environment_id, interaction_id = run_stream(stream)
```

三个文件各管一摊：

| 挂载路径 | 作用 |
| --- | --- |
| `.agents/AGENTS.md` | 持久指令：文风、工作流、执行规则 |
| `.agents/skills/digest-pdf/SKILL.md` | 自动注册成命名技能，Agent 按名字调用 |
| `.agents/skills/digest-pdf/scripts/generate_pdf.py` | 预制渲染脚本，Agent 写 summaries.json 后直接跑它 |

Skills 这套规范是跨平台的开放标准（agentskills.io），不是 Google 私有格式——这点值得点赞，说明它没打算靠格式锁死你。

跑完之后想加个"Why it matters"字段？**不用重跑 Agent**，复用 `environment_id` 接着说一句就行：

```python
stream = client.interactions.create(
    agent="antigravity-preview-05-2026",
    previous_interaction_id=interaction_id,   # 记得上次聊了什么
    environment=environment_id,               # 文件、包都还在
    input="每条新闻加一句 Why it matters。",
    stream=True,
)
```

配置调稳了，固化成命名 Agent，以后一行调用：

```python
client.agents.create(agent="my-digest", ...)   # 烘焙一次

stream = client.interactions.create(
    agent="my-digest",      # 之后直接按 ID 叫它
    input="Generate the digest.",
    stream=True,
    environment="remote",
)
```

## 快速上手：三步跑起来

**第 1 步：拿到 API Key**

去 [Google AI Studio](https://aistudio.google.com/) 申请，设到环境变量：

```bash
export GEMINI_API_KEY="your-key-here"
```

**第 2 步：装 SDK**

```bash
pip install google-genai
```

**第 3 步：第一次调用**

```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="写个 Python 脚本生成前 20 个斐波那契数存到 fibonacci.txt，然后读出来打印。",
    environment="remote",
)

print(f"Interaction ID: {interaction.id}")
print(f"Environment ID: {interaction.environment_id}")
print(f"输出: {interaction.output_text}")
```

要是你不想装 SDK，裸 curl 也行：

```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
    "agent": "antigravity-preview-05-2026",
    "input": [{"type": "text", "text": "写个 Python 脚本生成前 20 个斐波那契数并存到 fibonacci.txt"}],
    "environment": {"type": "remote"}
  }'
```

返回结果里记得**存下 `interaction.id` 和 `environment.id`**——这是你续接对话和复用沙箱的钥匙。`interaction.outputs` 里还列着 Agent 每一步干了什么（推理、工具调用、代码执行），排查问题时非常好用。

## 钱的事，得说清楚

这块我必须泼点冷水，因为"免费"两个字最容易让人上头。

**模型费用（按 token 付）**

Gemini 3.8 Flash / 3.7 Flash / 3.6 Flash 目前是**入门优惠价**：

| 项目 | 优惠价（至 2026-12-31） | 2027-01-01 起 |
| --- | --- | --- |
| 输入 | $0.75 / 百万 token | $1.50 / 百万 token |
| 输出 | $3.75 / 百万 token | $7.50 / 百万 token |

价格翻倍的日子已经写进日程表了，别当成永久价。

**沙箱算力（目前免费）**

预览期间 Google **不单独收沙箱算力钱**——CPU、内存、执行环境都白送。免费层和付费层都有额度，按底层 Gemini token 用量和用到的工具计费。

> 免费算力是获客策略，不是定价承诺。Google 当年给 Gemini API 免费额度也是这个套路，等大家把工作流跑顺了，计量表就该转了。我的建议是：现在拿它验证想法，但别把"沙箱不要钱"写进你的成本模型。

**真正的坑：token 消耗量**

一次普通聊天和一次 Agent 交互，完全不是一个量级。Google 官方文档自己就警告了：**复杂工作流单次交互可能烧掉 300 万到 500 万 token**，按当前价折算上限约 **5 美元**一次。

原因很简单：Agent 会循环。写脚本 → 跑 → 读报错 → 改 → 再跑，每一轮都把上下文带上。

所以务必设预算护栏：

```python
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="...",
    environment="remote",
    config={"max_total_tokens": 2_000_000},   # 别让它无限循环
)
```

## 关于底层模型

Antigravity 托管 Agent 默认跑在 Gemini Flash 系列上。Google 在 **2026 年 9 月 2 日**把 **Gemini 3.8 Flash** 设为 Antigravity 的默认模型。

你也可以通过 `agent_config` 换模型：

```python
stream = client.interactions.create(
    agent="antigravity-preview-05-2026",
    agent_config={"type": "antigravity", "model": "gemini-3.7-flash"},
    input="抓 Hacker News 首页，列出前 5 条。",
    environment="remote",
)
```

预览文档里列出的可选项包括 `gemini-3.7-flash`、`gemini-3.6-flash`、`gemini-3.5-flash`、`gemini-3.5-flash-lite`。具体可用列表以官方文档为准，毕竟这是 preview。

顺带说一句 3.8 Flash 的底子：DeepSWE v1.1 长程软件工程基准上 73.7%，跟 Claude Opus 5 的 74.0% 基本打平；HLE-Verified 多学科专家推理 54.9%。更狠的是成本——同样跑编程任务，平均模型成本约 **$2.36**，Claude Opus 5 是 **$11.84**，差了 5 倍。

## 我的判断

托管 Agent 这条路线，Google 押的是\*\*"开发者不想管基础设施"\*\*这个共识。

OpenAI 走过弯路——AgentKit 那种可视化搭 Agent 的东西已经宣布废弃，2026 年 11 月 30 日关停。Anthropic 走的是另一头：一个强模型 + 一台电脑 + 一套权限，Claude Agent SDK。Google 这次明显更靠近 Anthropic 的思路，但**多给了两样东西：云沙箱和暂时的免费算力**。

对个人开发者，最实在的变化是：你终于可以在不碰服务器的前提下，验证一个"能干完活"的 Agent 到底靠不靠谱。这个门槛以前是几天的工程量，现在是一杯咖啡的时间。

但也别上头。preview 会变，价格会涨，沙箱会开始计费，token 会烧。趁现在便宜，把想法跑通，把配置调稳，把 `AGENTS.md` 写好——这些东西不管价格怎么变，都是你自己的资产。

## 进阶

想深入折腾的话，这几条路径值得走：

* 读 Google 官方 [Managed Agents 快速入门](https://ai.google.dev/gemini-api/docs/managed-agents-quickstart)，把多轮对话、流式输出、沙箱文件下载都过一遍
* 跑一遍官方 Codelab《Build a Daily Tech Digest Agent with Managed Agents on the Gemini API》，亲手感受一次"配置文件 + 一次调用"
* 把 `AGENTS.md` 和 Skills 写扎实，这两个文件是 Agent 行为质量的天花板，比换模型管用
* 关注 Interactions API 的演进，它是 Google 统一模型和 Agent 调用的那层地基

更多开源技术干货和学习资料，关注公众号「遇码」，领取专属福利。