Eino ADK 深度解析：ChatModelAgent 核心机制与实战指南

1. 调模型，让模型先做判断
2. 如果模型直接给答案，那就结束
3. 如果模型发起 Tool Call，就执行工具
4. 把工具结果回灌给模型
5. 再让模型决定下一步
6. 直到模型不再需要工具，或者 Agent 被强制结束

这套循环里，用以下四个词能直接对应上：

• Reason：模型思考
• Action：模型决定调用什么
• Act：系统真的去执行动作
• Observation：把动作结果喂回去

所以 ChatModelAgent 的关键，不在于'它能调工具'，而在于它允许模型把一次复杂任务拆成多轮判断，而不是一口气把答案硬生成出来。这也是它和我们直接手写一段 ChatModel.Generate(...) 的根本区别。

没有 Tool 时会怎样

可以这么说：如果没有配置工具，ChatModelAgent 会退化为一次普通的 ChatModel 调用。这意味着不是所有 ChatModelAgent 都一定会循环，只有当你给了工具、协作能力，或者模型真的产生 Tool Call，它才会进入完整的 ReAct 运行形态。

为什么还需要 MaxIterations

ReAct 的好处是灵活，风险是兜不住时会一直绕。所以 MaxIterations 本质上是一个保险丝。默认值是 20。超过这个次数还没结束，Agent 会直接报错退出。

这在真实业务里非常有必要。否则你很容易遇到两种问题：

• 模型在几个工具之间来回试探，始终拖沓着
• Prompt 写得含糊，模型不知道该答还是该继续调工具

很多线上'为什么 Agent 一直在调用工具'的问题，本质上都不是框架 bug，而是没有把循环上限和结束策略设计清楚。

4. 哪几组配置真正决定了行为

Name / Description

这两个字段经常被初学者轻视。但实际上它们比你想象的重要。

• Name 是 Agent 的身份标识
• Description 决定别的 Agent 会不会把任务转给它

尤其在 Transfer 场景里，Description 不是装饰品，而是模型判断'谁更适合接手这件事'的依据。

Instruction / Model

这两个字段是最直观的：

• Instruction：Agent 的系统约束
• Model：底层使用哪个 ChatModel

但有一点别搞混：Instruction 决定行为风格，Model 决定能力底座。

ToolsConfig

这组配置是 ChatModelAgent 和普通模型调用真正拉开差距的地方。其中有两个很关键的扩展字段起到了作用：

• ReturnDirectly
• EmitInternalEvents

ReturnDirectly

这个字段的意思是：某些工具一旦被调用成功，就不要再把结果送回模型二次润色了，直接把结果带着返回。

这个能力特别适合两类场景：

• 工具结果本身就是最终答案
• 工具结果本身就是'交接单''审批单''跳转结果'，再回模型反而会把结果弄脏

比如后面 Demo 里的 handoff_to_human，就很适合 ReturnDirectly。

EmitInternalEvents

这个配置只在 AgentAsTool 场景里有意义。默认情况下，当你把一个 Agent 包成 Tool 后，外层只会拿到最终的 ToolResult，看不到内层 Agent 的事件流。

而 EmitInternalEvents=true 时，内层 Agent 产生的事件会继续往外透出，调用方就能实时看到里面到底在干什么。这个能力特别适合你把一个复杂 Agent 当 Tool 用，但又希望前端或调用方还能看到它的实时输出。

OutputKey

这个字段很实用：把 Agent 最后一条输出消息，以某个 key 写进 SessionValues。如果你的后续 Agent、Workflow、或者外层业务逻辑还要继续消费这次结果，它比你手动到处传字符串干净得多。

Exit

你可以把他当作一个特殊 Tool。模型调用这个 Tool 并成功执行后，ChatModelAgent 会直接退出，效果和 ReturnDirectly 很像，但语义更明确：

• ReturnDirectly 更像'某个工具调用后直接收口'
• Exit 更像'模型自己宣布：到这里结束，把这个最终结果拿出去'

ModelRetryConfig

这是一个典型的工程字段。它解决的不是'让回答更聪明'，而是'模型调用失败时，系统要不要重试，以及怎么重试'。

如果流式响应过程中发生错误，但策略允许重试，调用方读 stream 时会收到 WillRetryError。

所以在真实系统里做流式输出时，不能只管 happy path。否则一旦流中途断掉，你都不知道是彻底失败了，还是下一轮马上会补回来。

5. Tool、Transfer、AgentAsTool 到底怎么选

这一段是最值得展开讲的地方。很多人第一次看这三种能力时，会觉得它们都像'把事情交给别人做'。但它们不是一回事。

普通 Tool

适合那种边界特别清晰、输入输出很稳定的能力，比如：

• 查错误码
• 查 runbook
• 算时间
• 调外部 HTTP 接口

它更像函数调用。

Transfer

Transfer 的意思不是'调用另一个能力'，而是当前 Agent 判断，另一个 Agent 更适合接手这件事，于是把任务控制权转过去。

官方页对应的实现机制是：

• 给 ChatModelAgent 配置子 Agent
• 框架自动生成一个 Transfer Tool
• 模型根据各个 Agent 的 Description 决定要不要跳转
• Runner 收到 Transfer Event 后，切到目标 Agent 继续执行

最小示意像这样：

// 创建一个上层 Agent，作为请求分发器使用。
// 它本身由聊天模型驱动，职责是根据用户问题决定该交给谁处理。
supervisor, _ := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
    Name:    "dispatcher",
    Description: "负责分发用户请求",
    Model:   cm,
})

// 创建一个子 Agent，专门处理数据库相关问题。
dbExpert, _ := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
    Name:    "db_expert",
    Description: "擅长数据库故障排查",
    Model:   cm,
})

// 给 supervisor 挂载可协作的子 Agent。
// 这样 supervisor 在处理请求时，就可以把数据库类问题分发给 dbExpert。
dispatcher, _ := adk.SetSubAgents(ctx, supervisor, []adk.Agent{dbExpert})

如果一个问题本来就该交给另一个 Agent 独立负责，那应该优先考虑 Transfer，而不是让当前 Agent 硬撑到底。

AgentAsTool

它的语义又不同：我不是把任务彻底交出去，我只是把另一个 Agent 当成一个'高级工具'来用。

什么时候适合这么做？当被调用的 Agent 不需要完整运行上下文，只要一个明确请求参数就能独立完成工作，更像一个'复杂工具'而不是一个'新的控制者'。

我这里从官方源码 NewAgentTool(...) 截取片段举例：

reporterTool := adk.NewAgentTool(ctx, reporterAgent)
agent, _ := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
    Name: "ops_assistant",
    Description: "负责处理线上故障",
    Model: cm,
    ToolsConfig: adk.ToolsConfig{
        ToolsNodeConfig: compose.ToolsNodeConfig{
            Tools: []tool.BaseTool{reporterTool},
        },
        EmitInternalEvents: true,
    },
})

一句话记忆这三者：

• Tool：调用一个函数
• Transfer：把控制权交给另一个 Agent
• AgentAsTool：把另一个 Agent 当函数来调

6. Middleware / Handler 才是工程化分水岭

如果说 Tool 解决的是