ADK-Go 源码阅读系列

Posted on Sep 19, 2026

ADK-Go 源码阅读合集

用户发来一句“杭州天气怎么样”，从接收输入到给出答案，中间会经历模型请求、工具执行、事件保存和下一轮推理。多 Agent、人工确认、流式输出和长会话则会改变这条路径。

这个系列沿着一次请求追踪 ADK-Go 的实现：谁创建对象，谁调用接口，数据在哪一步变成事件，结果又如何成为下一次输入。 各篇聚焦一个模块，并用相邻模块的实际调用方说明它的边界。

系列源码基准：ADK-Go v2.4.0，commit 4e57df40cbd35f055ba654b03ffb0e509fdd754a。

各篇使用同一版本的接口、实现和调用方。普通 Run、Live、不同模型适配器与存储后端的行为分别说明；一种运行方式的结论不自动适用于其他方式。

阅读路线

Overview / Quickstart
        ↓
Launcher / Model / Agent
        ↓
Runner → Flow → Tool
        ↓
Context → Session / Event
        ↓
Memory / Plugin / Workflow
        ↓
Artifact → Server → Registry
        ↓
Auth / Telemetry / Platform

如果还不了解 ADK，先读 Overview 和 Quickstart；如果已写过简单 Agent，可从 Flow 的天气示例进入，再沿 Runner → Tool → Context → Session 追踪它上下游的实现。

你想理解的问题推荐路线读完后应能解释
一个 Agent 应用如何启动Overview → Quickstart → Launcher配置如何变成可运行的 Agent
一句话如何触发工具并得到答案Model → Agent → Flow → ToolFunctionCall 为什么不等于已经执行工具
执行结果如何保存并进入下一轮Runner → Context → Session / Event → 存储实现内存对象、状态 delta、持久化事件之间的区别
多 Agent 与暂停恢复如何协作Agent → Plugin → Workflow回调、转移、调度和恢复各由谁控制
外部服务、观测和测试如何接入Artifact → Server → Auth/Telemetry/Platform文件版本、协议暴露、身份与可替换系统操作的边界
如何发现云端 Agent 和 MCP 服务Agent Registry → Agent / Tool注册资源怎样变成 RemoteAgent 或 Toolset

把模块放回同一次请求

应用 / Launcher
    ↓
Runner：取得 Session，装配 Context，驱动运行
    ↓
Agent：定义角色、指令、工具和协作关系
    ↓
Flow：准备 Request → 调用 Model → 解释 Response
    ↑                                  ↓
下一步的历史输入 ← Session ← Event ← Tool 执行结果

这是普通 LLM Agent 的主线示意。Plugin 可以在相关生命周期介入；Workflow 负责节点调度与暂停恢复；Memory 提供跨 Session 的检索能力。Flow 处理模型与工具循环，Workflow 调度图中的节点。

系列中的主要对象也各有自己的单位：Session 可以覆盖多次交互，一次 invocation 可以包含多个模型 step，一个 step 又可以产生多条 Event。LLMRequest 是模型输入，Event 是运行记录；同一条记录中的 Author 与 Content.Role 也不表达同一个概念。

文章目录

完整阅读顺序

  1. Agent Development Kit (ADK) · 01 - Overview

    从一次天气查询建立 ADK-Go v2.4.0 的运行全貌，理解 Agent、Runner、Flow、Model、Tool、Session、Context 与 Workflow 如何协作。

  2. Agent Development Kit (ADK) · 02 - 初见 ADK

    沿 ADK-Go v2.4.0 官方 Quickstart，从 Model、LlmAgent、Loader、Launcher 进入 Runner，理解内置搜索、会话创建与事件输出，并给出运行命令和排障路径。

  3. Agent Development Kit (ADK) · 03 - Launcher

    对照 ADK-Go v2.4.0 源码，拆解 Launcher 如何校验配置、选择 console 或 web、装配服务与 AgentLoader，并把输入交给 Runner。

  4. Agent Development Kit (ADK) · 04 - Model

    从 ADK-Go v2.4.0 的 LLM 契约进入 Gemini、OpenAI Responses 与 Apigee 实现，拆解请求转换、工具调用 ID、流式聚合、错误与模型注册表。

  5. Agent Development Kit (ADK) · 05 - Agent

    从 ADK-Go v2.4.0 的 Agent 接口、回调骨架、LlmAgent 和组合 Agent，理解事件流、停止条件、并行握手与节点运行边界。

  6. Agent Development Kit (ADK) · 06 - Runner

    沿 ADK-Go v2.4.0 的普通 Run、节点运行时、HITL、Live 和压缩路径，理解 Runner 的对象生命周期、事件顺序、错误与恢复边界。

  7. Agent Development Kit (ADK) · 07 - Flow

    对照 ADK-Go v2.4.0 源码，以一次天气工具调用和可运行示例，逐层拆解 Flow 的双层循环、请求拼装、事件持久化、回调、流式响应、人工确认与 Agent 转移。

  8. Agent Development Kit (ADK) · 08 - Tool

    对照 ADK-Go v2.4.0 源码，沿一个天气查询请求解释 Tool 的声明、注册、执行、回调替代结果、流式结果、长任务和人工确认恢复。

  9. Agent Development Kit (ADK) · 09 - Context

    从 ADK-Go v2.4.0 看 Context 的接口组合、回调和工具护栏、StateDelta、浅拷贝、取消与 HITL 恢复。

  10. Agent Development Kit (ADK) · 10 - Session&Event

    以天气偏好跨两段会话的变化为线索，拆解 ADK-Go v2.4.0 的 Session、Event、StateDelta、作用域和保存时序，区分接口契约与存储实现限制。

  11. Agent Development Kit (ADK) · 11 - Session InMemory

    以天气用户偏好为例，解释 ADK-Go v2.4.0 InMemory Session 的有序键、拷贝边界、三层 State、临时 delta、锁和后写覆盖语义。

  12. Agent Development Kit (ADK) · 12 - Session Database

    以天气偏好更新为例，解释 ADK-Go v2.4.0 session/database 的四张表、JSON 往返、事务边界、微秒排序、stale 检查及失败后的本地快照风险。

  13. Agent Development Kit (ADK) · 13 - Session Vertex AI

    对照 ADK-Go v2.4.0，拆解 session/vertexai 如何把 Session Service 映射到 Vertex AI Agent Engine，并与 InMemory、Database 的语义边界对比。

  14. Agent Development Kit (ADK) · 14 - Memory

    从两段天气会话出发，拆解 ADK-Go v2.4.0 Memory 的显式摄取、关键词排序、load/preload 消费路径和 Vertex MemoryBank 的真实作用域与完成语义。

  15. Agent Development Kit (ADK) · 15 - Plugin

    对照 ADK-Go v2.4.0，以天气查询贯穿 Runner、PluginManager、条件回调链、事件持久化和内置插件，解释每个条件会跳过哪些后续步骤。

  16. Agent Development Kit (ADK) · 16 - Workflow

    对照 ADK-Go v2.4.0，以天气简报贯穿 Node、图调度、输入输出、事件握手、路由、并发汇合和从历史重建的暂停恢复。

  17. Agent Development Kit (ADK) · 17 - Artifact

    对照 ADK-Go v2.4.0 源码，拆解 Artifact Service 的六个操作、版本与作用域、InMemory/GCS 实现，以及 Context 中 ArtifactDelta 的真实边界。

  18. Agent Development Kit (ADK) · 18 - Server

    对照 ADK-Go v2.4.0，沿一次天气请求梳理 REST、SSE、A2A、Agent Engine 与入站认证授权，并区分协议适配层和 Launcher 挂载层。

  19. Agent Development Kit (ADK) · 19 - Agent Registry

    对照 ADK-Go v2.4.0，沿一个注册资源发现请求解释 Agent Registry 的 ADC/mTLS、分页、Agent Card、A2A 兼容 transport 与 MCP Toolset 出站边界。

  20. Agent Development Kit (ADK) · 20 - Auth、Telemetry 与 Platform

    对照 ADK-Go v2.4.0，拆解 auth 的凭据解析、Telemetry 的 OpenTelemetry 生命周期，以及 platform 的时间和 UUID 注入边界。

分阶段阅读地图

1. 先建立整体认识

主题文章重点
全貌ADK OverviewADK 的模块划分与总体运行模型
初见ADK Quickstart从示例程序进入 ADK
入口Launcher应用启动与运行入口

2. Agent 执行主链

主题文章重点
ModelModelLLM 请求与响应的底层抽象
AgentAgentAgent 接口、Agent tree 与执行能力
RunnerRunnerSession、Invocation、事件持久化和恢复
FlowFlow双层循环、对象快照、离线运行示例、确认与流式分支
ToolToolTool 声明、执行、确认和结果恢复

3. 运行时上下文与持久化

主题文章重点
ContextContextContext 分层、派生、状态 delta 与取消
Session / EventSession & EventSession、Event、State 的关系
InMemorySession InMemory内存 Session Service 的实现
DatabaseSession DatabaseGORM 持久化、事务与 StateDelta
Vertex AIVertex AI SessionAgent Engine RPC、远端事件与 localSession
MemoryMemory跨 Session 的长期记忆检索

4. 横切能力与工作流

主题文章重点
PluginPlugin生命周期、callback 调度、替代结果和事件改写
WorkflowWorkflowNode、scheduler、interrupt 与 resume

5. 服务边界与基础设施

主题文章重点
ArtifactArtifactService 六个操作、版本、user 作用域与 GCS
ServerServerREST、SSE、A2A、Agent Engine 与入站 authn/authz
Agent RegistryAgent RegistryADC/mTLS 发现、Agent Card、RemoteAgent 与 MCP Toolset
Auth / Telemetry / Platform基础设施出站凭据、OTel 生命周期、时间/UUID/并发替换点

6. 已在相邻文章中提及、但不单列专题的适配器

源码中还有一些针对部署或具体能力的包。session/compaction 已在 Runner 篇讨论；tool/skilltoolset、tool/exitlooptool 与 tool/toolconfirmation 已在 Tool 篇的能力矩阵中定位；cmd/launcher/web 的 WebUI、A2A、Agent Engine、Eventarc/PubSub 子入口已在 Launcher/Server 篇定位。cmd/adkgo 部署 CLI 和 util/{aiplatform,instructionutil,vertexai} 仍属于配套辅助层，当前不单列运行时专题；独立 nested module plugin/agentanalytics 的版本约束见 Plugin 篇源码索引，不把它误算作根模块 v2.4.0 的同一包。

源码包覆盖表

下面按 adk-go v2.4.0 的公共目录核对文章入口；“配套定位”表示源码已在相邻文章或索引中出现，但没有再拆一篇重复解释。

源码包对应文章 / 位置覆盖状态
agent, agent/remoteagent, model, runner, workflowAgent / Model / Runner / Workflow独立专题
cmd/launcher 及 cmd/launcher/web/*Launcher / Server入口装配与协议挂载
tool 及 agenttool, mcptoolset, skilltoolset, exitlooptool, toolconfirmationTool主链专题 + 子包源码索引
session, session/database, session/inmemory, session/vertexai, session/compactionSession/Event、Database、InMemory、Vertex AI Session、Runner后端与压缩配套
memoryMemory独立专题
artifact, artifact/gcsartifactArtifact存储契约与两个实现
pluginPlugin生命周期专题
server/adkrest, server/adka2a, server/agentengine, server/authn, server/authzServer协议与入站身份专题
agentregistryAgent Registry发现与远端工厂专题
auth, auth/gcp, telemetry, platformAuth / Telemetry / Platform横切基础设施专题
cmd/adkgo, util/*本索引“配套辅助层”说明尚无独立运行时专题
plugin/agentanalyticsPlugin 源码索引独立 nested module，依赖版本单独说明

系列文章的组织方式

  1. 源码入口与阅读地图；
  2. 核心接口与数据结构；
  3. 主执行路径：调用栈、数据流和事件流；
  4. 关键细节与分支；
  5. 重新梳理运行时架构与边界；
  6. 这个模块解决了什么问题；
  7. 重点结论、常见误解和理解检查；
  8. 对应版本的源码、测试与进一步阅读。

每篇从一个具体输入开始，先解释正常路径，再一次改变一个条件：回调提供替代结果会怎样，工具失败会怎样，流式响应未结束会怎样，暂停后又凭什么恢复。源码片段旁解释触发条件、执行顺序和对象变化，便于在不同模块之间继续追踪同一条调用链。

源码摘录、删节代码、解释性伪代码与可运行示例分别标注。固定版本的函数链接用于定位实现；测试和示例用于观察具体输入的结果。模型服务能力与 SDK 中的能力判定也分别说明，避免把一个版本的代码规则当成所有版本的通用保证。

继续阅读

  • Flow：从一个不需要 API Key 的天气示例，观察两次模型调用之间的工具与事件闭环。
  • Blog：返回全部文章。