Google在2026年9月17日更新Antigravity Agent预览版，推出antigravity-preview-09-2026，并宣布旧的05-2026预览版本将在10月5日停止。若应用只在远程沙箱读取最终文本，迁移可能只是更改Agent名称；若本地执行工具或解析function_call，内置工具参数和文件编辑语义已经变化，需要逐项检查。这个案例提醒开发者：模型升级不一定只是替换一行标识。
一、先判断自己使用哪条执行路径
查看当前请求是否指定远程环境，是否只读取output_text或model_output。如果是，官方说明迁移相对简单。若使用local_environment、自己接管工具执行、监听函数调用或将工具参数映射到本地命令，必须把它当作接口兼容升级。先梳理调用链，再决定测试范围，避免只看一个示例请求成功就上线。
二、文件写入接口变化
旧版使用write_file承担创建和整文件重写，新版区分write_to_file与replace_file_content，后者按行范围替换。应用若直接读取工具名称或把整段代码写回文件，需要调整映射。更细粒度编辑可以减少无关改动，但错误的行号会误改内容，因此要校验目标文件版本并在冲突时停止。
三、参数命名变化不可忽略
新版内置工具使用PascalCase参数，例如TargetFile、StartLine和EndLine，而旧实现更多使用snake_case。依赖原始JSON键名的路由代码可能静默丢字段。迁移时建立明确的字段转换表，并对缺失参数返回错误，不要使用默认空字符串继续写文件。尤其要检查日志和权限策略是否仍能识别目标路径。
四、读取和搜索能力改变
文件读取由按偏移量的read_file变为支持行号的view_file，目录列表也换成list_dir，并新增按名称和内容搜索能力。前端展示工具步骤时需要能处理新类型。权限检查不能只沿用旧工具名，否则新搜索工具可能绕过目录白名单。所有路径在执行前都应规范化并限制在授权工作区。
五、做一组最小回归任务
准备创建新文件、局部替换、读取指定行、搜索文件、搜索代码与执行安全命令六类任务。每个任务保存预期工具名、参数、结果和工作区差异。对失败输入也要测试，包括不存在路径、超界行号和同时修改造成的冲突。若代码有解析function_call的分支，这些用例比只检查最终回答更重要。
六、升级要留有回退窗口
旧预览版有明确停止日期，回滚只能作为短期兜底。灰度阶段保留两个版本的路由与日志，观察工具调用成功率和意外文件修改。确认新接口稳定后移除旧字段适配，不要长期留下两个平行实现。上线当天要有负责人和快速关闭开关，避免Agent持续执行错误操作。
七、对非开发用户的影响
普通用户可能只看到Agent版本变化，但本地工具权限更值得关心。遇到大量文件被改动或首次出现新的工具请求，应先暂停并查看详情。重要项目先保存版本，再允许Agent写入。模型回答是否看起来正确，不能证明文件变更过程安全。
八、可复用的迁移原则
任何托管Agent升级，都应检查模型标识、工具schema、状态事件、权限映射和文件编辑语义。先跑受控样例，再做小流量灰度，最后清理旧实现。把“API返回200”当成迁移完成，是Agent系统最容易犯的错误。
参考资料：官方文档或公告。本文依据公开资料独立整理，并补充适用场景与操作建议。
