vault backup: 2026-04-29 18:36:58

2026-04-29 18:36:58 +08:00
parent bce0924def
commit 7bb4b3b498
96 changed files with 29367 additions and 0 deletions
@@ -0,0 +1,309 @@
+---
+Description: ""
+date: "2026-03-12"
+lastmod: ""
+tags: []
+title: 第二章：ChatModelAgent、Runner、AgentEvent（Console 多轮）
+weight: 2
+---
+
+本章目标：引入 ADK 的执行抽象（Agent + Runner），并用一个 Console 程序实现多轮对话。
+
+## 代码位置
+
+- 入口代码：[cmd/ch02/main.go](https://github.com/cloudwego/eino-examples/blob/main/quickstart/chatwitheino/cmd/ch02/main.go)
+
+## 前置条件
+
+与第一章一致：需要配置一个可用的 ChatModel（OpenAI 或 Ark）。
+
+## 运行
+
+在 `examples/quickstart/chatwitheino` 目录下执行：
+
+```bash
+go run ./cmd/ch02
+```
+
+看到提示后输入问题（空行退出）：
+
+```
+you> 你好，解释一下 Eino 里的 Agent 是什么？
+...
+you> 再用一句话总结一下
+...
+```
+
+## 关键概念
+
+### 从 Component 到 Agent
+
+第一章我们学习了 **Component**（组件），它是 Eino 中可替换、可组合的能力单元：
+
+- `ChatModel`：调用大语言模型
+- `Tool`：执行特定任务
+- `Retriever`：检索信息
+- `Loader`：加载数据
+
+**Component 和 Agent 的关系：**
+
+- **Component 不构成完整的 AI 应用**：它只是能力单元，需要被组织、编排、执行
+- **Agent 是完整的 AI 应用**：它封装了完整的业务逻辑，可以直接运行
+- **Agent 内部使用 Component**：最核心的是 `ChatModel`（对话能力）和 `Tool`（执行能力）
+
+**为什么需要 Agent？**
+
+如果只有 Component，你需要自己：
+
+- 管理对话历史
+- 编排调用流程（何时调用模型、何时调用工具）
+- 处理流式输出
+- 实现中断恢复
+- ...
+
+**Agent 提供了什么？**
+
+- **完整的运行时框架**：通过 `Runner` 统一管理执行过程
+- **标准的事件流输出**：`Run() -> AsyncIterator[*AgentEvent]`，支持流式、中断、恢复
+- **可扩展能力**：可以添加 tools、middleware、interrupt 等
+- **开箱即用**：创建 Agent 后直接运行，无需关心内部细节
+
+**本章示例：**
+
+`ChatModelAgent` 是最简单的 Agent，它内部只使用了 `ChatModel`，但已经具备了 Agent 的完整能力框架。后续章节会展示如何添加 `Tool` 等更多能力。
+
+### Agent 接口
+
+`Agent` 是 ADK 中的核心接口，定义了智能体的基本行为：
+
+```go
+type Agent interface {
+    Name(ctx context.Context) string
+    Description(ctx context.Context) string
+    
+    // Run 执行 Agent，返回事件流
+    Run(ctx context.Context, input *AgentInput, options ...AgentRunOption) *AsyncIterator[*AgentEvent]
+}
+```
+
+**接口职责：**
+
+- `Name()` / `Description()`：标识 Agent 的名称和描述
+- `Run()`：执行 Agent 的核心方法，接收输入消息，返回事件流
+
+**设计理念：**
+
+- **统一抽象**：所有 Agent（ChatModelAgent、WorkflowAgent、SupervisorAgent 等）都实现这个接口
+- **事件驱动**：通过事件流（`AsyncIterator[*AgentEvent]`）输出执行过程，支持流式响应
+- **可扩展性**：后续加入 tools、middleware、interrupt 等能力时，接口保持不变
+
+### ChatModelAgent
+
+`ChatModelAgent` 是 Agent 接口的一个实现，基于 ChatModel 构建：
+
+```go
+agent, err := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
+    Name:        "Ch02ChatModelAgent",
+    Description: "A minimal ChatModelAgent with in-memory multi-turn history.",
+    Instruction: instruction,
+    Model:       cm,
+})
+```
+
+**ChatModel vs ChatModelAgent：本质区别**
+
+<table>
+<tr><td>维度</td><td>ChatModel</td><td>ChatModelAgent</td></tr>
+<tr><td><strong>定位</strong></td><td>Component（组件）</td><td>Agent（智能体）</td></tr>
+<tr><td><strong>接口</strong></td><td><pre>Generate() / Stream()</pre></td><td><pre>Run() -> AsyncIterator[*AgentEvent]</pre></td></tr>
+<tr><td><strong>输出</strong></td><td>直接返回消息内容</td><td>返回事件流（包含消息、控制动作等）</td></tr>
+<tr><td><strong>能力</strong></td><td>单纯的模型调用</td><td>可扩展 tools、middleware、interrupt 等</td></tr>
+<tr><td><strong>适用场景</strong></td><td>简单的对话场景</td><td>复杂的智能体应用</td></tr>
+</table>
+
+**为什么需要 ChatModelAgent？**
+
+1. **统一抽象**：ChatModel 只是 Component 的一种，而 Agent 是更高层的抽象，可以组合多种 Component
+2. **事件驱动**：Agent 输出事件流，支持流式响应、中断恢复、状态转移等复杂场景
+3. **可扩展性**：ChatModelAgent 可以添加 tools、middleware、interrupt 等能力，而 ChatModel 只能调用模型
+4. **编排友好**：Agent 可以被 Runner 统一管理，支持 checkpoint、恢复等运行时能力
+
+**简单来说：**
+
+- **ChatModel** = "负责与大语言模型通信的组件，屏蔽不同模型提供商的差异（OpenAI、Ark、Claude 等）"
+- **ChatModelAgent** = "基于模型构建的智能体，可以调用模型，但还能做更多事"
+
+**类比理解：**
+
+- **ChatModel** 就像"数据库驱动"：负责与数据库通信，屏蔽 MySQL/PostgreSQL 的差异
+- **ChatModelAgent** 就像"业务逻辑层"：基于数据库驱动构建，但还包含业务规则、事务管理等
+
+**特点：**
+
+- 封装了 ChatModel 的调用逻辑
+- 提供统一的 `Run() -> AgentEvent` 输出形态
+- 后续可以添加 tools、middleware 等能力
+
+### Runner
+
+`Runner` 是执行 Agent 的入口点，负责管理 Agent 的生命周期：
+
+```go
+type Runner struct {
+    a Agent  // 要执行的 Agent
+    enableStreaming bool
+    store CheckPointStore  // 用于中断恢复的状态存储
+}
+```
+
+**为什么需要 Runner？**
+
+虽然 Agent 提供了 `Run()` 方法，但直接调用会缺少很多运行时能力：
+
+1. **生命周期管理**：Runner 管理 Agent 的启动、恢复、中断等状态
+2. **Checkpoint 支持**：配合 `CheckPointStore` 实现中断恢复（后续章节涉及）
+3. **统一入口**：提供 `Run()` 和 `Query()` 等便捷方法
+4. **事件流封装**：将 Agent 的事件流转换为可消费的 `AsyncIterator[*AgentEvent]`
+
+**使用方式：**
+
+```go
+runner := adk.NewRunner(ctx, adk.RunnerConfig{
+    Agent:           agent,
+    EnableStreaming: true,
+})
+
+// 方式 1：传入消息列表
+events := runner.Run(ctx, history)
+
+// 方式 2：便捷方法，传入单个查询字符串
+events := runner.Query(ctx, "你好")
+```
+
+### AgentEvent
+
+`AgentEvent` 是 Runner 返回的事件单元：
+
+```go
+type AgentEvent struct {
+    AgentName string
+    RunPath   []RunStep
+
+    Output *AgentOutput  // 输出内容
+    Action *AgentAction  // 控制动作
+    Err    error         // 执行错误
+}
+```
+
+**主要字段：**
+
+- `event.Err`：执行错误
+- `event.Output.MessageOutput`：message 或 message stream（流式）
+- `event.Action`：中断/转移/退出等控制动作（后续章节用到）
+
+### AsyncIterator：事件流的消费方式
+
+`Runner.Run()` 返回的是 `*AsyncIterator[*AgentEvent]`，这是一个非阻塞的流式迭代器。
+
+**为什么用 AsyncIterator 而不是直接返回结果？**
+
+因为 Agent 的执行是**流式**的：模型逐 token 生成回复，Tool 调用穿插其中。如果等全部完成再返回，用户需要等待更长时间。`AsyncIterator` 让你可以实时消费每一个事件。
+
+**消费方式：**
+
+```go
+// events 是 *AsyncIterator[*AgentEvent]，由 runner.Run() 返回
+events := runner.Run(ctx, history)
+
+for {
+    event, ok := events.Next()  // 获取下一个事件，阻塞直到有事件或结束
+    if !ok {
+        break  // 迭代器关闭，全部事件已消费
+    }
+    if event.Err != nil {
+        // 处理错误
+    }
+    if event.Output != nil && event.Output.MessageOutput != nil {
+        // 处理消息输出（可能是流式）
+    }
+}
+```
+
+**注意：**每次 `runner.Run()` 创建新的迭代器，消费一次后不可重复使用。
+
+## 多轮对话的实现
+
+本章实现的是简单的多轮对话：用户输入 → 模型回复 → 用户继续输入 → ...
+
+**实现方式：**
+
+没有 tools 时，`ChatModelAgent` 在一次 `Run()` 里只会完成一轮模型调用。多轮对话是通过调用侧维护 history 实现的：
+
+1. 用 `history []*schema.Message` 保存累计对话
+2. 每次用户输入：把 `UserMessage` 追加到 history
+3. 调用 `runner.Run(ctx, history)` 得到事件流，消费得到 assistant 文本
+4. 把本轮 assistant 文本追加回 history，进入下一轮
+
+**关键代码片段（**注意：这是简化后的代码片段，不能直接运行，完整代码请参考** [cmd/ch02/main.go](https://github.com/cloudwego/eino-examples/blob/main/quickstart/chatwitheino/cmd/ch02/main.go)）：
+
+```go
+history := make([]*schema.Message, 0, 16)
+
+for {
+    // 1. 读取用户输入
+    line := readUserInput()
+    if line == "" {
+        break
+    }
+    
+    // 2. 追加用户消息到 history
+    history = append(history, schema.UserMessage(line))
+    
+    // 3. 调用 Runner 执行 Agent
+    events := runner.Run(ctx, history)
+    
+    // 4. 消费事件流，收集 assistant 回复
+    content := collectAssistantFromEvents(events)
+    
+    // 5. 追加 assistant 消息到 history
+    history = append(history, schema.AssistantMessage(content, nil))
+}
+```
+
+**流程图：**
+
+```
+┌─────────────────────────────────────────┐
+│  初始化 history = []                     │
+└─────────────────────────────────────────┘
+                   ↓
+        ┌──────────────────────┐
+        │  用户输入 UserMessage  │
+        └──────────────────────┘
+                   ↓
+        ┌──────────────────────┐
+        │  追加到 history       │
+        └──────────────────────┘
+                   ↓
+        ┌──────────────────────┐
+        │  runner.Run(history) │
+        └──────────────────────┘
+                   ↓
+        ┌──────────────────────┐
+        │  消费事件流           │
+        └──────────────────────┘
+                   ↓
+        ┌──────────────────────┐
+        │  追加 AssistantMessage│
+        └──────────────────────┘
+                   ↓
+              (循环继续)
+```
+
+## 本章小结
+
+- **Agent 接口**：定义智能体的基本行为，核心是 `Run() -> AsyncIterator[*AgentEvent]`
+- **ChatModelAgent**：基于 ChatModel 实现的 Agent，提供统一的执行抽象
+- **Runner**：Agent 的执行入口，管理生命周期、checkpoint、事件流等运行时能力
+- **AgentEvent**：事件驱动的输出单元，支持流式响应和控制动作
+- **多轮对话**：通过调用侧维护 history 实现，每次 `Run()` 完成一轮对话