Field SOP
Field SOP

Four Graduate, Three Break: Should You Upgrade ADK 2.14.0?

Upgrading google-adk from 2.13.x to 2.14.0 graduates execution environments, A2A, evaluation and core runtime from experimental to stable, with 26 auth, environment, app, CLI and cache modules plus 16 toolset and integration features listed in the same notes. Stable means the API shape has settled, not that your application is production ready. The same release carries three breaking changes: an Enum no longer equals a string, VertexAiSessionService.create_session accepts only display_name, ttl, expire_time and labels, and RunSkillScriptTool in environment mode no longer takes command but args, short_options and positional_args, returning UNSUPPORTED_SCRIPT_TYPE and INVALID_ARGUMENTS. The notes self-report 23% less time and 9% lower peak memory on a 30-node, 200-turn workflow, useful as a trend only and not an acceptance threshold. The changelog is dated November 4, 2026 while the GitHub v2.14.0 tag was published November 7 at 00:58 UTC; the two dates must not be merged. This is a five-step upgrade and regression checklist for existing projects, not a from-scratch integration guide.

Published November 9, 20269 min read
<!-- adk-214-upgrade-breaking-changes-sop | sop | Four Graduate, Three Break: Should You Upgrade ADK 2.14.0? -->

You bump google-adk from 2.13.x to 2.14.0 and the tool calls that behaved on your laptop start failing in the pipeline: an Enum argument no longer equals a string, a session call gets rejected, and a script tool returns an unfamiliar error code. This is not a flaky environment but three breaking changes written into the 2.14.0 release notes. The same notes also graduate four areas from experimental to stable, which reads like a green light. Graduation and breakage shipping together is the question here: is this upgrade worth doing, and does one version bump deserve a full pass over your code?

The four pieces in this batch take different angles. The hotspot column covers GIF and SVG additions in OpenAI Images 2.6 (hotspot); the open-source column goes deep on oxc-project/tsrs (breakdown); the comparison column examines a different set of objects (four-path comparison). This one is only about upgrading an existing ADK project to 2.14.0 and verifying it: a breaking-change checklist plus a five-step runbook, not a from-scratch integration. That first-touch integration and its billing questions belong to the Gemini Omni API setup SOP. One starts from zero; the other swaps a version under a live codebase, rewrites call sites, and runs regressions.

Why This Upgrade Is Worth Doing

Settle whether it is worth it first. The 2.14.0 release notes graduate four areas from experimental to stable: execution environments, A2A, evaluation, and core runtime, with a finer tally of 26 auth, environment, app, CLI, and cache modules plus 16 toolset and integration features. Read 26 and 16 as API surfaces being frozen, not as new feature counts.

One caveat has to be pinned down. stable describes the API surface: the public shapes settle and their signatures are unlikely to change again. It does not mean your application is production-ready, and it does not mean every experimental feature graduated. Mistaking a stable API surface for permission to ship without verification is the common reading error here. Its real value is dependency management: these interfaces are less likely to break on later minor releases, so pinned constraints can be looser. That is a promise at the interface layer, not a substitute for your own regression and canary work.

The performance side needs the same framing. As the release notes report, a 30-node workflow's 200-turn run is 23% faster with 9% lower peak memory. This is Google's own measurement, scoped to that workflow and turn count; the notes give no baseline version and no method, and the figure is not cross-checked against any third-party benchmark or leaderboard, nor folded into an estimate built from someone else's numbers. It says long multi-turn sessions got cheaper, not that 23% and 9% are what your cluster will see. Read them as vendor-reported and scenario-specific.

Post-upgrade additions, noted without expanding: MultiRunConfig with adk eval --num_runs and --parallelism runs each eval case multiple times concurrently and combines scores or pass rates; ToolArgsMatcher compares arguments with exact, case-insensitive, numeric-tolerance, or LLM semantic checks; adk generate_agent_card builds an A2A agent card from the CLI. Also TeamsRunner for Microsoft Teams, OpenAIDecisionsClassifier for tool-gating questions, and MongoDbMemoryService with vector search retrieval and TTL expiration. One boundary: AgentEngineEnvironment reports a timeout early for commands longer than 570 seconds, so long scripts must be re-estimated against that ceiling.

Step 1: Verify the Version and the Two Dates

Align the facts before touching anything; many bad decisions collapse two dates into one. The version is 2.14.0. The date printed inside the changelog is November 4, 2026. The GitHub tag v2.14.0, released by haranrk, is stamped at 00:58 UTC on November 7, 2026. Some roundups list only 11-07 and drop the changelog date, reading as if 2.14.0 shipped on November 7 as one date; that is an omission. The two dates describe different things: one dates the release notes, the other the moment code and package were tagged. Keep them separate.

Four actions. Print the installed google-adk version and confirm you are on 2.13.x or earlier. Pin the version in requirements or your lockfile with the Python environment and record resolved hashes, so the bump does not silently raise unrelated dependencies. Install 2.14.0 on an isolated branch, never on main. Write the version, both dates, and the dependency snapshot into a change record; rollback needs it to reconstruct the scene, and clear dates tell which package matched which notes.

Step 2: Statically Scan the Three Breaking Changes

Scan call sites before rewriting and turn results into a checklist with an explicit hit or miss per line. All three changes have clean text signatures, so a search beats flipping through files.

For the Enum change, search for arg == "value", string methods such as .upper() and .startswith(), and places where json.dumps takes the argument directly. Any tool whose input is an Enum is a hit. Watch indirect forms too: assigning s = arg then treating s as a string still slips through, so follow the variable one hop.

For VertexAiSessionService.create_session, search for create_session(, list the config keys at each site, and compare them against the whitelist display_name, ttl, expire_time, and labels. Any extra key is a risk. Do not stop at literal dictionaries; keys assembled at runtime, read from config, or spread through **kwargs need tracing to their source.

For RunSkillScriptTool in environment mode, search for RunSkillScriptTool and command=, mark every call still passing command, then check whether each script ends in .py, .sh, or .bash, listing other extensions separately.

The checklist should land on file, line number, hit type, and intended fix, not a vague guess. Hit count, affected services, and whether calls cluster in one package decide what you rewrite first in Step 3 and stress in Step 4. Skip this and the rewrite misses something that surfaces in the canary in the least debuggable way.

Step 3: Rewrite Each Call Site

The three changes are independent, so commit and verify them separately. For each, see why the old form fails, apply the pattern, and note one acceptance check. Custom names are yours to replace; flagged forms and error codes come from the release notes, so add no endpoints or parameters the notes never mention.

Enum arguments: from string comparison to .value or StrEnum

From 2.14.0, a tool argument declared as an Enum receives an enum member, not a string. The old arg == "value" is always false, string methods such as .upper() have nothing to act on, and json.dumps fails when handed those members directly. The old logic is not wrong; the input type changed. Two fixes: compare and serialize through .value, or define the enum as StrEnum to keep string behavior.

python
if arg.value == "value":
    ...
json.dumps(arg.value)

class Mode(StrEnum):
    ...

Acceptance check: one call with a known enum value confirms the comparison branch and that the serialized result is still the original string.

create_session: narrow config to four keys

VertexAiSessionService.create_session accepts only display_name, ttl, expire_time, and labels as config keys; any other key raises ValueError. Custom entries silently ignored in older versions interrupt session creation in 2.14.0. Narrow the config dictionary to the whitelist and store displaced keys elsewhere, without smuggling them in or renaming them to look legal.

python
session = VertexAiSessionService.create_session(
    config={
        "display_name": ...,
        "ttl": ...,
        "expire_time": ...,
        "labels": ...,
    }
)

Acceptance check: the call returns a session and the removed keys were migrated, not dropped.

Script tool: replace command with three parameters

RunSkillScriptTool in environment mode no longer accepts command. The release notes are blunt: the change "closes a hole that let a prompt-injected model run arbitrary shell commands". Pass args, short_options, and positional_args instead. Only .py, .sh, and .bash are supported; anything else returns UNSUPPORTED_SCRIPT_TYPE, and still passing command returns INVALID_ARGUMENTS.

python
tool = RunSkillScriptTool(
    args=...,
    short_options=...,
    positional_args=...,
)

Acceptance check: a supported extension runs, a wrong extension surfaces UNSUPPORTED_SCRIPT_TYPE, and a stray command surfaces INVALID_ARGUMENTS rather than passing silently. Move to regression before committing.

Step 4: Regression Verification

Verify against the changes, not one happy path. Use MultiRunConfig with adk eval --num_runs to run each case multiple times, use --parallelism to control concurrency, and combine scores or pass rates to see variance rather than one lucky run. Use ToolArgsMatcher to confirm the exact, case-insensitive, numeric-tolerance, and LLM semantic modes behave consistently, so the enum type change does not corrupt parameter comparisons. Assert that an unsupported extension produces UNSUPPORTED_SCRIPT_TYPE and a stray command produces INVALID_ARGUMENTS, instead of eyeballing them once.

The 30-node workflow and its 200-turn run make a reasonable load target for long-session time and peak memory, but the 23% and 9% are vendor-reported from the release notes: a trend reference, not an acceptance threshold. The self-hosted eval writeup adds a layer on structuring the eval, recording multi-run metrics, and merging concurrent results. Keep a regression record: which cases ran, how many turns, whether each error code reproduced, and how results differ from a 2.13.x baseline. Step 5 uses it to decide on a wider rollout.

Step 5: Canary and Rollback

Canary first, never a full cutover in one step. Watch the four newly stable areas under real traffic: script execution in execution environments, agent cards and cross-agent calls in A2A, multi-run results in evaluation, and tool argument passing in core runtime, each checked against 2.13.x. Group observations by those four areas, give each one or two alertable metrics, grow batches from small to large, and let the window cover enough turns rather than only the first hour.

Keep the 2.13.x rollback path and the Step 1 dependency snapshot, so if enum comparison, session creation, or script invocation misbehaves you step back instead of debugging live code. Be explicit about the rollout criterion: stable describes the API surface, not a production-ready application. The canary must confirm those four interfaces stopped changing, every call site was rewritten, multi-run evals are steady, and rollback is ready at any time. stable is not a free pass that skips verification. Base the decision on your own telemetry, not a version label.

When to Hold Off

Several situations call for holding the upgrade until the ground is ready.

If your script tool leans on command to assemble shell lines and there is no time to split it into args, short_options, and positional_args, hold: shipping before the rewrite turns the feature off. If create_session passes a long list of custom config keys with no clean narrowing plan, wait until migration is done or you trade the upgrade for a wall of ValueError. If AgentEngineEnvironment runs commands longer than 570 seconds that cannot be split or scheduled, the early timeout will hit, so assess that first. If you are inside a release window with no isolated branch, no 2.13.x rollback snapshot, and no reusable multi-run eval in CI, even canary and regression are out of reach; build rollback and eval capability first.

One more, easy to miss: if the project leans on other experimental features and expects this release to graduate them too, wait longer. stable covers the four named areas and the 26 plus 16 items in the release notes, not every experimental flag. None of this means 2.14.0 is a bad release; the change surface and verification cost need absorbing first. Separating whether to upgrade from when to upgrade is steadier than one yes-or-no call.

FAQ

Q1: Which calls fail outright after upgrading to 2.14.0?

A1: Three kinds. Code that compares an Enum argument to a string, calls string methods on it, or feeds it to json.dumps stops working. VertexAiSessionService.create_session raises ValueError when config carries keys beyond display_name, ttl, expire_time, and labels. RunSkillScriptTool in environment mode returns INVALID_ARGUMENTS if you still pass command, and UNSUPPORTED_SCRIPT_TYPE when the extension is not .py, .sh, or .bash. These are the three patterns Step 2 scans for.

Q2: How do I rewrite Enum tool arguments?

A2: From 2.14.0 the argument is an enum member rather than a string. Change arg == "value" to arg.value == "value", change json.dumps(arg) to json.dumps(arg.value), or define the enum as StrEnum to keep string semantics. Move string methods onto .value too, then run one call with a known enum value to confirm the branch and the serialized result.

Q3: What if create_session is passed extra keys?

A3: Narrow config to display_name, ttl, expire_time, and labels and move the rest out of config, or the call raises ValueError. Search every create_session( site from Step 2, check key names including assembled dictionaries and kwargs spreads, narrow them consistently, and confirm the migrated keys did not lose functionality.

Q4: Can the script tool still take command?

A4: Not in environment mode. Pass args, short_options, and positional_args instead, and keep scripts to .py, .sh, or .bash; a stray command yields INVALID_ARGUMENTS and an unsupported extension yields UNSUPPORTED_SCRIPT_TYPE. The change closes a hole that let a prompt-injected model run arbitrary shell commands, so assert both error codes during regression.

Q5: Does stable mean I can ship to production right away?

A5: No. stable means the API surface of execution environments, A2A, evaluation, and core runtime is settled; it does not mean your application is production-ready, nor that every experimental feature graduated. Keep the static scan, per-item rewrite, regression verification, and canary with rollback from Step 2 through Step 5, and decide on rollout only after confirming with your own telemetry.

Related reading

This article is AI-assisted and human-edited. Last updated: 2026-11-09

FAQ

Which calls fail outright after upgrading to 2.14.0?
Three kinds. Code that compares an Enum argument to a string, calls string methods on it, or feeds it to json.dumps stops working. VertexAiSessionService.create_session raises ValueError when config carries keys beyond display_name, ttl, expire_time, and labels. RunSkillScriptTool in environment mode returns INVALID_ARGUMENTS if you still pass command, and UNSUPPORTED_SCRIPT_TYPE when the extension is not .py, .sh, or .bash. These are the three patterns Step 2 scans for.
How do I rewrite Enum tool arguments?
From 2.14.0 the argument is an enum member rather than a string. Change `arg == "value"` to `arg.value == "value"`, change json.dumps(arg) to json.dumps(arg.value), or define the enum as StrEnum to keep string semantics. Move string methods onto `.value` too, then run one call with a known enum value to confirm the branch and the serialized result.
What if create_session is passed extra keys?
Narrow config to display_name, ttl, expire_time, and labels and move the rest out of config, or the call raises ValueError. Search every create_session( site from Step 2, check key names including assembled dictionaries and kwargs spreads, narrow them consistently, and confirm the migrated keys did not lose functionality.
Can the script tool still take command?
Not in environment mode. Pass args, short_options, and positional_args instead, and keep scripts to .py, .sh, or .bash; a stray command yields INVALID_ARGUMENTS and an unsupported extension yields UNSUPPORTED_SCRIPT_TYPE. The change closes a hole that let a prompt-injected model run arbitrary shell commands, so assert both error codes during regression.
Does stable mean I can ship to production right away?
No. stable means the API surface of execution environments, A2A, evaluation, and core runtime is settled; it does not mean your application is production-ready, nor that every experimental feature graduated. Keep the static scan, per-item rewrite, regression verification, and canary with rollback from Step 2 through Step 5, and decide on rollout only after confirming with your own telemetry.

Related

Field SOP

GitHub Copilot: Six Models Deprecated December 14, What to Fix

Six GitHub Copilot models are deprecated on December 14, 2026, and the official November 13, 2026 changelog gives six migration sentences but no configuration file name, model ID string or migration script. This SOP turns those sentences into a checkable list: replace hardcoded model names in workflows and integrations, enable model policies in Copilot settings, and understand what global default, the model selector, Copilot Chat, inline edits and code completions each do. All six model names and suggested alternatives are quoted as published, Kimi K3 stays To be announced, and the Claude Haiku 4.5 annual-plan exception for individual subscribers is spelled out.

Nov 16, 20269 min read
Field SOP

Bedrock AgentCore V2 Snapshots: Four Patterns, One Pre-warm

Turns the four official AWS section names into a checkable sequence for Bedrock AgentCore runtime V2 session startup: measure Latency and OverheadLatency in CloudWatch first, move imports and static data into init, use Working with hooks for build-time large files, then send a background warm-up request with Pre-warm on user engagement and keep the session ID. It records the 120-second /ping gate, that the V2 default applies only to new and updated runtimes, that existing ones need explicit platformVersion=V2, and that the sample code is for non-production use. The Region and cold-start discrepancies between the two official pages are kept side by side.

Nov 15, 20269 min read