跳到主要内容

数据截至 (上游 commit aa6a07bc97f1)

Google ADK (Python) — 架构与原理

30 秒导读: ADK 是 Google 开源的「代码优先」AI agent 框架。你用 Python 写 Agent(给它指令和工具)和 Workflow(把多个 agent/函数连成一张图),框架负责跑模型、调工具、管会话状态、流式吐事件,还能在中途暂停等人类批准再恢复。2.0 的核心变化是:一切都被统一成「图里的节点」(BaseNode),连单个 Agent 也是一个节点。

1. 这是什么(零基础也能懂)​

一句话定义。 ADK(Agent Development Kit)是一个让你用代码搭建、评测、部署 AI agent 的 Python 框架。

解决什么问题。 假设你想做一个客服 bot:它要能理解用户问题、调用「查订单」「退款」等工具、必要时把难题转交给「专家 agent」、遇到退款金额过大时停下来等人类批准。如果从零写,你得自己处理:怎么把工具描述喂给模型、怎么解析模型要调哪个工具、怎么把工具结果再喂回去、怎么存对话历史、怎么在「等人批准」时把执行暂停后又恢复。ADK 把这些全做好了,你只描述「有哪些 agent、哪些工具、它们怎么连」。

给谁用。 主要给在 Google 生态(Gemini、Vertex AI)里搭 agent 的工程师;但模型层是可插拔的,也能接别的 LLM。

它能做什么(功能):

  • 定义 LLM agent:指令、工具、输出 schema、子 agent。
  • 把多个步骤连成图:顺序、并行扇出、汇合(fan-in)、条件路由、循环。
  • 流式产出事件(模型每吐一段文字、每次调工具都是一个 Event)。
  • 会话与状态:对话历史和共享状态自动持久化(内存 / SQLite / 数据库 / Vertex)。
  • 人类介入(HITL):在图中途暂停、等人输入、再从断点恢复。
  • agent 间委派:一个 agent 把控制权转交给另一个(transfer),或把一个子任务委派出去(Task API)。
  • 配套评测(evaluation/)、CLI(adk run / adk web)、可观测性(OpenTelemetry tracing)。

用起来什么样。 最小的「一个 agent」长这样(摘自 README.md):

# 示意,非源码(改编自 README Quick Start)
from google.adk import Agent

root_agent = Agent(            # Agent 是 LlmAgent 的别名
    name="greeting_agent",
    model="gemini-2.5-flash",
    instruction="You are a helpful assistant. Greet the user warmly.",
)

把两个 agent 连成一条流水线(前一个输出喂给后一个):

# 示意,非源码(改编自 README)
from google.adk import Agent, Workflow

fruit = Agent(name="fruit", instruction="Return a random fruit name only.")
benefit = Agent(name="benefit", instruction="Tell a health benefit of the fruit.")

root_agent = Workflow(
    name="root_agent",
    edges=[("START", fruit, benefit)],   # START → fruit → benefit
)

然后 adk run path/to/my_agent 就能在终端里和它对话。

一句话直觉/类比。 把 ADK 想成一台带「暂停/继续」按钮的流水线工厂:每个工位是一个节点(可能是个 LLM,也可能是个普通 Python 函数),产品(数据)沿着传送带(图的边)流动;遇到「需要主管签字」的工位,整条线可以冻结,等签字回来再原地解冻继续。

2. 顶层全景(它大概怎么转)​

ADK 2.0 最关键的一句话:Agent、工具、普通函数、子工作流——全部统一成 BaseNode。LlmAgent 继承 BaseAgent,而 BaseAgent 又继承 BaseNode(见 src/google/adk/agents/base_agent.py:94,class BaseAgent(BaseNode, abc.ABC))。Workflow 本身也是 BaseNode(src/google/adk/workflow/_workflow.py:145)。于是「一个 agent」和「一张包含很多 agent 的图」在运行时是同一种东西,可以任意嵌套。

怎么读下面这张图: 从上到下是一次用户请求的生命周期。左边是「用户/入口」,中间是「调度与执行」,右边是「持久化」。

部件一句话职责:

部件干什么在哪个文件
Runner对外入口;取/建 session,建 InvocationContext,驱动根节点,把事件落库runners.py(class Runner,runners.py:205)
BaseNode一切可执行单元的基类;定义 run()(对外)与 _run_impl()(子类重写)workflow/_base_node.py:36
LlmAgent / Agent一个会调模型、用工具、可有子 agent 的节点agents/llm_agent.py:236
BaseLlmFlow单个 LLM agent 的「思考→调工具→再思考」循环flows/llm_flows/base_llm_flow.py:569
Workflow一张图节点;_run_impl() 就是图调度循环workflow/_workflow.py:145
Graph / Edge把 edges=[...] 解析成校验过的有向图workflow/_graph.py(class Graph,_graph.py:95)
NodeRunner跑「一个节点的一次执行」:建子 Context、超时/重试、把输出/状态落到事件workflow/_node_runner.py:50
Context节点运行期的把手:读写 state、设 output/route、run_node() 动态调子节点agents/context.py:119
Event流经一切的统一数据单元;模型回复、工具调用、状态变更都是 Eventevents/event.py:91
Session / SessionService对话历史(events)+ 共享 state 的存储与读写sessions/session.py:28、sessions/base_session_service.py:157
App应用级容器:根节点 + plugins + 压缩/可恢复配置apps/app.py:53

主线走一遍(高层,不进代码):

  1. 你调 runner.run_async(user_id, session_id, new_message=...)。
  2. Runner 取出 Session,把根 agent/workflow 用 build_node 包成节点,建一个根 Context。
  3. 如果根是 Workflow,它的 _run_impl 启动图调度循环:从 START 出发,给后继节点投递「触发器」,然后并发地用 NodeRunner 跑就绪的节点。
  4. 节点若是 LlmAgent,BaseLlmFlow 跑一圈:组装请求(指令+历史+工具)→ 调模型 → 如果模型要调工具就执行工具、把结果塞回历史、再调模型,直到出最终回复。
  5. 每一步产出的 Event 一路向上流,Runner 把它 append_event 落库(同时应用状态增量),并 yield 给你。
  6. 节点完成后,调度循环按图的边(可能带路由/扇出)触发下游节点;遇到需要人类输入时整个调用暂停,记录足够的事件,以便下次带 invocation_id 恢复。

3. 阅读地图(建议顺序)​

这是个大项目(src/google/adk 下 30+ 模块、tools 一个就 159 个文件),所以拆成四章,由浅入深:

  1. 01-agents-and-models.md — 先搞懂「一个 agent」。 不碰图,只看 LlmAgent:模型/工具/指令怎么解析,单个 agent 内部的 agentic 循环(BaseLlmFlow)怎么把「调工具」这件事跑通。这是最常用、最该先懂的部分。
  2. 02-workflow-runtime.md — 再搞懂「一张图」。 2.0 的招牌特性:BaseNode 统一抽象、edges DSL 怎么变成 Graph、Workflow._run_impl 的触发器调度循环、路由 / 扇出扇入 / 循环 / 并发 / 重试是怎么实现的。
  3. 03-runner-events-sessions.md — 把运行时串起来。 Runner 入口、Event 数据模型、Session/State 存储、以及 ADK 的杀手锏:中断恢复与人类介入(HITL)。
  4. 04-task-api-and-delegation.md — 多 agent 协作 + 收尾。 三种 mode(chat/task/single_turn)、transfer_to_agent 与 Task API 两种委派、巧妙之处、边界局限、横向对比、代码地图。

想最快上手:读完第 1 章你就能写单个 agent;读完第 2 章你能搭多步流程;第 3、4 章是把它做成「生产级、可恢复、多 agent」的进阶。