Google Antigravity Agent API 入门：Interactions API、工具调用与状态续接

美国区 Google Trends 的 “coding agent” 上升查询中出现 Antigravity。

Google 现在又提供了 Antigravity Agent 的 Interactions API 预览入口，因此“IDE 里能用”与“程序里调用”需要分开理解。

这个 API 适合什么任务

它适合有明确目标、需要多步推理与工具操作的开发任务。

例如读仓库、定位错误、修改代码并运行测试。

单轮补全文本不必使用 Agent 运行时。

预览版也不适合未经隔离直接操作生产环境。

开始前记录四项信息

• Google AI Studio 项目。

• API key 所属项目。

• 选择的模型和区域可用性。

• 免费层或付费层的配额。

密钥只放环境变量：

1

$env:GEMINI_API_KEY = Read-Host "Gemini API key"

不要把真实密钥写进示例脚本、截图或 Git 历史。

先做不带工具的最小请求

使用官方文档当前展示的 SDK 与字段名。

预览 API 变化较快，复制旧博客代码前先核对版本。

请求目标只写一个可验收动作，例如“解释这段错误并给出两种假设”。

保存响应 ID、模型名、耗时和用量。

响应 ID 是后续续接状态与排错的重要证据。

再增加只读工具

第一种工具应是读取文件，而不是执行 shell。

把允许目录固定到测试仓库：

1

C:\sandbox\antigravity-demo

工具参数需要做路径规范化。

拒绝绝对路径、..、符号链接逃逸和隐藏的网络共享。

返回内容设置字节上限，避免把整个仓库塞进上下文。

工具调用循环怎么验收

每次调用都记录：

1. Agent 提出的工具名。

2. 原始参数。

3. 参数校验结果。

4. 工具退出码。

5. 截断后的输出。

6. Agent 最终结论。

工具执行器不应根据自然语言自行扩大权限。

Agent 请求读取文件，就不能顺便允许写入。

状态续接不要依赖聊天文本拼接

如果 API 返回可续接的 interaction 标识，优先使用官方状态机制。

手工把所有历史消息重复发送，会增加成本，也可能丢失工具状态。

续接前确认上一次运行是完成、等待工具还是失败。

失败状态不要直接当成功上下文继续。

写操作采用两阶段提交

第一阶段只生成 diff。

第二阶段由人或策略引擎批准后才应用。

1
2

git diff --check
git diff --stat

应用后运行最小测试集。

测试失败时保留工作树与日志，不要让 Agent 自动清理证据。

给命令工具加明确的允许列表

可以先允许：

1
2
3
4

git status --short
git diff --check
npm test -- --runInBand
python -m pytest tests/unit

拒绝命令拼接、重定向、下载执行和提权。

不要只按命令开头匹配。

参数同样需要校验。

控制成本的三个边界

设置最大 Agent 步数。

设置单次工具输出上限。

设置整个 interaction 的时间与预算上限。

达到上限后返回“未完成”和已有证据，不要伪装成完成。

常见失败定位

401 先检查密钥与项目。

403 检查 API 是否开放、账号资格和区域。

429 区分每分钟配额、每日配额与并发限制。

工具反复调用同一参数，通常说明返回结果不够结构化。

最终答案与 diff 不一致，应以真实工作树为准。

一个可靠的测试任务

准备一个故意失败的单元测试。

要求 Agent 找出原因，但第一轮禁止写文件。

确认它读取了相关源文件和测试输出。

第二轮允许生成补丁。

人工审核补丁后应用并运行测试。

最后开启新 interaction，让另一个检查流程复核 diff。

这比让 Agent 修改真实项目更能暴露权限与状态问题。

上线前检查

• 预览版变更被锁定到明确 SDK 版本。

• 密钥不进入仓库和日志。

• 文件工具限制在沙箱根目录。

• 命令参数经过解析而非字符串前缀匹配。

• 写入必须经过 diff 审批。

• 步数、时间、输出和费用均有限额。

• 失败状态保留证据。

Antigravity Agent 的重点不是“能自动写代码”，而是能否在可观测、可停止、可回滚的边界内完成代码任务。

Agent API 官方入口

把工具返回值设计成稳定 JSON

工具不要返回一整段无法区分状态的终端文本。文件读取结果至少包含 path、encoding、truncated 和 content；命令结果至少包含 exit_code、stdout、stderr 与 duration_ms。Agent 才能区分“命令失败”和“命令成功但没有输出”。

1
2
3
4
5
6
7
8

{
  "tool": "read_file",
  "ok": true,
  "path": "src/app.py",
  "encoding": "utf-8",
  "truncated": false,
  "content": "print('hello')"
}

命令执行器的结果可以使用下面的形状：

1
2
3
4
5
6
7
8

{
  "tool": "run_test",
  "ok": false,
  "exit_code": 1,
  "stdout": "3 passed, 1 failed",
  "stderr": "",
  "duration_ms": 1842
}

ok 由执行器根据退出码产生，不能让模型自己填写。输出发生截断时还要返回截断位置，并允许 Agent 请求更小范围的日志。

流式响应中断后的处理

网络中断不代表任务没有执行。重试前先查询 interaction 状态；如果服务端已经接受工具结果，重复提交可能让写操作执行两次。

为每个写工具增加幂等键。键由 interaction ID、工具调用 ID 和目标资源组成，执行器发现相同键时返回第一次结果。

1

idempotency_key = interaction_id + tool_call_id + target

如果官方 SDK 没有暴露状态查询接口，就把写操作留在人类确认阶段，不要在不确定状态下自动重试。

预览版升级记录

每次升级 SDK 都保存锁文件 diff、请求字段变化、响应字段变化和一条成功录制。先在固定测试任务上重放，再开放真实仓库。

特别检查工具调用参数是否更名、状态枚举是否增加，以及旧 interaction 能否由新 SDK 续接。无法续接时让旧任务自然结束，不在运行中切换版本。

一次故障注入测试

让读取工具返回一次超时，确认 Agent 不会把超时解释成文件不存在。让测试命令返回退出码 1 和空 stderr，确认它仍判断为失败。再让写工具返回“已执行但响应丢失”，确认幂等机制能阻止第二次写入。

最后撤销测试密钥，重新运行同一任务。系统应在认证阶段停止，并且不请求更多文件权限。

为 Interaction 建立本地审计记录

审计记录不要保存完整源码和提示，只保存定位运行所需的元数据。推荐结构如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  "interaction_id": "int_example",
  "started_at": "2026-07-27T03:00:00Z",
  "model": "replace-with-current-model",
  "repository": "demo-api",
  "base_commit": "8c18d4a",
  "tool_policy": "readonly-v2",
  "tool_calls": 7,
  "write_approved": false,
  "result": "needs_review"
}

repository 使用内部别名，避免把客户名称写进集中日志。源码片段只保存在权限更严格的任务附件中，并设置独立过期时间。

人工批准之后仍要重新校验参数

批准界面展示的参数与执行器收到的参数可能存在时间差。执行前重新计算规范化路径、命令 argv 和内容哈希；任何一项变化都使原批准失效。

1

approval = hash(tool_name + normalized_arguments + target_revision)

目标分支在等待批准期间发生变化时，Agent 应重新生成 diff。不要把旧补丁静默应用到新版本代码。

退出时留下可继续的状态

达到预算、超时或人工中止时，输出已经读取的文件、尚未验证的假设、最后一个成功工具调用和工作树状态。

下一次运行从这些事实开始，不需要重新扫描整个仓库。若工作树含未提交修改，先由人决定继续、保存补丁还是丢弃，Agent 不自行清理。

• Google：Antigravity Agent API

• Google：Antigravity 平台介绍