elonnzhang

VSCode Remote SSH 问题排查

Sat, 10 Oct 2026 00:00:00 +0800

一台开发机可以正常 SSH 登录，VS Code 的 Remote-SSH 却始终无法建立开发会话。问题不一定在网络或账号：SSH 登录成功之后，VS Code 还要在远端安装并启动 VS Code Server。这一步有自己的系统依赖。

本文记录一次实际排查：宿主机运行 CentOS 7，内核为 4.14，glibc 为 2.21。我们最终让本机 VS Code 通过 SSH 连接远端 Docker daemon，再直接进入开发容器。文末也说明为什么给宿主机补新版 glibc sysroot 只能算临时方案，以及容器对旧内核的限制。

SSH 连通，为什么 Remote-SSH 仍然失败？

普通 SSH 只需在远端启动 shell。Remote-SSH 的完整路径则是：

本机 VS Code → SSH 登录宿主机 → 安装或启动 VS Code Server → 打开远端工作区

VS Code 当前的 Linux 远程开发文档列出的通用要求包括：内核 ≥ 4.18、glibc ≥ 2.28、libstdc++ ≥ 3.4.25。这台机器的内核与 glibc 均低于门槛。所以 ssh 能打开 shell，并不能证明 VS Code Server 能在宿主机运行。遇到类似问题，先在宿主机检查 uname -r 和 getconf GNU_LIBC_VERSION，再查看 VS Code 的 Remote - SSH 输出，确认失败发生在登录、下载、安装还是启动阶段。仅凭版本号可以判断存在兼容风险，但不要把所有连接报错都归因于 glibc。

Agent Development Kit (ADK) · 08 - Tool

Wed, 23 Sep 2026 00:00:00 +0800

ADK-Go 源码阅读笔记 · Tool：从声明到执行，再回到事件

源码基准：ADK-Go v2.4.0，commit 4e57df40cbd35f055ba654b03ffb0e509fdd754a。下文的“当前实现”均指这个版本。

返回 ADK 源码阅读合集 · 前置阅读：Flow · 配套阅读：Plugin、Workflow。

用户问：“东京现在天气怎样？”模型返回 get_weather(city="Tokyo")。Tool 的工作不是把这串 JSON 直接交给某个函数，而是把模型可见的声明、本地可执行的实现、工具上下文里的动作和要写回 Session 的事件接成一条协议。本文用这一次调用贯穿正常、失败、流式、长任务与确认恢复路径。

FunctionDeclaration 只是模型可见的能力描述；本地执行还要在当前请求的 req.Tools 中找到实现。

词	在本文中的准确含义	不要混淆
Tool	`Name`、`Description`、`IsLongRunning` 三项公共元数据	不是必然带 `Run` 的公开接口
FunctionCall ID	模型这一次调用的 `FunctionCall.ID`，如 `call-weather-1`	工具确认事件自己的 ID 可以不同
Toolset	根据上下文返回工具集合，本条 Flow 会缓存收集结果	不是静态全局注册表
FunctionResponse	Tool 结果在 `session.Event` 中的模型协议表示	不等于已对用户显示的文本

一、源码入口与阅读地图

阅读顺序	源码	需要回答的问题
1	`tool/tool.go#L37-L57`	公共 Tool/Toolset 契约是什么？
2	`internal/toolinternal/tool.go#L28-L62`	哪些能力只在 ADK 内部识别？
3	`tool/toolutils/toolutils.go#L29-L73`	声明与本地实现如何写入请求？
4	`tool/functiontool/function.go#L77-L181`	Go 泛型函数怎样获得 schema 和声明？
5	`internal/llminternal/base_flow.go#L1160-L1360`	FunctionCall 怎样并发执行并生成事件？
6	`internal/llminternal/request_confirmation_processor.go#L37-L229`	确认回复怎样从历史恢复原调用？

Tool / Toolset
 │ Tools(ReadonlyContext)
 ▼
 Flow.f.Tools
 │ ProcessRequest
 ├───────────────┐
 ▼ ▼
req.Tools req.Config.Tools
本地执行表 模型声明
 │ │
 └──────┬────────┘
 ▼
 FunctionCall
 │ ID + Name + Args
 ▼
 ToolContext
 │
 ├─ Run / RunStream
 ├─ Actions / StateDelta
 └─ FunctionResponse Event

二、接口与数据：公开能力、内部能力和对象生命周期

1. 公共接口故意很小

源码中的 Tool 只有三个方法；Toolset.Tools 接收只读上下文并返回当前工具列表（tool/tool.go#L37-L57）。它没有 Run、Declaration 或 ProcessRequest。原因是 Tool 也可以代表 Gemini 原生能力或仅修改请求的工具，并不一定有本地 handler。

Agent Development Kit (ADK) · 09 - Context

Wed, 23 Sep 2026 00:00:00 +0800

ADK-Go 源码阅读笔记 · Context：上下文能力、状态变化与恢复边界

源码基准：ADK-Go v2.4.0，commit 4e57df40cbd35f055ba654b03ffb0e509fdd754a。本文的“当前实现”均指这个版本。

范围：公开 Context 接口、commonContext、callback/tool wrapper、状态与 artifact 追踪、派生和恢复信息；workflow 调度算法见配套文章。

返回 ADK 源码阅读合集 · 配套阅读：Agent、Runner、Flow、Tool、Workflow、Session Event。

工具函数收到一个 agent.Context，里面既能读用户输入，也能写状态、搜索 Memory、请求用户确认。它究竟是一份数据、一组服务，还是一个可以随时结束 Agent 的控制器？

答案需要分两层：Context 接口列出运行能力，具体构造器和 wrapper 决定当前调用点真正可用的能力。 同样写着 agent.Context，Agent 回调、工具、workflow 节点收到的对象并不完全相同。

本文用“杭州天气怎么样”贯穿：weather_agent 调用 get_weather，工具写入 last_city=Hangzhou，然后返回天气。第四节再把工具改成需要确认的“购买天气报告”，观察正常读写与暂停恢复的区别。

本文回答三个问题：

Go context、InvocationContext、ReadonlyContext、Context 各自提供什么？
工具写入的状态怎样进入 Event，何时才涉及持久化？
Context 派生、取消、分支和确认能保证什么，又不能保证什么？

阅读前先分清这些词

术语	含义	不应混成
Go Context	Deadline、Done、Err、Value 的请求链	Session 状态容器
InvocationContext	当前 Agent、Session、服务和 invocation 环境	单次模型请求
EventActions.StateDelta	本事件声明的状态变化	Context 派生用的 Delta
FunctionCallID	模型要求的一次函数调用 ID	Event.ID 或 InterruptID
InterruptID	workflow 等待外部响应的中断键	当前节点 RunID
Branch / IsolationScope	历史选择条件	用户权限或数据库隔离

一、源码入口与阅读地图

阅读顺序	文件 / 符号	要回答的问题
1	`agent/context.go`	三个公开接口之间到底怎样组合？
2	`internal/context/invocation_context.go`	Runner 创建的基础环境在哪里？
3	`agent/common_context.go`	callbacks、tools、nodes 怎样共享实现？
4	`callback_context_wrapper.go`、`tool_context_wrapper.go`	同一接口在不同调用点有哪些护栏？
5	`agent/common_context_delta.go`	浅拷贝派生保留和替换哪些字段？
6	`internal/llminternal/request_confirmation_processor.go`	确认对象怎样在下一次输入后重建？
7	`runner/run_node.go`、`runner/runner.go`	谁把 Context 里的 actions 接到 Event 和存储？

应用的 context.Context
 │ Runner 注入父子树、Plugin、运行配置等 Value
 ▼
internal/context.InvocationContext
 ├─ Session、Agent、InvocationID、UserContent
 ├─ Artifacts、Memory、RunConfig
 └─ Branch、IsolationScope、Ended
 │
 ▼
agent.commonContext
 ├─ Go Context 链 + invocation 环境
 ├─ actions / artifacts
 ├─ functionCallID / confirmation
 └─ resumeInputs / Path / RunID / SubScheduler
 │
 按场景构造
 ┌───────┼─────────────────┐
 ▼ ▼ ▼
普通节点 callback wrapper tool wrapper

public API 位于 agent；internal/context 是 Runner 等框架代码使用的适配层，应用不能从模块外直接导入 internal。业务扩展通常由框架把 Context 传进 callback、工具或节点函数。

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

Wed, 23 Sep 2026 00:00:00 +0800

ADK-Go 源码阅读笔记 · Vertex AI Session：远端后端怎样保持 Session 契约

源码基准：ADK-Go v2.4.0，commit 4e57df40cbd35f055ba654b03ffb0e509fdd754a。以下“当前实现”均指此版本。

返回 ADK 源码阅读合集 · 前置阅读：Session、Event 与 State、InMemory、Database · 配套阅读：Runner、Server。

session.Service 是 Runner 依赖的抽象，但不同后端并不提供相同的性能和事务语义。InMemory 把对象放在进程内，Database 把对象编码进本地数据库；session/vertexai 则把 Session、Event 和 State 映射到 Vertex AI Agent Engine 的 RPC。

这篇文章只追踪这个适配层，不把 Agent Engine 当成另一个 Runner。Runner 仍然负责 invocation 和事件消费，Vertex AI service 负责远端 Session 的创建、读取、列举、删除及追加。

一、源码入口与阅读地图

入口	源码	要回答的问题
构造	`session/vertexai/vertexai.go#L34-L56`	Project、Location、ReasoningEngine 怎样变成 Service？
Service	`vertexai.go#L58-L155`	五个公开操作如何委托远端 client？
本地句柄	`session.go#L29-L91`	远端 Session 返回后，Runner 持有的对象保存什么？
State	`session.go#L116-L154`	State 的读写是否需要再次 RPC？
RPC 映射	`vertexai_client.go#L69-L110`	Create 如何映射 Agent Engine resource？
Get 并发	`vertexai.go#L69-L114`	Session 元数据和 Events 如何同时读取？

runner.Run
 │ session.Service
 ▼
vertexAiService
 ├─ vertexAiClient.Get/Create/List/Delete
 ├─ Vertex AI Agent Engine RPC
 └─ localSession（本地句柄与快照）
 ├─ State() → 本地 map + mutex
 └─ Events() → 本地切片快照

二、接口与数据：远端资源加本地句柄

1. 配置中的 AppName 不是 Reasoning Engine ID

VertexAIServiceConfig 要求 ProjectID、Location 和 ReasoningEngine。创建 Session 时，client 会根据 req.AppName 解析对应的 Agent Engine resource，再把 req.UserID、初始 State 和可选 SessionID 转成 CreateSessionRequest（vertexai_client.go#L69-L105）。因此一个 service 可以服务多个 app，但每个 app 必须能解析到自己的 reasoning engine。

Agent Development Kit (ADK) · 15 - Plugin

Wed, 23 Sep 2026 00:00:00 +0800

ADK-Go 源码阅读笔记 · Plugin：理解每一次拦截会跳过什么

源码基准：ADK-Go v2.4.0，commit 4e57df40cbd35f055ba654b03ffb0e509fdd754a。以下行为均限定于此版本。

返回 ADK 源码阅读合集 · 配套阅读：Runner、Flow、Context、Tool、Workflow。

用户问“东京现在天气怎样”，Agent 调 get_weather(city="Tokyo")，模型再生成回答。应用希望同时记录审计日志、复用缓存并限制高风险能力。Plugin 把这些横切逻辑接到 Runner、Agent、Model、Tool 和 Event 的真实调用点上。

回调返回值决定哪些后续步骤会执行。AfterModel 不保证在 BeforeModel 后出现；OnEvent 不保证收到每个曾被写入 Session 的事件；AfterRun 也有尚未注册 defer 就返回的分支。

本文让 audit、cache、policy 三个插件按此顺序注册。正常路径先假设所有回调返回 nil,nil，然后逐一改变缓存命中、工具错误和事件拒绝条件。

术语	准确含义
Plugin 实例	Runner 共享的一组 callback 和可选 CloseFunc，可同时服务多个 invocation
PluginManager	内部按注册顺序调度回调的对象
返回 nil	保留当前对象并继续同阶段；共享指针仍可能已被原地修改
返回非 nil	结束当前阶段的回调链，具体跳过哪些后续步骤由调用方决定
Invocation / FunctionCall / Event ID	分别标识逻辑运行、一次工具请求、一个历史事件，不能相互替代

一、源码入口与阅读地图

层	入口	阅读问题
配置	`plugin/plugin.go#L28-L80`	注册的函数保存在哪里？
调度	`plugin_manager.go#L44-L133`	顺序、去重、nil 与 error 怎样处理？
Run / Event	`runner.go#L703-L775`	插件先于持久化还是后于持久化？
Agent	`agent.go#L163-L211`	BeforeAgent 返回内容后还会运行 AfterAgent 吗？
Model / Tool	`base_flow.go#L815-L999`、`#L1374-L1465`	两种 before 返回替代结果后分别跳过什么？

runner.PluginConfig.Plugins = [audit, cache, policy]
 │
 ▼
 PluginManager
 │ context value（共享实例）
 ┌──────────┼────────────┐
 ▼ ▼ ▼
 Runner Agent Flow
 Run/Event Agent hooks Model/Tool hooks
 │ │ │
 └──────────┴────────────┘
 │
 每一个调用点自己决定后续控制流

二、核心接口与数据结构

Plugin 与 Agent Callback 的边界

源码：runner/runner.go#L113-L161。

Agent Development Kit (ADK) · 16 - Workflow

Wed, 23 Sep 2026 00:00:00 +0800

ADK-Go 源码阅读笔记 · Workflow：图怎样执行，暂停后怎样继续

源码基准：ADK-Go v2.4.0，commit 4e57df40cbd35f055ba654b03ffb0e509fdd754a。下文的“当前实现”均指此版本。

本文完整比较三组相关代码：workflow 定义 Node、Edge 与图调度，agent/workflowagent 将图接入 Agent/Runner，agent/workflowagents 下的 Sequential、Parallel、Loop 直接组合已有 Agent。先解释图的构建与执行，再比较两种组合方式的数据传递、并发、停止和恢复边界。

返回 ADK 源码阅读合集 · 配套阅读：Agent、Runner、Context、Tool、Plugin。

用户要求“为东京生成天气简报”。最小实现可以是三个确定性节点：规范化城市名、查询天气、格式化简报。以后还可以同时查询出行提示，根据天气路由到不同模板，或者在发送简报前等待用户确认。

flowchart TD
 city["city：规范化城市名<br/>东京 → Tokyo"] -->|"城市名 Tokyo"| weather["weather：查询天气<br/>晴，22°C"]
 weather -->|"天气数据 Weather"| format["format：生成简报<br/>Tokyo：晴，22°C"]

图中的天气是示例程序返回的固定数据。city 输出城市名，weather 输出天气结构，format 把结构化数据变成简报文本；节点之间的箭头对应后文的 Edge。

Agent Development Kit (ADK) · 17 - Artifact

Wed, 23 Sep 2026 00:00:00 +0800

ADK-Go 源码阅读笔记 · Artifact：文件版本、作用域与事件摘要

源码基准：ADK-Go v2.4.0，commit 4e57df40cbd35f055ba654b03ffb0e509fdd754a。本文的“当前实现”均指这个版本。

本文范围：公开 artifact.Service 契约、请求校验、InMemoryService、GCS 实现，以及 Runner 如何把它们接到 agent.Context。Session/Event 中的 ArtifactDelta 只作为“版本摘要”解释，不展开整个 Session Service 的实现。

返回 ADK 源码阅读合集 · 配套阅读：Context、Runner、Session & Event、Tool。

用户上传一张天气截图，工具把它保存成 report.txt，随后又生成一版带结论的文件。应用需要回答几个看似简单的问题：第二次保存是不是覆盖第一次，下一次会话能不能看到同一个文件，Event 里的 ArtifactDelta 是否就是文件内容，以及 GCS 返回的 URI 能不能直接拿来下载？

先给结论：Artifact Service 保存的是带版本号的 genai.Part，版本键由 app/user/session/filename 组成；agent.Artifacts 只是把当前 Session 的身份填进请求；ArtifactDelta 只记录“某文件成功保存到了哪个版本”，并不代替保存，也不包含 payload。 InMemory 和 GCS 遵守同一个六方法接口，但版本竞争、返回的 Part 形态和元数据能力不同。

本文用同一组身份贯穿：AppName=weather、UserID=u-1、SessionID=s-1。先保存两次 report.txt，再读最新版本、指定版本和元数据；第四节把文件改名为 user:profile.json，并把后端换成 GCS，观察作用域和并发分支。

阅读前先分清这些词

术语	本文中的准确含义	不要混成什么
Artifact	一个 genai.Part 指针及其文件名、版本和存储身份	Session Event 本身；Event 只可携带版本摘要
artifact.Service	接受 AppName/UserID/SessionID/FileName 请求的六操作存储契约	agent.Artifacts 这个给 Context 使用的薄适配器
版本 0	在 Load/GetArtifactVersion 中表示“取最新”，在 Delete 中表示“删全部”	一个实际存储版本；实际版本从 1 开始
user: 文件名	触发跨 Session 的用户作用域	文件系统路径；路径分隔符仍会被拒绝
ArtifactDelta	filename -> version 的事件动作字段	保存操作、payload 或事务日志
CanonicalURI	后端原生方案的对象身份，例如 gs://…	已认证的 HTTP 下载地址

一、源码入口与阅读地图

Artifact 的入口不在 Runner，而在顶层 artifact 包。Runner 只负责把当前 Session 的身份装配进内部适配器；Context 和工具看到的是 agent.Artifacts，不是 artifact.Service 的请求结构。

Agent Development Kit (ADK) · 18 - Server

Wed, 23 Sep 2026 00:00:00 +0800

ADK-Go 源码阅读笔记 · Server：同一个 Agent 怎样被暴露成四种协议

源码基准：ADK-Go v2.4.0，commit 4e57df40cbd35f055ba654b03ffb0e509fdd754a。下文的“当前实现”均指这个版本。

返回 ADK 源码阅读合集 · 前置阅读：Runner、Artifact · 配套阅读：Launcher、基础设施。

用户向服务发送“东京现在天气怎样？”。在 ADK-Go 中，这句话可以从 REST POST /run 进入，也可以从 /run_sse 按事件流返回；同一个 Agent 还可以由 A2A JSON-RPC 或 Agent Engine 的执行方法调用。对应的执行入口最终都把输入交给 Runner，但它们对事件的包装、结束状态、会话 ID 和错误传递方式并不相同；Agent Engine 另外提供的会话 CRUD 方法则不会进入 Runner。

本文把 server 看成协议边界，而不是另一个 Agent 执行引擎：

server/adkrest 建立 REST 路由、认证 middleware、授权检查，并为每次请求创建 Runner；
server/adka2a/v2 实现 A2A AgentExecutor，把 ADK session.Event 转成 Task、artifact 和 status event；根路径的 server/adka2a 是兼容旧版 a2a-go 的 façade，已委托给 v2，不是另一套执行引擎；
server/agentengine 把 Agent Engine 的 class_method 分派到会话方法或 JSONL 流式方法；
cmd/launcher/web 只负责把这些 handler 挂到总 router、加前缀、CORS 和 HTTP server 生命周期。

REST、A2A 和 Agent Engine 都把实际推理交给 Runner；Server 负责身份、传输、编码和状态协议，不复制 Flow 的模型/工具循环。

Agent Development Kit (ADK) · 19 - Agent Registry

Wed, 23 Sep 2026 00:00:00 +0800

ADK-Go 源码阅读笔记 · Agent Registry：从目录记录到 RemoteAgent 与 MCPToolset

源码基准：ADK-Go v2.4.0，commit 4e57df40cbd35f055ba654b03ffb0e509fdd754a。下文的“当前实现”均指这个版本。

本文范围是根模块 agentregistry：客户端创建、Agent/MCP server/模型 endpoint 的只读发现、分页迭代器，以及两个工厂 RemoteAgent 和 MCPToolset。注册资源的写入 API、远端 Agent 的业务推理和 MCP server 的工具实现不在这个包里。

返回 ADK 源码阅读合集 · 配套阅读：Agent、Tool、Context、Server、基础设施。

用户要“生成东京天气简报”。应用不把某个 MCP endpoint 写死，而是在 projects/demo/locations/global 中寻找声明了 get_weather 的 MCP server；找到后用 MCPToolset 接入一个本地 llmagent。另一条路径把已注册的天气专家解析成 RemoteAgent，让本地 Agent 通过 A2A 委托整段任务。

这两个路径共享同一个目录访问层，却在各自读完记录后分开出站：注册表请求可以用 ADC，MCP 的 Google API endpoint 可以复用这份客户端，A2A 远端则不会自动拿到注册表凭据。Agent Registry 返回元数据和 endpoint；后续 A2A/MCP 流量直接发往远端服务。

本文回答三个问题：

New 如何选择 ADC、mTLS endpoint、配额项目和自定义 HTTP client？
List/Get/All 如何拼资源名、保留过滤器并按需分页？
一条 Agent 记录怎样变成 agent.Agent，一条 MCP 记录怎样变成 tool.Toolset，两者的出站认证边界在哪里？

阅读前先分清这些词

术语	本文中的准确含义	不要混淆
Registry `Agent`	注册表返回的目录记录，包含协议、技能和可选嵌入卡片	可运行的 `agent.Agent`；它只是元数据
Agent Card	A2A 客户端协商所需的 `a2a.AgentCard`，可从 `Card.Content` 解码或由协议字段合成	注册表记录本身
`List` / `All`	`List` 返回一页；`All` 返回 Go `iter.Seq2`，消费时才请求下一页	一次请求就把所有资源读入内存
Registry HTTP client	调用 `agentregistry.googleapis.com` 的 REST client，可能带 ADC	发往 A2A/MCP endpoint 的出站 client
MCP `Tool` 元数据	`MCPServer.Tools` 中目录声明的工具名称和提示	MCP 会话连上后由 server 实际返回的 live tool
`agent.Loader`	本地名字到已构造 `agent.Agent` 的装载器	注册表的远程目录查询

贯穿示例使用三个资源名：

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

Wed, 23 Sep 2026 00:00:00 +0800

ADK-Go 源码阅读笔记 · Auth、Telemetry 与 Platform：横切能力怎样进入一次运行

源码基准：ADK-Go v2.4.0，commit 4e57df40cbd35f055ba654b03ffb0e509fdd754a。本文的“当前实现”均指这个版本。

返回 ADK 源码阅读合集 · 配套阅读：Runner、Context、Plugin、Server。

ADK 的主链文章通常从 Runner 开始：取得 Session，运行 Agent，保存 Event。但真实应用还要解决三类横切问题：工具访问外部服务时用谁的凭据，运行过程怎样被观测，以及事件里的时间戳和 ID 怎样在测试中变得可控。

这三件事分别落在 auth、telemetry 和 platform 包。它们都不负责调用模型，也不拥有 Session；它们通过接口和 context.Context 进入调用树，把能力交给真正的请求、事件或服务。

凭据和测试 provider 都沿着 context 或对象边界传递。因此“配置了 ADC”不等于每个 HTTP 请求都会自动带 token，“初始化了 Telemetry”也不等于已经注册成全局 provider。

阅读前先分清三个层次

层次	负责什么	不负责什么
`auth.CredentialProvider`	在一次请求上下文中解析可用凭据	不发送 HTTP 请求
`auth.Credential`	把已解析凭据写入 HTTP headers	不决定何时刷新或重试
`auth.Transport`	每次 `RoundTrip` 解析并应用凭据	不替调用方管理用户授权
`telemetry.Providers`	持有 OTel tracer/logger provider，注册和关闭	不自动创建业务 span
`platform` provider	为当前 context 提供时间、UUID 和任务调度策略	不改变包级默认行为

一、源码入口与阅读地图

阅读顺序	源码	要回答的问题
1	`auth/credential.go#L25-L120`	一个凭据怎样写到请求头？
2	`auth/providers.go#L29-L178`	Static token、ADC、Service Account 的解析边界是什么？
3	`auth/transport.go#L22-L75`	provider 何时被调用，Request 是否会被原地修改？
4	`telemetry/telemetry.go#L28-L119`	OTel provider 怎样创建、注册和关闭？
5	`telemetry/config.go#L55-L136`	Cloud 导出和自定义 processor 怎样组合？
6	`platform/time.go#L22-L50`、`uuid.go#L23-L52`	时间和 ID 的 provider 如何只影响当前调用树？
7	`platform/exec.go#L22-L94`	模型工具并发怎样替换为宿主自己的 TaskRunner？
8	`auth/gcp/client.go#L203-L370`	Agent Identity / IAM Connector 的 transport client 如何轮询和映射凭据？

agent.Context / request.Context
 │
 ├── auth.Transport.RoundTrip
 │ ├─ CredentialProvider.Credential
 │ ├─ Credential.Apply
 │ └─ Base.RoundTrip
 │
 ├── session.NewEvent / other ADK code
 │ ├─ platform.Now(ctx)
 │ └─ platform.NewUUID(ctx)
 │
 └── telemetry.New → Providers.SetGlobalOtelProviders
 └─ Providers.Shutdown

二、核心接口与数据

1. Provider、Credential、Transport 是三次分工

CredentialProvider 只返回一个实现 Apply(http.Header) 的 Credential。例如 BearerCredential 设置 Authorization: Bearer ...，APIKeyCredential 设置调用方指定的 header；OAuth2Credential 则在每次 Apply 时从 TokenSource 取得 token（credential.go#L47-L95）。

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

Tue, 22 Sep 2026 00:00:00 +0800

ADK-Go 源码阅读笔记 · Session、Event 与 State：一轮执行怎样留下历史和状态

源码基准：ADK-Go v2.4.0，commit 4e57df40cbd35f055ba654b03ffb0e509fdd754a。以下“当前实现”均指这个版本。

返回源码阅读合集 · 配套阅读：Runner、Context、InMemory Session、Database Session、Memory。

用户先说“以后天气都用摄氏度”，再问“杭州天气怎么样”。应用需要保留三类信息：用户说过什么、这一轮执行发生过什么、下次应该读取哪个偏好。ADK 分别用 Event、Session.Events() 和带作用域的 State 表达这些信息。

Session 是一段会话的历史与状态入口；Event 承载一次可记录的交互及其动作；StateDelta 则把本次状态修改送进 Session 服务。 理解这套模型，重点是区分本地可读、事件携带、存储成功。工具能读到自己刚写的值，并不意味着数据库已经提交。

本文回答三个问题：一段会话怎样标识多轮执行？一次 State().Set 如何变成下轮可见的状态？哪些事件会保存、哪些字段只是给其他运行时组件消费？

贯穿示例与术语

应用名为 weather，用户为 u1，有两段会话 s1、s2。s1 的 invocation i1 接收“杭州天气怎么样，以后用摄氏度”，工具产生以下增量：

// 对象快照示意：同一个事件可以同时修改不同作用域。
map[string]any{
 "app:weather_provider": "provider-a",
 "user:temperature_unit": "C",
 "last_city": "Hangzhou",
 "temp:lookup_attempt": 1,
}

概念	例子	生命周期和用途
Session 身份	`(weather, u1, s1)`	一段跨多轮的对话；不能仅凭 `s1` 区分所有用户
Invocation	`i1`	一次执行关联的一组事件；恢复路径可能延续已有身份
Event	`e-tool`	一条工具结果、模型响应、用户消息或框架记录
State	`user:temperature_unit=C`	当前可读的键值视图
StateDelta	`{"user:temperature_unit":"C"}`	这条事件携带的变更，不是完整状态

一、源码入口与阅读地图

顺序	文件 / 符号	需要回答的问题
1	`session/service.go: Service`	创建、读取和追加分别通过什么接口？
2	`session/session.go: Session / Event`	谁保存身份、历史和状态？
3	`agent/common_context.go: callbackContextState`	Context 的写入为什么会记录 delta？
4	`runner/runner.go`	Agent 事件何时追加，何时交给调用方？
5	`internal/sessionutils/utils.go`	混合前缀怎样拆成独立状态？
6	`session/sessiontestsuite/service_suite.go`	服务共享的行为检查有哪些？

应用与工具 运行协调层 存储层
ctx.State().Set(k, v) ──┐
 ├─> Event.Actions.StateDelta ──> AppendEvent
模型 / 工具返回 Content ┘ ↑ │
 Runner 消费 Agent ├─ 追加历史
 ├─ 更新状态
 └─ 更新时间

session 是公开包；internal/sessionutils 是框架内部的拆合实现，应用不应导入它。应用通常选择一种 session.Service 注入 Runner，而不是直接构造未导出的内存 Session 或数据库 Session。

Agent Development Kit (ADK) · 11 - Session InMemory

Tue, 22 Sep 2026 00:00:00 +0800

ADK-Go 源码阅读笔记 · InMemory Session：一把锁下的两份 Session

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

返回源码阅读合集 · 前置阅读：Session、Event 与 State · 对照阅读：Database Session、Memory。

session.InMemoryService() 适合单进程、短生命周期的运行。它没有数据库连接和 JSON 往返，而是用一个有序 map 保存 Session，再用 App/User 两级 map 保存共享状态。真正容易误解的地方是：一次 AppendEvent 同时改调用者持有的 Session 和服务 map 中保存的 Session；两边不是同一条 Event 切片。

贯穿例子仍是 weather/u1：s1 把 user:temperature_unit=C 和 last_city=Hangzhou 写入；s2 读取到用户偏好，却不会自动看到 s1 的 Session 状态。随后用 temp:attempt 展示当前实现的临时键例外。

术语先分开

词	在 InMemory 中的含义	不能推断什么
服务保存的 Session	`omap` 中服务持有的记录	不是调用方拿到的同一个指针
调用方持有的 Session	`Create` / `Get` 返回给调用方的 `*session`	不是数据库事务代理
State map	读视图中的扁平 key map	不代表物理上只有一块 map
保存后的 Event	追加到某个 Session 的事件对象	不保证与传入 Event 深拷贝一致

一、源码入口与阅读地图

顺序	位置	作用
1	`session/service.go:79-85`	`InMemoryService()` 装配 App/User map
2	`session/inmemory.go:37-44`	`inMemoryService` 的锁、Session 表、共享状态
3	`session/inmemory.go:46-93`	Create 与初始 State 分发
4	`session/inmemory.go:95-176`	Get/List 的过滤、合并和复制
5	`session/inmemory.go:197-303`	AppendEvent、共享状态与服务记录
6	`session/inmemory.go:319-481`	本地 Session、State、临时键过滤

InMemoryService()
 │
 ├── mu: sync.RWMutex
 ├── sessions: ordered map[encoded(app,user,session)] *session
 ├── appState: map[app]stateMap
 └── userState: map[app][user]stateMap

Create/Get ──复制──> 调用方 调用方 *session
AppendEvent ───────> 调用方 *session + 服务记录 *session

有序 map 的价值不只是“稳定遍历”：List 通过 ordered.Encode 后的范围扫描，按 App、User、Session 的编码前缀选出范围。编码与扫描边界决定了 userID=="" 时列出某 App 下所有用户。

Agent Development Kit (ADK) · 12 - Session Database

Tue, 22 Sep 2026 00:00:00 +0800

ADK-Go 源码阅读笔记 · Database Session：一次 AppendEvent 如何跨四张表提交

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

返回源码阅读合集 · 前置阅读：Session、Event 与 State · 对照阅读：InMemory Session、Memory。

session/database 并不是把完整 Session JSON 塞进一列。它把 Session 元数据和 Session state 放在 sessions，事件放在 events，App/User 共享状态各自放在独立表；一次 AppendEvent 在一个 GORM 事务内更新状态、插入事件和推进 update_time。

例子中，weather/u1/s1 的 e1 把 user:temperature_unit=C、last_city=Hangzhou 写入；另一个请求持有旧快照并尝试追加 e2。数据库实现会先把 e2 应用到本地 localSession，再在事务里用更新时间拒绝 stale 快照。拒绝不等于调用方手中的对象自动回滚。

一、源码入口与阅读地图

顺序	文件 / 符号	作用
1	`database/service.go:46-82`	构造 Service 与 AutoMigrate
2	`database/storage_session.go:30-108`	四个 GORM 模型中的 Session/Event
3	`database/service.go:85-158`	Create 事务
4	`database/service.go:160-253`	Get 的 SQL 过滤和 JSON 解码
5	`database/service.go:354-482`	AppendEvent、stale 检查与事务
6	`database/gorm_datatypes.go`	`stateMap` / `dynamicJSON` 的数据库适配

Create / Get / AppendEvent
 │
 ▼
 databaseService (*gorm.DB)
 │
 ┌───────┴──────────┐
 │ GORM 操作 │
 │ app_states │
 │ user_states │
 │ sessions │
 │ events │
 └───────┬──────────┘
 │
 ▼
 PostgreSQL / MySQL / SQLite / Spanner Dialector

NewSessionService 自己调用 gorm.Open；NewSessionServiceFromDB 接收既有连接；AutoMigrate 通过具体类型断言拿到 *gorm.DB，把其他 Session Service 实现传进去会返回 invalid session service type。构造代码说明它不是所有 Session Service 都共享的迁移入口。

Agent Development Kit (ADK) · 14 - Memory

Tue, 22 Sep 2026 00:00:00 +0800

ADK-Go 源码阅读笔记 · Memory：过去的会话怎样进入下一次模型请求

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

返回源码阅读合集 · 配套阅读：Session、Event 与 State、Runner、Context、Tool、Flow。

用户在 s1 说“以后请用摄氏度报告天气”，第二天新建 s2，问“还记得我偏好的温度单位吗”。Session 服务知道每段会话的历史，却不会自动把 s1 的内容塞进 s2。Memory 提供一条独立路径：应用显式摄取旧 Session，再在新请求中搜索相关 Entry，把结果放进工具响应或模型 instruction。

最先要分清的是保存 Session、摄取 Memory、消费检索结果。Runner 会在普通事件路径追加 Session 事件，但仅仅配置 MemoryService 不会让每轮结束时自动摄取，也不会自动修改 Prompt。

本文用 weather/u1/s1 的温度偏好和 weather/u1/s2 的新问题，追踪谁写、什么时候写、如何搜、结果又通过哪条路径到达模型。

阅读前先分清这些词

术语	本文中的含义	与相近概念的区别
Session	一段特定对话的历史与状态	不等于跨会话搜索索引
Memory Service	摄取 Session、执行检索的接口	不强制向量数据库或自动摘要
Entry	后端返回的一条记忆内容	InMemory 是文本事件，Vertex 可以是服务端提炼的 fact
`load_memory`	模型显式调用的函数工具	搜索 query 由模型给出
`preload_memory`	模型请求处理器形式的工具	每次请求自动检索，且不向模型声明函数

一、源码入口与阅读地图

顺序	位置	需要回答的问题
1	`memory/service.go`	公共写入和检索契约是什么？
2	`runner/runner.go:676-694`	配置的服务怎样进入 InvocationContext？
3	`internal/memory/memory.go`	搜索作用域由谁填充？
4	`memory/inmemory.go`	摄取、覆盖、词索引、排序与限制
5	`loadmemorytool/tool.go`	显式工具如何把 Entry 交回模型？
6	`preloadmemorytool/tool.go`	哪个 query、哪次请求、注入什么 instruction？
7	`memory/vertexai/vertexai_client.go`	云端写入究竟上传内容还是引用 Session？

上一段会话 s1 新一段会话 s2
Session.Events 用户新问题
 │ │
应用调用 AddSessionToMemory ├─ preload: 请求前搜索
 │ └─ load: 模型调用工具
 ▼ │
Memory 后端 <──────────── SearchMemory(query) ─────┘
 │
 └─ Entry[] ──> instruction 或 FunctionResponse ──> 模型

internal/memory.Memory 是 Context 适配器，不是另一个记忆库。它填充 AppName/UserID，再调用配置的公开 memory.Service。服务是进程级或应用装配阶段的依赖；适配器则随 invocation 绑定当前用户和应用身份。

Agent Development Kit (ADK) · 05 - Agent

Mon, 21 Sep 2026 00:00:00 +0800

ADK-Go 源码阅读笔记 · Agent：统一事件流与不同执行策略

源码基准：ADK-Go v2.4.0，commit 4e57df40cbd35f055ba654b03ffb0e509fdd754a。本文的“当前实现”均指这个版本。

范围：base Agent 的普通 Run、LlmAgent 的 Flow 创建过程、顺序 / 循环 / 并行 Agent，以及 Remote 和节点入口的边界。

返回 ADK 源码阅读合集 · 配套阅读：Runner、Flow、Context、Workflow、Plugin。

用户问“杭州天气怎么样”，模型要求调用 get_weather(city="Hangzhou")，工具返回气温，模型再生成答案。这几次操作属于同一个 Agent call，却包含两次模型调用和多条事件。

Agent 模块解决的是：把不同执行策略统一成“接收上下文、逐条产生事件”的对象，让 Runner 和父 Agent 可以用相同方式驱动它们。 模型回合由 Flow 实现，顺序与并行由组合 Agent 实现，共同的回调和事件骨架则放在 base Agent。

本文回答三个问题：

Agent 的接口为何只有几个方法，却不能由应用直接从零实现？
before → 主体 → after 的真实顺序是什么，错误和内容如何改变后续步骤？
LlmAgent、Sequential、Loop、Parallel、Remote 怎样接入这套协议，又有哪些不同边界？

阅读前先分清这些词

术语	准确含义	天气例子
Agent 对象	保存名称、配置、子 Agent 和执行函数的对象	`weather_agent` 可以被多次运行
Agent call	一次 `Agent.Run` 的实际迭代过程	读取天气并回答
Invocation	Runner 组织的一次执行；恢复可沿用 ID	可包含多个 Agent call
Flow step	准备请求、一次模型调用及其工具处理	查询 step + 总结 step
Event	ADK 运行记录，承载 Content、Actions、身份等	调用、工具结果、答案
Ended	当前上下文关联的提前停止标志	不是 Go 的 Done 通道

主线假设回调都返回 nil、没有 transfer、非流式输出，工具成功返回 {"temperature":26}。理解正常路径后，再改变这些条件。

Agent Development Kit (ADK) · 06 - Runner

Mon, 21 Sep 2026 00:00:00 +0800

ADK-Go 源码阅读笔记 · Runner：一次输入的执行、持久化与恢复

源码基准：ADK-Go v2.4.0，commit 4e57df40cbd35f055ba654b03ffb0e509fdd754a。本文的“当前实现”均指这个版本。

范围：普通 Run 的两条执行路径、消息与 Plugin、HITL、Live 和 Context Compaction。模型与工具内部循环见 Flow，数据库内部存储见 Session 配套文章。

返回 ADK 源码阅读合集 · 配套阅读：Agent、Flow、Context、Plugin、Workflow、Session Event。

用户问“杭州天气怎么样”，Agent 可以调用工具并产出答案，但应用还需要决定：这条输入属于哪个会话、由哪个 Agent 接着回答、工具结果何时保存、用户确认回来后从哪里继续，以及前端断开后还执行哪些收尾。

Runner 把输入、运行环境、事件持久化和恢复入口接成一条调用链。 它不直接实现模型推理，却决定 Agent 产生的记录怎样进入 Session、怎样经过 Plugin、怎样交到调用方。

本文回答三个问题：

Runner 为一次输入创建哪些对象，它们被谁读取和修改？
用户消息、模型 FunctionCall、工具结果、最终答案如何按序保存并流出？
错误、提前停止、长任务恢复、Live 和压缩分别改变哪一段协议？

阅读前先分清这些词

术语	本文中的含义	易混淆之处
Runner	长期持有 root Agent、服务、Plugin 和配置的运行器	不是每次模型调用都新建
Session	App + User + SessionID 关联的历史与状态	一个 Session 可以有多次 invocation
Invocation	一次执行关联的逻辑 ID	暂停和恢复可能共用 ID
普通 Run	返回一个迭代函数，range 时才执行	非 LLM root 与 LLM root 内部路径不同
Node runtime	LLM root 的合成 workflow / 节点运行路径	不代表所有 root 都进入它
Partial	流式过程中尚未形成完整记录的响应	final 判断和 partial 标志不是同一件事
AppendEvent	服务收到一条待记录事件	不等于跨工具、artifact、数据库的原子事务

贯穿示例

主线使用 AppName=weather_app、userID=user-1、sessionID=session-1，root 为 chat 模式 weather_agent。输入是“杭州天气怎么样”，模型先请求 get_weather(city="Hangzhou")，工具返回 temperature=26，第二次模型调用生成中文回答。

Agent Development Kit (ADK) · 01 - Overview

Sun, 20 Sep 2026 00:00:00 +0800

ADK-Go 源码阅读笔记 · Overview：从一次请求看懂整个框架

源码版本：ADK-Go v2.4.0，commit 4e57df40cbd35f055ba654b03ffb0e509fdd754a。

系列目录 · 下一篇：Quickstart · 执行主线：Runner、Flow。

用户问“杭州现在多少度”，模型输出一个 get_weather 调用，工具返回 26°C，模型再组织成自然语言回答。这里至少发生了两次模型请求、一次工具执行和多次事件追加。

ADK-Go 把这些工作分给不同组件：Agent 描述行为，Runner 驱动执行，Flow 连接模型和工具，服务保存历史与状态。一次模型响应只是 Agent 运行过程中的一步。

这篇总览围绕三个问题展开：

从程序入口到模型、工具和数据库，中间有哪些边界？
一次输入怎样变成事件，工具结果又怎样进入下一次模型请求？
接口抽象提供了什么，又有哪些必须结合具体实现理解的限制？

一、源码入口与阅读地图

ADK-Go 是用 Go 代码构建 Agent 应用的框架。应用通过构造函数组合 Agent、Model、Tool、服务和运行入口，不需要先把整个应用写成一份声明式工作流。

阅读层次	文件 / 入口	解决的问题
应用示例	`examples/quickstart/main.go`	最小应用怎样装配
启动入口	`cmd/launcher/launcher.go`	console / web 如何共用应用配置
Agent 契约	`agent/agent.go`	什么对象可以被执行
请求驱动	`runner/runner.go`	一次输入如何进入运行时
模型工具循环	`internal/llminternal/base_flow.go`	模型提出调用后由谁执行
会话记录	`session/session.go`	历史、状态和事件如何表达
图调度	`workflow/scheduler.go`	节点、事件和恢复如何协调

先把模块放在同一张结构图上：

Application
 |
 +-- Launcher / HTTP handler / 自定义入口
 | |
 | v
 | Runner <------ SessionService
 | | <--------- ArtifactService / MemoryService
 | v
 | InvocationContext：绑定本次执行所需的对象
 | |
 | v
 | Agent / node runtime
 | |
 | +-- LlmAgent --> Flow --> Model
 | | | |
 | | +<- Tool <-+ FunctionCall
 | |
 | +-- 自定义 Agent / Workflow / 远程 Agent
 |
 +-- Plugin：在已接入的生命周期边界观察或改变行为

Model 适配器与 Tool 的业务实现可以替换，运行层仍围绕请求、响应和事件协作。但是模型共用接口并不意味着所有 provider 支持相同工具、多模态或流式能力。

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

Sun, 20 Sep 2026 00:00:00 +0800

ADK-Go 源码阅读笔记 · Quickstart：一个 main 函数怎样启动 Agent 应用

源码版本：ADK-Go v2.4.0，commit 4e57df40cbd35f055ba654b03ffb0e509fdd754a。

系列目录 · 前置阅读：Overview · 后续阅读：Launcher、Model、Agent。

一个能回答天气问题的程序，为什么既要创建 Model，又要创建 Agent，还要经过 Loader 和 Launcher？因为这几个对象回答的是不同问题：调用哪个模型、如何组织行为、如何找到应用入口、用户通过什么界面交互。

官方 Quickstart 把这条装配链放在一个 main 中。先看它的结构，再跟踪用户输入到达以后发生的事情，就能把配置代码与运行代码分开。

一、源码入口与阅读地图

文件 / 符号	在这个例子中的职责
examples/quickstart/main.go	创建模型、Agent、Loader 与 Launcher
gemini.NewModel	创建 Gemini SDK client 和模型适配器
llmagent.New	把配置装配为 LlmAgent
agent.NewSingleLoader	用一个 Agent 提供加载入口
full.NewLauncher	提供 console 与 web 两类启动方式
console.Run	创建 Session 和 Runner，进入输入循环

构造阶段
 genai.ClientConfig
 |
 v
 gemini.NewModel -> llmagent.New -> NewSingleLoader
 |
 v
 launcher.Config
 |
运行阶段 v
 os.Args[1:] ----------------> Launcher.Execute
 |
 console 或 web 入口
 |
 Runner / Agent

创建了 Agent 对象，还不代表模型已经生成过一次回答。模型请求通常要等到入口收到输入并消费运行事件时才发生。

Agent Development Kit (ADK) · 03 - Launcher

Sun, 20 Sep 2026 00:00:00 +0800

ADK-Go 源码阅读笔记 · Launcher：从命令行到 Runner

源码版本：ADK-Go v2.4.0，commit 4e57df40cbd35f055ba654b03ffb0e509fdd754a。

系列目录 · 前置阅读：Quickstart · 后续阅读：Runner、Flow。

Launcher 是 ADK 应用的进程入口层。它处理命令行参数、校验进程级配置、选择运行方式，并把同一份 AgentLoader、SessionService、Plugin 和鉴权配置交给 console 或 web 子入口。

它不负责模型推理，也不负责工具执行。Launcher 选择怎么进入应用，Runner 才驱动一次 Agent 运行。

一、源码入口与阅读地图

层次	文件 / 符号	作用
顶层契约	`cmd/launcher/launcher.go`	Launcher、SubLauncher、Config
选择器	`cmd/launcher/universal/universal.go`	按第一个关键词选择入口
预设组合	`cmd/launcher/full/full.go`	console + 全部 web 子入口
生产组合	`cmd/launcher/prod/prod.go`	REST API + A2A
终端运行	`cmd/launcher/console/console.go`	Session、Runner、stdin 循环
HTTP 运行	`cmd/launcher/web/web.go`	router、sublauncher、HTTP server
REST 挂载	`cmd/launcher/web/api/api.go`	创建 `adkrest.Server` 并挂到 path prefix

整体关系可以先压缩成一张图：

Agent Development Kit (ADK) · 04 - Model

Sun, 20 Sep 2026 00:00:00 +0800

ADK-Go 源码阅读笔记 · Model：统一接口怎样连接不同模型服务

源码版本：ADK-Go v2.4.0，commit 4e57df40cbd35f055ba654b03ffb0e509fdd754a。

系列目录 · 配套阅读：Quickstart、Flow、Tool。

Flow 已经准备好用户消息、历史、指令和工具声明，下一步要把请求交给模型服务。Gemini 和 OpenAI 的请求字段、角色、函数调用与流式事件并不相同；Model 层把这些差异放在适配器中处理，向上提供统一的 LLMRequest → LLMResponse 接口。

实现了同一个 LLM 接口，不代表所有模型支持相同的配置和工具。这篇文章围绕一次天气函数调用，说明统一数据怎样跨过 provider 边界，以及信息在转换中如何被保留或拒绝。

一、源码入口与阅读地图

model/
├─ llm.go LLM / LLMRequest / LLMResponse
├─ registry.go 模型名正则 -> Factory
├─ gemini/gemini.go GenAI SDK 适配器
├─ openaimodel/
│ ├─ openai.go Responses API 调用与流式收尾
│ ├─ request.go 请求、消息、配置转换
│ ├─ tools.go 函数声明与 tool choice
│ ├─ response.go 返回内容、usage、结束原因
│ └─ stream.go Responses 事件 -> GenAI 中间结构
└─ apigee/apigee.go 配置代理后委托 Gemini adapter

入口 / 文件	阅读时要回答的问题
model/llm.go	上层到底传什么、收到什么
Flow.callLLM	哪些 callback 返回后不再调用模型
gemini.GenerateContent	普通调用和流式调用如何选择
buildOpenAIParams	通用请求如何转换成 Responses 参数
streamTranslator	provider 的 delta 事件怎样转成通用 part
streamingResponseAggregator	增量和完整响应怎样共存
model.Register / NewLLM	字符串名称怎样解析成实例

二、核心接口与数据结构

1. 两个方法的公共契约

下面是接口与请求结构的源码摘录：