Google ADK

Google ADK 快速入门

Google 官方 Agent 工具箱 —— 构建、评估、部署、Workflow 一条龙。

这是什么？适合谁？

Google ADK（Agent Development Kit）是 Google 官方开源的 Agent 开发框架，定位是「code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents」。GitHub 20.8K+ stars（截至 2026-07），Apache-2.0 开源，当前主版本是 2.0（2025 年底发布，带 Workflow Runtime 和 Task API 两项重大升级）。

它和 LangChain/CrewAI 的最大区别是「自带一整套生产工具链」——不只是写 Agent，还内置了：

• Agent + Workflow Runtime：Agent 走 LLM 推理，Workflow 用确定性图编排串起 Agent/Task 节点（支持 routing、fan-out/in、loops、retry、嵌套 workflow）。
• Task API：结构化的 Agent-to-Agent 委派（多轮、单轮、人在环中）。
• adk run / adk web CLI：本地跑 Agent 的 CLI 和 Web UI，跟 adk-samples 仓库开箱即用。
• 评估与可观测：内置 evaluation 工具 + tracing，跟 Langfuse 等可插拔。
• Gemini 原生 + 任意 LLM：默认 Gemini（gemini-2.5-flash 等），但通过 LiteLLM/Anthropic 也能跑 OpenAI/Claude/本地模型。

适合谁？一是已经在 Google Cloud / Vertex AI 生态的团队（集成最顺）；二是想用「图编排 + Agent」的混合架构（Workflow Runtime 干确定性部分、Agent 干 LLM 部分）；三是需要 enterprise-grade 工具链（评估、可观测、guardrails）的开发者。不适合：只想 5 分钟跑一个 demo 的用户（LangChain / OpenAI Agents SDK 上手更快）；也不适合非 Python 用户（ADK 是纯 Python）。

准备工作

1. Python 3.10 及以上：访问 python.org 下载安装。
2. 模型 API Key：推荐 Google AI Studio 免费领一个 Gemini Key（每分钟 15 次、每天 1500 次免费额度），也支持 Vertex AI / Anthropic / OpenAI。
3. （可选）Docker / Cloud CLI：要把 Agent 部署到 Cloud Run / GKE 时需要。
4. 包管理器：pip 或 uv 都行。

环境变量：GOOGLE_API_KEY（Gemini）或 ANTHROPIC_API_KEY / OPENAI_API_KEY。

3 步快速上手

第 1 步：安装

pip install google-adk

可选 extras：pip install "google-adk[extensions]" 拉 LangChain/LiteLLM 等扩展。

第 2 步：创建 Agent

新建一个目录 my_agent/，在目录下建 agent.py：

from google.adk import Agent

root_agent = Agent(
    name="greeting_agent",
    model="gemini-2.5-flash",   # 也可以写 "gemini-2.5-pro" 或 Anthropic 模型
    instruction="你是一个有帮助的中文助手。用户打招呼时请热情回应。",
    description="基础问候 Agent",
)

注意官方 import 是 from google.adk import Agent（包名是 google-adk PyPI 包，但 Python 命名空间是 google.adk——下划线和点的区别是新手最常踩的坑）。

第 3 步：本地运行

# 在 my_agent/ 目录下
adk run my_agent          # 交互式 CLI
adk web my_agent           # 启动本地 Web UI（浏览器聊天）

adk web 会起一个 React 前端，支持多 Agent 切换、会话历史、工具调用可视化，调试体验非常友好。

常见踩坑

踩坑 1：from google_adk import Agent ImportError

• 症状：按照 PyPI 包名 google-adk 直觉写成 from google_adk import Agent，运行时报 ModuleNotFoundError
• 原因：PyPI 包名是 google-adk（带连字符），但 Python 命名空间是 google.adk（用点分隔），下划线和点的区别是新用户最高频的报错
• 解决：正确写法是 from google.adk import Agent（注意是点不是下划线）；如果已经 from google_adk import ... 了，全局替换即可
• 参考：GitHub Issue #2133（ADK Roadmap 中讨论了 API 命名一致性问题）

踩坑 2：adk run 找不到 agent

• 症状：执行 adk run my_agent/agent.py 报错说找不到 agent 配置
• 原因：adk run 期望的路径是「包含 agent 目录的父目录」，而不是直接指向 agent.py 文件。Agent 类通过目录扫描自动发现
• 解决：命令应写成 adk run my_agent（不带 /agent.py）；确保 my_agent/agent.py 中定义了 root_agent 变量（ADK 按名称 root_agent 搜索）
• 参考：GitHub Issue #211（context caching 支持讨论中也反映了 agent 发现机制的问题）

踩坑 3：升级到 2.0 之后老 session 读不出来

• 症状：从 ADK 1.x 升级到 2.0 后，已有的会话历史全部失效，加载时报 schema 兼容性错误
• 原因：2.0 引入了 breaking changes——agent API、event model、session schema 全部调整。2.0 能读 1.x session（多余字段忽略），但 1.x 代码无法加载 2.0 session
• 解决：新项目直接用 2.0（pip install "google-adk>=2.0"）；老项目先评估 session schema 兼容性再升级，迁移前导出重要会话；官方提供了少量迁移工具但仅覆盖 key schemas
• 参考：GitHub Issue #3611（Support Claude skill feature 讨论中涉及 2.0 的 API 变化）

踩坑 4：Gemini API Key 在国内连不上

• 症状：配置好 GOOGLE_API_KEY 后 Agent 无响应，日志报 grpc._channel._InactiveRpcError 或超时
• 原因：Gemini API 入口 generativelanguage.googleapis.com 在国内部分地区 DNS 污染或 TCP 阻断，无法直连
• 解决：环境变量设 HTTPS_PROXY=http://your-proxy:port 走代理；或改用 Vertex AI（需要 GCP 账号，配置 VERTEXAI_PROJECT 和 VERTEXAI_LOCATION）；或切换模型为 Anthropic/OpenAI（通过 LiteLLM 兼容层）
• 参考：GitHub Issue #4764（Governance callbacks 讨论中也涉及 Gemini API 连接稳定性）

踩坑 5：Agent 工具调用失败（tool 不生效）

• 症状：Agent 定义中有 tools 列表，但实际运行时 Agent 完全不调用工具，或调用后报错
• 原因：自定义 tool 必须用 FunctionTool 包装；Gemini 对工具描述（docstring）非常敏感，描述不清晰或不完整时模型不会调用；tool 返回格式不匹配也会导致静默失败
• 解决：确保用 from google.adk.tools import FunctionTool 包装 tool；docstring 包含「用途、参数、返回、何时调用」四要素；在 adk web 中查看 tool call trace 定位问题
• 参考：GitHub Issue #3534（AgentSpace Agent 注册授权错误——工具描述问题导致的远程调用失败）

踩坑 6：Workflow 跑出无限循环

• 症状：Workflow 图执行后一直不结束，占用 CPU 持续增长
• 原因：Workflow 默认 max_steps 较高（约 100），复杂图（尤其是包含回环的 DAG）容易绕回起点造成无限循环
• 解决：每个 Loop 节点显式设置 max_iterations（如 Loop(max_iterations=5)）；在 Workflow(..., max_steps=30) 参数设全局上限；各节点加时间戳日志便于定位循环路径
• 参考：GitHub Issue #211（Workflow 执行时间控制——context caching 支持讨论中提及循环检测机制）

踩坑 7：adk web 启动后浏览器白屏

• 症状：执行 adk web my_agent 终端显示启动成功，但浏览器打开后空白或报错
• 原因：默认 8000 端口被其他服务占用（如本地 Node 服务、其他 Python 服务）；或前端 bundle 在首次启动时未正确构建（Node.js 依赖缺失）
• 解决：先 netstat -ano | findstr 8000 检查端口占用情况，换一个端口用 adk web my_agent --port 3000；确保 Node.js 已安装（node --version）；首次启动稍等前端 bundle 编译完成
• 参考：GitHub Issue #2133（ADK Roadmap 中提及 Web UI 稳定性改进计划）

踩坑 8：中文 prompt 报 UnicodeEncodeError

• 症状：Windows 终端下运行 adk run 或 adk web，输入中文后报 UnicodeEncodeError: 'charmap' codec can't encode characters
• 原因：Windows 中文版控制台默认 GBK 编码，Python 的 print/stdout 尝试输出 Unicode 字符时无法映射到 GBK
• 解决：运行前执行 set PYTHONIOENCODING=utf-8 或 chcp 65001 切换到 UTF-8；推荐直接用 adk web 浏览器 UI（浏览器原生 UTF-8 无此问题）
• 参考：GitHub Issue #211（ADK 本地化编码问题在多个 issue 中被提及）

初级用法

• 单 Agent：上面示例就是——一个 Agent(name=..., model=..., instruction=...) 跑起来。
• 内置工具：google.adk.tools 提供 google_search、code_execution、VertexAISearchTool 等几十个开箱即用工具。
• MCP 工具：from google.adk.tools.mcp_tool import McpToolset，一行接入任意 MCP Server。
• 多 Agent 协作：用 sub_agents=[...] 参数把多个 Agent 组成层级，主 Agent 委派子 Agent。
• Workflow：用 from google.adk import Workflow，通过 edges=[(START, agent_a, agent_b)] 显式定义节点和路由，适合「确定性业务流 + 节点用 Agent」的混合架构。

高级玩法

• Task API（多轮委派）：from google.adk.tasks import Task，定义结构化任务（带 schema、上下文、超时），Agent A 可以把 Task 派给 Agent B，B 完成后再把结果带回 A。
• Workflow Runtime：Workflow(edges=[...]) 是图引擎，支持 routing、fan-out/fan-in、loops、retry、nested workflows——用确定性图串 Agent，比纯靠 LLM 调度可靠得多。
• 人在环中（Human-in-the-loop）：approval_required=True 让 Agent 关键操作前暂停等用户确认。
• 评估（Evaluation）：adk eval my_agent/eval_set.json 用内置 eval 跑用例集，支持自定义 metric。
• 可观测：默认输出 OpenTelemetry trace，可对接 Langfuse / Arize Phoenix / GCP Cloud Trace。
• Vertex AI 部署：adk deploy cloud_run --agent=my_agent 一键部署到 GCP Cloud Run，自动构建镜像、绑 IAM、暴露 HTTPS。
• AgentOS 兼容：跟 Agno AgentOS / LangGraph Studio 等 agent runtime 工具部分互通（社区还在补全）。

小技巧

1. 先用 gemini-2.5-flash 试水：免费额度大、响应快（< 1s）、中文能力强；跑通后再换 gemini-2.5-pro 提质量。
2. adk web 是调试神器：本地浏览器里能看到完整的 thinking、tool call、retry 链路，比 print 调试快 10 倍。
3. instruction 用英文 + 中文对照：Gemini 对英文 instruction 响应更稳，可以在 instruction 里写「Respond to user queries in Chinese unless the user writes in English.」。
4. Workflow 节点一定要命名：name="generate_fruit_agent" 决定了 trace 里的可读性，匿名节点排查问题时痛苦。
5. Tool docstring 写完整：Gemini 工具调用的准确率几乎完全取决于 docstring 质量——包含「用途、参数、返回、何时调用、何时不调用」五要素。
6. session 持久化：默认 session 在内存，生产用 DatabaseSessionService（支持 SQLite/PostgreSQL）持久化。
7. 别把所有逻辑塞进 instruction：把工具调用规则放进 tool 自己的 docstring，主 instruction 只描述角色和约束。

进阶学习建议

如果你想从「能跑通 ADK」走到「能用 ADK 上生产」，按这条路径走最快：

1. 先看官方 README + Quickstart：google.github.io/adk-docs 的 Quickstart 5 分钟跑通 hello world。
2. 学 Agent + Workflow 二元模型：理解「Agent 走 LLM 推理，Workflow 走确定性图」的区别，先用单一 Agent 写，再升级到 Workflow。
3. 看 adk-samples 仓库：Google 官方维护的几十个完整示例，覆盖 RAG、多 Agent、Vertex AI 部署、Workflow 等场景。
4. 接 Vertex AI 跑真实部署：adk deploy cloud_run 一键部署，比 LangChain 的部署链短很多。
5. 接入评估：adk eval 写用例集，把 Agent 质量量化，比看 demo 视频靠谱。
6. 生产化：接 DatabaseSessionService、Cloud Trace、IAM 鉴权、限流。

可以对比阅读的几个相关项目：LangGraph、CrewAI、Agno AgentOS。

FAQ

Q1: Google ADK 是免费的吗？

A1: 软件本身 Apache-2.0 开源免费。模型成本取决于你接的 LLM：默认 Gemini 走 Google AI Studio，有免费额度（gemini-2.5-flash 每分钟 15 次 / 每天 1500 次）；生产建议接 Vertex AI，按 token 计费（比 AI Studio 更稳定、有 SLA）。也可以接 OpenAI/Anthropic/本地模型，按对应厂商价格走。

Q2: 和 LangGraph 有什么区别？

A2: LangGraph 是 LangChain 旗下的图编排库，核心是「节点 + 边 + 状态机」，Agent 只是节点的一种；ADK 的 Workflow Runtime 设计类似，但 ADK 把 Agent 当一等公民——Workflow(edges=[(START, agent_a, agent_b)]) 直接接 Agent 类。LangGraph 生态更成熟（LangSmith 调试、SLA、企业用户多），ADK 跟 Gemini/Vertex AI 集成更紧、Google Cloud 用户体验最好。

Q3: 必须用 Gemini 吗？

A3: 不是。ADK 通过 LiteLLM 兼容层支持任意 OpenAI 兼容模型。代码里把 model="gemini-2.5-flash" 换成 "claude-sonnet-4" / "openai/gpt-4o" 都能跑（需要相应 API Key 和 pip install "google-adk[litellm]"）。

Q4: 1.x 还能用吗？要不要升级 2.0？

A4: 1.x 仍然在维护，但官方主推 2.0。新项目直接用 2.0；老项目先评估 session schema 兼容性再升级。2.0 的 Workflow Runtime 和 Task API 是 1.x 没有的，值得迁移。

Q5: 跟 LangChain Agent 比呢？

A5: LangChain Agent 偏「单 Agent + 工具链」，生态庞大（Retrievers、Memory、Output Parsers 一应俱全）；ADK 偏「企业级工具链 + 图编排」，评估、部署、tracing 都内置。如果你是 LangChain 老用户、想最小迁移成本，留在 LangChain；如果你刚开始一个新项目、想用 Google 生态，ADK 上手快。

参考链接

• Google ADK GitHub
• Google ADK 官方文档
• ADK Samples 仓库
• Google AI Studio 申请 API Key
• Vertex AI Agent Engine

免责声明

本文涉及的 GitHub stars 数、版本号、价格等信息基于公开资料整理（截至 2026-07），实际数据请以各项目仓库为准。Google ADK 仍在快速迭代（每两周发版），API 接口可能在后续版本变化，部署到生产前请阅读最新 README 和 CHANGELOG。文中代码示例仅供学习参考，请在遵循各项目许可证的前提下使用。