← Frameworks

Google ADK（Agent Development Kit）Google ADK（Agent Development Kit）

Google

PythonPython TypeScriptTypeScript 开源Open source Apache-2.0Apache-2.0 编排框架Orchestration framework 图执行Graph execution 工作流Workflows 多AgentMulti-agent HITLHITL 工具确认Tool confirmation evaleval CloudRunCloudRun MCPMCP partial lifecycle: active 核验Checked 2026-10-23

一句话说清它是什么：

Google ADK 是「code-first 的 agent 编排框架，核心资产是一个图执行引擎」。它的作用是把多个 agent 组织成一条流程，不替你跑单个 agent。

官方 README 的第一项特性就说明了它的身份：

Workflow Runtime: A graph-based execution engine for composing deterministic execution flows for agentic apps, with support for routing, fan-out/fan-in, loops, retry, state management, dynamic nodes, human-in-the-loop, and nested workflows.

What it is, in one line: Google ADK is a "code-first agent orchestration framework whose core asset is a graph execution engine". It organises several agents into one flow; it does not run a single agent for you.

The official README states its identity in the first feature it lists:

Workflow Runtime: A graph-based execution engine for composing deterministic execution flows for agentic apps, with support for routing, fan-out/fan-in, loops, retry, state management, dynamic nodes, human-in-the-loop, and nested workflows.

适合与不适合When to use it, when not to

适合：

要把多个 agent 组织成有分支、有循环、有人工介入的确定性流程
要 code-first 定义逻辑，便于测试与版本管理
团队在 Google 生态内
需要内建 eval 与开发 UI

不适合：

只跑单个 agent、不需要图结构 —— 用 OpenAI Agents SDK 更轻
需要文件级 / 网络级沙箱边界，但不想自己实现 —— 官方未提供沙箱
长上下文压缩依赖 1.16+ 的 Context Compaction（滑动窗口）

Fits: organising multiple agents into deterministic flows with branches, loops and human intervention; defining agents and tools code-first so they are testable and versionable; a team inside the Google ecosystem (Cloud Run / Vertex / Gemini); needing built-in eval and a development UI; wanting one framework across Python and TypeScript; needing tool-level human confirmation, session persistence and resume. Not a fit: running a single agent with no graph structure (OpenAI Agents SDK or Deep Agents are lighter); needing built-in file- or network-sandbox boundaries — the official docs provide none, so file access goes through the Artifacts abstraction or a tool you wire up yourself; wanting self-hosted weights out of the box without going through the LiteLLM adaptor layer.

中文生态China availability 国产 / 国内可直接用 / 备案状态 · 快照domestic / direct access / CAC filing · snapshot 2026-10-20

出品属地Origin: 国外出品foreign-made　国外主体（网信办公示名单未见对应备案主体）。foreign entity (no matching filing entity in the CAC registry).
国内使用Direct access: 大陆可直连direct OK　官网 adk.dev 直连实测 200。adk.dev measured 200 direct.
备案状态CAC filing: 未见于备案名单not in filing list：未见于网信办公示名单（2026-10-20 检索 13 批附件，https://www.cac.gov.cn/2024-04/02/c_1713729983803145.htm）；该产品未面向大陆公众提供服务，备案不适用。not in the CAC public registry (13 batch attachments searched 2026-10-20, https://www.cac.gov.cn/2024-04/02/c_1713729983803145.htm); the product does not serve the mainland public, so filing does not apply.

备案信息以网信办《生成式人工智能服务已备案信息》公示名单为准（按批次滚动更新，本站只抄编号不解读）；「大陆可直连」是本站从大陆网络直连实测的结果，不是厂商承诺。GitHub 类站点当日实测有波动，口径写在依据里。Filing status is quoted from the CAC public registry (updated batch by batch; this site copies the number and does not interpret it). "Direct access" is this site's own reachability measurement from a mainland network, not a vendor promise. GitHub-hosted sites fluctuated on the measurement day — the note says so.

固定坐标系Fixed coordinate system

8 个维度dimensions, 与同分区其他对象逐项可比each comparable item by item against others in the same section.

模型与开放条件Model & openness: 官方口径：为 Gemini 优化，但它同时是 model-agnostic。

README 原文："While optimized for Gemini, ADK is model-agnostic, deployment-agnostic, and compatible with other frameworks."

所以非 Gemini 模型能接。 官方「Models for Agents」页给出三条接入机制：

① 直接字符串 / 注册表 —— Gemini、Claude、Agent Platform 托管模型
② model connectors —— LiteLlm / ApigeeLlm 包装类
③ 模型路由 —— 运行时动态选型 + 出错自动切换

官方原文："providing a standardized, OpenAI-compatible interface to over 100+ LLMs"

本地 / 自托管模型有官方专页：Ollama、vLLM、LiteRT-LM。

⚠ 官方未说明："optimized for Gemini" 优化了什么。

⚠ 也未给出非 Gemini 模型下工具调用与 structured output 的可靠性对比。已查 Models 页与 LiteLLM 页。
Official line: optimized for Gemini, but it is also model-agnostic.

README verbatim: "While optimized for Gemini, ADK is model-agnostic, deployment-agnostic, and compatible with other frameworks."

So non-Gemini models can be connected. The official "Models for Agents" page gives three integration mechanisms:

① direct string / registry — Gemini, Claude, Agent Platform hosted models
② model connectors — LiteLlm / ApigeeLlm wrapper classes
③ model routing — runtime dynamic model selection + automatic failover

Official wording: "providing a standardized, OpenAI-compatible interface to over 100+ LLMs"

Local / self-hosted models have dedicated official pages: Ollama, vLLM, LiteRT-LM.

⚠ Not stated officially: what "optimized for Gemini" actually optimizes.

⚠ Nor is there a reliability comparison of tool calling and structured output under non-Gemini models. Checked: the Models page and the LiteLLM page.
运行位置Where it runs: 四种运行形态，全部由 adk CLI 或容器提供（README 核验）。

① 交互式 CLI —— adk run <agent-folder>
② 内建 Web UI —— adk web <agent-folder>。官方说明支持 multi-agent directories 或直接指向单个 agent 文件夹

③ Development UI —— 内建的开发调试台
④ 容器化部署 —— adk deploy docker --with_ui <agent-folder>

官方原文："A built-in development UI to help you test, evaluate, debug, and showcase your agent(s)"

⚠ 这四种都是你本地或你的云上进程。ADK 本身不提供托管服务。

托管要靠 Vertex AI Agent Engine 或 Cloud Run —— 那是 Google 的产品，不是本框架的。
Four run forms, all provided by the adk CLI or containers (README verified).

① interactive CLI — adk run <agent-folder>
② built-in Web UI — adk web <agent-folder>. The official docs state support for multi-agent directories or pointing directly at a single agent folder

③ Development UI — the built-in development/debug console
④ containerized deployment — adk deploy docker --with_ui <agent-folder>

Official wording: "A built-in development UI to help you test, evaluate, debug, and showcase your agent(s)"

⚠ All four are your local or your cloud processes. ADK itself provides no hosted service.

Hosting requires Vertex AI Agent Engine or Cloud Run — those are Google products, not this framework's.
本地文件Local files: 官方对「文件」的答案是抽象层 Artifacts，不是裸文件系统（已核验）。 换句话说，它自己不读写磁盘。

官方 Artifacts 页原文：

官方原文：Artifacts "represent a crucial mechanism for managing named, versioned binary data associated either with a specific user interaction session or persistently with a user"

落盘位置由你选的 ArtifactService 决定。 官方原文："Their storage and retrieval are managed by a dedicated Artifact Service"

两个后端：

InMemoryArtifactService —— 重启即丢
GcsArtifactService —— 持久、带版本

ADK 是库，不内置 Read/Write/Bash 这类文件工具。 磁盘访问要靠自己写 function tool，或接 MCP。官方 MCP 页示例正是 filesystem MCP server。

⚠ 官方未提供沙箱机制或文件系统权限模型（已查 Artifacts、tools、deploy 各页）。默认访问边界取决于你自己接的工具。
The official answer to "files" is the abstraction layer Artifacts, not the raw filesystem (verified on 2026-10-08). In other words, it does not read or write disks itself.

Official Artifacts page verbatim:

Official wording: Artifacts "represent a crucial mechanism for managing named, versioned binary data associated either with a specific user interaction session or persistently with a user"

Where things land is decided by the ArtifactService you choose. Official wording: "Their storage and retrieval are managed by a dedicated Artifact Service"

Two backends:

InMemoryArtifactService — lost on restart
GcsArtifactService — persistent, versioned

ADK is a library; it does not ship Read/Write/Bash style file tools. Disk access means writing your own function tool, or connecting MCP. The official MCP page example is exactly a filesystem MCP server.

⚠ Not provided officially: any sandbox mechanism or filesystem permission model (Artifacts, tools, deploy pages checked). The default access boundary depends on whatever tools you connect.
关机后的任务Tasks after shutdown: 它不托管后台。官方有两条明确证据：会话 / 状态持久化，以及中断续跑（Resume）。

① 持久化 —— SessionService 分三档：

InMemorySessionService —— 官方原文： "All conversation data is lost if the application restarts"

DatabaseSessionService —— "Data survives application restarts"
VertexAiSessionService —— 托管

MemoryService 另有 InMemory 与 Vertex AI Memory Bank 两档。

② 续跑 —— ADK Python 1.16+ 可给 App 配 ResumabilityConfig(is_resumable=True)。

官方原文：

官方原文："allows an agent workflow to pick up where it left off"

用 Invocation ID 恢复。经 /run_sse 或 runner.run_async 都可以。

ADK 本身是库、不托管。 真后台要靠部署到 Cloud Run / Vertex AI Agent Engine —— 那是你的云资源。

⚠ 官方两条边界：

Resume 目前 "not currently supported" 从 Web UI / CLI 触发
工具可能被重复执行（官方提醒有副作用的工具要自己防重）
It does not host a background. The official docs give two explicit pieces of evidence: session/state persistence, and resume-after-interruption.

① Persistence — SessionService comes in three tiers:

InMemorySessionService — official wording: "All conversation data is lost if the application restarts"

DatabaseSessionService — "Data survives application restarts"
VertexAiSessionService — hosted

MemoryService separately has InMemory and Vertex AI Memory Bank tiers.

② Resume — ADK Python 1.16+ can configure an App with ResumabilityConfig(is_resumable=True).

Official verbatim:

Official wording: "allows an agent workflow to pick up where it left off"

Resume by Invocation ID. Works via /run_sse or runner.run_async.

ADK itself is a library and hosts nothing. A true background means deploying to Cloud Run / Vertex AI Agent Engine — that is your cloud resource.

⚠ Two official boundaries:

Resume is currently "not currently supported" triggered from the Web UI / CLI
tools may be re-executed (the official docs remind: side-effectful tools need your own dedup)
工具与扩展Tools & extensions: 工具生态是它最强调的部分，MCP 在官方文档里是一等能力。

README 原文：

"Utilize pre-built tools, custom functions, OpenAPI specs, MCP tools or integrate existing tools"

官方另有专门的 MCP tools 文档页。它给出 McpToolset 类，且是双向的：

让 ADK 作 MCP 客户端，接外部 MCP server （示例含 filesystem / Google Maps MCP server）

也能把 ADK 工具包成 MCP server 对外暴露
传输覆盖 stdio 与 Streamable HTTP

工具级人工确认（HITL） 官方原文："a tool confirmation flow (HITL) that can guard tool execution with explicit confirmation and custom input"

对应文档 tools/confirmation。机制细节见 permissions 轴。

这是本站已收录对象里少见的「工具级人工确认」。 它与 OpenAI Agents SDK 的 input/output guardrail 是不同层次的东西。
The tool ecosystem is what it emphasizes most, and MCP is a first-class capability in the official docs.

README verbatim:

"Utilize pre-built tools, custom functions, OpenAPI specs, MCP tools or integrate existing tools"

There is also a dedicated MCP tools documentation page. It provides the McpToolset class, and it is bidirectional:

let ADK act as an MCP client, connecting external MCP servers (examples include filesystem / Google Maps MCP servers)

ADK tools can also be wrapped as an MCP server and exposed outward
transports cover stdio and Streamable HTTP

Tool-level human confirmation (HITL) Official wording: "a tool confirmation flow (HITL) that can guard tool execution with explicit confirmation and custom input"

Corresponding doc tools/confirmation. Mechanism details in the permissions axis.

This is a rare "tool-level human confirmation" among objects collected on this site. It is a different layer from the OpenAI Agents SDK's input/output guardrail.
上下文与记忆Context & memory: 官方对 session / memory 有清晰区分，且有专门的上下文压缩特性。

官方 sessions 页三句 官方原文：Session 是 "single, ongoing interaction"， State 是 "data within the current conversation"， Memory 是 "searchable, cross-session information"

前两者由 SessionService 管。长期知识由 MemoryService 管。

压缩：ADK Python 1.16.0+ 提供 Context Compaction。官方原文："reduce the size of context as an agent is running by summarizing older parts of the agent workflow event history"

机制是滑动窗口：

配 EventsCompactionConfig(compaction_interval, overlap_size)
到阈值即摘要更早的 event
summarizer 可换模型

⚠ 按本站「状态 ≠ 上下文」：state 管流程数据。 Compaction 管历史压缩。这是两套机制，官方也分开描述。
The official docs draw a clear distinction among session / memory, and there is a dedicated context-compaction feature.

Three sentences on the official sessions page, official wording: Session is "single, ongoing interaction", State is "data within the current conversation", Memory is "searchable, cross-session information"

The first two are managed by SessionService. Long-term knowledge is managed by MemoryService.

Compaction: ADK Python 1.16.0+ provides Context Compaction. Official wording: "reduce the size of context as an agent is running by summarizing older parts of the agent workflow event history"

The mechanism is a sliding window:

configure EventsCompactionConfig(compaction_interval, overlap_size)
at the threshold, earlier events get summarized
summarizer can swap models

⚠ Per this site's "state ≠ context": state governs flow data. Compaction governs history compression. These are two mechanisms, and the official docs describe them separately.
权限与限制Permissions & limits: 官方明确的机制是「工具级人工确认」Tool Confirmation（HITL）。

文档 tools/confirmation（v1.14.0 起，标注 Experimental）官方原文："allows an ADK Tool to pause its execution and interact with a user or other system for confirmation"

两种用法已核验。

① 简单确认 —— FunctionTool(..., require_confirmation=True) 要一次 yes/no；也可传入返回布尔值的函数（如"金额 > 1000 才问"）

② 高级确认 —— tool_context.request_confirmation(hint, payload)。可暂停工具、收集结构化数据（如审批天数）后再续跑

无 UI 时可以用 ADK server 的 /run 或 /run_sse REST 端点远程确认。

这只是「执行前问一下」，不是边界划定。 官方未提供沙箱或文件系统权限模型。已查 confirmation、Artifacts、deploy 各页。

⚠ 官方已知限制：DatabaseSessionService 与 VertexAiSessionService 不支持该特性。
The officially explicit mechanism is tool-level human confirmation, Tool Confirmation (HITL).

Doc tools/confirmation (since v1.14.0, labeled Experimental) official wording: "allows an ADK Tool to pause its execution and interact with a user or other system for confirmation"

Two usage styles verified.

① simple confirmation — FunctionTool(..., require_confirmation=True) asks once yes/no; you can also pass a function returning a boolean (e.g. "only ask when amount > 1000")

② advanced confirmation — tool_context.request_confirmation(hint, payload). Can pause the tool, collect structured data (e.g. approval days) and then resume

Without a UI, the ADK server's /run or /run_sse REST endpoints allow remote confirmation.

This is only "ask before executing", not boundary-setting. The official docs provide no sandbox or filesystem permission model. Checked: confirmation, Artifacts, deploy pages.

⚠ Official known limitation: DatabaseSessionService and VertexAiSessionService do not support this feature.
适合什么任务Best for: 适合这些情况。

要把多个 agent 组织成有分支、有循环、有人工介入的确定性流程
要用代码优先（code-first）定义 agent 与工具，便于测试与版本管理
团队在 Google 生态内（Cloud Run / Vertex / Gemini）
需要内建 eval 与开发 UI
希望用同一套框架覆盖 Python 与 TypeScript
需要工具级人工确认、会话持久化与中断续跑

不适合这些情况。

只跑单个 agent、不需要图结构 —— 用 OpenAI Agents SDK 或 Deep Agents 更轻
需要框架内置的文件 / 网络沙箱边界 —— 官方未提供。文件访问靠 Artifacts 抽象或自接工具

想开箱即用接自托管权重，又不愿经 LiteLLM 适配层
Fits these cases.

organizing multiple agents into a deterministic flow with branching, loops and human intervention
defining agents and tools code-first, for testability and version control
teams inside the Google ecosystem (Cloud Run / Vertex / Gemini)
needing built-in eval and a development UI
wanting one framework covering both Python and TypeScript
needing tool-level human confirmation, session persistence and resume-after-interruption

Does not fit these cases.

running a single agent only, no graph structure needed — OpenAI Agents SDK or Deep Agents are lighter
needing framework-built file / network sandbox boundaries — not provided officially. File access relies on the Artifacts abstraction or tools you connect yourself

wanting out-of-the-box self-hosted weights without going through the LiteLLM adapter layer

头号误解Top misconception

以为是「Google 版 OpenAI Agents SDK」—— 它是编排框架，核心资产是 Workflow Runtime 的图执行引擎，不是单 agent 原语Assuming it is "Google's version of the OpenAI Agents SDK" — it is an orchestration framework whose core asset is the Workflow Runtime graph engine, not single-agent primitives
把 state management 读成「有上下文管理」—— 前者是流程状态；后者是独立的 Context Compaction 机制（1.16+）Reading state management as "has context management" — the former is process state; the latter is the separate Context Compaction mechanism (1.16+)
把 MCP 当成它的核心依赖 —— README 只把 MCP 列为工具来源之一，与 OpenAI Agents SDK 把 mcp>=1.19.0 放进 dependencies 不是一回事Treating MCP as a core dependency — the README lists MCP only as one tool source, which is not the same as OpenAI Agents SDK putting mcp>=1.19.0 in dependencies
以为 Tool Confirmation 等于沙箱 —— 它是「执行前问一句」，不是边界划定Assuming Tool Confirmation equals a sandbox — it is "ask once before running", not a boundary
以为开源免费等于零成本 —— Cloud Run / Vertex Agent Engine 的云费用自理，且有 GOOGLE_GENAI_USE_ENTERPRISE 开关Assuming open source and free means zero cost — Cloud Run / Vertex Agent Engine costs are yours, and there is a GOOGLE_GENAI_USE_ENTERPRISE switch
以为只有 Python —— 还有独立的 TypeScript 仓（google/adk-js，1,426★），本站按粒度只收录 Python 主体Assuming it is Python-only — there is a separate TypeScript repo (google/adk-js, 1,426★); the Python body is the only thing indexed here
搞混仓库名 —— 样例仓显示为 google/adk-recipes，描述里写的是 adk-samplesMixing up repo names — the sample repo shows as google/adk-recipes while the description says adk-samples

未知项清单Known unknowns

默认沙箱机制、文件系统权限模型、网络访问控制
跨进程、跨机的任务续跑与恢复粒度
分布式部署下的状态存储方案
MCP 接入的实现层次（框架级依赖 vs 工具来源）
Python 与 TypeScript 版的能力对齐度
Vertex AI Agent Engine 部署时状态的托管方式
Gemini 单价与 Vertex AI Agent Engine / Cloud Run 的实际费率（GOOGLE_GENAI_USE_ENTERPRISE 的含义已核验，费率未核验）
"optimized for Gemini" 具体优化了什么（官方未说明，已查 Models 页与 LiteLLM 页）
非 Gemini 模型下工具调用与 structured output 的可靠性对比（官方未给出）

Default sandbox mechanism, filesystem permission model, network access control
Cross-process, cross-machine task resume and recovery granularity
State-storage schemes under distributed deployment
The implementation layer of MCP integration (framework-level dependency vs tool source)
Capability alignment between the Python and TypeScript editions
How state is hosted when deploying to Vertex AI Agent Engine
Gemini unit prices and the actual rates of Vertex AI Agent Engine / Cloud Run (the meaning of GOOGLE_GENAI_USE_ENTERPRISE is verified; the rates are not)
What exactly "optimized for Gemini" optimizes (not stated officially; Models page and LiteLLM page checked)
Tool-calling and structured-output reliability comparison under non-Gemini models (not given officially)

证据来源Evidence sources

判断可回到以下一手源复核。本站核验日Every judgement can be rechecked against the primary sources below. Verified on 2026-10-23，内容更新日content updated on 2026-10-01。

类型Type	名称Name	链接Link
repo	google/adk-python · 仓库（21,966★，Apache-2.0，滚动核验 2026-10-23）google/adk-python · repository (21,966★, Apache-2.0, rolling check 2026-10-23)	https://github.com/google/adk-python
docs	主 README（Workflow Runtime / Task API / Tool Confirmation / 部署方式 / eval）Main README (Workflow Runtime / Task API / Tool Confirmation / deployment methods / eval)	https://github.com/google/adk-python/blob/main/README.md
docs	官方文档首页Official docs home	https://google.github.io/adk-docs/
docs	官方文档 · Tool Confirmation（HITL）（require_confirmation / request_confirmation 机制、Experimental、已知限制，核验 2026-10-08）Official docs · Tool Confirmation (HITL) (require_confirmation / request_confirmation mechanism, Experimental, known limits, verified 2026-10-08)	https://google.github.io/adk-docs/tools/confirmation/
docs	官方文档 · Models for Agents（三条模型接入机制：直接注册表 / model connectors / 模型路由，核验 2026-10-08）Official docs · Models for Agents (three model-integration mechanisms: direct registry / model connectors / model routing, verified 2026-10-08)	https://google.github.io/adk-docs/agents/models/
docs	官方文档 · LiteLLM connector（`LiteLlm` 包装类，OpenAI-compatible，over 100+ LLMs，核验 2026-10-08）Official docs · LiteLLM connector (`LiteLlm` wrapper class, OpenAI-compatible, over 100+ LLMs, verified 2026-10-08)	https://google.github.io/adk-docs/agents/models/litellm/
docs	官方文档 · Sessions & Memory（Session/State/Memory 区分、SessionService 三档持久化，核验 2026-10-08）Official docs · Sessions & Memory (Session/State/Memory distinction, SessionService three-tier persistence, verified 2026-10-08)	https://google.github.io/adk-docs/sessions/
docs	官方文档 · Context Compaction（滑动窗口摘要，v1.16.0+，核验 2026-10-08）Official docs · Context Compaction (sliding-window summarization, v1.16.0+, verified 2026-10-08)	https://google.github.io/adk-docs/context/compaction/
docs	官方文档 · Artifacts（ArtifactService、InMemory/GCS 落盘，核验 2026-10-08）Official docs · Artifacts (ArtifactService, InMemory/GCS storage, verified 2026-10-08)	https://google.github.io/adk-docs/artifacts/
docs	官方文档 · Resume stopped agents（ResumabilityConfig、Invocation ID 续跑，核验 2026-10-08）Official docs · Resume stopped agents (ResumabilityConfig, resume by Invocation ID, verified 2026-10-08)	https://google.github.io/adk-docs/runtime/resume/
docs	官方文档 · MCP tools（McpToolset、ADK 作 MCP 客户端 / ADK 工具暴露为 MCP server，核验 2026-10-08）Official docs · MCP tools (McpToolset, ADK as MCP client / ADK tools exposed as MCP server, verified 2026-10-08)	https://google.github.io/adk-docs/tools/mcp-tools/
docs	官方文档 · Agent Config（不写代码建agent）Official docs · Agent Config (building agents without code)	https://google.github.io/adk-docs/agents/config/
docs	Google 官方 codelab · Building AI Agents with ADK: The Foundation（`GOOGLE_GENAI_USE_ENTERPRISE` / `GOOGLE_CLOUD_PROJECT` / `GOOGLE_CLOUD_LOCATION` 三个变量的官方逐条说明，含 "enable billing" 表述，核验 2026-10-01）Google official codelab · Building AI Agents with ADK: The Foundation (official item-by-item explanation of the three variables `GOOGLE_GENAI_USE_ENTERPRISE` / `GOOGLE_CLOUD_PROJECT` / `GOOGLE_CLOUD_LOCATION`, including the "enable billing" wording, verified 2026-10-01)	https://codelabs.developers.google.com/devsite/codelabs/build-agents-with-adk-foundation
docs	Google Cloud 文档 · Manage sessions with Agent Development Kit（同一组三变量的另一种取值写法 TRUE / True，核验 2026-10-01）Google Cloud docs · Manage sessions with Agent Development Kit (the same three variables with TRUE / True spellings, verified 2026-10-01)	https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/sessions/manage-with-adk
repo	google/adk-js · TypeScript 版（1,426★，Apache-2.0）google/adk-js · TypeScript edition (1,426★, Apache-2.0)	https://github.com/google/adk-js
repo	google/adk-recipes · 样例集（10,404★）google/adk-recipes · sample collection (10,404★)	https://github.com/google/adk-recipes
changelog	Releases（v2.12.0 @ 2026-10-13）Releases (v2.12.0 @ 2026-10-13)	https://github.com/google/adk-python/releases

实测记录Measured runs

本档未跑集成与性能实测；结论只覆盖 API 与官方文档披露的能力面。

实测建议（按编排框架维度定制）：

#	测什么	为什么值得测
1	容器部署后的默认文件与网络权限边界	补上本站最大的缺口，也是选型前提
2	跑 `adk eval` 的最小完整案例	它是唯一内建 eval 的对象，值得看真实成本
3	流程中途 kill 进程后的恢复语义	官方有 retry / state management，但恢复粒度未核验
4	Tool Confirmation 在长循环里的人工打断频率	官方说可 guard，但要测实际打断次数
5	换成非 Gemini 模型后工具调用与 structured output 的可靠性	官方说 model-agnostic，验证代价
6	Python 版与 TS 版的能力差距	两个独立仓，官方没说是否对齐

This site has not completed measured runs.

The test protocol is at protocols/framework/_protocol.md.

Suggested measurement (tailored to the orchestration-framework dimension):

#	What to test	Why it is worth testing
1	Default file and network permission boundaries after container deployment	fills this site's biggest gap, and is a selection prerequisite
2	The minimal complete case of running `adk eval`	it is the only object with built-in eval; its real cost is worth seeing
3	Recovery semantics after killing the process mid-flow	the official docs have retry / state management, but recovery granularity is unverified
4	How often Tool Confirmation interrupts humans in a long loop	officially it can guard, but the actual interruption count needs measuring
5	Tool-calling and structured-output reliability after switching to a non-Gemini model	officially model-agnostic; verify the cost
6	The capability gap between the Python and TS editions	two separate repositories; the official docs never say they are aligned

为什么把它归到 orchestration，而不是 coding-baseWhy it is classified as orchestration rather than coding-base

本站前四个编程底座是 OpenAI Agents SDK、Deep Agents、 Claude Agent SDK、Codex SDK。

它们回答的都是同一个问题：

怎么跑一个 agent？

ADK 回答的是另一个问题：

怎么把多个 agent 组织成一个有分支、有循环、有人工介入的流程？

关键词是 deterministic：它要解决的不是「agent 能不能干活」。（deterministic 就是「确定性」。）

它要解决的是「多个 agent 组成的流程，在多次运行之间是否可重复、可预期」。

这也直接落到本站关心的分野上：

本站关注的面	ADK 给的
状态（流程控制）	✅ 图执行引擎：routing / loops / retry / state management / nested workflows
上下文（长任务压缩）	✅ 1.16+ 的 Context Compaction：滑动窗口摘要更早 event（`EventsCompactionConfig(compaction_interval, overlap_size)`），`summarizer` 可换模型

⚠ 不要把 state management 读成「有上下文管理」。 这正是本站反复强调的那条分野。

This site's first four coding bases are the OpenAI Agents SDK, Deep Agents, Claude Agent SDK, Codex SDK.

They all answer the same question:

how do you run one agent?

ADK answers a different question:

how do you organize multiple agents into a flow with branching, loops and human intervention?

The keyword is deterministic: what it sets out to solve is not "whether an agent can work". (deterministic means "certainty".)

What it sets out to solve is whether a flow composed of multiple agents is repeatable and predictable across runs.

This lands directly on the distinction this site cares about:

The surface this site watches	What ADK gives
state (flow control)	✅ graph execution engine: routing / loops / retry / state management / nested workflows
context (long-task compression)	✅ Context Compaction since 1.16+: sliding-window summarization of earlier events (`EventsCompactionConfig(compaction_interval, overlap_size)`), `summarizer` swappable

工具生态：MCP 是其中一员，但量级要注意The tool ecosystem: MCP is one member, but note the weight

README 原文：

Utilize pre-built tools, custom functions, OpenAPI specs, MCP tools or integrate existing tools to give agents diverse capabilities, all for tight integration with the Google ecosystem.

⚠ 本站的判断（推断，未核验实现）：README 把 MCP 与 OpenAPI specs 并列。

这说明它接 MCP 的方式是「把 MCP 当作一种工具来源」。

这与 OpenAI Agents SDK 不同。

那个把 mcp>=1.19.0,<3 直接放在 dependencies 里。那是框架级依赖。

两者不是同一量级的一等公民。

一项值得单独看的官方能力：Tool Confirmation（HITL）

A tool confirmation flow (HITL) that can guard tool execution with explicit confirmation and custom input.

文档在 tools/confirmation。

这是本站已收录对象里少见的「工具级人工确认」。 input/output guardrail 与它是不同层次的东西：

guardrail 是校验内容（这个输入 / 输出合不合规）
tool confirmation 是拦执行（这个工具要不要真跑，可以附带自定义输入）

README verbatim:

Utilize pre-built tools, custom functions, OpenAPI specs, MCP tools or integrate existing tools to give agents diverse capabilities, all for tight integration with the Google ecosystem.

⚠ This site's judgment (inference; implementation not verified): the README lists MCP alongside OpenAPI specs.

This suggests it integrates MCP as "one source of tools".

This differs from the OpenAI Agents SDK.

That one puts mcp>=1.19.0,<3 directly in dependencies. That is a framework-level dependency.

The two are not first-class citizens of the same weight.

One official capability worth a separate look: Tool Confirmation (HITL)

A tool confirmation flow (HITL) that can guard tool execution with explicit confirmation and custom input.

The doc is at tools/confirmation.

This is a rare "tool-level human confirmation" among objects collected on this site. input/output guardrails are a different layer from it:

guardrails validate content (is this input / output compliant)
tool confirmation gates execution (should this tool really run, optionally with custom input)

部署：四条命令，从本地到 Google 云Deployment: four commands, from local to Google cloud

README 给的四种运行 / 部署形态全部核验：

adk run<agent-folder>              # 交互式 CLI
adk web                <agent-folder>       # 内建 Web UI
adk deploy docker   --with_ui <agent-folder>         # 容器化
adk deploy cloud_run --with_ui <agent-folder>        # Cloud Run

另有两个本站认为值得注意的点。

① 内建开发 UI 与内建 eval。

官方原文：

A built-in development UI to help you test, evaluate, debug, and showcase your agent(s)

另有 adk eval <agent-folder> <evalset.json> 命令与 .evalset.json 配置格式。

这是本站已收录对象里唯一把「评估」做成框架内建命令的。 对「不要实测」的铁律来说，这类能力值得记一笔：它让用户能自己跑评测。

② 有个部署级开关要注意，而且它本质上是「计费路径开关」。

README 的 Cloud Run 示例里出现了 GOOGLE_GENAI_USE_ENTERPRISE=1。

已核验清楚（2026-10-01，Google 官方 codelab 与 Cloud 文档）：它不是「解锁企业功能」的开关。

它是一条路由开关：把请求从 Gemini Developer API 切到 Google Cloud 企业平台（Gemini Enterprise Agent Platform / Vertex AI），计费口径随之改变。

换句话说，改的是请求去向，不是功能权限。

官方 codelab 对三个变量的说明原文：

变量	官方含义
`GOOGLE_GENAI_USE_ENTERPRISE`	"This tells the ADK that you intend to use Google's Gemini Enterprise Agent Platform service for your Generative AI operations."
`GOOGLE_CLOUD_PROJECT`	"ADK needs this to correctly associate your agent with your cloud resources and enable billing."
`GOOGLE_CLOUD_LOCATION`	地域，如 `global`

最关键的一条。

官方把 "enable billing" 明确写在 GOOGLE_CLOUD_PROJECT 上。

那三个变量成组设上，agent 就落进你的 Google Cloud 项目并开始计费。 不设则走 Gemini Developer API 那条路（它有另一套免费层与配额）。

另外两点值得记：

三个变量必须成组出现 —— 官方所有示例（README、codelab、Cloud 文档的 Live API 指南）都是三个一起设，没有只设其一的写法

取值不统一 —— README 与 codelab 的 .env 写 1， Cloud 文档写 TRUE 或 True。按布尔语义皆真，但官方自己不一致这点值得注意

⚠ 仍未核验：Gemini 的具体单价。以及 Vertex AI Agent Engine 与 Cloud Run 的实际费率。

All four run/deployment forms given by the README are verified:

adk run <agent-folder>              # interactive CLI
adk web                <agent-folder>       # built-in Web UI
adk deploy docker   --with_ui <agent-folder>         # containerized
adk deploy cloud_run --with_ui <agent-folder>        # Cloud Run

Two more points this site considers notable.

① Built-in development UI and built-in eval.

Official wording:

A built-in development UI to help you test, evaluate, debug, and showcase your agent(s)

There is also the adk eval <agent-folder> <evalset.json> command and the .evalset.json config format.

This is the only object collected on this site that makes "evaluation" a framework-built-in command. Against the "no measured runs" rule, this kind of capability deserves a note: it lets users run their own evaluations.

② There is a deployment-level switch to note, and it is essentially a "billing-path switch."

The README's Cloud Run example contains GOOGLE_GENAI_USE_ENTERPRISE=1.

Verified clearly the 2026-10-08 check (2026-10-01, Google's official codelab and Cloud docs): it is not a switch that "unlocks enterprise features".

It is a routing switch: moving requests from the Gemini Developer API to the Google Cloud enterprise platform (Gemini Enterprise Agent Platform / Vertex AI), and the billing basis changes with it.

In other words, what changes is where requests go, not feature entitlements.

The official codelab's explanation of the three variables, verbatim:

Variable	Official meaning
`GOOGLE_GENAI_USE_ENTERPRISE`	"This tells the ADK that you intend to use Google's Gemini Enterprise Agent Platform service for your Generative AI operations."
`GOOGLE_CLOUD_PROJECT`	"ADK needs this to correctly associate your agent with your cloud resources and enable billing."
`GOOGLE_CLOUD_LOCATION`	region, e.g. `global`

The single most important line.

The official docs write "enable billing" explicitly against GOOGLE_CLOUD_PROJECT.

Set all three variables together and the agent lands in your Google Cloud project and starts billing. Unset, it goes the Gemini Developer API route (which has its own free tier and quotas).

Two more points worth recording:

the three variables must appear as a group — every official example (README, codelab, the Cloud docs' Live API guide) sets all three; there is no set-one-only style

values are inconsistent — the README and codelab .env files write 1, the Cloud docs write TRUE or True. All are truthy by boolean semantics, but the official inconsistency itself is worth noting

⚠ Still unverified: Gemini's specific unit prices. And the actual rates of Vertex AI Agent Engine and Cloud Run.

本地文件与沙箱：本站最大的证据缺口Local files and sandbox: this site's biggest evidence gap

README 讲工具生态时列的是 pre-built tools、custom functions、 OpenAPI specs、MCP tools。

那全是「怎么把工具接进来」。

它没有把「读写本地文件」列为一项能力。

它也没有描述默认的文件访问边界。

对比本站其它对象在这块的做法：

OpenHands 给了明确的 Docker 沙箱形态与 API key 机制，且在无沙箱安装选项上挂 WARNING

Codex SDK 源码里有三档 SandboxMode 枚举
ADK 这边本站没有拿到任何沙箱或权限边界的官方表述

⚠ 官方未提供：默认沙箱机制、文件系统权限模型、网络访问控制。 如果你选它，容器隔离要自己确认。

When the README discusses the tool ecosystem it lists pre-built tools, custom functions, OpenAPI specs, MCP tools.

All of that is "how to connect tools in".

It does not list "reading/writing local files" as a capability.

It also does not describe a default file-access boundary.

Compare what other objects on this site do here:

OpenHands gives an explicit Docker sandbox form and API-key mechanism, and hangs a WARNING on the no-sandbox install option

Codex SDK source has a three-tier SandboxMode enum
on the ADK side this site has obtained no official statement of any sandbox or permission boundary

⚠ Not provided officially: default sandbox mechanism, filesystem permission model, network access control. If you choose it, container isolation is yours to confirm.

同厂双版本 + 样例仓Same-vendor dual versions + the samples repository

仓库	用途	核验（2026-10-01）
`google/adk-python`	Python 主体（本档收录）	21,966★ · Apache-2.0
`google/adk-js`	TypeScript 版	1,426★ · Apache-2.0
`google/adk-recipes`	样例集（描述里写 adk-samples）	10,404★

⚠ 按本站「一个对象 = 一套决策依据」的粒度，只收录 Python 主体。

Repository	Purpose	Verified (2026-10-01)
`google/adk-python`	Python mainline (collected by this entry)	21,966★ · Apache-2.0
`google/adk-js`	TypeScript edition	1,426★ · Apache-2.0
`google/adk-recipes`	sample collection (description says adk-samples)	10,404★

⚠ Per this site's "one object = one decision basis" granularity, only the Python mainline is collected.

核验说明Verification notes

confidence: partial 的依据。

为什么不是 verified。 三维已核到官方机制：

local_files —— Artifacts 抽象
context —— 1.16+ 的 Context Compaction
permissions —— Tool Confirmation

但 permissions 只有「执行前确认」。官方未提供沙箱或文件系统权限模型。

其余缺口集中在费率与部署语义：

Gemini 单价与 Vertex AI Agent Engine / Cloud Run 的实际费率
跨进程跨机续跑语义
分布式状态存储

已核验：仓库存在与星数（21,966 · 滚动核验 2026-10-23）、许可（Apache-2.0，经 license API）、最近推送（2026-10-22，仍活跃）、最新版 v2.12.0（releases @ 2026-10-13）、 README 全文的六项特性列表与四类运行形态、两种 adk deploy 命令与 GOOGLE_GENAI_USE_ENTERPRISE 环境变量、adk eval 命令与 .evalset.json 格式、 google/adk-js（1,426★ · Apache-2.0）与 google/adk-recipes（10,404★）两仓元数据

2026-10-01 补充：GOOGLE_GENAI_USE_ENTERPRISE 的确切含义。它是计费路径开关（切到 Gemini Enterprise Agent Platform / Vertex AI），不是企业功能开关。官方把 "enable billing" 挂在 GOOGLE_CLOUD_PROJECT 上，三个变量须成组设置。来源为 Google 官方 codelab 与 Cloud 文档。

未核验：非 Gemini 模型下的工具调用与 structured output 可靠性（对齐度）、默认沙箱与文件权限模型、网络访问控制、跨进程/跨机续跑语义、分布式状态存储、 MCP 接入的实现层次（框架级依赖 vs 工具来源）、 Gemini 单价与 Vertex AI Agent Engine / Cloud Run 的实际费率

Basis for confidence: partial.

Why not verified. Three dimensions were verified against official mechanics the 2026-10-08 check:

local_files — the Artifacts abstraction
context — Context Compaction since 1.16
permissions — Tool Confirmation

But permissions is only "confirm before executing". The official docs provide no sandbox or filesystem permission model.

The remaining gaps concentrate on rates and deployment semantics:

Gemini unit prices and the actual rates of Vertex AI Agent Engine / Cloud Run
cross-process cross-machine resume semantics
distributed state storage

Verified: repository exists and star count (21,966 · rolling check 2026-10-23), license (Apache-2.0, via the license API), last push (2026-10-22, still active), latest version v2.12.0 (releases @ 2026-10-13), the README's full six-feature list and four run forms, the two adk deploy commands and the GOOGLE_GENAI_USE_ENTERPRISE env var, the adk eval command and .evalset.json format, metadata of the google/adk-js (1,426★ · Apache-2.0) and google/adk-recipes (10,404★) repositories

Added the 2026-10-08 check (2026-10-01): the exact meaning of GOOGLE_GENAI_USE_ENTERPRISE. It is a billing-path switch (moving to Gemini Enterprise Agent Platform / Vertex AI), not an enterprise-feature switch. The official docs hang "enable billing" on GOOGLE_CLOUD_PROJECT; the three variables must be set as a group. Sources: Google's official codelab and Cloud docs.

Not verified: tool-calling and structured-output reliability (alignment) under non-Gemini models, default sandbox and file permission models, network access control, cross-process/cross-machine resume semantics, distributed state storage, the implementation layer of MCP integration (framework-level dependency vs tool source), Gemini unit prices and the actual rates of Vertex AI Agent Engine / Cloud Run