1
创建链：NewChatModel → NewChatModelAgent → NewRunner → Run
2
           (模)            (代)             (跑)       (消息)
3

4
两种迭代：Agent 用 Next() → (event, ok) —— !ok 结束
5
          Stream 用 Recv() → (chunk, err) —— io.EOF 结束
6

7
Agent 管能力：{Name, Instruction, ToolsConfig, Model}
8
Runner 管执行：{Agent, EnableStreaming, CheckPointStore}
9

10
三种 Tool 创建：90% 用 InferTool(函数+struct tag)
11
              需要约束用 NewTool(schema+函数)
12
              有状态用结构体实现接口
13

14
中断恢复三要素：CheckPointStore + CheckPointID + Resume
15

16
核心包（按使用频率）：
17
  github.com/cloudwego/eino/adk        ← Agent, Runner, Message
18
  github.com/cloudwego/eino/schema      ← UserMessage, SystemMessage
19
  github.com/cloudwego/eino/components/tool/utils  ← InferTool, NewTool
20
  github.com/cloudwego/eino-ext/components/model/openai  ← ChatModel

1
Runner.Run() 返回 Iterator = 你拿到一个"对讲机"
2
Agent 在后台干活，每隔一会通过对讲机说句话
3
你在前台: Next() → 收到一条消息 → Next() → 收到下一条 → ...
4
Next() 返回 (event, false) = 对讲机没信号了 = Agent 干完了

1
type AsyncIterator[T any] struct {
2
    // 内部有 channel，连接"生产者"（Agent goroutine）和"消费者"（你的代码）
3
}
4

5
func (iter *AsyncIterator[T]) Next() (item T, ok bool) {
6
    // 阻塞等待下一个事件
7
    // ok=true: 拿到了新事件
8
    // ok=false: 管道关闭，Agent 执行完毕
9
}

1
第1步 创建 ChatModel     →  第2步 创建 Agent     →  第3步 创建 Runner     →  第4步 发送消息并运行
2
（"嘴巴"，负责调用LLM）      （"大脑"，封装业务逻辑）    （"引擎"，管理执行过程）      （用户说的话）

1
package main
2

3
import (
4
    "context"
5
    "fmt"
6
    "log"
7
    "os"
8

9
    "github.com/cloudwego/eino/adk"
10
    "github.com/cloudwego/eino/schema"
11
    "github.com/cloudwego/eino-ext/components/model/openai"
12
)
13

14
func main() {
15
    // 【固定写法】所有 Eino 调用的"通行证"，贯穿整个调用链
16
    ctx := context.Background()
17

18
    // ─── 第1步：创建 ChatModel（"嘴巴"）───
19
    // ChatModel = 与 LLM 通信的组件，屏蔽不同厂商差异
20
    model, err := openai.NewChatModel(ctx, &openai.ChatModelConfig{
21
        APIKey:  os.Getenv("OPENAI_API_KEY"),
22
        Model:   os.Getenv("OPENAI_MODEL"),
23
        BaseURL: os.Getenv("OPENAI_BASE_URL"),
24
    })
25
    if err != nil {
26
        log.Fatal(err)
27
    }
28

29
    // ─── 第2步：创建 Agent（"大脑"）───
30
    agent, err := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
31
        Name:        "hello_agent",
32
        Description: "A friendly greeting assistant",
33
        Instruction: "You are a friendly assistant. Please respond warmly.",
34
        Model:       model,   // ← 把第1步的 model 注入进来
35
    })
36
    if err != nil {
37
        log.Fatal(err)
38
    }
39

40
    // ─── 第3步：创建 Runner（"引擎"）───
41
    runner := adk.NewRunner(ctx, adk.RunnerConfig{
42
        Agent:           agent,
43
        EnableStreaming: true,
44
    })
45

46
    // ─── 第4步：组装消息并运行 ───
47
    input := []adk.Message{
48
        schema.UserMessage("Hello, please introduce yourself."),
49
    }
50

51
    // runner.Run() 返回事件迭代器，逐个消费事件
52
    events := runner.Run(ctx, input)
53
    for {
54
        event, ok := events.Next()
55
        if !ok {
56
            break
57
        }
58
        if event.Err != nil {
59
            log.Printf("错误: %v", event.Err)
60
            break
61
        }
62
        if msg, err := event.Output.MessageOutput.GetMessage(); err == nil {
63
            fmt.Printf("Agent: %s\n", msg.Content)
64
        }
65
    }
66
}

1
NewChatModel → NewChatModelAgent → NewRunner → Run
2
    (模)            (代)             (跑)       (消息)

1
"github.com/cloudwego/eino-ext/components/model/openai"   // OpenAI 兼容模型，更多代码支持不再列出，直接参考官方文档
2
"github.com/cloudwego/eino/adk"                            // Agent, Runner, Message
3
"github.com/cloudwego/eino/schema"                         // UserMessage, SystemMessage 等

1
NewChatModel → NewChatModelAgent → NewRunner → Run
2
event, ok := iter.Next(); if !ok { break }
3
msg, err := event.Output.MessageOutput.GetMessage()

1
import (
2
    "github.com/cloudwego/eino/components/prompt"
3
    "github.com/cloudwego/eino/schema"
4
)
5

6
// 创建模板：用 {变量名} 做占位符
7
func createTemplate() prompt.ChatTemplate {
8
    return prompt.FromMessages(schema.FString,
9
        schema.SystemMessage("你是一个{role}。用{style}的语气回答。"),
10
        schema.MessagesPlaceholder("chat_history", true),
11
        schema.UserMessage("问题: {question}"),
12
    )
13
}
14

15
// 用模板生成实际消息
16
func createMessages() []*schema.Message { // 正如上面所说，这里使用adk.Message也是一样的
17
    template := createTemplate()
18
    messages, err := template.Format(context.Background(), map[string]any{
19
        "role":     "程序员鼓励师",
20
        "style":    "积极、温暖且专业",
21
        "question": "我的代码一直报错，该怎么办？",
22
        "chat_history": []*schema.Message{
23
            schema.UserMessage("你好"),
24
            schema.AssistantMessage("嘿！加油！", nil),
25
        },
26
    })
27
    // ... 处理 err
28
    return messages
29
}

1
result, err := model.Generate(ctx, messages)
2
if err != nil {
3
    log.Fatal(err)
4
}
5
fmt.Println(result.Content)

1
streamReader, err := model.Stream(ctx, messages)
2
if err != nil {
3
    log.Fatal(err)
4
}
5
defer streamReader.Close()  // ⚠️ 用完记得关闭！
6

7
for {
8
    chunk, err := streamReader.Recv()
9
    if err == io.EOF { break }
10
    if err != nil {
11
        log.Fatal(err)
12
    }
13
    fmt.Print(chunk.Content)
14
}

1
// ─── 模式A：Agent Runner 事件迭代 ───
2
// Next() 返回 (event, bool)，!ok 表示结束
3
for {
4
    event, ok := iter.Next()
5
    if !ok { break }
6
}
7

8
// ─── 模式B：ChatModel Stream 流式迭代 ───
9
// Recv() 返回 (chunk, error)，io.EOF 表示结束
10
defer streamReader.Close()
11
for {
12
    chunk, err := streamReader.Recv()
13
    if err == io.EOF { break }
14
}

1
"github.com/cloudwego/eino/components/prompt"   // ChatTemplate, FromMessages

1
一次性：model.Generate(ctx, messages) → (*Message, error)
2
流式：  model.Stream(ctx, messages) → (*StreamReader, error)
3
        defer close → Recv() 循环 → io.EOF 结束
4

5
模板：  prompt.FromMessages(schema.FString, ...messages)
6
        template.Format(ctx, map[string]any{...})

1
import (
2
    "github.com/cloudwego/eino/components/tool"
3
    "github.com/cloudwego/eino/components/tool/utils"
4
)
5

6
// ① 定义输入结构体（用 json tag + jsonschema tag 描述参数）
7
type BookSearchInput struct {
8
    Genre    string `json:"genre" jsonschema_description:"书籍类型"`
9
    MaxPages int    `json:"max_pages" jsonschema_description:"最大页数"`
10
}
11

12
type BookSearchOutput struct {
13
    Books []string `json:"books"`
14
}
15

16
// ② 写业务函数 + utils.InferTool 自动包装
17
func NewBookSearchTool() tool.InvokableTool {
18
    t, _ := utils.InferTool(
19
        "search_book",
20
        "Search books by preferences",
21
        func(ctx context.Context, input *BookSearchInput) (*BookSearchOutput, error) {
22
            return &BookSearchOutput{Books: []string{"《三体》"}}, nil
23
        },
24
    )
25
    return t
26
}

1
func getAddTodoTool() tool.InvokableTool {
2
    info := &schema.ToolInfo{
3
        Name: "add_todo",
4
        Desc: "Add a todo item",
5
        ParamsOneOf: schema.NewParamsOneOfByParams(map[string]*schema.ParameterInfo{
6
            "content": {
7
                Desc:     "The content of the todo item",
8
                Type:     schema.String,
9
                Required: true,
10
            },
11
            "deadline": {
12
                Desc: "The deadline of the todo item, in unix timestamp",
13
                Type: schema.Integer,
14
            },
15
        }),
16
    }
17
    return utils.NewTool(info, AddTodoFunc)
18
}
19

20
type TodoAddParams struct {
21
    Content  string `json:"content"`
22
    Deadline *int64 `json:"deadline,omitempty"`
23
}
24

25
func AddTodoFunc(_ context.Context, params *TodoAddParams) (string, error) {
26
    return `{"msg": "add todo success"}`, nil
27
}

1
type ListTodoTool struct{}
2

3
func (lt *ListTodoTool) Info(_ context.Context) (*schema.ToolInfo, error) {
4
    return &schema.ToolInfo{
5
        Name: "list_todo",
6
        Desc: "List all todo items",
7
        ParamsOneOf: schema.NewParamsOneOfByParams(map[string]*schema.ParameterInfo{
8
            "finished": {
9
                Desc: "filter todo items if finished",
10
                Type: schema.Boolean,
11
            },
12
        }),
13
    }, nil
14
}
15

16
func (lt *ListTodoTool) InvokableRun(_ context.Context, argumentsInJSON string, _ ...tool.Option) (string, error) {
17
    return `{"todos": [...]}`, nil
18
}

1
package main
2

3
import (
4
    "context"
5
    "fmt"
6
    "log"
7
    "os"
8

9
    "github.com/cloudwego/eino/adk"
10
    "github.com/cloudwego/eino/components/tool"
11
    "github.com/cloudwego/eino/compose"
12
    "github.com/cloudwego/eino/schema"
13
    "github.com/cloudwego/eino-ext/components/model/openai"
14
)
15

16
func main() {
17
    ctx := context.Background()
18

19
    // ─── 创建模型 ───
20
    model, err := openai.NewChatModel(ctx, &openai.ChatModelConfig{
21
        APIKey:  os.Getenv("OPENAI_API_KEY"),
22
        Model:   os.Getenv("OPENAI_MODEL"),
23
        BaseURL: os.Getenv("OPENAI_BASE_URL"),
24
    })
25
    if err != nil {
26
        log.Fatal(err)
27
    }
28

29
    // ─── 创建 Agent（配置 Tool）───
30
    agent, err := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
31
        Name:        "BookRecommender",
32
        Description: "An agent that recommends books",
33
        Instruction: "You are a book expert. Use search_book tool to find books.",
34
        Model:       model,
35
        ToolsConfig: adk.ToolsConfig{
36
            ToolsNodeConfig: compose.ToolsNodeConfig{
37
                Tools: []tool.BaseTool{
38
                    NewBookSearchTool(),
39
                },
40
            },
41
        },
42
    })
43
    if err != nil {
44
        log.Fatal(err)
45
    }
46

47
    // ─── 创建 Runner（配置流式）───
48
    runner := adk.NewRunner(ctx, adk.RunnerConfig{
49
        Agent:           agent,
50
        EnableStreaming: true,
51
    })
52

53
    // ─── 运行 ───
54
    iter := runner.Query(ctx, "推荐一本科幻小说")
55
    for {
56
        event, ok := iter.Next()
57
        if !ok { break }
58
        if event.Err != nil {
59
            log.Fatal(event.Err)
60
        }
61
        fmt.Printf("Event: %+v\n", event)
62
    }
63
}

1
type Agent interface {
2
    Name(ctx) string
3
    Description(ctx) string
4
    Run(ctx, input, ...options) *AsyncIterator[*AgentEvent]
5
}

1
"github.com/cloudwego/eino/components/tool"       // BaseTool, InvokableTool, Option
2
"github.com/cloudwego/eino/components/tool/utils" // InferTool, NewTool
3
"github.com/cloudwego/eino/compose"               // ToolsNodeConfig

1
Agent.{Name, Instruction, ToolsConfig, Model}
2
Runner.{Agent, EnableStreaming, CheckPointStore}
3

4
Tool 三种创建：InferTool（90%）/ NewTool / 结构体接口
5
注册方式都一样：ToolsConfig.Tools = []tool.BaseTool{ toolfuction...}
6

7
附注：如果忘记某特定的struct需要填写什么可以直接看源码接口定义

1
[tool call] read_file(file_path: "nonexistent.txt")
2
Error: open nonexistent.txt: no such file or directory
3
// 💥 对话直接中断

1
Error: rate limit exceeded (429)
2
// 💥 对话中断

1
请求 → A.Wrap → B.Wrap → C.Wrap → 实际执行 → C返回 → B返回 → A返回 → 响应
2
         ↑                          ↑
3
    最外层先拦截                 最内层先接触实际执行结果

1
// 定义一个结构体来承载中间件的逻辑。内嵌一个基础中间件（Base Middleware），以复用其默认行为。
2
type safeToolMiddleware struct {
3
    *adk.BaseChatModelAgentMiddleware
4
}
5

6
// 拦截同步工具调用，BaseChatModelAgentMiddleware中定义了方法的签名
7
func (m *safeToolMiddleware) WrapInvokableToolCall(
8
    _ context.Context,
9
    endpoint adk.InvokableToolCallEndpoint,
10
    _ *adk.ToolContext,
11
) (adk.InvokableToolCallEndpoint, error) {
12
    return func(ctx context.Context, args string, opts ...tool.Option) (string, error) {
13
        // 拦截原始 endpoint的结果和err
14
        result, err := endpoint(ctx, args, opts...)
15
        if err != nil {
16
            // ⚠️ 中断错误必须继续传播，不能吞掉
17
            if _, ok := compose.IsInterruptRerunError(err); ok {
18
                return "", err
19
            }
20
            // 普通错误 → 转成字符串，让 LLM 看到
21
            return fmt.Sprintf("[tool error] %v", err), nil
22
        }
23
        // 没有错误就直接返回原始的结果
24
        return result, nil
25
    }, nil
26
}
27

28
// 还可以拦截其他的调用如WrapStreamableToolCall 拦截流式工具调用等等，可以自行查看官方示例

1
ModelRetryConfig: &adk.ModelRetryConfig{
2
    MaxRetries: 5,
3
    ShouldRetry: func(ctx context.Context, retryCtx *adk.TypedRetryContext[M]) *adk.TypedRetryDecision[M] {
4
        // 获取错误信息
5
        err := retryCtx.Error
6
        // 判断是否需要重试
7
        if err != nil && (strings.Contains(err.Error(), "429") || strings.Contains(err.Error(), "Too Many Requests")) {
8
            // 返回重试决策
9
            return &adk.TypedRetryDecision[M]{
10
                Retry: true,
11
                // 在这里你还可以修改重试时的输入或选项，等等
12
            }
13
        }
14
        // 不需要重试，返回 nil 或 Retry: false
15
        return nil
16
    },
17
},

1
toolSearchMiddleware, _ := toolsearch.New(ctx, &toolsearch.Config{
2
    DynamicTools: allDynamicTools,
3
})
4

5
agent, _ := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
6
    Name:  "tool_search_agent",
7
    Model: chatModel,
8
    Handlers: []adk.ChatModelAgentMiddleware{
9
        toolSearchMiddleware,  // ← 不是 ToolsConfig！
10
    },
11
})

1
skillBackend, err := skill.NewBackendFromFilesystem(ctx, &skill.BackendFromFilesystemConfig{
2
    Backend: be,
3
    BaseDir: skillsDir, // 指定扫描的根目录
4
})

1
sm, err := skill.NewMiddleware(ctx, &skill.Config{
2
    Backend: skillBackend,
3
})

1
// 文件系统中间件 → Skill 中间件（有序！）
2
agent, _ := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
3
    Name:  "LogAnalysisAgent",
4
    Model: cm,
5
    Handlers: []adk.ChatModelAgentMiddleware{
6
        fsm,  // 文件读写能力（洋葱模型外层，最先wrap，最后返回）
7
        sm,   // Skill 加载能力（洋葱模型内层，之后wrap，先返回）
8
    },
9
})

1
用户请求 → [安检A:查证件] → [安检B:过X光] → [安检C:金属探测] → 登机
2
用户收到 ← [安检A:盖章]   ← [安检B:贴标签] ← [安检C:称重]   ← 行李出来

1
SafeToolMiddleware = 错误转字符串（除了 InterruptRerunError）
2
ModelRetryConfig   = 限流自动重试（内置配置项）
3
ToolSearch         = 工具池动态搜索（替代 ToolsConfig）
4
Skill              = 文件系统加载技能
5

6
通用模式：嵌入 BaseChatModelAgentMiddleware → 覆写一个钩子 → 放入 Handlers

1
用户输入 "推荐一本书"
2
       │
3
       ▼
4
    runner := adk.NewRunner(ctx, adk.RunnerConfig{
5
    Agent:           a,
6
    CheckPointStore: store.NewInMemoryStore(), // runner设置CheckPointStore以储存后续的CheckPointID
7
  })
8
       │
9
       ▼
10
  runner.Query(ctx, "推荐一本书", WithCheckPointID("1")) 传入CheckPointID，后续恢复通过这个
11
       │
12
       ▼
13
  Agent 分析：信息不够 → Tool 返回 Interrupt("请问你喜欢什么类型的书？") 注：示例代码中NewInterruptAndRerunErr被标记启用
14
       │
15
       ▼
16
  事件流中收到 Interrupted 事件 → 暂停，等待用户输入
17
       │
18
       ▼
19
  runner.Resume(ctx, "1", WithToolOptions(WithNewInput("科幻"))) 通过CheckPointID进行恢复
20
       │
21
       ▼
22
  Agent 继续执行 → 用 "科幻" 重新调用 Tool → 返回结果

1
用户按 Ctrl-C
2
       │
3
       ▼
4
  cancelFn(CancelAfterChatModel, WithRecursive, 30s超时)
5
       │
6
       ├─→ CancelAfterChatModel: 等当前 ChatModel 调用完成再停
7
       ├─→ WithRecursive: 递归传播到子 Agent
8
       └─→ 超时兜底: 30s 内没到安全点 → 强制 CancelImmediate
9
       │
10
       ▼
11
  CheckPointStore 自动保存状态 → 新 Runner.Resume 恢复

1
// 创建取消选项与外部触发函数
2
cancelOpt, cancelFn := adk.WithCancel()
3

4
// 启动Agent运行，绑定断点ID
5
iter := runner.Run(ctx, input, cancelOpt, adk.WithCheckPointID(checkpointID))
6

7
// 注册系统信号监听：SIGINT(Ctrl-C)、SIGTERM
8
sigCh := make(chan os.Signal, 1)
9
signal.Notify(sigCh, syscall.SIGINT, syscall.SIGTERM)
10

11
go func() {
12
  sig := <-sigCh
13
  fmt.Printf("\n收到操作系统信号: %v，发起Agent优雅取消\n", sig)
14

15
  // 发起优雅取消：等待ChatModel安全点、递归传播子Agent、30s超时兜底
16
  handle, contributed := cancelFn(
17
    adk.WithAgentCancelMode(adk.CancelAfterChatModel),
18
    adk.WithRecursive(),
19
    adk.WithAgentCancelTimeout(30*time.Second),
20
  )
21
  fmt.Printf("取消请求是否成功提交: %v\n", contributed)
22

23
  // 阻塞等待取消流程完成（断点持久化完成后返回）
24
  if waitErr := handle.Wait(); waitErr != nil {
25
    fmt.Printf("优雅取消异常: %v\n", waitErr)
26
  } else {
27
    fmt.Println("优雅取消完成，断点已保存")
28
  }
29
}()

1
// 使用同一个CheckPointStore，新建Runner恢复
2
resumeRunner := adk.NewRunner(ctx, adk.RunnerConfig{
3
  Agent:           agent,
4
  EnableStreaming: true,
5
  CheckPointStore: cpStore,
6
})
7
resumeIter, err := resumeRunner.Resume(ctx, checkpointID)
8
if err != nil {
9
  log.Fatalf("断点恢复失败: %v", err)
10
}
11
drainEvents(resumeIter)

1
// ① 启动
2
iter := runner.Query(ctx, query, adk.WithCheckPointID("1"))
3

4
// ② 检测中断，提取 interruptID
5
interruptCtx := lastEvent.Action.Interrupted.InterruptContexts[0]
6
interruptID := interruptCtx.ID
7

8
// ③ 用户决策后，通过 ResumeWithParams 传回
9
iter, _ = runner.ResumeWithParams(ctx, "1", &adk.ResumeParams{
10
    Targets: map[string]any{
11
        interruptID: modifiedInfo,
12
    },
13
})

1
func FollowUp(ctx context.Context, input *FollowUpToolInput) (string, error) {
2
    // 首次进入（触发中断）
3
  wasInterrupted, _, storedState := tool.GetInterruptState[*FollowUpState](ctx)
4
  if !wasInterrupted {
5
        // 准备要展示给用户的信息（比如问题列表）
6
        info := &FollowUpInfo{Questions: input.Questions}
7
        // 准备要保存的状态（为了恢复时知道我们在干嘛）
8
        state := &FollowUpState{Questions: input.Questions}
9

10
        // 触发中断！把 info 发给前端展示，把 state 存起来，然后函数立刻返回
11
        return "", tool.StatefulInterrupt(ctx, info, state)
12
    }
13

14
    // 第二次进入
15
  isResumeTarget, hasData, resumeData := tool.GetResumeContext[*FollowUpInfo](ctx)
16
  if !isResumeTarget {
17
      // 如果系统唤醒了这个函数，但发现它不是当前该恢复的目标
18
        // 那就把之前保存的状态再拿出来，继续中断等待
19
    info := &FollowUpInfo{Questions: storedState.Questions}
20
    return "", tool.StatefulInterrupt(ctx, info, storedState)
21
  }
22
    // 被唤醒，但还没拿到答案（防御性重入）
23
  if !hasData || resumeData.UserAnswer == "" {
24
    return "", fmt.Errorf("tool resumed without a user answer")
25
  }
26

27
    // 成功恢复，拿到答案（正常退出）
28
  return resumeData.UserAnswer, nil
29
}

1
中断恢复三要素：CheckPointStore（存状态）+ CheckPointID（标识）+ Resume（恢复）
2

3
方式一：compose.Interrupt → runner.Resume(id, WithToolOptions)
4
方式二：Ctrl-C → cancelFn → 新 runner.Resume(id)
5
方式三：compose.Interrupt → runner.ResumeWithParams(id, {Targets: {interruptID: data}})

1
traceCloseFn, startSpanFn := trace.AppendCozeLoopCallbackIfConfigured(ctx)
2
defer traceCloseFn(ctx)
3

4
ctx, endSpanFn := startSpanFn(ctx, "MyTask", "user query")
5
// ... runner.Query(ctx, query) ...
6
endSpanFn(ctx, lastMessage)

1
// LoopAgent
2
a, _ := adk.NewLoopAgent(ctx, &adk.LoopAgentConfig{
3
    SubAgents:     []adk.Agent{mainAgent, critiqueAgent},
4
    MaxIterations: 5,
5
})
6

7
// ParallelAgent
8
a, _ := adk.NewParallelAgent(ctx, &adk.ParallelAgentConfig{
9
    SubAgents: []adk.Agent{stockAgent, newsAgent, socialAgent},
10
})
11

12
// SequentialAgent
13
a, _ := adk.NewSequentialAgent(ctx, &adk.SequentialAgentConfig{
14
    SubAgents: []adk.Agent{planAgent, writerAgent},
15
})

1
sv, _ := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
2
    Name: "supervisor",
3
    Instruction: "You are a supervisor managing a research_agent and math_agent.",
4
    Model: m,
5
})
6

7
supervisorAgent, _ := supervisor.New(ctx, &supervisor.Config{
8
    Supervisor: sv,
9
    SubAgents:  []adk.Agent{searchAgent, mathAgent},
10
})

1
entryAgent, _ := planexecute.New(ctx, &planexecute.Config{
2
    Planner:    planAgent,
3
    Executor:   executeAgent,
4
    Replanner:  replanAgent,
5
    MaxIterations: 20,
6
})

1
ADK (Agent+Runner)  >  Chain  >  Graph  >  Workflow
2
  高层，开箱即用                    底层，精细控制每个节点和数据流

1
g := compose.NewGraph[map[string]any, *schema.Message]()
2
_ = g.AddChatTemplateNode("prompt", pt)
3
_ = g.AddChatModelNode("model", chatModel)
4
_ = g.AddEdge(compose.START, "prompt")
5
_ = g.AddEdge("prompt", "model")
6
_ = g.AddEdge("model", compose.END)
7
runner, _ := g.Compile(ctx)
8
result, _ := runner.Invoke(ctx, input)

1
chain := compose.NewChain[map[string]any, string]()
2
chain.
3
    AppendLambda(preprocess).
4
    AppendBranch(compose.NewChainBranch(cond).AddLambda("b1", fn1).AddLambda("b2", fn2)).
5
    AppendLambda(postprocess)
6
runner, _ := chain.Compile(ctx)

1
Workflow Agent: LoopAgent / ParallelAgent / SequentialAgent
2
Supervisor:      supervisor.New({Supervisor, SubAgents})
3
Compose 编排:   Graph(AddEdge) / Chain(Append) / Workflow(MapFields)

1
┌─ 创建链 ─────────────────────────────────────────────┐
2
│ NewChatModel → NewChatModelAgent → NewRunner → Run   │
3
│   (模)            (代)             (跑)       (消息)  │
4
├─ 两种迭代 ───────────────────────────────────────────┤
5
│ Agent: for { event, ok := iter.Next(); if !ok {break}}│
6
│ Stream: for { chunk, err := sr.Recv(); io.EOF → break}│
7
├─ 职责分离 ───────────────────────────────────────────┤
8
│ Agent 管能力:{Name, Instruction, ToolsConfig, Model} │
9
│ Runner管执行:{Agent, EnableStreaming, CheckPointStore}│
10
├─ Tool 创建 ──────────────────────────────────────────┤
11
│ InferTool（90%）/ NewTool / 结构体接口               │
12
├─ Middleware  ────────────────────────────────────────┤
13
│ SafeTool / ModelRetry / ToolSearch / Skill           │
14
├─ 中断恢复 ──────────────────────────────────────────┤
15
│ CheckPointStore + CheckPointID + Resume              │
16
│ 三种方式：Tool中断 / Ctrl-C取消 / Human-in-the-Loop  │
17
├─ 编排层次 ──────────────────────────────────────────┤
18
│ ADK(Agent+Runner) > Chain > Graph > Workflow        │
19
├─ Agentic 路径（[Agentic 进阶](./agentic)）──────────────────────────┤
20
│ 所有类型加 Typed[*AgenticMessage] 即可               │
21
└──────────────────────────────────────────────────────┘

1
// 模型
2
"github.com/cloudwego/eino-ext/components/model/openai"    // OpenAI 兼容 ChatModel
3

4
// ADK 核心
5
"github.com/cloudwego/eino/adk"                             // Agent, Runner, Message, Middleware
6
"github.com/cloudwego/eino/schema"                          // UserMessage, SystemMessage, ToolInfo
7

8
// Tool
9
"github.com/cloudwego/eino/components/tool"                 // BaseTool, InvokableTool
10
"github.com/cloudwego/eino/components/tool/utils"           // InferTool, NewTool
11

12
// 编排
13
"github.com/cloudwego/eino/compose"                         // Graph, Chain, Workflow, ToolsNodeConfig
14

15
// Middleware 扩展
16
"github.com/cloudwego/eino/adk/middlewares/dynamictool/toolsearch"  // ToolSearch
17
"github.com/cloudwego/eino/adk/middlewares/skill"                   // Skill
18
"github.com/cloudwego/eino/adk/middlewares/filesystem"              // 文件系统
19

20
// Prompt
21
"github.com/cloudwego/eino/components/prompt"               // ChatTemplate, FromMessages

1
// ❌ 坏：忘记 Close，HTTP 连接永不释放，goroutine 泄漏
2
sr, _ := model.Stream(ctx, messages)
3
for { chunk, err := sr.Recv(); ... }
4

5
// ✅ 好：defer Close 保证无论怎么退出都会关闭
6
sr, _ := model.Stream(ctx, messages)
7
defer sr.Close()
8
for { chunk, err := sr.Recv(); ... }

1
// ❌ 坏：忘记 Close，消费端 Next() 永远等不到 false
2
func (m *MyAgent) Run(...) *AsyncIterator[*AgentEvent] {
3
    iter, gen := adk.NewAsyncIteratorPair[*AgentEvent]()
4
    go func() {
5
        gen.Send(&AgentEvent{...})
6
        // 忘记 gen.Close()！！！
7
    }()
8
    return iter
9
}
10

11
// ✅ 好：defer + recover 确保 Close 一定被调用
12
func (m *MyAgent) Run(...) *AsyncIterator[*AgentEvent] {
13
    iter, gen := adk.NewAsyncIteratorPair[*AgentEvent]()
14
    go func() {
15
        defer func() {
16
            if e := recover() { gen.Send(&AgentEvent{Err: ...}) }
17
            gen.Close()  // ← 必须调用！
18
        }()
19
        gen.Send(&AgentEvent{...})
20
    }()
21
    return iter
22
}

1
// ❌ 坏：所有 error 都转成字符串，中断错误也被吞了
2
func wrap(endpoint) endpoint {
3
    return func(ctx, args) (string, error) {
4
        result, err := endpoint(ctx, args)
5
        if err != nil { return fmt.Sprintf("[error] %v", err), nil }
6
        return result, nil
7
    }
8
}
9

10
// ✅ 好：区分中断错误和普通错误
11
func wrap(endpoint) endpoint {
12
    return func(ctx, args) (string, error) {
13
        result, err := endpoint(ctx, args)
14
        if err != nil {
15
            if _, ok := compose.IsInterruptRerunError(err); ok {
16
                return "", err  // ← 中断错误必须传播！
17
            }
18
            return fmt.Sprintf("[tool error] %v", err), nil
19
        }
20
        return result, nil
21
    }
22
}

1
// ❌ 坏：Query 和 Resume 用了不同的 ID——Runner 找不到之前的保存点
2
iter := runner.Query(ctx, "帮我推荐", adk.WithCheckPointID("session-1"))
3
// ... 中断 ...
4
iter, _ = runner.Resume(ctx, "session-2")  // ← ID 不一致！应该是 "session-1"
5

6
// ✅ 好：同一个 ID
7
iter := runner.Query(ctx, "帮我推荐", adk.WithCheckPointID("session-1"))
8
// ... 中断 ...
9
iter, _ = runner.Resume(ctx, "session-1")  // ← 一致！

1
// ❌ 坏：新 Runner 没用同一个 CheckPointStore——状态丢失
2
runner1 := adk.NewRunner(ctx, adk.RunnerConfig{Agent: agent})  // 默认空 Store
3
iter := runner1.Query(ctx, "query", adk.WithCheckPointID("1"))
4
// ... Ctrl-C 取消 ...
5
runner2 := adk.NewRunner(ctx, adk.RunnerConfig{Agent: agent})  // 另一个空 Store
6
iter, _ = runner2.Resume(ctx, "1")  // ← 找不到 checkpoint！
7

8
// ✅ 好：共享同一个 CheckPointStore
9
store := store.NewInMemoryStore()
10
runner1 := adk.NewRunner(ctx, adk.RunnerConfig{Agent: agent, CheckPointStore: store})
11
runner1.Query(...)
12
// ...
13
runner2 := adk.NewRunner(ctx, adk.RunnerConfig{Agent: agent, CheckPointStore: store})
14
runner2.Resume(ctx, "1")  // ← 找得到！

1
// ❌ 坏：等不到 web_search 的 function_tool_result
2
for _, block := range msg.ContentBlocks {
3
    if block.Type == schema.ContentBlockTypeFunctionToolResult {
4
        // web_search 永远不会产生这个！
5
    }
6
}
7

8
// ✅ 好：理解 server_tool_call 在厂商侧执行，没有对应的 function_tool_result
9
for _, block := range msg.ContentBlocks {
10
    if block.Type == schema.ContentBlockTypeServerToolCall {
11
        // 模型已经消费了搜索结果——你只会看到后续的 reasoning/text block
12
        fmt.Println("服务端搜索完成:", block.ServerToolCall.Name)
13
    }
14
}