26DeepAgents 实战任务列表、子任务委派与文件协作《Eino 实战用 Go 构建 AI 应用与智能体》· 第 26 篇关键词DeepAgents、WriteTodos、TaskTool、FileSystem、委派前置条件已完成 22AgentAsTool 与 25Plan-Execute-Replan。前几篇的多智能体方案各有侧重AgentAsTool 灵活、Workflow Agents 固定、Supervisor 分层、Plan-Execute-Replan 可调整。DeepAgents 是官方给出的一个预置组合把“任务规划 子任务委派”打成一个开箱可用的 Agent。一句话概括它的构成DeepAgents ChatModelAgent WriteTodos任务规划与追踪 TaskTool子任务委派 可选 FileSystem 预置系统提示词一、它由哪些能力组成组件作用WriteTodos让 Agent 显式维护 TODO 列表执行中持续追踪进度TaskTool把子任务委派给子 Agent 独立执行结果汇总回主循环FileSystem可选提供文件读写与命令执行工具预置提示词内置行为规范与工具使用策略它的价值在于解决两个实际痛点复杂问题不该“一口气想完”。WriteTodos 强制先拆解、再逐步推进让过程可见、可中断、可恢复。单个 Agent 的能力边界有限。TaskTool 让主 Agent 按需把子任务交出去完成后汇总。二、两个内置工具write_todos创建和更新任务列表。{todos:[{content:收集打印机故障信息,status:in_progress},{content:整理处理建议,status:pending}]}它是 DeepAgents 内置的不需要你自己注册——配置好 DeepAgent 后模型就能调用它。task委派子任务。{subagent_type:researcher,description:整理打印机离线的处理建议}两个参数的含义参数说明subagent_type子 Agent 的名称必须与SubAgents里某个 Agent 的Name完全一致description子任务的说明subagent_type写错会直接报错本篇实测踩到过subagent type not found。这不是幻觉容错问题而是配置不一致——名字必须对得上。三、构建方式deepAgent,err:deep.New(ctx,deep.Config{Name:deep-assistant,Description:可以拆解复杂任务并逐步执行的助手,ChatModel:chatModel,SubAgents:[]adk.Agent{researcher,coder},})关键配置字段说明ChatModel决策模型使用工具时需支持WithToolsSubAgents可被委派的子 Agent 列表每个都必须有Name和DescriptionInstruction留空时会使用内置的默认提示词Backend提供文件系统能力可选Shell/StreamingShell提供命令执行能力可选二者互斥WithoutWriteTodos关闭内置的 TODO 工具WithoutGeneralSubAgent关闭默认的通用子 Agent几个实用细节默认会自动生成一个通用子 Agentgeneral-purpose。不想保留时用WithoutGeneralSubAgent关闭。WithoutWriteTodos只在明确不需要任务追踪时使用。关掉它就失去了 DeepAgents 的主要价值。文件系统与命令执行是可选的且属于高风险能力——稍后单独讨论。四、完整示例下面这段程序演示“规划 → 委派 → 汇总”的完整流程不访问外部服务packagemainimport(contextfmtloggithub.com/cloudwego/eino/adkgithub.com/cloudwego/eino/adk/prebuilt/deepgithub.com/cloudwego/eino/components/modelgithub.com/cloudwego/eino/schema)// scriptedModel 按脚本返回响应。typescriptedModelstruct{responses[]*schema.Message idxint}func(m*scriptedModel)Generate(_context.Context,_[]*schema.Message,_...model.Option)(*schema.Message,error){ifm.idxlen(m.responses){returnschema.AssistantMessage(脚本结束,nil),nil}r:m.responses[m.idx]m.idxreturnr,nil}func(m*scriptedModel)Stream(ctx context.Context,in[]*schema.Message,opts...model.Option)(*schema.StreamReader[*schema.Message],error){msg,err:m.Generate(ctx,in,opts...)iferr!nil{returnnil,err}sr,sw:schema.Pipe[*schema.Message](1)gofunc(){defersw.Close();sw.Send(msg,nil)}()returnsr,nil}func(m*scriptedModel)WithTools([]*schema.ToolInfo)(model.ToolCallingChatModel,error){returnm,nil}funcmain(){iferr:run();err!nil{log.Fatal(err)}}funcrun()error{ctx:context.Background()// 主 Agent先写 TODO 列表再委派子任务最后总结。// 注意 write_todos 与 task 是 DeepAgents 内置工具模型直接调用即可。mainModel:scriptedModel{responses:[]*schema.Message{// 1. 规划创建任务列表。schema.AssistantMessage(,[]schema.ToolCall{{ID:p1,Type:function,Function:schema.FunctionCall{Name:write_todos,Arguments:{todos:[{content:收集打印机故障信息,status:in_progress},{content:整理处理建议,status:pending}]},},}}),// 2. 委派把子任务交给子 Agent。schema.AssistantMessage(,[]schema.ToolCall{{ID:p2,Type:function,Function:schema.FunctionCall{Name:task,Arguments:{subagent_type:researcher,description:整理打印机离线的处理建议},},}}),// 3. 汇总。schema.AssistantMessage(最终报告先查网线再确认网段必要时提交工单。,nil),}}// 子 Agent执行被委派的任务。subAgent,err:adk.NewChatModelAgent(ctx,adk.ChatModelAgentConfig{Name:researcher,Description:负责整理处理建议,Instruction:你负责整理建议。,Model:scriptedModel{responses:[]*schema.Message{schema.AssistantMessage(建议1) 检查网线2) 确认网段3) 提交工单。,nil),}},})iferr!nil{returnerr}deepAgent,err:deep.New(ctx,deep.Config{Name:deep-assistant,Description:可以拆解复杂任务并逐步执行的助手,ChatModel:mainModel,SubAgents:[]adk.Agent{subAgent},})iferr!nil{returnfmt.Errorf(创建 DeepAgent 失败: %w,err)}runner:adk.NewRunner(ctx,adk.RunnerConfig{Agent:deepAgent})iter:runner.Query(ctx,帮我分析打印机离线问题并给出建议)n:0for{event,ok:iter.Next()if!ok{break}ifevent.Err!nil{fmt.Println( [事件错误],event.Err)continue}nifmv:messageOutput(event);mv!nilmv.Message!nil{label:mv.ToolNameiflabel{labelstring(mv.Role)}fmt.Printf( agent%-16s %-14s content%q\n,event.AgentName,label,trim(mv.Message.Content))}}fmt.Println(事件总数:,n)returnnil}functrim(sstring)string{r:[]rune(s)iflen(r)40{returnstring(r[:40])…}returns}funcmessageOutput(event*adk.AgentEvent)*adk.MessageVariant{ifeventnil||event.Outputnil{returnnil}returnevent.Output.MessageOutput}实机输出agentdeep-assistant assistant content agentdeep-assistant write_todos contentUpdated todo list to [{\content\:\收集打印机故… agentdeep-assistant assistant content agentdeep-assistant task content建议1) 检查网线2) 确认网段3) 提交工单。 agentdeep-assistant assistant content最终报告先查网线再确认网段必要时提交工单。 事件总数: 5事件流完整呈现了 DeepAgents 的工作方式模型请求write_todos先规划任务列表而不是直接动手。任务列表创建成功内容被更新。模型请求task把子任务委派给researcher。子 Agent 返回结果建议汇总回主循环。主 Agent 给出最终报告。这五步的形状和第 22 篇 AgentAsTool 完全一致——因为 TaskTool 本身就是 AgentAsTool 的一种封装。DeepAgents 的价值在于它把“规划 委派”这两件事做成了开箱可用的组合并配好了提示词。五、文件系统与命令执行DeepAgents 可选提供文件读写和命令执行能力deepAgent,err:deep.New(ctx,deep.Config{// ...Backend:myBackend,// 提供 read_file/write_file/edit_file/glob/grepShell:myShell,// 提供 execute命令执行})这两项是高危能力引入前必须想清楚。风险说明任意文件读写Agent 可能读到敏感文件密钥、配置、用户数据命令执行等价于给模型一个 shell风险等级最高路径穿越输入未校验时可访问预期外的目录数据外泄读取的内容可能随上下文发给模型服务如果确实需要底线是沙箱隔离。文件系统限定在专用目录命令执行放在容器里。最小权限。用只读挂载优先不要给 root。网络隔离。限制外联防止数据被带走。审计。记录所有文件访问与命令执行含调用者身份。仍然要鉴权。工具内部的权限校验不可省第 11 篇。不要在生产环境的宿主机上直接开放命令执行。这一条没有例外。六、什么时候用 DeepAgents场景建议复杂任务需要先拆解再逐步推进适合有明确可委派的子任务适合需要任务进度可见便于人工介入适合简单问答、单步操作不适合直接用 ChatModel 或简单 Agent流程完全固定不适合用 Workflow Agents需要读写文件/执行命令仅在有沙箱隔离时考虑判断依据任务是否“值得先规划”。三步以内能做完的事引入 TODO 列表只是增加开销。七、与前面几种模式的关系模式特点何时选AgentAsTool手动搭建委派需要精细控制Workflow Agents结构固定流程确定Supervisor分层指挥、共享上下文有明确层级Plan-Execute-Replan计划可改步骤无法一次确定DeepAgents规划 委派开箱可用想快速获得这两种能力DeepAgents 可以理解为 AgentAsTool 的一个“带规划能力的最佳实践版本”。如果你正打算自己写 AgentAsTool 加 TODO 管理先看看 DeepAgents 是否已满足需求。八、常见问题报错subagent type not foundtask工具里的subagent_type与子 Agent 的Name不一致。名字必须完全匹配本篇实测踩到过。子 Agent 永远不被调用检查子 Agent 是否设置了Description以及描述是否说明了适用场景。主 Agent 靠描述判断该不该委派。TODO 列表没有产生模型没调用write_todos。检查提示词是否鼓励“先规划”以及是否误设了WithoutWriteTodos。多出了不认识的general-purpose子 Agent这是默认自动生成的通用子 Agent。不需要时用WithoutGeneralSubAgent关闭。担心文件操作越权必须做沙箱隔离与路径校验。不要依赖提示词约束文件访问范围。运行变慢或成本上升规划与委派都会增加模型调用。用事件流统计实际次数确认是否值得。九、小结DeepAgents ChatModelAgent WriteTodos规划 TaskTool委派 可选 FileSystem 预置提示词。write_todos与task是内置工具无需注册task的subagent_type必须与子 AgentName完全一致。事件流清晰呈现“规划 → 委派 → 汇总”的形状与 AgentAsTool 一致差别在于开箱即用。默认会生成general-purpose子 Agent可用WithoutGeneralSubAgent关闭。文件系统与命令执行是高危能力必须沙箱隔离、最小权限、网络限制并保留审计。是否使用取决于“任务是否值得先规划”简单任务引入它只是增加开销。第五篇《多智能体》到此完成。下一篇进入第六篇《生产实践》讨论服务化、可观测性、可靠性、安全与评测。参考资料与版本说明资料核对日期为2026 年 10 月 9 日Eino ADK: DeepAgents五分钟上手 Eino ADKDeepAgents 部分Eino 官方示例DeepAgentsEino 主仓库本文示例按Eino v0.9.21编写使用脚本化模型不访问外部服务已实机运行正文输出含subagent_type报错踩坑为真实结果。
