Eino ADK 核心解析：ChatModelAgent 深度实践与原理

为什么还需要 MaxIterations

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

这在真实业务里非常有必要，否则很容易遇到模型在几个工具之间来回试探，始终拖沓着的问题。很多线上'为什么 Agent 一直在调用工具'的问题，本质上都不是框架 bug，而是没有把循环上限和结束策略设计清楚。

决定行为的关键配置

Name / Description

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

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

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

Instruction / Model

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

注意区分：Instruction 决定行为风格，Model 决定能力底座。

ToolsConfig

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

ReturnDirectly

某些工具一旦被调用成功，就不要再把结果送回模型二次润色了，直接把结果带着返回。

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

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

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

EmitInternalEvents

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

而 EmitInternalEvents=true 时，内层 Agent 产生的事件会继续往外透出，调用方就能实时看到里面到底在干什么。

OutputKey

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

Exit

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

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

ModelRetryConfig

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

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

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

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 当函数来调

Middleware / Handler 才是工程化分水岭

如果说 Tool 解决的是'Agent 能干什么'，那 Handler 解决的就是'Agent 在真实系统里怎么管'。

官方页给出的扩展点一共有几层：

• BeforeAgent
• BeforeModelRewriteState / AfterModelRewriteState
• WrapModel
• WrapInvokableToolCall / WrapStreamableToolCall

BeforeAgent

这是最适合做'运行前改配置'的地方。它能改的不是消息历史，而是本次运行的 Instruction、Tools、ReturnDirectly。

所以它很适合做这些事：

• 动态追加系统约束
• 按租户或环境动态加工具
• 把某个工具临时标记为 ReturnDirectly

BeforeModelRewriteState / AfterModelRewriteState

这两个钩子盯的是 Messages。适合做历史裁剪、敏感信息脱敏、在模型调用前后检查消息状态。如果你只是想管'发给模型的消息长什么样'，优先看这组。

WrapModel

这个钩子适合拦截模型调用本身。典型用途是统一日志、指标采集、审计、对模型输入输出做包装。它的价值在于：你不用改业务代码，就能把'模型调用前后'的工程逻辑拦下来。

WrapInvokableToolCall / WrapStreamableToolCall

这两个钩子盯的是工具层。特别适合打工具调用日志、统计耗时、做参数审计、对工具结果二次包装。

为什么新代码更推荐 Handlers

官方和本地源码都已经把这个方向说得很明确了：老的 AgentMiddleware 是 struct 风格，适合简单静态扩展；新的 ChatModelAgentMiddleware 是 interface 风格，更适合动态行为和上下文改写。

如果你是现在开始写新的 ChatModelAgent 扩展，优先用 Handlers 更稳。

实战：用 ChatModelAgent 搭一个故障分诊助手

目的：做一个'故障分诊助手'，能查 runbook、在高风险场景下直接升级给人工，并通过 handler 统一加上运行约束与工具日志。

本例子只演示三件事：

1. ChatModelAgent + Tool
2. ReturnDirectly
3. Handler

先装依赖

go get github.com/cloudwego/eino@latest
go get github.com/cloudwego/eino-ext/components/model/qwen@latest

环境变量至少准备两个：

export DASHSCOPE_API_KEY="你的百炼 API Key"
export QWEN_MODEL="qwen-plus"

完整代码

这段代码的目标不是做一个真正的运维平台，而是把 ChatModelAgent 这一页最重要的几个点跑通。

package main

import (
	"context"
	"fmt"
	"log"
	"os"
	"strings"

	"github.com/cloudwego/eino/adk"
	"github.com/cloudwego/eino/components/tool"
	"github.com/cloudwego/eino/components/tool/utils"
	"github.com/cloudwego/eino/compose"
	"github.com/cloudwego/eino/schema"
	"github.com/cloudwego/eino-ext/components/model/qwen"
)

// RunbookInput 是查询故障预案工具的输入。
type RunbookInput struct {
	Service   string `json:"service" jsonschema:"description=服务名，enum=user,enum=order,enum=payment,enum=search"`
	ErrorCode string `json:"error_code" jsonschema:"description=错误码，例如 DB_TIMEOUT、AUTH_EXPIRED、NO_STOCK"`
}

// RunbookOutput 是故障预案工具的输出。
type RunbookOutput struct {
	Level     string `json:"level"`
	Suggestion string `json:"suggestion"`
	Owner     string `json:"owner"`
}

// HandoffInput 是转人工工具的输入。
type HandoffInput struct {
	Reason string `json:"reason" jsonschema:"description=需要人工接手的原因"`
}

// HandoffOutput 是转人工工具的输出。
type HandoffOutput struct {
	Ticket string `json:"ticket"`
	Action string `json:"action"`
}

// OpsGuardHandler 是一个自定义 middleware，
// 用来在 Agent 运行前补充约束，并在工具调用时统一打日志。
type OpsGuardHandler struct {
	*adk.BaseChatModelAgentMiddleware
}

// NewOpsGuardHandler 创建自定义 handler。
func NewOpsGuardHandler() *OpsGuardHandler {
	return &OpsGuardHandler{
		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。"
	return ctx, &nRunCtx, nil
}

// WrapInvokableToolCall 包装普通工具调用。
// 这里主要用于统一记录工具名和入参日志。
func (h *OpsGuardHandler) WrapInvokableToolCall(ctx context.Context, endpoint adk.InvokableToolCallEndpoint, tCtx *adk.ToolContext) (adk.InvokableToolCallEndpoint, error) {
	return func(ctx context.Context, argumentsInJSON string, opts ...tool.Option) (string, error) {
		log.Printf("[tool] name=%s args=%s", tCtx.Name, argumentsInJSON)
		return endpoint(ctx, argumentsInJSON, opts...)
	}, nil
}

// newRunbookTool 创建'查询故障预案'工具。
// 模型可根据 service + error_code 获取预定义排查建议。
func newRunbookTool() tool.BaseTool {
	t, err := utils.InferTool("search_runbook", "根据服务名和错误码查询故障处置建议", func(ctx context.Context, input *RunbookInput) (*RunbookOutput, error) {
		switch {
		// payment 服务数据库超时时，返回对应预案
		case input.Service == "payment" && input.ErrorCode == "DB_TIMEOUT":
			return &RunbookOutput{
				Level:      "high",
				Suggestion: "先确认只读实例是否可用，再检查连接池是否打满，必要时切换到降级路径。",
				Owner:      "payment-oncall",
			}, nil
		// user 服务鉴权过期时，返回对应预案
		case input.Service == "user" && input.ErrorCode == "AUTH_EXPIRED":
			return &RunbookOutput{
				Level:      "medium",
				Suggestion: "先排查 token 过期时间配置，再确认网关和鉴权服务的时钟是否一致。",
				Owner:      "user-oncall",
			}, nil
		// 未命中预案时，返回兜底结果，引导补充信息
		default:
			return &RunbookOutput{
				Level:      "unknown",
				Suggestion: "没有命中预案，请补充 service、error_code 和最近一次发布时间。",
				Owner:      "triage-bot",
			}, nil
		}
	})
	if err != nil {
		log.Fatalf("new runbook tool failed: %v", err)
	}
	return t
}

// newHandoffTool 创建'转人工'工具。
// 当问题风险较高或信息不足时，用它生成交接单。
func newHandoffTool() tool.BaseTool {
	t, err := utils.InferTool("handoff_to_human", "当风险较高或信息不足时，生成交接给人工处理的说明", func(ctx context.Context, input *HandoffInput) (*HandoffOutput, error) {
		return &HandoffOutput{
			Ticket: "INC-2026-031",
			Action: "已生成交接单，请值班同学继续处理。原因：" + input.Reason,
		}, nil
	})
	if err != nil {
		log.Fatalf("new handoff tool failed: %v", err)
	}
	return t
}

// newModel 创建底层聊天模型。
func newModel(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"),
	})
	if err != nil {
		log.Fatalf("new qwen model failed: %v", err)
	}
	return cm
}

// newTriageAgent 创建一个故障分诊 Agent。
// 它可以：
// 1. 调用 runbook 工具查询预案
// 2. 调用 handoff 工具转人工
// 3. 在 handler 中做运行前约束和工具日志
func newTriageAgent(ctx context.Context) adk.Agent {
	agent, err := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
		Name:      "ops_triage_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()},
	})
	if err != nil {
		log.Fatalf("new triage agent failed: %v", err)
	}
	return agent
}

func main() {
	ctx := context.Background()
	// 默认查询内容，可通过命令行参数覆盖。
	query := "payment 服务出现 DB_TIMEOUT，连接池已满，请给我排查建议。"
	if len(os.Args) > 1 {
		query = strings.Join(os.Args[1:], " ")
	}
	// 创建 Runner，负责驱动 Agent 执行。
	runner := adk.NewRunner(ctx, adk.RunnerConfig{
		Agent:          newTriageAgent(ctx),
		EnableStreaming: false, // 这里关闭流式输出
	})
	// 发起查询，拿到事件流迭代器。
	iter := runner.Query(ctx, query)
	// 逐个消费 Agent 事件并打印结果。
	if err := printEvents(iter); err != nil {
		log.Fatal(err)
	}
}

// printEvents 用于遍历 Agent 运行事件。
// 如果是工具输出，打印工具名；否则按 assistant 输出打印。
func printEvents(iter *adk.AsyncIterator[*adk.AgentEvent]) error {
	for {
		event, ok := iter.Next()
		if !ok {
			return nil
		}
		if event.Err != nil {
			return event.Err
		}
		if event.Output == nil || event.Output.MessageOutput == nil {
			continue
		}
		mv := event.Output.MessageOutput
		msg, err := mv.GetMessage()
		if err != nil {
			return err
		}
		switch mv.Role {
		case schema.Tool:
			fmt.Printf("\n[tool:%s]\n%s\n", mv.ToolName, msg.Content)
		default:
			fmt.Printf("\n[assistant]\n%s\n", msg.Content)
		}
	}
}

// mustEnv 读取必填环境变量；缺失则直接退出。
func mustEnv(key string) string {
	v := os.Getenv(key)
	if v == "" {
		log.Fatalf("environment variable %s is required", key)
	}
	return v
}

// envOrDefault 读取环境变量；没有则返回默认值。
func envOrDefault(key, fallback string) string {
	if v := os.Getenv(key); v != "" {
		return v
	}
	return fallback
}

这个 Demo 到底对应了什么

1. search_runbook 是普通 Tool，模型先查事实，再组织答案
2. handoff_to_human 被配置成 ReturnDirectly，一旦调用就直接退出
3. OpsGuardHandler 通过 BeforeAgent 和 WrapInvokableToolCall 把运行约束和工具日志插进来了

如果你本地跑的时候传一个'高风险但信息不足'的问题，比如：

go run . "payment 服务持续报错，但我只有一句日志：DB_TIMEOUT，请直接给我下一步动作。"

常见表现会是两种：

• 模型先调 search_runbook，再组织答案返回
• 模型判断信息不足或风险过高，直接调 handoff_to_human，然后因为 ReturnDirectly 立即结束

这正是 ChatModelAgent 和普通模型调用的差别：它不是只会说话，而是会决定下一步怎么干。

总结

本篇最想帮你建立的，不是某个 API 记忆点，而是一个判断：

ChatModelAgent 不是'模型调用升级版'，而是 ADK 里默认的思考型 Agent 实现。

它真正解决的是：

• 让模型在回答、调工具、转交任务之间做动态决策
• 让这些动作按照 ReAct 方式循环运行
• 让运行过程以 AgentEvent 形式输出
• 让你能通过 Handler 把日志、审计、裁剪、动态工具这些工程能力插进去