github google/adk-python v2.14.0
on GitHub

32 minutes ago

2.14.0 (2026-11-04)

Highlights

This release graduates execution environments, A2A, evaluation, and core runtime modules from experimental, adds multi-run evaluation and semantic tool argument matching, adds Microsoft Teams and OpenAI Decisions integrations, and makes long multi-turn workflows faster.

  • Execution environments and sandboxes:
    • BaseEnvironment, LocalEnvironment, EnvironmentToolset, DaytonaEnvironment, and E2BEnvironment are now stable. (c54b253, 799fc94)
    • BaseEnvironment.read_file_stream streams files in chunks across LocalEnvironment, E2BEnvironment, and DaytonaEnvironment so ReadFileTool reads line ranges without loading the whole file into memory. See the unit guide for more details. (fd8d8c1)
    • AgentEngineEnvironment reads and writes large files in chunks and reports commands over 570 seconds as timed out before the service deadline. See the unit guide and sample for more details. (4c88040, 5843c58, b13fa19, d3a199d)
    • ContainerCodeExecutor supports input and output files, and RunSkillScriptTool runs skill scripts from validated paths and arguments instead of a shell command string. (effd641, ff61524)
  • Evaluation:
    • MultiRunConfig (adk eval --num_runs) and --parallelism run each eval case multiple times concurrently and combine scores or pass rates across runs. See the eval config and agent evaluator guides for more details. (7f3517e, e9e8f61)
    • AgentEvaluator accepts a BaseNode or App built at runtime, and --eval_storage_uri stores eval files outside a read-only agents_dir. (ce92e92, ff66b1f)
    • ToolArgsMatcher compares tool call arguments in evaluations and EnvironmentSimulation using exact, case-insensitive, numeric-tolerance, or LLM-backed semantic checks. See the unit guide for more details. (ed76f94, 08c289b)
  • A2A: The A2A integration is now stable, and adk generate_agent_card builds an A2A agent card from the CLI. See the unit guide for more details. (95d4a56, 875e2ae)
  • Integrations:
    • TeamsRunner connects an ADK agent to Microsoft Teams chats and channels. See the unit guide for more details. (c4376a6)
    • OpenAIDecisionsClassifier classifies workflow and tool-gating questions with the OpenAI Decisions API. See the unit guide for more details. (aa98d18)
    • MongoDbMemoryService adds vector search retrieval (retrieval_mode="vector" or "auto") and TTL expiration (memory_ttl_days). See the unit guide for more details. (1c84bb9)
  • Stable APIs: 26 auth, environment, app, CLI and cache modules, 16 toolset and integration features, and the mature evaluation and user simulation classes graduate from experimental, so you can build on them without experimental warnings. (c54b253, 799fc94, 1112606)
  • Workflow performance: Long multi-turn workflows run faster and use less memory; a 30-node workflow's 200-turn run is 23% faster with 9% lower peak memory. (532580c, 1f21370)

Breaking changes

  • Enum tool arguments arrive as members: FunctionTool parameters annotated Enum, Optional[Enum], or list[Enum] now receive enum members instead of the raw strings the model sent (as FUNCTION_TOOL_ARG_VALIDATION already did). For a plain Enum, arg == "value", string-keyed dict lookups, match on strings, json.dumps, and string methods no longer work. A callable require_confirmation still receives the raw values (unless FUNCTION_TOOL_ARG_VALIDATION is on). For a (str, Enum), str() and, on Python 3.11+, f-strings now render Cls.MEMBER. Compare against members, use .value, or switch to StrEnum. Enum members a tool returns in its result are still sent to the model as their values. (82fe029, 58332a2)
  • VertexAiSessionService.create_session accepts only session config options: extra keyword arguments are limited to display_name, ttl, expire_time, and labels (plus camelCase aliases). Other Sessions API config keys, such as http_options, session_state, sessionId, and wait_for_completion, now raise ValueError (HTTP 400 when sent as session options to adk api_server). Use state= and session_id= for state and IDs. (968cd86)
  • RunSkillScriptTool no longer takes command in environment mode: with a SkillToolset environment, the model now passes args, short_options, and positional_args instead of a free-form shell command, scripts run from the skill directory instead of the environment working directory, and only .py, .sh, and .bash scripts are supported (others return UNSUPPORTED_SCRIPT_TYPE). Calls, eval sets, or prompts that pass command now return INVALID_ARGUMENTS. This closes a hole that let a prompt-injected model run arbitrary shell commands. (ff61524)

Behavior changes

  • /run_live now closes the socket with code 1007 on a malformed frame and 1000 when the run ends, instead of leaving it hanging; reconnect for each new live run instead of reusing an idle socket. (3b227d6)
  • OpenAPI tool query parameters now follow their declared style and explode. (1d81896)
  • DatabaseSessionService creates new PostgreSQL JSON columns as json instead of jsonb; existing jsonb tables are not migrated and keep working (the PostgreSQL sample README shows how to convert them). Queries outside ADK that rely on jsonb-only operators or GIN indexes will not work on new tables. (d487c53)
  • gen_ai.invoke_workflow.duration, gen_ai.client.operation.duration, and gen_ai.client.token.usage histograms now use the semconv bucket bounds. (ba45671)
  • An agent with an output_schema, no tools of its own, and a transfer target now gets the set_model_response tool instead of JSON mode on models that cannot combine a response schema with function calling, which adds two events per response. (73b6790)
  • Token-threshold compaction counts tool outputs since the last model call, so it fires earlier for an unchanged token_threshold. (a72a8ed)
  • A nested workflow whose terminal wait_for_output node is re-triggered into a new waiting run no longer surfaces that node's earlier output. (cddc57f)
  • New teams and fsspec extras, and the e2b floor is raised to 2.29.5. (c4376a6, 6bf806a, 75fb788)
  • FirestoreSessionService stores event payloads as JSON strings and wraps nested lists in app and user state. Existing sessions keep loading and accept new events, but sessions this version writes to cannot be read by 2.13.0 or earlier after a rollback. (0894c03)
  • The 16 toolset and integration features promoted to stable (Bigtable, Computer Use, Daytona and E2B environments, Environment Simulation, GCS, MCP agent server, Pub/Sub, Spanner, and others) are always available: ADK_DISABLE_<FEATURE>, override_feature_enabled(<FEATURE>, False), and --disable_features no longer block them, with no error or warning. (799fc94)
All changes

Features

  • a2a: graduate the A2A integration from experimental (95d4a56)
  • add --reload_agents flag to adk run for hot-reloading (4f8e4ae), closes #3679
  • add a2a agent card generation with the CLI (875e2ae)
  • add get_active_events helper function (3640e7d), closes #4959
  • allow McpToolset callers to receive MCP server notifications (9a5117b), closes #6385
  • artifacts: add experimental FsspecArtifactService with read and listing support (6bf806a)
  • avoid ReadFileTool OOM by streaming file reads (fd8d8c1), closes #7131
  • bigquery: make built-in BigQuery skills loadable and discoverable via get_bigquery_skill (665945d)
  • classifiers: add RefusalAnswer for questions a model declines (d45df6a)
  • classifiers: label requests made by classifiers (7bfe227)
  • cli: pip install wheels and installable packages passed to --extra_packages (e3d0ec9)
  • cli: support Python versions other than 3.11 in adk deploy images (bd77f3f)
  • eval: run each eval case N times in adk eval for steadier verdicts (7f3517e)
  • evaluation: graduate mature evaluation and user simulation classes from experimental (1112606)
  • expose active lifecycle hook metadata (2084efb), closes #6979
  • expose session rewind as a REST endpoint (b01c5ff), closes #7177
  • features: graduate 26 auth, environment, app, cli, and cache modules from experimental (c54b253)
  • features: promote 16 toolset and integration features to stable (799fc94)
  • integrations: add OpenAIDecisionsClassifier for the OpenAI Decisions API (aa98d18)
  • integrations: add TeamsRunner for Microsoft Teams (c4376a6)
  • integrations: add vector search retrieval to MongoDbMemoryService (1c84bb9)
  • let a plugin configure event compaction per session (9331638), closes #4132
  • let AgentEvaluator evaluate an agent built at runtime (ce92e92), closes #1792
  • let applications customize tool retry guidance (03b4fbc), closes #7564
  • live: save image frames when save_live_blob is set (3cd8742)
  • plugins: add flag to write content_formatter error details to BigQuery (0f15a83)
  • plugins: record workflow node observations in the BigQuery analytics plugin (c31856d)
  • plugins: support conversation_only eval view mode and session prompt fallback (5762ef8)
  • read large files from AgentEngineEnvironment in chunks (4c88040)
  • serialize prompt-cache creation tokens on LlmResponse (b89dda4)
  • store eval files outside a read-only agents_dir (ff66b1f), closes #3887
  • support configuring eval case parallelism in eval config and CLI (e9e8f61)
  • support input and output files in ContainerCodeExecutor (effd641)
  • support large file writes in AgentEngineEnvironment (5843c58)
  • telemetry: measure streaming latency of model calls (e0b812a)
  • telemetry: record inference token metrics for failed calls (7367645)
  • telemetry: record the semconv-genai inference token metrics under schema v2 (ad46719)
  • tools: add extensible tool argument matcher (ed76f94)
  • tools: add semantic argument matching to Environment Simulation injections (08c289b)
  • tools: preserve tool display titles on BaseTool, McpTool, and events (29956a8)

Bug Fixes

  • a2a: propagate task cancellation to active runner invocations (14765ab)
  • accept declared field names in set_model_response for aliased schemas (3700f0d)
  • accept pre-parsed dict in ToolConfirmation response wrapper (4666178), closes #7681
  • align gen_ai.choice system name with request model for LiteLLM (960cd5d), closes #7631
  • allow a missing screenshot in ComputerState's type (8f8e0c2)
  • allow opentelemetry-api and opentelemetry-sdk up to 1.45.2 (73ae69e), closes #7433
  • allow whole-file reads of empty files in ReadFileTool (2a0bffa)
  • always send the A2A-Version header from RemoteA2aAgent's own HTTP client (e44b316)
  • answer the coordinator when a task-mode remote agent fails (6c67240)
  • antigravity: extract subagent names from step tool calls and avoid root_agent_subagent fallback (491d7db)
  • apps: close LLM stream on early exit in LlmEventSummarizer (c15f249)
  • ask for re-authorization when the OAuth2 refresh token is revoked (70e1cbd), closes #7730
  • auth: support raw token strings in HTTP and API key auth resume (d324744)
  • avoid passing unknown alternate judge verdicts (4c66a00)
  • avoid unconditional blocking credential refresh in AgentRegistry (cb91239)
  • bigquery: improve error messages when write_mode is BLOCKED (5849762)
  • block internal ADK toggles and exec gadgets in YAML configs (1c7e8f7)
  • build skill script commands from validated paths and arguments (ff61524)
  • classify compaction failures with error.type (8038bd7)
  • classify stream-level non-retryable BigQuery write errors as non_retryable (bd38535)
  • cli: monitor ASGI receive channel for client disconnect in /run_sse (1fbe9e0)
  • close inner async generators across node _run_impl and skip compaction on early close (facd7dd)
  • close malformed live WebSockets instead of wedging them (3b227d6)
  • compact AgentTool nested history at caller token threshold (ae8323b), closes #7397
  • compaction: cancel in-flight summarization when invocation aborts (87d9dcd)
  • complete A2A task when the run recovers from an error (512d56b)
  • convert Enum tool arguments to the declared member (82fe029)
  • convert list[Enum] tool arguments to the declared members (58332a2)
  • copy initial state in InMemorySessionService.create_session (cec52fc)
  • count tool outputs since the last model call toward token threshold (a72a8ed)
  • declare the retrieval tool query parameter as required (5cc364b), closes #7677
  • decode base64 bytes in rehydrated workflow node outputs (81c3fe6)
  • disambiguate colliding connector tool names in ApplicationIntegrationToolset (f08f9d6)
  • don't score a judge response that leaves a rubric without a verdict (d1f2add)
  • don't write shared state for a rejected duplicate Redis session (c501d8e), closes #7816
  • drop per-invocation retry counts when an invocation ends (42a8a87), closes #7637
  • drop temp: state keys in VertexAiSessionService.create_session (da4af77), closes #7818
  • eval: preserve live usage without extra inference calls (8cd3b12), closes #7321
  • exclude replayed nodes from workflow max_concurrency count (adc2433), closes #7618
  • exclude thought parts from SQLite memory search results (de34d8d), closes #7688
  • exclude thought text from preloaded memories (b138b5a)
  • export all shipped plugins from google.adk.plugins (4496bef)
  • filter hidden artifacts from LLM context (0c053dd), closes #6873
  • find CJK and Thai words inside a sentence in sqlite memory (f8ced6f), closes #7959
  • flows: elide system instruction markers from relayed agent text (cbe7c5e)
  • flows: run on_model_error callbacks when a model call is cancelled (36cb10d)
  • give ModelArmorPlugin its own client on each event loop (c9d2c48), closes #7644
  • handle an expired OAuth2 token that has no refresh token (cbe786b), closes #7728
  • handle non-UTF-8 avatar configuration files (27dda3e)
  • harden callable type hint resolution and FunctionNode TypeAdapter handling (da35ca7)
  • hold the SQLite write lock across the SqliteSessionService stale check (bc0b418)
  • honor query parameter style and explode (1d81896), closes #7204
  • honor tool_config function calling mode in AnthropicLlm (da786ed), closes #7633
  • ignore thought parts when scoring response_match_score (571670d)
  • keep a node's branch when it relays sub-agent events (27edb47)
  • keep a wildcard allow_origins off the builder and internal agents (b7ac5ef)
  • keep a2a converters utils importable without the a2a extra (f3fcccd)
  • keep content and errors when a workflow node delegates its output (efec445), closes #7949
  • keep create_session state when rewinding a session (dfd534a), closes #4933
  • keep in-memory artifact scopes separate when identifiers contain / (27cdf7f), closes #7706
  • keep partial events out of Agent Engine storage (3a6b7a5), closes #7828
  • keep rejected saves out of the FileArtifactService catalog (2cabbdd), closes #7832
  • keep span status and events in SqliteSpanExporter (28743ec), closes #7484
  • keep streamed ApigeeLlm tool call chunks without an index together (d563d80)
  • keep the keys beside result in a Responses tool output (9c45214), closes #7836
  • keep the model's thoughts out of to_mcp_server results (9688feb), closes #7834
  • keep the streamed thought signature on its own part (a9cabe7)
  • keep thought parts out of FirestoreMemoryService (af371b7)
  • keep thought parts out of Memory Bank events (4fae7b7), closes #7850
  • keep turns a rewind took back out of long-term memory (2591397), closes #7570
  • leave no-usage turns out of the token_usage_v1 average (5e52b21), closes #7734
  • list built-in tools in the rubric multi-turn trajectory evaluator (0478150)
  • live: drop saved audio from history replayed to the CascadeLive reasoner (50ab3b5)
  • live: log live event and request identifiers instead of contents (6582001)
  • live: make CascadeLive reply to history that ends with a user turn (e4a824f)
  • load AgentDetails tool declarations back as genai Tools (4255760), closes #7876
  • map Anthropic model_context_window_exceeded to MAX_TOKENS (cd72afa)
  • mark failed A2A tasks as error events (25d1917), closes #6708
  • mark failed MCP tool results as errors for Claude (37b1ab3), closes #7664
  • mark failed MCP tool results as errors on the interactions API (72205cd)
  • match SKILL.md frontmatter delimiters as whole lines (25105b4), closes #7725
  • normalize array-tail schema types (3a5bbd2)
  • only reject Firestore ids fully matching .* (e533f55), closes #7855
  • pass raw argument values to a callable require_confirmation (504d5d1)
  • pass the caller's temp: state to an AgentTool's wrapped agent (12c7bed), closes #7595
  • plugins: prevent BQAA offload data loss and preserve binary MIME (14236ff), closes #7868
  • present the mTLS client certificate from RemoteA2aAgent's default client (d2ae901)
  • preserve empty environment simulation responses (dcbeb54)
  • preserve non-UTF-8 bytes in EditFileTool (e3d1594), closes #7314
  • preserve span kinds in SQLite traces (ebec2c8)
  • preserve split Unicode surrogate pairs (0af1cdc)
  • preserve union arguments when exporting MCP tool schemas (ce4e0c4)
  • preserve workflow routes when flushing and delegating output (af6f671), closes #7930
  • prevent file truncation on invalid write_file content (611b8e7)
  • read interaction errors list on failed interactions (1a5a36d)
  • read Workflow.graph when drawing the dev UI graph (e5b7dc8), closes #7528
  • reap ADK sessions of dead MCP connections in to_mcp_server (17fb8af), closes #7154
  • record an invocation when an agent turn yields no events (94eb6c4)
  • record inference token metrics under google-genai instrumentor 0.7b2 (eb20e15)
  • reject model-supplied urls with a backslash in the authority (4d0cd98)
  • reject names with a trailing newline (e2e9336)
  • reject non-identifier or keyword agent names in adk create (3655990)
  • reject path-breaking identity ids in FirestoreSessionService (ec9756e), closes #7800
  • report a LiteLlm stream without a finish reason as truncated (f1f63d3)
  • report long-running AgentEngineEnvironment commands as timed out (b13fa19)
  • report truncated Apigee tool calls as max tokens (3638d76), closes #7648
  • report unreadable SKILL.md files to on_error (da98d4d)
  • report unusable LiteLlm tool call arguments as malformed (d5ecb99), closes #7802
  • resolve nested models in legacy function declarations (392feb2), closes #6984
  • restrict VertexAiSessionService.create_session config options (968cd86)
  • return AgentTool input_schema validation errors to the model (95dd267)
  • run LlamaIndexRetrieval lookups off the event loop (bc291ab), closes #7674
  • runner: close isolated runs that end on a terminal node outcome (471341f)
  • runner: key finished isolation scopes by invocation id (8d7445d)
  • runner: seal tool calls on task cancel and unify runner teardown (abd8f0f)
  • runner: skip abort seal when a newer turn has updated the session (7414308)
  • scope cached Eventarc publisher clients per running event loop (c77b5b4)
  • send a JSON-safe state_delta from VertexAiSessionService (f6325bc), closes #7826
  • send Enum members in tool results as their values (3f5b30e)
  • send the request's headers when loading MCP resources (28d4975), closes #7822
  • send the thinking level on the interactions API (c20b90a), closes #7924
  • serialize DatabaseSessionService writes on SQLite files (c3abc93)
  • serialize Firestore event payloads and wrap nested state arrays (0894c03)
  • serialize Gemma 3 tool results that hold datetimes, bytes or models (2b84cca), closes #7667
  • sessions: base64-encode non-UTF-8 bytes in JSON state serialization (73dca84)
  • sessions: encode binary bytes as base64 in session state (d91dd34)
  • set error.type on spans that end in an error (a96fc11), closes #7494
  • share the parent's memory service with AgentTool sub-agents (4e0ac64)
  • skip storage writes for partial events in RedisSessionService (7662758)
  • skip the MCP mTLS probe unless google-auth would use a client cert (0e5d6c9)
  • split CJK sentences in ElevenLabsTTS (0fe80f1)
  • stamp the model response event when finalizing it (1e63423), closes #7695
  • stop a session id from replacing sessionless in-memory memories (b8d69f8), closes #7711
  • stop a slow resumed node from timing out replayed siblings (3565ad3)
  • stop list_sessions(user_id="") from listing every user in Firestore (b981250), closes #7662
  • stop LiteLlm from running tool calls quoted in answer text (6b00a38)
  • stop McpTool falling back to HTTP auth on an empty OAuth2 token (83acbc5), closes #7646
  • stop rerunning a finished node when a later interrupt resumes (d0c3af5)
  • stop running truncated Claude tool calls (b9d2bc3)
  • store DatabaseSessionService JSON columns as json on PostgreSQL (d487c53)
  • store non-ASCII session JSON unescaped on SQLite (bdb1ced)
  • strip the JSON code fence when replaying schema output on resume (f4fa73e)
  • support deepcopy and pickling in AgentEngineSandboxCodeExecutor (d60c870)
  • take final input and cache counts from Anthropic message_delta (329933f)
  • telemetry: give every gen_ai duration and token histogram bucket bounds (ba45671)
  • telemetry: record the aggregated answer of a streamed inference, not its chunks (80a4411)
  • tracing: extract standard W3C traceparent and baggage headers on FastAPI requests (f27b8f1), closes #7844
  • treat after_timestamp=0 as a filter in session services (6b182d8)
  • treat an empty session id as absent in DatabaseSessionService (1a337ca)
  • unwrap PEP 604 optional parameters in BaseTool.from_config (19e3d5b), closes #7840
  • use set_model_response for output_schema agents that can transfer (73b6790), closes #7717
  • use the continue URI and scopes from Agent Registry bindings (a81df0e)
  • validate skill_id path segments before GCS blob lookup (7394fba)
  • wait for pending event appends before retrying a node (3b74a99), closes #7524
  • workflow: keep JoinNode in a loop firing after the first iteration (b6600be)
  • workflow: never retry configuration or invariant errors and add policy helpers (c4b2640)
  • workflow: retry a failed parallel worker item instead of the batch (a9714ec)
  • wrap class descriptors from dict (2de5876), closes #6980

Performance Improvements

  • cut a 30-node workflow's 200-turn run by 23% (532580c)
  • cut a 30-node workflow's peak memory by 9% (1f21370)
  • handle workflow node paths and branches as plain strings (ba8905a)
  • skip the rewind pass for a workflow node with no events (073b005)
  • skip three event-history scans when nothing can match (0ea43cc)
  • skip two per-turn history scans in an LLM agent node (e34f126)

Documentation

  • add security section to MongoDB integration README (1f49e28)
  • add unit guides for the app container, the runner and events (2147ef8)
  • add unit guides for writing tools and toolsets (09ab726)
  • agents: update ManagedAgent examples and tests to antigravity-preview-09-2026 (3fbf2b5)
  • disable all content paths in the telemetry admin lock recipe (34750dc)
  • guides: add LlmClassifier unit guide (6c20444)
  • guides: add TypesafeClassifier unit guide (48d18a6)
  • samples: add an AgentEngineEnvironment sample agent (d3a199d)
  • say ContainerCodeExecutor runs as the image's user, not non-root (7a64c7c), closes #7712
Check out latest releases or
releases around google/adk-python v2.14.0

Don't miss a new adk-python release

NewReleases is sending notifications on new releases.

Get notifications