把依赖里的 google-adk 从 2.13.x 升到 2.14.0,本地跑得好好的工具调用,升级后接连在流水线里抛错:一个枚举参数比不上字符串了,一个建会话的调用被拒,一个脚本工具干脆返回看不懂的错误码。这不是环境抽风,而是 2.14.0 里三处白纸黑字的破坏性变更。更让人犹豫的是,同一份 release notes 又写着四块能力从 experimental 转成了 stable,看上去像是「可以放心升级」的信号。转正和报错同时发生,这次升级到底该不该现在做,值不值得为一个版本号把代码动一遍,是本文要拆清楚的问题。
同批四篇稿子各管一段,别混着读:热点栏写的是 OpenAI Images 2.6 的 GIF 与 SVG 增量,见 Images 2.6 热点;开源栏深拆 oxc-project/tsrs 这一个项目,见 tsrs 开源解析;横评栏对照的是另一组对象,见 四路径横评。本篇只讲 ADK 2.14.0 已有项目的版本升级与回归验证,是一份破坏性变更清单加五步避坑操作,不是从零把一个新 API 接进来。那类首次接入与计费口径的问题,Gemini Omni API 接入 SOP 已经写过,本篇不重复:一个是从零接入,一个是在既有工程上换版本、改调用、做回归,动作和关注点都不同。
为什么这次升级值得做
先把「值不值」讲明白,再动手改代码。2.14.0 的 release notes 列出的主线,是把 execution environments、A2A、evaluation、core runtime 这四块从 experimental 标成 stable。同一段还给出更细的清单:26 个 auth、environment、app、CLI、cache 模块,以及 16 个 toolset 与 integration 特性一并转正。这里的 26 与 16 是官方在转正说明里自己数出来的模块与特性数量,读的时候按「有多少个 API 面被定下来」理解,而不是按「功能多了多少」理解。
必须先钉死一个口径:stable 说的是这些 API 的对外形状稳定下来、不再轻易改签名,不等于你手上的应用已经生产就绪,也不等于所有 experimental 特性都转正了。把 API 面稳定误读成应用可以免验证直接放量,是这次升级最容易踩的理解偏差。它对你真正的意义是依赖管理上的:这些模块往后再升小版本,接口 Breaking 的概率低了,你 pinned 的版本约束可以更从容;但这是接口层的承诺,不代替你自己的回归与灰度。
性能那一面同样要带口径看。release notes 自报,在一个 30 节点工作流、200 轮的长对话运行里,耗时快 23%、峰值内存低 9%。这是 Google 自己给出的测量,针对的是它圈定的那个工作流与轮数,没有配套给出基线版本与测量方法,也不与任何第三方榜单或基准互为解释、不能拿去和别的数字换算。它说明长回合场景确实有优化,但把 23% 与 9% 当成你集群上的收益承诺就过头了;正文里凡提到这两个数,都按「官方自报、特定场景」来读。
升级后能用上的新东西也可以顺带记一笔,本文不展开:MultiRunConfig 配合 adk eval --num_runs 与 --parallelism,让同一条评测用例并发跑多轮再合并得分或通过率;ToolArgsMatcher 在评测里比对工具调用参数,支持 exact、case-insensitive、numeric-tolerance 与 LLM 语义几种匹配;adk generate_agent_card 从命令行生成 A2A agent card;此外还有 TeamsRunner 把 ADK agent 接到 Microsoft Teams 的会话与频道、OpenAIDecisionsClassifier 处理工作流与工具门控问题、MongoDbMemoryService 的向量检索与 TTL。有一条边界值得单独记:AgentEngineEnvironment 对超过 570 秒的命令会提前报超时,长脚本要按这个上限重新估时,别等跑到一半被掐断。
第一步:核对版本与两个日期
动手之前先把事实对齐,很多误判来自把两个日期揉成一个。google-adk 的版本是 2.14.0;changelog 内标注的日期是 2026 年 11 月 4 日,即 November 4, 2026;而 GitHub 上 v2.14.0 这个 tag 的发布时间是 2026 年 11 月 7 日 00:58 UTC,发布者记为 haranrk。部分日报只写 11-07,把 changelog 日期整个漏掉,读起来像是「11 月 7 日发布 2.14.0」这一个日期,那是遗漏,不是事实。两个日期各管一件事:一个是版本说明的落款,一个是代码与安装包真正打上标签的时刻,不能调和成一个,也不能拿其中一个去否定另一个。
具体动作分四步。先在环境里 print 出装着的 google-adk 版本,确认你确实在 2.13.x 或更早,别把本来就在 2.14.0 的工程又「升」一遍。再锁定 requirements 或 lockfile 里的版本与 Python 环境,记录哈希或锁定行,别让升级顺带把别的依赖一起抬了。然后在隔离分支安装 2.14.0,不要直接在主分支或发布分支上试。最后把版本号、两个日期、依赖快照一起记进变更单——回滚时要靠这份记录还原现场,日期分清楚了,才能判断你装到的是哪一版说明对应的包。
第二步:静态扫描三处破坏性变更
改代码之前先扫一遍调用点,列成清单,逐条标「命中 / 未命中」。三处都有很干净的文本特征,适合用搜索批量搞定,比逐个文件肉眼翻可靠得多。
第一处,Enum 工具参数。搜 arg == "value" 这类把枚举参数和字符串直接比较的写法,搜 .upper()、.startswith() 一类字符串方法调用,搜 json.dumps 把参数直接塞进去的地方。凡是工具函数的入参被声明成 Enum,命中即要改。留意间接写法:先 s = arg 再对 s 做字符串操作,同样漏网,清单里要按变量追一层。
第二处,VertexAiSessionService.create_session。搜 create_session(,把每个调用点传进去的 config 字典键名列出来,对照白名单 display_name、ttl、expire_time、labels,多出来的键就是隐患。别只看字面量字典,拼出来的、从配置读来的、用 **kwargs 展开的也要追到源头。
第三处,RunSkillScriptTool 的 environment 模式。搜 RunSkillScriptTool 与 command=,把仍在传 command 的调用点全部标出,同时核对脚本文件扩展名是不是 .py、.sh、.bash 三者之一,把用到其它扩展名的目标文件单独列一栏。
清单要落到「文件 + 行号 + 命中类型 + 拟改法」,别只写「大概有几处」。命中数、涉及哪些服务、是否集中在某个包,这些信息决定第三步先改哪块、第四步重点压测哪块。这一步偷懒,后面改写一定漏,漏掉的点会在灰度里以最难查的方式冒出来。
第三步:逐项改写
三处改动彼此独立,可以分开提、分开验。下面每处先说旧写法为什么失效,再给改写范式,最后点一个验收点。范式里的自定义名按你的工程替换,标出的写法与错误码都按 release notes 核对过,不要顺手补官方文档没给的参数。
Enum 参数:从字符串比到 .value 或 StrEnum
2.14.0 起,声明为 Enum 的工具参数收到的是 enum 成员对象,而不是字符串。于是 2.13.x 里成立的 arg == "value" 恒为假,.upper()、.startswith() 这类字符串方法没有着落,json.dumps 直接对这些成员序列化也会失效。旧写法不是逻辑错,是入参类型变了,比较与序列化的前提被抽掉。
改法两条:要么把比较与序列化都换成取 .value,要么把枚举定义成 StrEnum,让它本身按字符串行为工作。范式:
if arg.value == "value":
...
json.dumps(arg.value)
class Mode(StrEnum):
...验收点:拿一个已知的枚举值跑一遍工具调用,确认比较分支走对、序列化结果仍是原来的字符串,而不是对象表示。
create_session:把 config 收敛到四个键
VertexAiSessionService.create_session 现在只接受 display_name、ttl、expire_time、labels 四个 config 键,其它任意键都会抛 ValueError。旧版本里那些自定义配置项被默默忽略或透传,现在会直接把建会话打断。改写就是把 config 字典收敛到白名单,多余的键另找地方存,不要硬塞、也不要改名伪装成合法键:
session = VertexAiSessionService.create_session(
config={
"display_name": ...,
"ttl": ...,
"expire_time": ...,
"labels": ...,
}
)验收点:建会话成功返回,且把原先多余的键确实迁到了别处,功能没有随之丢失。
脚本工具:command 换成三个参数
RunSkillScriptTool 在 environment 模式下不再接受 command。release notes 对这一改动的说明很直白,称它 closes a hole that let a prompt-injected model run arbitrary shell commands,也就是堵上了被提示注入的模型借 command 执行任意 shell 命令的口子。改传 args、short_options、positional_args 三个参数;扩展名只支持 .py、.sh、.bash,其余返回 UNSUPPORTED_SCRIPT_TYPE;若还坚持传 command,返回 INVALID_ARGUMENTS。范式:
tool = RunSkillScriptTool(
args=...,
short_options=...,
positional_args=...,
)验收点:脚本按 .py、.sh、.bash 之一正常执行,传错扩展名能看到 UNSUPPORTED_SCRIPT_TYPE,误传 command 能看到 INVALID_ARGUMENTS,而不是静默通过。三处改完别急着提交,先进回归。
第四步:回归验证
验证要针对改动,别只跑一条顺利路径。用 MultiRunConfig 配合 adk eval --num_runs 把每个用例跑多轮,用 --parallelism 控制并发,把得分或通过率合并起来看波动;用 ToolArgsMatcher 覆盖参数匹配,确认 exact、case-insensitive、numeric-tolerance 与 LLM 语义这几档在你的用例里行为一致,参数比对别因为枚举类型变化而误判。重点复核脚本工具的两个错误码:给不支持的扩展名要能看到 UNSUPPORTED_SCRIPT_TYPE,误传 command 要能看到 INVALID_ARGUMENTS,把这两条写成断言而不是人工看一眼。
前面提到的 30 节点工作流、200 轮运行可以拿来当压测对象,顺带观察长回合下的耗时与峰值内存,但记住那 23%、9% 是 release notes 自报口径,只作趋势参照,不作验收线。评测怎么搭、多轮指标怎么记、并发结果怎么合并,可对照 自建评测那篇 的思路补一层,别凭一次跑通就放行。回归记录要留档:跑了哪些用例、多少轮、各错误码是否复现、结果与 2.13.x 基线的差异,都是第五步放量的依据。
第五步:灰度与回滚
先灰度,不要一把全量。重点盯 stable 四块在真实流量里的行为差异:execution environments 的脚本执行、A2A 的 agent card 与跨体调用、evaluation 的多轮结果、core runtime 的工具参数传递,是不是和 2.13.x 一致。把第五步的观测项按这四块分组,每块设一两个能报警的指标,灰度批次从小到大,观察窗口覆盖足够长的回合数,别只盯首小时。
保留 2.13.x 的回滚路径与第一步记下的依赖快照,一旦枚举比较、建会话、脚本调用任一环出问题,能立刻退回旧版本,而不是边查边改线上。放量的判断依据写清楚:stable 指 API 面稳定,不等于应用已生产就绪。灰度里要确认的是「这四块接口没再变、调用点全改对、评测多轮稳定、回滚随时可用」,而不是把 stable 当成免验证的通行证。把这两件事分开,升级才不会变成一次赌注;判断依据要落在自己的观测数据上,不落在版本标签上。
什么情况下先别升
有几种场景,答案是先按住,等条件补齐。
脚本工具重度依赖 command 拼命令、短期来不及拆成 args、short_options、positional_args 的,先别升,改写没做完就上等于把功能关掉。create_session 传了大量自定义 config 键、又没有一个干净收敛方案的,等配置迁移做完再说,硬上只会换来一片 ValueError。AgentEngineEnvironment 里跑着超过 570 秒的长命令、暂时无法拆步或调度的,升级后会撞上提前超时,得先评估再动。还有一类:你正处在发布窗口、没有隔离分支、没有 2.13.x 回滚快照、CI 里也没有可复用的多轮评测,连灰度和回归条件都不具备,那顺序应该是先补齐回滚与评测能力,而不是先升版本。
再补一条容易忽略的:如果工程还压在别的 experimental 特性上、指望这次「一并转正」,那更要等——stable 覆盖的是 release notes 点名的四块与 26 加 16 项,不覆盖全部实验特性。这些都不是「2.14.0 不好」,而是改动面与验证成本需要先被消化掉;把「该不该升」和「什么时候升」分开回答,比一刀切更稳。
常见问题
Q1:升级到 2.14.0 后,哪些调用会直接报错?
A1:三类。把 Enum 参数当字符串比较、调字符串方法或丢进 json.dumps 的调用会失效;VertexAiSessionService.create_session 传了 display_name、ttl、expire_time、labels 之外 config 键的会抛 ValueError;RunSkillScriptTool 在 environment 模式仍传 command 会返回 INVALID_ARGUMENTS,脚本扩展名不是 .py、.sh、.bash 会返回 UNSUPPORTED_SCRIPT_TYPE。这正是第二步要静态扫描的三处。
Q2:Enum 工具参数具体怎么改?
A2:2.14.0 起收到的是 enum 成员而非字符串。把 arg == "value" 改成 arg.value == "value",把 json.dumps(arg) 改成 json.dumps(arg.value),或把枚举定义改为 StrEnum 以保持字符串语义。字符串方法一并换成对 .value 的操作,改完用已知枚举值跑一遍工具调用,确认比较分支与序列化结果都对。
Q3:create_session 多传了键怎么办?
A3:把 config 收敛到 display_name、ttl、expire_time、labels 四个键,其余键移出 config 另存,否则会抛 ValueError。先按第二步清单搜出所有 create_session( 调用点,逐个核键名,包括拼出来和用 kwargs 展开的字典,再统一收敛,并确认迁走的键没有丢功能。
Q4:脚本工具还能传 command 吗?
A4:在 environment 模式下不能。改传 args、short_options、positional_args,且脚本仅限 .py、.sh、.bash;仍传 command 会得到 INVALID_ARGUMENTS,扩展名不符得到 UNSUPPORTED_SCRIPT_TYPE。这一改动是为堵住 prompt-injected 模型借 command 执行任意 shell 命令的口子,回归时把两个错误码写成断言复核。
Q5:标成 stable 是不是就能直接放量上生产?
A5:不能。stable 指 execution environments、A2A、evaluation、core runtime 等 API 面稳定,不等于应用已生产就绪,也不等于所有 experimental 特性转正。该做的静态扫描、逐项改写、回归验证、灰度与回滚一步都不能省,按第二步到第五步走完、并用自己的观测数据确认过,再判断放量。
延伸阅读
- Gemini Omni API 接入与成本账 SOP:从零接入新 API 的范式,与本篇的版本升级角度互补。
- Agent harness 横评:理解工具与运行时行为差异的背景,可对照 core runtime 的观测项。
- 自建评测实践:多轮评测与指标记录的做法,可对接第四步回归验证。
- Images 2.6 的 GIF 与 SVG 增量:同批热点栏,看单一产品的能力口径。