拨开迷雾看本质：从零推导 ChatModelAgent（模型适配层与 Agent 运行时）

在 react.md 里看到的是 “ReAct 作为范式” 的推导；而本篇把视角切到 chatmodel.go 作为工程实现：它不只是“为了 ReAct 画图”，更是把 模型层（SDK/MCP） 变成 可观测、可插拔、可恢复 的 Agent 运行时。

0. 前置基建：大模型 API 的抽象演进

在深入推导 ChatModelAgent 之前，我们必须先弄清楚：底层的 LLM 到底是个什么东西？ 从模型厂商提供的原生 SDK 到 Eino ADK 里的 ChatModelAgent，这中间经历了怎样的抽象演进？

0.1 寻找“第一性原理”：原生厂商 SDK 与手写 HTTP

最原始的业务需求是：把一串对话发给模型，拿回一串回答。
如果不使用任何框架，我们直接调用 OpenAI 的 SDK，代码是这样的：

// 第一性原理：原生厂商 SDK
func CallOpenAI(history []openai.ChatCompletionMessage) string {
    req := openai.ChatCompletionRequest{
        Model:    openai.GPT4,
        Messages: history,
        Tools:    []openai.Tool{{...}}, // 绑定一堆工具 Schema
    }
    resp, err := client.CreateChatCompletion(ctx, req)
    return resp.Choices[0].Message.Content
}

痛点与危机：

1. 厂商绑定（Vendor Lock-in）：OpenAI 的 Message 结构体和 Anthropic (Claude) 的结构体完全不一样。如果业务想切模型，整个系统的代码都要重写。
2. 多模态与工具调用的碎片化：怎么传图片？怎么传工具结果？各家的 JSON 格式千奇百怪。
3. 并发安全危机（状态突变）：注意看，Tools 是绑在 Request 上的。如果你在一个全局单例的 Client 上调用 BindTools()（很多早期框架的设计），当并发请求进来时，A 用户的工具会覆盖 B 用户的工具！

0.2 第一次演进：组件层的大一统接口 (components/model)

为了解决上述痛点，Eino 在最底层（components 包）做了一次极其关键的接口抽象。
目标是：抹平所有模型厂商的差异，定义统一的对话与工具挂载协议。

在 components/model/interface.go 中，我们看到了演进后的本质代码：

// 统一的消息结构（抹平 OpenAI、Claude 差异）
type Message struct {
    Role    RoleType
    Content string
    ToolCalls []ToolCall
}

// 演进一：最基础的生成接口
type BaseChatModel interface {
    Generate(ctx, input []*schema.Message) (*schema.Message, error)
    Stream(ctx, input []*schema.Message) (*schema.StreamReader, error)
}

// 演进二：解决并发工具挂载的终极形态（不可变模式）
type ToolCallingChatModel interface {
    BaseChatModel
    
    // 极其关键的设计：WithTools 必须返回一个新的实例！
    // 绝对不能修改当前实例的状态，彻底解决并发工具覆盖的 Bug
    WithTools(tools []*schema.ToolInfo) (ToolCallingChatModel, error)
}

至此，底层的基建已经完成。我们得到了一个绝对干净、并发安全、支持工具挂载的标准化模型底座。
但这只是“执行器”，还缺一个“大脑（引擎）”来驱动它。这就是 adk.ChatModelAgent 诞生的背景。

---

1. 第一性原理：ChatModelAgent 解决的是什么问题？

components/model 已经能让我们“调模型拿回答”。但真实业务要的是一个 Agent 运行时，它需要把“模型调用”变成：

• 可观测的事件流：对外统一输出 AgentEvent，支持打字机与工具结果。
• 可插拔的生命周期：允许在模型调用前后改写消息、指令、工具清单、重试策略。
• 可恢复的执行现场：支持 Human-in-the-loop 的挂起与恢复（Interrupt/Resume）。
• 可组网的控制流：支持 Transfer/Exit 这种改变控制权的动作语义。

这些职责，才是 chatmodel.go 的存在理由。

---

2. 抽象主线一：事件流（把模型与工具统一成 AgentEvent）

2.1 模型事件：从 schema.Message 到 AgentEvent

过程（How）：模型输出原本是 *schema.Message 或其流。ChatModelAgent 通过事件发送包装器，把它转成 AgentEvent 并推到外层 Iterator。

源码对应：

• NewEventSenderModelWrapper：见 wrappers.go#L239-L320

2.2 工具事件：工具结果也必须进入同一根事件管道

过程（How）：工具执行的输出会被包装为 ToolMessage，再转成 Tool 事件发出去；并且允许工具“附带一个 Action”。

源码对应：

• ToolCall middleware 的顺序声明：见 chatmodel.go#L361-L376
• eventSenderToolHandler：见 wrappers.go#L344-L483

动作类比：

• 模型吐字像“口述”。
• 工具返回像“递交一张凭证”。
• AgentEvent 像“加盖了身份与角色的公文”，便于流式 UI、日志、调度器统一消费。

---

3. 抽象主线二：状态与中间件（把模型调用升格为可重写生命周期）

3.1 stateModelWrapper：模型调用的交通枢纽

过程（How）：

• 从 compose 的 State 读出当前会话消息。
• 执行旧式 AgentMiddleware 的前后钩子。
• 执行新式 ChatModelAgentMiddleware 的前后钩子（可返回新 ctx，可改写 state）。
• 调用真实模型，再把结果写回 State。

源码对应：

• stateModelWrapper.Generate/Stream：见 wrappers.go#L611-L745

3.2 关键收益：中间件不仅能“看”，还能“改”

这意味着很多能力不需要侵入核心引擎，而能以切面方式落地，例如：

• 动态裁剪工具（只把相关的 5 个工具发给模型看）。
• 注入/改写指令（system prompt 拼接规则）。
• 模型重试（按策略重放 Generate/Stream）。

为什么“之前做不到”？核心差别是：能不能在正确的时机改到“真正生效”的东西

很多人直觉里的“中间件”只是 Before() / After() 两个回调：调用模型前做点事，调用模型后做点事。
这在“只需要打日志/计时”时够用，但在 “要改变模型的输入、要改变工具清单、要改变重试行为、还要对流式输出生效” 时就会失效。

下面用三个非常具体的对比解释“旧做不到/现在能做到”的本质。

1. 动态裁剪工具：以前往往只能改‘提示词’，改不了‘发送给模型的 Tools 列表’

   • 旧做法（做不到的点）：很多系统只能在 Prompt 里写“你现在可用工具有 A/B/C”。但 Function Calling 真正起作用的是 API 请求里的 tools 字段。你改提示词，模型依然看见 100 个工具的 schema，就仍然会“选错/幻觉/超 token”。
   • 现在怎么做（How）：在 ChatModelAgentMiddleware.BeforeModelRewriteState 或 WrapModel 里，基于当前上下文筛选出 5 个工具，并通过模型 option 的方式绑定到本次调用。stateModelWrapper 会在调用模型前构造 ModelContext{Tools: ...} 并把它传给 handler（见 wrappers.go#L628-L637），从而做到“本次调用真正只发 5 个工具给模型看”。
   • 具象例子：你有 100 个工具，其中 80 个是运维危险操作。如果用户只在问“解析 JSON”，裁剪后只发 parse_json、read_file 等 5 个工具，模型不会再误触发 delete_db 之类的工具。

2. 注入/改写指令：以前只能拼字符串，现在能改‘状态机里的消息序列’

   • 旧做法（做不到的点）：只在最外层拼一个 System Prompt 字符串，无法保证它在每次模型调用前都能和历史消息以一致的策略合并；更无法在恢复（Resume）后对历史做局部补丁。
   • 现在怎么做（How）：stateModelWrapper 在每次 Generate/Stream 前把 state.Messages 交给 BeforeModelRewriteState，允许你把某些消息替换、插入、降噪，然后再写回 compose 的 State（见 wrappers.go#L639-L642）。这属于“改状态机的事实”，不是“改一句提示词的愿望”。
   • 动作类比：以前你只能在会议前发一封邮件强调纪律；现在你能直接改会议纪要，把关键事实加粗写进正式记录，所有后续决策都会基于这份纪要。

3. 模型重试：流式场景下的“预检阻塞”机制（解决半截报错痛点）

   • 旧做法（外层 for 循环的灾难）：在普通的流式输出中，一旦 Stream() 调用成功返回，普通的 for 循环重试就失效了（因为它只管“建立连接”成功与否）。如果流读到第 10 个 token 时网络断了，外层重试会开启一个新流，再次发送第 1 到 10 个 token，导致前端 UI 出现严重的“重复叠字”或“事件序号错乱”。
   • 现在怎么做（How）：RetryWrapper 采用了一种极其极端的 Copy & Consume (双胞胎预检) 策略：
     • 调用底层 Stream 后，使用 stream.Copy(2) 复制出两个流。
     • 预检阻塞：拦截器会阻塞地把第一个流从头读到尾，只为了检查中间有没有报错（见 retry_chatmodel.go#L213-L274 的 consumeStreamForError）。
     • 如果预检发现错误且允许重试，直接丢弃第二个流，进入下一次重试；只有预检成功跑到 EOF，才把第二个完好的流返回给上层和前端。
   • 代价（Why Trade-off）：这种设计完美解决了“半截报错导致前端脏数据”的问题，但付出了巨大的代价——牺牲了 TTFT (Time To First Token)。用户侧无法实时看到 token 逐个蹦出，而是会经历一段较长的空白期，然后瞬间拿到全部结果，流式输出在某种意义上变成了“伪流式”。这是为了在不可靠网络下保证内容绝对一致性而做出的工程妥协。

---

4. ChatModelAgent 并不等于 ReAct（它决定何时走图，何时不走图）

4.1 无工具模式：不走 ReAct，直接跑（降级捷径）

过程（How）：工具列表为空时，buildRunFunc 会选择 no-tools 的运行函数，避免图编译开销。

源码对应：

• buildRunFunc 的分支选择：见 chatmodel.go#L884-L905

4.2 有工具模式：才进入 ReAct 图（react.go 只是拓扑生成器）

过程（How）：有工具时才构建 ReAct 的 runFunc；最终由 Run 决定走 Invoke 还是 Stream，并处理 OutputKey 的会话存储。

源码对应：

• Run 的 Invoke/Stream 与 OutputKey：见 chatmodel.go#L820-L855

---

5. 抽象主线三：运行时改写、缓存与冻结（“一次编译，多次运行”）

5.1 once + frozen：为什么要冻结？

过程（How）：第一次运行后，Agent 会被冻结；冻结后不能再改 subAgents 等结构性配置。

源码对应：

• buildRunFunc：见 chatmodel.go#L884-L910
• OnSetSubAgents 的冻结保护：见 chatmodel.go#L514-L517

Why：防止“运行了一半才改图拓扑”的不可恢复状态，保证 checkpoint 的可解释性。

5.2 applyBeforeAgent：为什么还允许每次 Run 动态改写？

痛点与危机：
既然在 NewChatModelAgent 阶段所有的工具和配置都已经初始化并固化成了闭包，那为什么还要在每次调用 Run() 的时候，通过中间件提供一个 BeforeAgent 钩子来允许动态修改呢？

答案是：为了实现“上下文感知”的动态能力。

有些业务场景下，Agent 拥有的能力不是静态的，而是随着用户状态或环境动态变化的：

1. 动态工具发现（Tool Discovery）：一个“企业级助手”Agent 可能对接了内部上千个系统 API。如果把一千个工具的 Schema 在初始化时全塞给模型，Context Window 会当场爆炸。因此，最佳实践是初始化时不带任何工具，而在 BeforeAgent 阶段，根据用户当前输入的问题，利用向量检索找出最相关的 5 个 API，临时把它们挂载上去。
2. 基于权限的工具挂载 (Permission-based Access)：同一个 Agent 模板，管理员调用时动态注入 delete_database 工具，普通用户调用时不注入。
3. 千人千面的配置：不同的用户调用同一个 Agent，可能需要加载不同的系统指令（比如 VIP 用户和普通用户的语气不同）。

它会破坏 Checkpoint (断点续传) 吗？
这是一个极其尖锐且关键的架构拷问！因为 Checkpoint 记录的是“历史状态”，如果在恢复（Resume）时，Agent 的工具列表突然变了，状态机难道不会崩溃吗？

Eino 的精妙解法：意图与物理结构的解耦
框架不仅不会崩溃，反而原生支持了这种动态性。这背后依赖于三个步骤的严密配合，缺一不可：

1. 重新触发拦截器 (BeforeAgent)：
   在源码中（adk/chatmodel.go#L1004），无论是首次 Run 还是中继点 Resume，都会重新走一遍 getRunFunc，这意味着所有的 BeforeAgent 钩子会被重新执行。
   为什么光有这一步不够？ 因为 BeforeAgent 只是在逻辑上（Config/Context 层面）修改了你想用的工具。但底层的 compose.Graph 在编译后是静态冻结的，如果底层图压根没有处理工具的节点，你光改配置是没用的。

2. 底层图的即时重构 (Rebuild Graph)：
   你可能会问：“只是给个 Tool 说明不行吗？为什么要重新编译图？”
   这是因为 Eino 底层的 compose.Graph 在拓扑上对“有无工具”是极其敏感的。

   • 如果初始化时没有工具，编译出的是一张线性图（只有 ChatModel 节点，跑完直接结束）。
   • 如果初始化时有工具，编译出的是一张ReAct 循环图（包含 ChatModel 节点、Branch 分支、ToolsNode 节点）。
     为什么不能事先连接一个空的 Tool Node？
     这是一个非常好的质疑！如果框架在初始化时，不管有没有工具，都强制画一张“带有空 ToolNode 的 ReAct 循环图”，不就不需要 Rebuild 了吗？
     Eino 放弃这种做法，是基于性能、状态管理与语义正确性的三重考量：
   • 执行开销的降维打击：无工具的 buildNoToolsRunFunc 是一条极简的线性链 (Chain) (START -> ChatModel -> END)，没有分支判断，没有沉重的 State 状态机。而 ReAct 图每次模型吐字后，都要跑一遍 Branch 函数去检查有没有 ToolCall，还要维护迭代次数（防止死循环）。如果一个纯聊天的 Agent 被迫跑在 ReAct 图上，是对计算资源的纯粹浪费。
   • 语义防错：大模型偶尔会产生“幻觉（Hallucination）”。如果你给它一张带 ToolNode 的图，哪怕工具列表是空的，模型也有极小概率因为提示词污染而强行生成一个不存在的 ToolCall。如果图里有分支，它就会跳进去报错；如果是线性图，它根本没有跳出去的物理轨道，从根本上阻断了这种幻觉路径。
   • 类比：线性图就像是“直达电梯”，ReAct 图就像是“带有安检和循环分拣的传送带”。如果顾客（开发者）明确表示没有包裹（工具），强迫他们走安检传送带是不合理的。因此，只有当包裹真的出现时，框架才不惜代价去重建那条复杂的传送带。

3. 状态注入新图：
   重构完图结构后，最致命的问题来了：新编译的图是“空白”的，没有记忆。所以最后一步，框架必须把从 Checkpoint 数据库里捞出来的“历史对话消息（Messages）”和“中断位点”，像灵魂注入躯体一样，精准地注入到这张新图里继续跑。

总结：BeforeAgent 决定了改什么（意图），Rebuild Graph 负责让改动在物理上生效（拓扑结构），状态注入 保证了历史记忆的延续。这三者共同配合，将 “历史对话状态（存在 DB 里）” 和 “运行时环境契约（每次 Run/Resume 时动态生成）” 彻底解耦。

---

6. Interrupt/Resume：把图引擎中断翻译成 Agent 级挂起恢复

6.1 中断：抽取 interrupt info + 拉取 checkpoint bytes + 组装复合中断事件

过程（How）：当底层返回 interrupt error，ChatModelAgent 从 bridgeStore 拉到 checkpoint 数据并打包成 CompositeInterrupt 事件发送给外层。

源码对应：

• interrupt 提取与 checkpoint 读取：见 chatmodel.go#L856-L881

6.2 恢复：允许注入新信息（HistoryModifier）

过程（How）：Resume 从 InterruptState 取回 checkpoint bytes；如果用户提供 ChatModelAgentResumeData，可以在恢复前对历史做一次函数式改写。

源码对应：

• Resume 的 HistoryModifier：见 chatmodel.go#L1001-L1052
• resume 执行：见 chatmodel.go#L1054-L1077

动作类比：恢复前的 HistoryModifier 像“把补充材料钉进工单首页”，确保后续推理基于最新事实继续。

---

7. 批判性总结：强在哪里，代价是什么？

优势：

• 模型与工具都被统一进 AgentEvent，天然适配 UI/日志/调度器。
• 模型调用被中间件化，很多能力变成可插拔切面。
• 中断与恢复以 bytes checkpoint 作为桥接，让 Human-in-the-loop 工程化落地。

代价与局限：

• chatmodel.go + wrappers.go 形成厚胶水层：协议转换、状态读写、图适配、兼容旧中间件全部叠加，调试成本高。

更 Unix 的演进方向：

• 收敛两套中间件 API，把旧 AgentMiddleware 逐步退役，只保留接口型中间件。
• 进一步解耦“执行策略”（例如 ReAct 图）与 “Agent 运行时”，让用户显式选择策略，而不是只能靠固化拓扑 + Hack 中间件。