AI 大模型落地系列｜Eino ADK体系篇：你对 ChatModelAgent 有了解吗？

声明本文源于官方文档重点参考 Eino ADK: ChatModelAgent、Eino ADK: 概述、Eino ADK: Agent 协作为什么很多人把 ChatModelAgent 想简单了一文讲透 ReAct、Transfer、AgentAsTool 与 Middleware1. 为什么很多人会把 ChatModelAgent 想简单2. ChatModelAgent 在 ADK 里到底是什么3. 其内部本质是一个 ReAct 循环没有 Tool 时会怎样为什么还需要 MaxIterations4. 哪几组配置真正决定了行为Name / DescriptionInstruction / ModelToolsConfigReturnDirectlyEmitInternalEventsOutputKeyExitModelRetryConfig5. Tool、Transfer、AgentAsTool 到底怎么选普通 ToolTransferAgentAsTool6. Middleware / Handler 才是工程化分水岭BeforeAgentBeforeModelRewriteState / AfterModelRewriteStateWrapModelWrapInvokableToolCall / WrapStreamableToolCall为什么新代码更推荐 Handlers7. 实战用 ChatModelAgent 搭一个故障分诊助手先装依赖完整代码这个 Demo 到底对应了什么8. 总结ChatModelAgent 是一个以 LLM 为决策核心、默认采用 ReAct 式循环来推进任务的 Agent。很多人第一次看ChatModelAgent可能会下意识的认为不就是ChatModel Instruction Tools吗这句话不算错但不全。ChatModelAgent在 ADK 里承担的是“默认思考型 Agent”的角色。它不是单纯帮你调一次模型而是把模型决策、工具调用、协作跳转、事件输出和扩展钩子统一规范到一个可运行的 Agent 骨架里。本篇不在重复Runner / Console 多轮这种入门动作而是从以下 6 个更关键的问题入手ChatModelAgent在 ADK 里到底是什么它内部为什么是一个ReAct循环而不是一次模型调用ReturnDirectly / Exit / MaxIterations / OutputKey这些字段到底解决什么问题Tool、Transfer、AgentAsTool到底怎么选Middleware / Handler为什么才是工程化分水岭一个更贴后端场景的 Demo应该怎么搭1. 为什么很多人会把ChatModelAgent想简单很多人一上来就把注意力放在这几个字段上InstructionModelTools然后得出一个很自然的结论这就是一个“会调模型、也会调工具”的配置对象。但他的重点其实是另一层ChatModelAgent是 ADK 里最核心、最常用的预构建 Agent 之一它把“思考 决策 调工具 协作 输出事件”规范成了一个统一实现。也就是说它不是ChatModel的语法糖。它解决的是当一个 Agent 需要靠 LLM 自己判断下一步该答、该调工具、该转给别人、还是该退出时系统应该怎么组织这段运行过程。这也是为什么你会发现它有ReAct循环它有Transfer它可以把别的 Agent 当 Tool它有专门的Handler它还要把整个过程输出成AgentEvent如果只是“模型外面包一层”根本没必要长出这一整套能力。2.ChatModelAgent在 ADK 里到底是什么官方定义很直接ChatModelAgent是 Eino ADK 中的一个核心预构建 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 时会怎样可以这么说如果没有配置工具ChatModelAgent会退化为一次普通的 ChatModel 调用。这意味着不是所有ChatModelAgent都一定会循环只有当你给了工具、协作能力或者模型真的产生 Tool Call它才会进入完整的ReAct运行形态为什么还需要MaxIterationsReAct的好处是灵活风险是兜不住时会一直绕。所以MaxIterations本质上是一个保险丝。默认值是20。超过这个次数还没结束Agent 会直接报错退出。这在真实业务里非常有必要。否则你很容易遇到两种问题模型在几个工具之间来回试探始终拖沓着Prompt 写得含糊模型不知道该答还是该继续调工具很多线上“为什么 Agent 一直在调用工具”的问题本质上都不是框架 bug而是没有把循环上限和结束策略设计清楚。4. 哪几组配置真正决定了行为Name / Description这两个字段经常被初学者轻视。但实际上它们比你想象的重要。Name是 Agent 的身份标识Description决定别的 Agent 会不会把任务转给它尤其在Transfer场景里Description不是装饰品而是模型判断“谁更适合接手这件事”的依据。Instruction / Model这两个字段是最直观的InstructionAgent 的系统约束Model底层使用哪个ChatModel但有一点别搞混Instruction决定行为风格Model决定能力底座。ToolsConfig这组配置是ChatModelAgent和普通模型调用真正拉开差距的地方。其中有两个很关键的扩展字段起到了作用ReturnDirectlyEmitInternalEventsReturnDirectly这个字段的意思是某些工具一旦被调用成功就不要再把结果送回模型二次润色了直接把结果带着返回。这个能力特别适合两类场景工具结果本身就是最终答案工具结果本身就是“交接单”“审批单”“跳转结果”再回模型反而会把结果弄脏比如这篇后面 demo 里的handoff_to_human就很适合ReturnDirectly。EmitInternalEvents这个配置只在AgentAsTool场景里有意义。默认情况下当你把一个 Agent 包成 Tool 后外层只会拿到最终的 ToolResult看不到内层 Agent 的事件流。而EmitInternalEventstrue时内层 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 接口它更像函数调用。TransferTransfer的意思不是“调用另一个能力”而是当前 Agent 判断另一个 Agent 更适合接手这件事于是把任务控制权转过去。官方页对应的实现机制是给ChatModelAgent配置子 Agent框架自动生成一个Transfer Tool模型根据各个 Agent 的Description决定要不要跳转Runner 收到 Transfer Event 后切到目标 Agent 继续执行最小示意像这样// 创建一个上层 Agent作为请求分发器使用。// 它本身由聊天模型驱动职责是根据用户问题决定该交给谁处理。supervisor,_:adk.NewChatModelAgent(ctx,adk.ChatModelAgentConfig{Name:dispatcher,// Agent 名称运行时用于标识当前 AgentDescription:负责分发用户请求,// 描述帮助上层协作逻辑理解它的职责Model:cm,// 底层使用的聊天模型})// 创建一个子 Agent专门处理数据库相关问题。dbExpert,_:adk.NewChatModelAgent(ctx,adk.ChatModelAgentConfig{Name:db_expert,// 子 Agent 名称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把控制权交给另一个 AgentAgentAsTool把另一个 Agent 当函数来调6.Middleware / Handler才是工程化分水岭如果说 Tool 解决的是“Agent 能干什么”那Handler解决的就是“Agent 在真实系统里怎么管”。官方页给出的扩展点一共有几层BeforeAgentBeforeModelRewriteStateAfterModelRewriteStateWrapModelWrapInvokableToolCall / WrapStreamableToolCall把它们放到一张执行图里会比只看接口名字更容易懂BeforeAgent这是最适合做“运行前改配置”的地方。它能改的不是消息历史而是本次运行的InstructionToolsReturnDirectly所以它很适合做这些事动态追加系统约束按租户或环境动态加工具把某个工具临时标记为ReturnDirectlyBeforeModelRewriteState / AfterModelRewriteState这两个钩子盯的是Messages。适合做历史裁剪敏感信息脱敏在模型调用前后检查消息状态如果你只是想管“发给模型的消息长什么样”优先看这组。WrapModel这个钩子适合拦截模型调用本身。典型用途是统一日志指标采集审计对模型输入输出做包装它的价值在于你不用改业务代码就能把“模型调用前后”的工程逻辑拦下来。WrapInvokableToolCall / WrapStreamableToolCall这两个钩子盯的是工具层。特别适合打工具调用日志统计耗时做参数审计对工具结果二次包装为什么新代码更推荐Handlers官方和本地源码都已经把这个方向说得很明确了老的AgentMiddleware是 struct 风格适合简单静态扩展新的ChatModelAgentMiddleware是 interface 风格更适合动态行为和上下文改写如果你是现在开始写新的ChatModelAgent扩展优先用Handlers更稳。7. 实战用ChatModelAgent搭一个故障分诊助手目的做一个“故障分诊助手”能查 runbook、在高风险场景下直接升级给人工并通过 handler 统一加上运行约束与工具日志。本例子只演示三件事ChatModelAgent ToolReturnDirectlyHandler先装依赖go get github.com/cloudwego/einolatest go get github.com/cloudwego/eino-ext/components/model/qwenlatest环境变量至少准备两个$env:DASHSCOPE_API_KEY你的百炼 API Key$env:QWEN_MODELqwen-plus完整代码这段代码的目标不是做一个真正的运维平台而是把ChatModelAgent这一页最重要的几个点跑通。packagemainimport(contextfmtlogosstringsgithub.com/cloudwego/eino/adkgithub.com/cloudwego/eino/components/toolgithub.com/cloudwego/eino/components/tool/utilsgithub.com/cloudwego/eino/composegithub.com/cloudwego/eino/schemagithub.com/cloudwego/eino-ext/components/model/qwen)// RunbookInput 是查询故障预案工具的输入。typeRunbookInputstruct{Servicestringjson:service jsonschema:description服务名,enumuser,enumorder,enumpayment,enumsearchErrorCodestringjson:error_code jsonschema:description错误码例如 DB_TIMEOUT、AUTH_EXPIRED、NO_STOCK}// RunbookOutput 是故障预案工具的输出。typeRunbookOutputstruct{Levelstringjson:levelSuggestionstringjson:suggestionOwnerstringjson:owner}// HandoffInput 是转人工工具的输入。typeHandoffInputstruct{Reasonstringjson:reason jsonschema:description需要人工接手的原因}// HandoffOutput 是转人工工具的输出。typeHandoffOutputstruct{Ticketstringjson:ticketActionstringjson:action}// OpsGuardHandler 是一个自定义 middleware// 用来在 Agent 运行前补充约束并在工具调用时统一打日志。typeOpsGuardHandlerstruct{*adk.BaseChatModelAgentMiddleware}// NewOpsGuardHandler 创建自定义 handler。funcNewOpsGuardHandler()*OpsGuardHandler{returnOpsGuardHandler{BaseChatModelAgentMiddleware:adk.BaseChatModelAgentMiddleware{},}}// BeforeAgent 在整次 Agent 运行开始前执行。// 这里给本次运行动态追加额外指令。func(h*OpsGuardHandler)BeforeAgent(ctx context.Context,runCtx*adk.ChatModelAgentContext,)(context.Context,*adk.ChatModelAgentContext,error){// 拷贝一份运行上下文避免直接改原对象。nRunCtx:*runCtx// 动态补充本次运行约束// 1. 始终中文回复// 2. 先给结论再给依据// 3. 信息不足或风险高时优先转人工nRunCtx.Instruction\n\n始终使用中文回复。先给结论再给依据。若缺少关键信息或风险较高优先调用 handoff_to_human。returnctx,nRunCtx,nil}// WrapInvokableToolCall 包装普通工具调用。// 这里主要用于统一记录工具名和入参日志。func(h*OpsGuardHandler)WrapInvokableToolCall(ctx context.Context,endpoint adk.InvokableToolCallEndpoint,tCtx*adk.ToolContext,)(adk.InvokableToolCallEndpoint,error){returnfunc(ctx context.Context,argumentsInJSONstring,opts...tool.Option)(string,error){log.Printf([tool] name%s args%s,tCtx.Name,argumentsInJSON)returnendpoint(ctx,argumentsInJSON,opts...)},nil}// newRunbookTool 创建“查询故障预案”工具。// 模型可根据 service error_code 获取预定义排查建议。funcnewRunbookTool()tool.BaseTool{t,err:utils.InferTool(search_runbook,根据服务名和错误码查询故障处置建议,func(ctx context.Context,input*RunbookInput)(*RunbookOutput,error){switch{// payment 服务数据库超时时返回对应预案caseinput.Servicepaymentinput.ErrorCodeDB_TIMEOUT:returnRunbookOutput{Level:high,Suggestion:先确认只读实例是否可用再检查连接池是否打满必要时切换到降级路径。,Owner:payment-oncall,},nil// user 服务鉴权过期时返回对应预案caseinput.Serviceuserinput.ErrorCodeAUTH_EXPIRED:returnRunbookOutput{Level:medium,Suggestion:先排查 token 过期时间配置再确认网关和鉴权服务的时钟是否一致。,Owner:user-oncall,},nil// 未命中预案时返回兜底结果引导补充信息default:returnRunbookOutput{Level:unknown,Suggestion:没有命中预案请补充 service、error_code 和最近一次发布时间。,Owner:triage-bot,},nil}})iferr!nil{log.Fatalf(new runbook tool failed: %v,err)}returnt}// newHandoffTool 创建“转人工”工具。// 当问题风险较高或信息不足时用它生成交接单。funcnewHandoffTool()tool.BaseTool{t,err:utils.InferTool(handoff_to_human,当风险较高或信息不足时生成交接给人工处理的说明,func(ctx context.Context,input*HandoffInput)(*HandoffOutput,error){returnHandoffOutput{Ticket:INC-2026-031,Action:已生成交接单请值班同学继续处理。原因input.Reason,},nil})iferr!nil{log.Fatalf(new handoff tool failed: %v,err)}returnt}// newModel 创建底层聊天模型。funcnewModel(ctx context.Context)*qwen.ChatModel{cm,err:qwen.NewChatModel(ctx,qwen.ChatModelConfig{BaseURL:https://dashscope.aliyuncs.com/compatible-mode/v1,APIKey:mustEnv(DASHSCOPE_API_KEY),Model:envOrDefault(QWEN_MODEL,qwen-plus),})iferr!nil{log.Fatalf(new qwen model failed: %v,err)}returncm}// newTriageAgent 创建一个故障分诊 Agent。// 它可以// 1. 调用 runbook 工具查询预案// 2. 调用 handoff 工具转人工// 3. 在 handler 中做运行前约束和工具日志funcnewTriageAgent(ctx context.Context)adk.Agent{agent,err:adk.NewChatModelAgent(ctx,adk.ChatModelAgentConfig{Name:ops_triage_agent,// Agent 名称Description:负责排查后端线上故障能查询 runbook并在高风险时升级给人工处理,Instruction:你是后端故障分诊助手。优先使用工具获取事实再给结论。,Model:newModel(ctx),// 配置可用工具。ToolsConfig:adk.ToolsConfig{ToolsNodeConfig:compose.ToolsNodeConfig{Tools:[]tool.BaseTool{newRunbookTool(),newHandoffTool(),},},// handoff_to_human 一旦被调用工具结果可直接作为输出返回。ReturnDirectly:map[string]bool{handoff_to_human:true,},},MaxIterations:8,// 最多允许 8 轮 Agent 内部迭代OutputKey:triage_result,// 本次运行结果的输出键名// 注册自定义 middleware。Handlers:[]adk.ChatModelAgentMiddleware{NewOpsGuardHandler(),},})iferr!nil{log.Fatalf(new triage agent failed: %v,err)}returnagent}funcmain(){ctx:context.Background()// 默认查询内容可通过命令行参数覆盖。query:payment 服务出现 DB_TIMEOUT连接池已满请给我排查建议。iflen(os.Args)1{querystrings.Join(os.Args[1:], )}// 创建 Runner负责驱动 Agent 执行。runner:adk.NewRunner(ctx,adk.RunnerConfig{Agent:newTriageAgent(ctx),EnableStreaming:false,// 这里关闭流式输出})// 发起查询拿到事件流迭代器。iter:runner.Query(ctx,query)// 逐个消费 Agent 事件并打印结果。iferr:printEvents(iter);err!nil{log.Fatal(err)}}// printEvents 用于遍历 Agent 运行事件。// 如果是工具输出打印工具名否则按 assistant 输出打印。funcprintEvents(iter*adk.AsyncIterator[*adk.AgentEvent])error{for{event,ok:iter.Next()if!ok{returnnil}ifevent.Err!nil{returnevent.Err}ifevent.Outputnil||event.Output.MessageOutputnil{continue}mv:event.Output.MessageOutput msg,err:mv.GetMessage()iferr!nil{returnerr}switchmv.Role{caseschema.Tool:fmt.Printf(\n[tool:%s]\n%s\n,mv.ToolName,msg.Content)default:fmt.Printf(\n[assistant]\n%s\n,msg.Content)}}}// mustEnv 读取必填环境变量缺失则直接退出。funcmustEnv(keystring)string{v:os.Getenv(key)ifv{log.Fatalf(environment variable %s is required,key)}returnv}// envOrDefault 读取环境变量没有则返回默认值。funcenvOrDefault(key,fallbackstring)string{ifv:os.Getenv(key);v!{returnv}returnfallback}这个 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不是“模型调用升级版”而是 ADK 里默认的思考型 Agent 实现。它真正解决的是让模型在回答、调工具、转交任务之间做动态决策让这些动作按照ReAct方式循环运行让运行过程以AgentEvent形式输出让你能通过Handler把日志、审计、裁剪、动态工具这些工程能力插进去