声明本文数据源于官方文档与官方示例重点参考 Eino ADK: 概述、Eino ADK: Quickstart、Eino ADK: Agent 抽象、Eino ADK: Agent 协作、Eino ADK: Agent Runner 与扩展 与 Eino-examples/adk。什么是 Eino ADK什么是 Agent以及我们该如何开始1. 为啥初学者会觉得 ADK 很高深2. 什么是 Eino ADK3. 什么是 Agent以及它为什么是 ADK 的核心抽象3.1 为什么 ADK 要先定义 Agent 接口3.2 三个基础方法AgentInput、AgentEvent、Runner3.3 ChatModelAgent 为何重要3.4 为什么 Agent Runner 不该被忽略4. ADK 的四类基础扩展与封装关系到底该怎么理解4.1 为什么这四类东西不能混着看5. 多 Agent 协作到底在说什么5.1 协作方式5.2 上下文策略5.3 决策自主性5.4 把组合原语放在一起看就清楚多了6. ADK Examples 案例6.1 如果你是第一次学我建议这样看 examples7. 最小 runnable 入口7.1 安装依赖7.2 配环境变量7.3 第一份完整代码7.4 运行7.5 这份最小代码真正让你建立的是什么8. What’s Next这篇之后你该怎么继续学 ADK8.1 如果你是第一次学我建议按这条顺序往下走参考资料ADK是“构建单 Agent 和多 Agent 系统的一整套框架”如果之前你看过 Eino ADK 官方文档就会有一种很真实的感觉名词我都见过。ChatModelAgent、Workflow Agents、Supervisor、Plan-Execute、Agent Runner这些词单独看都不陌生。可如果现在关掉浏览器自己讲一遍Eino ADK到底是什么Agent为什么是它的核心抽象几类 Agent 到底是什么关系多 Agent 协作到底在协作什么我第一次真正上手应该从哪里开始估计很多人还是很蒙的。所以本篇文章将会围绕以下 6点 讲清楚Eino ADK是什么Agent是什么ChatModel Agent / Workflow Agents / Custom Agent / Built-in Multi-Agent分别是什么多 Agent 协作到底在协作什么第一个最小可运行入口应该怎么搭看完这篇以后下一步该读什么1. 为啥初学者会觉得 ADK 很高深Eino ADK 天然就横跨了几层不同的问题有一层在回答什么叫 Agent有一层在回答多个 Agent 怎么协作有一层在回答哪些模式是开箱即用的还有一层在回答Runner 怎么把 Agent 真的跑起来如果你第一次接触时直接把这些内容混在一起看脑子里就很容易形成一种误解“ChatModelAgent、SequentialAgent、Supervisor、Plan-Execute不都是 Agent 吗那我是不是直接挑一个最厉害的就行了”问题就在这里。它们都和 Agent 有关。但它们不是同一层的概念。有的是实现一种 Agent。有的是组合多个 Agent。有的是把多个基础能力封装成成熟范式。还有的是负责运行 Agent 的执行器。所以本篇文章将会带你建立对整个体系的基础认知并带给你一个基础小demo。这样你后面再看Workflow Agents、Supervisor、Plan-Execute就不会觉得自己手足无措。2. 什么是 Eino ADK先给一句最短的定义。Eino ADK是 Eino 提供的 Go 语言 Agent / Multi-Agent 开发框架。它参考了 Google-ADK 的设计但不是简单照搬概念。它真正想解决的是当你开始写 Agent而且不止一个 Agent 时如何把“运行、协作、上下文、治理”这些问题统一起来。如果只说“它是一个 Agent 框架”其实还不够全面。更准确一点你可以把它理解成它给你一个统一的 Agent 抽象它给你多 Agent 协作时的通用原语它给你几种开箱即用的协作范式它还给你运行时能力比如Runner、中断恢复、切面能力等官方在概述页里强调的几个关键词其实非常关键上下文传递事件流分发与转换任务控制权转让中断与恢复通用切面这几个词合在一起看你就会发现ADK不是“给模型外面再包一层壳”。它更像是一个Agent 运行时和协作框架。这点后端开发者应该可以更敏感的感受到Eino 的 Components 层更像“零件层”ADK 更像“让这些零件长成会运行、会协作、可治理的智能体系统”所以它适合的就不只是“能聊天的 Agent”。还包括对话型智能体非对话型智能体多步骤任务型智能体工作流式智能体Multi-Agent 协同系统官方概述页里给了一个总览图先看这个图你会更容易理解 ADK 到底在体系里的哪个位置图源 这是我从 CloudWeGo 官方文档扒拉出来的。先别急着把图里每个词都吃透。你只要先抓住一个核心结论ADK 的目标不是让你多学几个模式名。而是让你围绕 Agent 抽象把单体 Agent、多 Agent 协作和运行时能力串成一套完整开发方法。3. 什么是 Agent以及它为什么是 ADK 的核心抽象官方给的定义很朴素且准确Agent 是一个独立的、可执行的智能任务单元。大家可以把它先想象成一个“有明确身份、有明确职责、能被调起来执行的智能体”。只要一个场景需要和大语言模型交互它通常都可以被抽象成 Agent。例如一个查询天气的 Agent一个安排会议的 Agent一个回答特定领域知识的 Agent3.1 为什么 ADK 要先定义Agent接口因为没有统一抽象后面的协作、组合、Runner、Interrupt、Callback 都没法成立。Eino ADK 把 Agent 的基础接口定义成这样typeAgentinterface{Name(ctx context.Context)stringDescription(ctx context.Context)stringRun(ctx context.Context,input*AgentInput,opts...AgentRunOption)*AsyncIterator[*AgentEvent]}这 3 个方法里最值得注意的是下面这层含义Name这个 Agent 叫什么它的身份标识是什么Description这个 Agent 会什么其他 Agent 怎么判断要不要找它协作Run这个 Agent 怎么真正被运行起来所以 Agent 不是 Prompt 的别名。它至少同时包含了三件事身份职责执行入口3.2 三个基础方法AgentInput、AgentEvent、Runner很多人第一次卡住不是在Agent三个方法本身。而是在这几个配套概念名词你可以先怎么理解AgentInput这次要交给 Agent 的任务材料。默认最重要的是Messages也就是消息、上下文、历史、背景数据。AgentEventAgent 运行过程中吐出来的事件。不是只返回最终字符串而是把执行过程和结果按事件流交给调用方。RunnerAgent 的执行器。真正把 Agent 跑起来并负责很多运行时能力。比如AgentInput的核心定义官方抽象页里写得很直接typeAgentInputstruct{Messages[]Message EnableStreamingbool}这说明一个很重要的事实Agent 的输入并不只是“一句话”。它更像一份任务上下文。而AgentEvent为什么重要因为 ADK 不是把 Agent 看成“同步返回一个字符串的函数”。它把 Agent 看成“会在运行中持续产生事件的对象”。这也是为什么Run()的返回值不是string而是AsyncIterator[*AgentEvent]。3.3ChatModelAgent为何重要在 ADK 里ChatModelAgent是最关键、也最适合作为第一站的 Agent 实现。原因很简单它直接封装了和大语言模型的交互逻辑它本身就是一个“会思考、会生成、能调用工具”的 Agent你第一次上手最容易从它开始建立直觉可以先把它理解成用 LLM 做“大脑”的 Agent 实现。3.4 为什么Agent Runner不该被忽略很多人会把注意力全放在 Agent 身上然后忽略Runner。但官方文档里说得很清楚Runner 是 Eino ADK 中负责执行 Agent 的核心引擎。任何 Agent 都应通过 Runner 来运行。而且只有通过Runner跑起来时你才能真正用到多 Agent 协作过程中的上下文管理中断与恢复切面机制Context 环境预处理所以第一次学 ADK 时一定要先把握住一个关系Agent是任务单元。Runner是执行器。二者缺一不可。4. ADK 的四类基础扩展与封装关系到底该怎么理解这部分是很多人最容易略过去但其实最该慢下来看的一段。因为它在告诉你ADK 围绕 Agent 抽象至少有四种不同层次的能力块。类别你可以先把它理解成核心典型代表更适合干什么ChatModel Agent用 LLM 做大脑的 Agent推理、生成、工具调用ChatModelAgent单 Agent 推理、ReAct、动态决策Workflow Agents预先写好流程的 Agent 组合器顺序 / 循环 / 并发SequentialAgent、LoopAgent、ParallelAgent结构化编排、固定流程Custom Logic你自己实现的 Agent自定义代码与定制逻辑type MyAgent struct{}官方预置能力不够时的定制需求EinoBuiltInAgent开箱即用的 Multi-Agent 范式封装基于前几类能力做出的成熟模式Supervisor、Plan-Execute更复杂的协作与问题求解如果你非要把它再压缩成一句话我会这么说ChatModel Agent是会“想”的 AgentWorkflow Agents是会“排流程”的 AgentCustom Agent是你自己“写”的 AgentBuilt-in Agent是官方帮你“封装好范式”的 Agent官方 Quickstart 也给了一个分类关系图图源 这是我从 CloudWeGo 官方文档扒拉出来的。4.1 为什么这四类东西不能混着看因为它们虽然都围绕 Agent 展开但解决的问题根本不同。比如ChatModelAgent关注的是“一个 Agent 如何自己思考和调用工具”Sequential / Loop / Parallel关注的是“多个 Agent 如何按规则协作”Supervisor / Plan-Execute关注的是“复杂协作范式怎么开箱即用”你如果把这些东西都当成“同一层菜单”就很容易出现两种误解明明只是要一个会思考的 Agent却上来就找Plan-Execute明明只是固定三步流程却非要套Supervisor提醒本篇说的Workflow Agents是 ADK 里的 Agent 级协作抽象。它和 Eino Compose 层Chain / Graph / Workflow那套字段映射与节点编排不是同一个层级。一个是多个Agent之间的协作另一个是节点之间的编排5. 多 Agent 协作到底在说什么这也是 ADK 最容易被说得很玄、但其实完全可以讲明白的一部分。很多人一听“多 Agent 协作”脑子里就只有一句话“几个 Agent 一起干活。”这当然没错。但如果只停在这句话后面你还是不知道 ADK 到底在设计什么。这其实可以从三个维度来讲这件事协作方式上下文策略决策自主性5.1 协作方式Transfer和AgentAsTool先看最关键的一层。ADK 里两个最基础的协作动作可以先这么理解协作方式新手能先怎么理解什么时候更像它Transfer当前 Agent 把任务转交给另一个 Agent自己退出当前这轮像“任务移交”ToolCall(AgentAsTool)当前 Agent 把另一个 Agent 当成工具调一下拿到结果后自己继续像“调用一个子能力”这个区别非常重要。因为很多人第一次上手时会误把“找别的 Agent 帮忙”和“把任务完全转给别的 Agent”混成一回事。5.2 上下文策略为什么多 Agent 不只是“把消息丢过去”官方文档里强调了两种核心上下文策略上下文策略新手理解上游 Agent 全对话当前 Agent 直接看到上游 Agent 的完整历史与事件结果全新任务描述不直接传完整历史而是把上游结果压缩成一份新的任务摘要再交给下游 Agent如果你再把官方协作文档继续往下看会看到 ADK 还把上下文传递拆成了两个核心机制History更像“运行过程中的对话与事件历史”SessionValues更像“跨 Agent 共享的结构化状态”其中History对新手尤其重要因为它解释了很多人第一次看多 Agent 时的一个疑问为什么后一个 Agent 会“知道”前一个 Agent 干了什么答案不是魔法。而是前面 Agent 产生的AgentEvent会进入 History后面的 Agent 构造AgentInput时可以读到这些历史。5.3 决策自主性谁在决定下一个 Agent 是谁它本质上只是在区分两件事决策方式新手理解自主决策Agent 自己决定要不要找谁协作预设决策开发者提前把执行顺序写死这个维度一旦加进来你就更容易理解ChatModelAgent/SubAgents往往更接近“自主决策”Sequential / Parallel / Loop更接近“预设决策”5.4 把组合原语放在一起看就清楚多了下面这张表是我按照官方协作文档的结构专门给新手重写的一版组合原语你可以先怎么理解协作方式上下文决策方式SubAgents父 Agent 带一组子 Agent自主决定是否移交任务Transfer上游 Agent 全对话自主决策Sequential多个 Agent 按顺序一个接一个执行Transfer上游 Agent 全对话预设决策Parallel多个 Agent 基于同一输入并发执行Transfer上游 Agent 全对话预设决策Loop一组 Agent 按顺序循环执行Transfer上游 Agent 全对话预设决策AgentAsTool把一个 Agent 转成 Tool 给别的 Agent 调用ToolCall全新任务描述自主决策写这张表的目的不只是帮大家记住概念更是想建立一个简单的判断你到底是在做“任务移交”还是在做“能力调用”你到底要的是“自主路由”还是“预设流程”只要这两个问题能回答清楚你后面再看Workflow Agents、Supervisor、Plan-Execute理解速度会快非常多。6.ADK Examples案例官方 Quickstart 里给了很多 examples。很多人第一时间会把这些例子当成“代码仓库目录”。其实更有效的看法是每个 example 都是在帮使用者建立一种 Agent 模式的直觉。所以之下的案例将会带你明白每个例子你到底该学什么。示例你该从它身上学到什么第一次学时的建议intro/workflow/sequential看清楚顺序接力一个 Agent 的结果如何成为下一个 Agent 的输入背景最先看最好intro/workflow/loop看清楚反思迭代为什么“写完再批判再改”天然适合 Loop第二个看intro/workflow/parallel看清楚并行协作几个独立分析任务如何同时运行第三个看multiagent/supervisor看清楚中心调度一个总控 Agent 如何挑选专家 Agent前三个看懂后再看multiagent/layered-supervisor看清楚层级协作为什么复杂任务会出现多层监督者放在 supervisor 后面看multiagent/plan-execute-replan看清楚“计划 - 执行 - 重规划”的长任务闭环先别急着实操先理解结构intro/chatmodel书籍推荐看清楚中断恢复、Checkpoint、runner.Query / Resume 的配合当你开始关心运行时治理时再看6.1 如果你是第一次学我建议这样看 examples第一次上手不要把 examples 全部平铺打开。更稳的顺序是先看sequential再看loop再看parallel然后再看supervisor最后再去理解plan-execute-replan这个顺序的本质不是“由简单到复杂”这么空泛。而是先建立Workflow Agents的直觉再看更高级的 Multi-Agent 协作范式如果这条顺序不安排好很多人第一次看Supervisor或Plan-Execute会直接觉得“这不就是又包了一层 Agent 吗”但其实它们都是在前面基础之上更高层的封装。7. 最小 runnable 入口先跑通你的第一个ChatModelAgent Runner已讲完基础体系终于该回到“第一段代码”了。注意这里我故意不直接上Sequential、Loop或Supervisor。是因为你第一次要跑通的不是 Multi-Agent。而是 ADK 里最小、最完整的执行骨架。也就是ChatModel - ChatModelAgent - Runner7.1 安装依赖mkdireino-adk-first-cardcdeino-adk-first-card go mod init eino-adk-first-card go get github.com/cloudwego/einolatest go get github.com/cloudwego/eino-ext/components/model/qwenlatest7.2 配环境变量如果你在 macOS / LinuxexportDASHSCOPE_API_KEY你的百炼 API KeyexportQWEN_MODELqwen3.5-flash如果你在 Windows PowerShell$env:DASHSCOPE_API_KEY你的百炼 API Key$env:QWEN_MODELqwen3.5-flash7.3 第一份完整代码把下面代码保存成main.gopackagemainimport(contextfmtlogosstringsgithub.com/cloudwego/eino/adkgithub.com/cloudwego/eino/schemagithub.com/cloudwego/eino-ext/components/model/qwen)funcmain(){ctx:context.Background()// 默认问题也支持从命令行覆盖方便本地调试与演示。query:请用新手能看懂的话解释一下什么是 Eino ADK。iflen(os.Args)1{querystrings.Join(os.Args[1:], )}// 初始化底层大模型客户端。// 这里使用阿里百炼兼容接口通过环境变量读取密钥与模型名避免硬编码敏感信息。cm,err:qwen.NewChatModel(ctx,qwen.ChatModelConfig{BaseURL:https://dashscope.aliyuncs.com/compatible-mode/v1,APIKey:mustEnv(DASHSCOPE_API_KEY),Model:envOrDefault(QWEN_MODEL,qwen3.5-flash),})iferr!nil{log.Fatalf(new qwen chat model failed: %v,err)}// 将底层模型封装为一个可执行的 Agent。// Name / Description 用于标识与协作Instruction 用于约束该 Agent 的行为风格。agent,err:adk.NewChatModelAgent(ctx,adk.ChatModelAgentConfig{Name:ADKIntroAgent,Description:负责向新手解释 Eino ADK 的基础概念,Instruction:你是一个面向 Go 新手的 Eino ADK 讲解助手。先给一句结论再给三点解释控制在 300 字以内。,Model:cm,})iferr!nil{log.Fatalf(new chat model agent failed: %v,err)}// Runner 是 Agent 的统一执行入口。// 这里关闭流式输出改为按事件迭代读取完整结果。runner:adk.NewRunner(ctx,adk.RunnerConfig{Agent:agent,EnableStreaming:false,})fmt.Printf(user %s\n\n,query)// 发起一次查询并消费 Agent 返回的事件流。iferr:printAssistantOutputs(runner.Query(ctx,query));err!nil{log.Fatalf(run agent failed: %v,err)}}// printAssistantOutputs 负责从事件流中提取 assistant 消息并打印。// 这里只关心最终可读的消息内容忽略中间无效事件或非 assistant 输出。funcprintAssistantOutputs(events*adk.AsyncIterator[*adk.AgentEvent])error{for{event,ok:events.Next()if!ok{// 事件流结束说明本次执行完成。returnnil}// 运行过程中的错误会挂在事件上需要显式向上返回。ifevent.Err!nil{returnevent.Err}// 非消息类输出或空输出直接跳过。ifevent.Outputnil||event.Output.MessageOutputnil{continue}mv:event.Output.MessageOutput// 只处理 assistant 角色的消息。// 某些场景下 Role 可能为空这里一并兼容。ifmv.Role!schema.Assistantmv.Role!{continue}ifmv.Messagenil{continue}content:strings.TrimSpace(mv.Message.Content)ifcontent{continue}fmt.Printf(assistant\n%s\n,content)}}// mustEnv 读取必填环境变量缺失时直接终止进程。// 适用于 API Key、数据库地址等启动必需配置。funcmustEnv(keystring)string{v:os.Getenv(key)ifv{log.Fatalf(%s is empty,key)}returnv}// envOrDefault 读取可选环境变量若未配置则回退到默认值。// 适用于模型名、超时、开关等可提供默认行为的配置项。funcenvOrDefault(key,fallbackstring)string{ifv:os.Getenv(key);v!{returnv}returnfallback}7.4 运行go run.--请解释一下为什么 Eino ADK 不只是几个 Agent 模式名你大概会看到这样一段输出user 请解释一下为什么 Eino ADK 不只是几个 Agent 模式名 assistant ...7.5 这份最小代码真正让你建立的是什么第一次跑通时你最该看见的不是“模型回复成功了”。而是下面这条骨架终于成型了qwen.NewChatModel先有一个可调用的大模型adk.NewChatModelAgent再把模型包成一个可执行的 Agentadk.NewRunner再交给 Runner 驱动执行runner.Query(...)最后发起一次真正的 Agent 运行也就是说这段代码不是在教你“怎么问模型一个问题”。它是在教你ADK 里第一个能跑起来的 Agent到底是怎么被组装出来的。8. What’s Next这篇之后你该怎么继续学 ADK你可以把这个当成 “ADK 后续学习树”。图源 这是我从 CloudWeGo 官方文档扒拉出来的。8.1 如果你是第一次学我建议按这条顺序往下走先看懂整体目录Quickstart概述Agent 抽象Agent 协作ChatModelAgentWorkflow AgentsAgent Runner 与扩展再往后如果你要继续深入再接着看Supervisor AgentPlan-Execute AgentAgent CallbackInterrupt / Resume / HITL参考资料Eino ADK: 概述Eino ADK: QuickstartEino ADK: Agent 抽象Eino ADK: Agent 协作Eino ADK: Agent Runner 与扩展Eino-examples/adk