chore(release/candidate): release 2.12.0

[adk-bot]

2.12.0 (2026-10-13)

Highlights

This release enhances execution performance in long sessions while introducing finer control over tool execution, workflow approvals, and deployment security.

• Performance: Cut time to first model request by 40% in long sessions. (1754b3e)
• Tools: Intercept and filter tool outputs before returning them to the model using after_tool_callback. (fdda17c)
• Workflows: Require human confirmation before executing workflow nodes via require_confirmation. (988fd1a)
• Deployment: Deploy agents to Agent Engine using dedicated custom service accounts. (629e119)
• Python 3.15: Install and run ADK on Python 3.15. (75aef1e)

All changes

Features

• add --state_file option to adk run (c390266), closes #7083
• add after_tool_callback to screen tool output (fdda17c), closes #6966
• add skill-level security support to AgentCardBuilder (79a7e49)
• agents: adapt BaseNode in tool consumers and preserve ToolUnion compatibility (8350c14)
• antigravity: preserve model thinking parts, client tool responses, and sub-agent hierarchy in ADK events (fac77be)
• cli: source the agent builder assistant's ADK knowledge from the installed package (ab9fffc)
• continue with de-identified text when only SDP matched (315c3dd), closes #7369
• encrypt google credential in session (42a17a9)
• eval: report the efficiency metrics for evals run from the Dev UI (49bf291)
• install lightweight Gemini Enterprise (Agent Platform) SDK without the GAPIC stack (d92735d)
• live: add an internal model for Live background tool calls (3f25ab5)
• live: implement CascadeLive model & sample (128faab)
• migrate ADK to google-cloud-aiplatform v2.2 (agentplatform) (77d4dcd)
• migrate VertexAiExampleStore and VertexAiRagRetrieval away from vertexai.preview (9e411be)
• persist skill-script outputs as artifacts (beaef0d), closes #5579
• plugins: add on_schema_error and on_schema_ready callback hooks to BigQueryLoggerConfig (4d31fa9)
• plugins: enrich AGENT_STARTING metadata in BigQueryAgentAnalyticsPlugin (c32ad3b)
• print next steps after adk create (06b7847)
• resume Gemini generations paused with a continuation token (b3cbb47)
• skills: migrate GCPSkillRegistry.search_skills from GET to POST (e9464ca)
• support custom service accounts for agent engine deploy (629e119), closes #2951
• telemetry: name skill tool spans after the skill they touch (c11060c)
• tools: run a sync FunctionNode tool's callable on the tool thread pool (71d5ed7)
• tools: run non-live generator FunctionTools via FunctionNode (0ee891a)
• tools: tag model_consult advisor requests with client label (068610f)
• user feedback survey workflow (f5efa2a)
• vmaas: add sandbox lifecycle helpers to the sandbox manager (46dff4b)
• vmaas: find or create sandbox templates per container config (650394f)
• workflow: run a sync generator FunctionNode's steps on the tool thread pool (8112f4a)
• workflow: support require_confirmation in @node and FunctionNode (988fd1a)
• workflow: support scalar auto-boxing for ToolNode input (873eed5)
• workflow: support task sub-agent delegation and resume in task-mode wrapper (8d71635)
• workflow: support tool authentication requests and credential resume in _ToolNode (c001a6c)

Bug Fixes

• a2a: support tool_call and tool_response in A2A part converter (a334bac)
• add JSON-tolerant LiteLLM tool call argument parsing (a01b226)
• add namespaced mode for forwarded A2A session context_id (c213adf), closes #7305
• agent engine memory service with A2A endpoint activated (d919ec0), closes #3458
• agents: centralize resume routing decision and fix sub-branch/callback/abort routing (8a43244)
• agents: route user FunctionResponses to sub-agents when is_resumable is False (86a47f6)
• allow built-in search tools with sub-agents on Gemini 3+ (6d52a23)
• allow OIDC token exchange without client_secret (4b1e004), closes #2256
• antigravity: harden parallel tool call IDs, start_subagent resolution, and thinking types (1e1ed51)
• artifacts: isolate InMemoryArtifactService entries from caller mutation (cb8ced5)
• avoid mutating caller Content role in live send_to_model (12b4924)
• bigquery: attribute BigQuery and Dataplex clients to active telemetry surface (6d6828f)
• build the rewind tombstone part once instead of on every check (11584d9)
• cancel and await parallel tool tasks on BaseException and GeneratorExit (a344350)
• cancel sibling tools on child-originated cancellation (1ab2fe8), closes #7172
• check where a builder app name imports from (8c5b3df)
• clear 23 strict mypy errors in evaluation and optimization (9d8e602)
• cli: restrict mutating /dev and agent builder endpoints to local clients by default (97f9379)
• close remaining plugins when plugin close is cancelled (f9558b3)
• count ID-less responses when resuming parallel calls (531f410), closes #7387
• decode error bodies with the declared charset (962fe9b), closes #7206
• decode url-safe base64 strictly so malformed input is rejected (c2ddeef)
• default RubricContent.text_property to None so rubrics save (7d8c950)
• docs: fix broken code example rendering in the BaseLlm.generate_content_async docs (ccd868a)
• don't forward the caller's abort signal to AgentTool runs on another event loop (6bbef14)
• drop a flushed live audio cache that could not be written (1da622c)
• drop MIME parameters from saved live audio filenames (8c513c9)
• eval: generate Agent Engine-compliant eval session IDs (4368d68), closes #6683
• evaluation: disable AFC in all LlmAsJudge judge requests (cc339e0), closes #7146
• evaluation: stop loading deprecated Vertex RAG on eval import (6854b88), closes #7415
• exclude thoughts from typed workflow node inputs (2d43701)
• expose trigger delivery id so tools can detect redeliveries (74cd0ef), closes #7322
• extract bucket name from eval_storage_uri when a path is given (490cfd7), closes #6881
• flows: keep tool sub-branch events out of the calling agent's LLM context (2e06fdc)
• flows: replay sub-branch interrupted tool calls when is_resumable is False (51dbf89)
• flows: unify decide_step_resume across resumable and non-resumable invocations (b591910)
• format code execution and capture custom metadata in BigQuery Agent Analytics telemetry (c4b9eaa)
• give failed migrations and deploy usage errors the right exit code (e896ecb)
• harden SetModelResponseTool fallback to prevent infinite loops (d185ca5)
• hide thoughts from nonverbose debug output (53cb763)
• honor auto_create_session in the /run_live websocket endpoint (4912a08)
• honor explicit None for audio transcription (c0f92f8), closes #6827
• include grounding metadata in hallucinations judge context (e5ee44e), closes #7157
• inherit usage_metadata when after_model_callback replaces response (8e386a9), closes #7451
• inject artifact text, not the Part repr, into instructions (cd5814e)
• install the exporters the cloud telemetry flags need (e54eba0)
• isolate dev deploy log and staging paths per invocation (25b8a18)
• keep auth credentials out of the caller's tool args (d8483a0), closes #7162
• keep every text part of an assistant message (b158f9f)
• keep GCS bookkeeping keys out of custom_metadata (1094775)
• keep Gemini thought signatures on streamed LiteLlm tool calls (3abea3e), closes #7438
• keep proxied file uploads inside the proxy (24f2a2e), closes #6722
• keep rejected saves out of in-memory artifact catalog (b1a3b7c), closes #7411
• keep SQLite session state numbers exact across updates (13787a5)
• keep streamed artifacts when a Task snapshot arrives mid-stream (71c4fd7), closes #6680
• keep text sent alongside a function response in ApigeeLlm (f5db310), closes #7475
• live: drop internal artifact parts from live history replay (f03d23d)
• live: invoke before_run and after_run plugin callbacks in run_node_live (8a93ce9)
• load artifacts removed by a rewind as None in file and GCS services (a116c22), closes #7482
• load custom services from the agent folder in single agent mode (f5b6b08)
• make adk eval --print_detailed_results invocation details readable (69c58ea)
• make the firestore session and memory services usable (b0ffa24), closes #7192
• match ExecuteBashTool allowlist on whole shell tokens (2a2364f)
• mcp: respect proxy environment variables in mTLS transport (3d11f9f)
• memory: skip credential exchange events when adding to Memory Bank (56a6842)
• name the missing pandas package in VertexAiExampleStore (6a38283)
• only enable the built-in agents when adk web is bound to loopback (eca36ac)
• preserve append order for tied timestamps in SqliteSessionService (f33343f)
• preserve context for invalid byte encodings in safe_json_loads (c5dca19)
• preserve field constraints in state validation (cc88d05)
• preserve history after filtered Redis reads (233e64c)
• raise SessionNotFoundError when appending to unknown Redis session (7d10709)
• raise ValueError instead of assert in Gemma model check (608ce2d), closes #7355
• read and write CLI text files as UTF-8 (d4e092e)
• record the artifact version the service assigns on rewind (ecb2230)
• redact non-oauth credential secrets from the auth request event (82af2ef)
• refuse the reserved tool name set_model_response (cc5d516), closes #7144
• request the cloud-platform scope for GCP OTel exporters (6be386d)
• require a boolean email_verified claim in GoogleOidcVerifier (4434070), closes #7289
• require oidc audience when trigger endpoints are enabled (b3ccb29)
• resume paused A2A tasks on ordinary user replies (539a0d0), closes #4934
• retain sessions for SQLite memory URIs (51a20e2), closes #7405
• return 403, not 500, for built-in agents on a non-loopback adk web (7e4407f)
• return 500 instead of 404 when an agent fails to load (65ab126)
• return long_running_tool_ids from message and artifact converters (7099ce4), closes #6988
• return structured error when RestApiTool is missing required path param (b930828), closes #7282
• reuse Vertex AI clients per event loop in session and memory (3f09197), closes #7353
• revert the 25-round tool cap on agents with output_schema and tools (e58293a)
• run a confirmed tool once per approval (bfdeb4a), closes #7434
• run after_run_callback when an aborted run is cancelled (d806a36)
• runners: resolve invocation_id from FunctionResponse when is_resumable is False (ea656b0)
• samples: use behavior instead of response_scheduling in non-blocking tool sample (ff75783)
• sanitize generated session IDs (3f474f4), closes #6435
• scripts: require a unit guide only for re-exported modules (1cd0a2a)
• send role 'tool' for Gemma-4 on OpenAI-compatible endpoints (7d190e6), closes #6482
• send the body for oneOf/anyOf/allOf OpenAPI request schemas (2036206), closes #6991
• serialize credential lifecycle by key (28be9c8), closes #6475
• serialize path, header, and cookie parameters and omit None values (b4cf70c), closes #7164 #7099
• serialize V1OwnerReference with wire names in GKE code executor (b9a2c05), closes #7443 #7444
• sessions: check user_id is not None instead of truthiness in SqliteSessionService.list_sessions (ac990df)
• skip a compaction that cannot shrink the request (36779a0)
• skip compaction instead of failing when summarization errors (5c54055)
• skip empty text parts in Anthropic message conversion (6e8546c), closes #6982
• skip ignored params' annotations on the legacy declaration path (62745cc), closes #7436
• stabilize unit tests in test_litellm and test_gke_code_executor (6aa1fdd)
• stage extra_packages for cloud_run and gke deployments (de1df98), closes #4980
• stop compaction failing on tool responses JSON cannot encode (d4f9eb1)
• stop double-counting cumulative cache invocation counters (1492ff7)
• stop dropping temperature and top_p on the interactions API (8e89a64)
• stop OAuth2 secrets from leaking over /run, /run_sse, /run_live, dev_server, and session endpoints (63aed55)
• stop orphaned function_call from permanently blocking compaction (3f34675), closes #7236
• stop partial tools colliding and send the call docstring (6a60d6a), closes #7190
• stop run_llm_agent_as_node mutating the shared node agent (60c4081)
• stop to_a2a from overriding the application's log level (7a50a85), closes #7462
• stringify enum values in legacy schema declarations (014f987), closes #6978
• strip embedded thought signature from LiteLLM tool call ids (be42798), closes #6742
• take the ADK user id only from an authenticated principal (d0c4060)
• telemetry: stop holding OTel context across async generator yields (10c694f)
• tolerate trailing slash on discovered OAuth2 issuer (c220fca), closes #7265
• tools: guard concurrent lazy initialization in ComputerUseToolset and EnvironmentToolset (15486db)
• tools: key NodeTool node runs by function call id (40edc5b)
• update session last_update_time on Vertex AI append_event (11d92d7), closes #7338
• use asyncio.sleep in PlaywrightComputer async methods (9c83a65)
• use card descriptions for initial routing (9311d6f), closes #4064
• use the project backend when generating eval scenarios (1135d7f)
• warn when session state is dropped (d2cb22e), closes #6854
• warn when the dev server binds a non-loopback address (ec7756b)
• workflow: avoid mutating LlmAgent.mode when resolving effective mode (666c26d)
• workflow: isolate parallel agent_states by node_path (19bc401)
• workflow: isolate single-turn workflow node events and contents by node path (097ae1e)
• workflow: rerun rerun_on_resume nodes as soon as any interrupt is resolved (5ee5cf8)
• workflow: support retry_config on dynamic node failures in NodeRunner (2b8b6d5)
• workflow: wait for all direct interrupts before rerunning rerun_on_resume nodes (bcac35a)
• workflow: wait for in-flight workers on HITL interrupt in ParallelWorker (531a86a)

Performance Improvements

• cut time to first model request by 40% in long sessions (1754b3e)
• flows: stop importing unused providers on the first LLM request (3c31fa5)

Documentation

• add guides and details for internal event metadata and ToolCallIntegrityPlugin (72f7c93)
• api: consider new fields under storage services as breaking changes (f03015c)
• changelog: remove false-positive breaking changes from v2.9.0 and v2.11.0 (d8dc299)
• correct Redis session retention and configuration defaults (0f6a3d5)
• fix docstring argument names that do not match signatures (865a6d6)
• fix eval and CLI docstrings that contradict the code (d56a994)
• refresh stale links and a broken sample in the repo docs (e0f8e2b)
• replace retiring model names in docstrings and skill references (5c2567c)
• samples: add Microsoft Teams notification sample (5d9cc1d)
• samples: enhance Model Consult sample README with inspection guide and architecture graph (8af4652)
• sessions: correct the rationale for InMemorySessionService event deduplication (20ee4a2)
• skills: document AgentMode and path/node builders in adk-style (262a8a4)
• skills: document internal metadata, test runners, and private wrapper nodes in adk-style (f84c432)
• skills: update the bigquery-ai-ml skill (cb9b8f7)

Miscellaneous Chores

• release as 2.12.0 (cfc5854)

[github-actions]

Release artifact check: PASS

Comparing 2.12.0 against 2.11.0.
Modules swept: 794 candidate, 775 baseline.

No module regressed against the baseline.

New modules that do not import (2)

Not a failure. New modules usually sit behind an optional extra, so this is expected on a bare install -- but a module that is meant to work without extras belongs on the list above, so it is worth a glance.

• google.adk.dependencies._agentplatform
  • ModuleNotFoundError: No module named 'agentplatform'
• google.adk.dependencies._agentplatform_frameworks
  • ModuleNotFoundError: No module named 'agentplatform'

No longer shipped (4)

• google.adk.cli.built_in_agents.sub_agents
• google.adk.cli.built_in_agents.sub_agents.google_search_agent
• google.adk.cli.built_in_agents.sub_agents.url_context_agent
• google.adk.cli.built_in_agents.tools.search_adk_knowledge