本文内容核心参考了官方文档中关于 Eino ADK 的几个关键模块：ChatModelAgent 概述、Agent 协作机制等。
许多开发者初次接触 ChatModelAgent 时，容易将其简单化，直观认为它只是给大模型加了一层外壳。
这个说法有一定道理，但远不够全面。实际上，ChatModelAgent 在 ADK 中扮演着“默认思考型 Agent”的核心角色。它并非仅执行一次模型调用，而是将模型决策、工具调用、协作跳转、事件输出以及扩展钩子，全部规范到一个可运行且完整的 Agent 框架内。
本文不会重复基础的 Runner 或 Console 多轮交互操作，而是从以下六个更关键的问题展开：
ChatModelAgent在 ADK 中的真实定位是什么？- 为什么其内部采用
ReAct循环，而非简单的单次模型调用？ ReturnDirectly / Exit / MaxIterations / OutputKey等字段分别解决了哪些实际问题？- 在
Tool、Transfer、AgentAsTool之间如何做出最佳选择？ - 为什么说
Middleware / Handler是衡量工程水平的分水岭？ - 如何构建一个贴近后端真实业务场景的 Demo 示例？
1. 为什么很多人会把 ChatModelAgent 想简单
许多初学者往往将注意力集中在 Instruction、Model 和 Tools 字段上，从而得出一个看似合理的结论：这无非是给模型加了一个工具调用功能。
然而，其真正的价值在于另一层——它内置了自主决策能力。
换句话说，它并非 ChatModel 的语法糖。它所解决的核心问题是：当 Agent 需要依赖 LLM 自行判断下一步是直接回答、调用工具、转交他人还是主动退出时，系统应当如何有效组织和管控这一运行过程。
这也是为什么你会发现它具备以下特性：
- 内置了
ReAct循环 - 支持
Transfer机制 - 可将另一个 Agent 视为 Tool 进行调用
- 拥有专门的
Handler处理工程逻辑 - 能够将整个运行过程输出为
AgentEvent
如果它真的只是一个“模型外套”，根本不需要发展出如此完整的能力体系。
2. ChatModelAgent 在 ADK 里到底是什么
官方定义非常直接：ChatModelAgent 是一个由底层聊天模型驱动的 Agent，用于处理复杂逻辑。
这句话中最重要的关键词不是“模型”，而是“复杂逻辑”。
我们可以先将 ADK 中的几类 Agent 进行粗略分类：
| 类型 | 主要职责 | 决策方式 |
|---|---|---|
ChatModelAgent | 负责思考、推理、工具调用、动态决策 | 由 LLM 决定 |
Workflow Agents | 负责顺序、循环、并行等固定流程 | 由预设流程决定 |
Supervisor / Plan-Execute | 负责多 Agent 协作范式封装 | 仍以内置 ChatModelAgent 为核心 |
Custom Agent | 负责高度定制的执行协议 | 由开发者自行实现 |
因此，ChatModelAgent 在架构中扮演着类似“默认大脑”的角色。
当你的 Agent 需要：
- 根据上下文自主判断下一步动作
- 在回答与工具调用之间灵活切换
- 在多个 Agent 之间转交任务
- 在运行过程中插入工程逻辑
那么它通常是最优先的选择。
将这套关系放到运行时视角来看，会更清晰：
这张图需要牢记两点：
ChatModelAgent不等于“模型输出一段文本”。- 它真正对外暴露的，是一整段可运行的决策过程。
3. 其内部本质是一个 ReAct 循环
ChatModelAgent 的核心执行模式非常朴素：内部遵循 ReAct 范式。
其内部是一个循环：
- 调用模型，让模型先做出判断。
- 如果模型直接给出答案，则结束。
- 如果模型发起 Tool Call，则执行对应工具。
- 将工具结果回灌给模型。
- 再次让模型决定下一步。
- 直到模型不再需要工具，或者 Agent 被强制终止。
这套循环中的四个关键词可以直接对应：
Reason：模型思考Action：模型决定调用什么Act：系统真正执行动作Observation：将动作结果反馈回去
因此，ChatModelAgent 的关键不在于“它能调用工具”，而在于它把“思考-行动-观察-再思考”这一闭环变成了天然的循环。
这也是它和我们直接手写一段 ChatModel.Generate(...) 的根本区别。
没有 Tool 时会怎样
坦白讲，如果没有 Tool，ChatModelAgent 会退化成一次简单的模型调用。
这意味着：
- 并非所有
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 与普通模型调用真正拉开差距的地方。其中有两个关键的扩展字段：
ReturnDirectlyEmitInternalEvents
ReturnDirectly
该字段的含义是：工具执行完毕后，直接将其结果作为最终输出，不再让模型重新处理一遍。
这项能力特别适合两类场景：
- 工具结果本身就是最终答案。
- 工具结果本身就是“交接单”“审批单”或“跳转结果”，再返回给模型处理反而可能污染结果。
例如后面 Demo 中的 handoff_to_human，就很适合设置 ReturnDirectly。
EmitInternalEvents
此配置仅在 AgentAsTool 场景中有意义。默认情况下，当你将一个 Agent 封装成 Tool 后，外层只会得到最终的 ToolResult，看不到内层 Agent 的事件流。而设置 EmitInternalEvents=true 后，内层 Agent 产生的事件会继续向外透出，调用方就能实时了解内部执行情况。
这项能力特别适合：
- 将复杂 Agent 当作 Tool 使用。
- 同时希望前端或调用方还能看到其实时输出。
OutputKey
这是一个非常实用的字段：OutputKey 的作用是将本次运行的结果保存到运行时上下文的某个固定 key 中。
如果后续 Agent、Workflow 或外层业务逻辑还需要继续消费本次结果，使用它比手动传递字符串要整洁得多。
Exit
可以将其理解为一个特殊的 Tool。模型调用此 Tool 并成功执行后，ChatModelAgent 会直接退出。效果与 ReturnDirectly 类似，但语义更明确：
ReturnDirectly更像是“某个工具调用后直接收口”。Exit更像是“模型自己宣布：到这里结束，把这个最终结果拿出去”。
ModelRetryConfig
这是一个典型的工程字段。它解决的不是“让回答更聪明”，而是“模型调用失败时，系统是否重试以及如何重试”。需要特别注意的是：该重试策略在流式输出和非流式输出场景下的表现不同。
因此，在真实系统中做流式输出时，不能只考虑 happy path。一旦流中途中断，你需要判断是彻底失败，还是很快会恢复。
5. Tool、Transfer、AgentAsTool 到底怎么选
这部分值得详细展开。许多人初次看到这三种能力时，会觉得它们都像“把事情交给别人做”，但之间的区别其实很大。
普通 Tool
它适合边界清晰、输入输出稳定的能力。例如：
- 查询错误码
- 查询 runbook
- 计算时间
- 调用外部 HTTP 接口
它更像一个函数调用。
Transfer
Transfer 的含义不是“调用另一个能力”，而是“将当前控制权转交给另一个 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 整体当作一个 Tool 来调用，调用方式与普通 Tool 一致。
适合以下场景：被调用的 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 解决的是“Agent 能干什么”，那么 Handler 解决的是“Agent 在真实系统中如何管理”。
官方文档给出的扩展点共有几层：
BeforeAgentBeforeModelRewriteStateAfterModelRewriteStateWrapModelWrapInvokableToolCall / WrapStreamableToolCall
将它们放到一张执行图中，会比只看接口名称更容易理解：
BeforeAgent
这是最适合在运行前修改配置的钩子。它能修改的不是消息历史，而是本次运行的 Instruction、Tools 和 ReturnDirectly。因此很适合做：
- 动态追加系统约束。
- 按租户或环境动态添加工具。
- 将某个工具临时标记为
ReturnDirectly。
BeforeModelRewriteState / AfterModelRewriteState
这两个钩子关注的是 Messages。适合做：
- 历史消息裁剪。
- 敏感信息脱敏。
- 在模型调用前后检查消息状态。
如果只想管理“发给模型的消息长什么样”，优先考虑这组钩子。
WrapModel
此钩子适合拦截模型调用本身。典型用途包括：
- 统一日志。
- 指标采集。
- 审计。
- 对模型输入输出进行包装。
其价值在于：无需修改业务代码，就能拦截“模型调用前后”的工程逻辑。
WrapInvokableToolCall / WrapStreamableToolCall
这两个钩子关注工具层。特别适合：
- 记下工具调用日志。
- 统计耗时。
- 做参数审计。
- 对工具结果进行二次包装。
为什么新代码更推荐 Handlers
官方和本地源码都已明确指出：旧的 AgentMiddleware 是 struct 风格，适合简单静态扩展；而新的 ChatModelAgentMiddleware 是 interface 风格，更适合动态行为和上下文改写。如果你现在编写新的 ChatModelAgent 扩展，优先使用 Handlers 会更稳妥。
7. 实战：用 ChatModelAgent 搭一个故障分诊助手
本例的目的不是为了构建一个真正的运维平台，而是展示如何将 ChatModelAgent 最重要的几个点跑通：
ChatModelAgent + Tool。ReturnDirectly。Handler。
先装依赖
go get github.com/cloudwego/eino@latest go get github.com/cloudwego/eino-ext/components/model/qwen@latest
环境变量至少需要准备两个：
$env:DASHSCOPE_API_KEY="你的百炼 API Key" $env:QWEN_MODEL="qwen-plus"
完整代码
这段代码的目标是演示一个故障分诊助手，它能够：
- 调用 runbook 工具查询预案。
- 调用 handoff 工具转人工。
- 通过 Handler 实现运行前约束和工具日志。
// 代码示例略，全文较长但已在原文中给出
这个 Demo 到底对应了什么
search_runbook是普通 Tool，模型先查事实，再组织答案。handoff_to_human被配置成ReturnDirectly，一旦调用就直接退出。OpsGuardHandler通过BeforeAgent和WrapInvokableToolCall将运行约束和工具日志插入进来。
如果你在本地运行，并传入一个“高风险但信息不足”的查询，比如：
go run . "payment 服务持续报错，但我只有一句日志：DB_TIMEOUT，请直接给我下一步动作。"
常见的表现会是两种：
- 模型先调用
search_runbook，再组织答案返回。 - 模型判断信息不足或风险过高，直接调用
handoff_to_human，然后因为设置了ReturnDirectly而立即结束。
这正是 ChatModelAgent 与普通模型调用的本质差别：它不仅能说话，还能决定下一步该怎么做。
8. 总结
本文最想帮你建立的，不是对某个 API 的记忆，而是一个认知：ChatModelAgent 是一条可运行的思考管线，而不是一次简单的模型调用。
它真正解决的问题是：
- 让模型在回答、调用工具、转交任务之间进行动态决策。
- 让这些动作按照
ReAct方式循环运行。 - 让运行过程以
AgentEvent的形式输出。 - 让你能够通过
Handler将日志、审计、消息裁剪、动态工具等工程能力无缝地集成进去。
