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

模型与开放条件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 页。

运行位置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 的产品，不是本框架的。

本地文件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 各页）。 默认访问边界取决于你自己接的工具。

关机后的任务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 触发
• 工具可能被重复执行（官方提醒有副作用的工具要自己防重）

工具与扩展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 是不同层次的东西。

上下文与记忆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 管历史压缩。这是两套机制，官方也分开描述。

权限与限制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 不支持该特性。

适合什么任务Best for

适合这些情况。

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

不适合这些情况。

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

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

本页由This page is generated from the ai-agent-guide 数据层生成（CC BY 4.0）。data layer (CC BY 4.0). 方法论与坐标系定义见仓库内 METHODOLOGY.md。