如果你最近在折腾多智能体系统大概率已经刷到过 deepagents 这个词。它不是又一个“拖拽编排平台”而是 Hugging Face 在 smolagents 之上开源的一套轻量级多智能体协调框架核心卖点是三件事轻量、可组合、路由可控。我把这个框架用在真实项目里已经有一段时间了这篇算作我“deepagents in action”系列实战记录里的第八个任务重点不是复述官方文档而是把从搭环境到跑通多智能体协作流水线的完整过程以及中间踩过的坑一次性讲清楚。这套东西适合谁我认为是三类人一是想在真实业务里落地 AI Agent 的开发者二是做数据分析、自动化脚本的工程师三是想研究多智能体协作机制但不希望被重型框架绑住的学习者。如果你只是想在笔记本上调几个 demo它上手也很快如果你想把它塞进生产流程这篇文章里的路由调试、工具设计和坑位排查部分应该能帮你省下不少时间。1. 为什么是 deepagents框架选型背后的那些考量1.1 “代码即行动”的智能体到底跟传统 Agent 有什么不一样deepagents 底层沿用了 smolagents 的核心思路智能体在解决任务时不是输出 JSON 格式的“动作序列”而是直接生成一段可执行的 Python 代码。这一点的差别非常大。传统的 agent 循环是“模型输出一个动作 → 解析成工具调用 → 拿到结果 → 继续”每一步都要做结构化解析稍有一点格式漂移就会让整条链路断掉。而 deepagents 让模型直接把计划变成代码工具调用本质上是代码里的函数调用解析这一步几乎被消掉了整个循环更短、更不容易出错。我用一个生活化的类比来解释传统 Agent 相当于你给一个实习生发指令他每做一步都要回来跟你汇报“我现在要打开浏览器了”“我现在要输入文字了”你批准后他才继续而 deepagents 的 Code Agent 相当于你直接让一个熟练员工拿到任务后自己写一个小脚本一步到位把活干完。前者的好处是可观测后者的好处是高效而在真实自动化场景里高效往往比全程汇报更重要。当然“代码即行动”也有代价它要求模型有不错的代码生成能力并且运行环境必须能安全地执行模型生成的代码。如果你是坐在本机跑自己的自动化任务代码执行风险是可控的如果你要做成多用户 SaaS 服务那就要在沙箱隔离上花心思了。1.2 Agent、Tool、ManagedAgent三个概念撑起一套体系deepagents 的整个 API 几乎可以由三个核心概念概括Agent、Tool、ManagedAgent。Tool 是最小单位通常用装饰器声明一个 Python 函数函数的 docstring 就是这个工具的“使用说明书”Agent 是一个有“角色设定”的智能体里面装了若干个工具和一组 system promptManagedAgent 则是把 Agent 再包装一层给它一个在外部可见的名字和能力描述方便被其他 Agent 识别和调用。这个层级关系才是 deepagents 真正想表达的设计哲学主智能体也叫 boss不直接掌握所有工具而是通过 ManagedAgent 列表知道“我可以把什么样的子任务交给谁”。子智能体各自持有专用工具boss 负责拆解任务、分发、汇总。这样每个模块都能独立测试、独立替换组合度很高。实际写代码的时候你会发现你几乎不需要关注复杂的底层协调逻辑只要把“谁干什么事”定义清楚剩下的路由和委派交给框架就好。1.3 和 LangGraph、AutoGen、CrewAI 对比为什么在这个任务里选它我最早也评估过其他几个主流框架最终在 task08 这个场景里选择 deepagents主要是因为它解决了一个很具体的痛点中小规模自动化任务不需要重型编排。这里简单列一下我的选型对比框架核心模型上手成本典型场景我的评价AutoGen会话式对话agent 之间互相发消息中高研究性多智能体对话、辩论、协作灵活但太发散跑业务要写很多控制逻辑LangGraph显式状态图节点和边都要自己定义高需要精细控制状态流的复杂流程控制力强但样板代码多小任务用起来累CrewAI角色扮演式任务/角色/流程组件化低内容生成、流程编排上手快但内部过程像一个黑盒路由不可控deepagents代码即行动 图路由ManagedAgent 协作低自动化流水线、工具组合、代码分析轻量直接路由可观测适合快速落地我并不是说 deepagents 全面优于其他框架。如果你的流程有复杂的条件分支、人工审批环节LangGraph 可能更好如果你就是在研究多个智能体如何通过对话达成共识AutoGen 的生态更丰富。但在“收集资料 → 分析整理 → 生成报告”这类中等复杂度的自动化流水线里deepagents 的轻和快就是最大的优势。2. 环境准备与第一个多智能体协作 Demo2.1 安装配置其实只需要一个 Python 环境和一份模型配置deepagents 的安装相当简单因为它没有把整个 SDK 做成一个庞然大物。先确保你的 Python 版本在 3.9 以上然后直接安装依赖库即可。官方推荐从 smolagents 入手因为 deepagents 是在 smolagents 基础上扩展出来的运行时会把两者一起装好。安装完成后代码里通常是from deepagents import Agent, ManagedAgent, Tool同时可能会用到from smolagents import CodeAgent之类的类。模型接入也很有弹性你可以通过 model_id 直接指定 Hugging Face 推理服务上的模型也可以传入 OpenAI、Anthropic 等兼容接口的模型配置。我在本地实验时会用一个中型的开源模型比如 Qwen 系列的 Instruct 版本跑正式任务时则换容量更大的模型。需要注意的是deepagents 对模型有“隐形要求”代码生成能力要够强所以模型选型直接决定了自动化任务的完成度这一点后面会展开说。2.2 几个你不得不知道的核心参数在你动手写第一个多智能体任务之前有两个参数建议先理解因为它们会直接出现在你几乎每次 run 调用里。第一个是return_agent_route设为 True 后run()会返回一个路由信息对象里面记录着任务被派发给了哪个子智能体、每个子智能体收到了什么子任务、最后又回到了谁手里。第二个是max_operations它限制一次任务中智能体最多可以执行多少步工具调用和代码操作相当于一个“安全阀”用来防止模型陷入死循环或者刷爆你的 API 额度。这两个参数的作用是互补的return_agent_route让你看得见max_operations让你兜得住。我通常的习惯是先用默认值跑通确认路由正确后再把max_operations调到一个合理上限既给模型足够的操作空间又不至于失控。调试阶段我会把return_agent_routeTrue一直开着等流程稳定后再关掉。2.3 写一个最小的两智能体 demo光说不练意义不大这里先展示一个能完整跑通的最小示例。这个场景很简单主智能体负责判断“查询天气”和“查询时间”两种请求分别交给两个子智能体处理。代码结构就是定义两个工具、两个子智能体、一个主智能体最后调用 run。from smolagents import CodeAgent from deepagents import Agent, ManagedAgent, Tool Tool def get_weather(city: str) - str: 查询指定城市的实时天气。当用户想了解天气情况时使用。 # 这里替换成真实天气 API 调用 return f{city}: 20 度多云 Tool def get_current_time(timezone: str) - str: 查询指定时区的当前时间。当用户询问时间、日期时使用。 from datetime import datetime return datetime.now().astimezone().strftime(%Y-%m-%d %H:%M:%S) weather_agent Agent( nameweather_agent, role天气查询员负责回答所有与天气相关的问题。, tools[get_weather], model_idQwen/Qwen2.5-72B-Instruct, ) time_agent Agent( nametime_agent, role时间查询员负责回答所有与时间、日期相关的问题。, tools[get_current_time], model_idQwen/Qwen2.5-72B-Instruct, ) boss Agent( nameboss_agent, role客服主管负责分析用户问题并分派给对应的子智能体。, tools[], managed_agents[ ManagedAgent(agentweather_agent, nameweather, description查询天气), ManagedAgent(agenttime_agent, nametime, description查询时间), ], model_idQwen/Qwen2.5-72B-Instruct, ) result, route boss.run( 请帮我查一下北京今天的天气顺便告诉我当前时间。, return_agent_routeTrue, ) print(result) print(route)这个例子虽然简单但已经把 deepagents 的核心流程走了一遍boss 收到用户请求后按照子智能体的 description 判断应该委派给谁子智能体用自己的工具完成任务后把结果返回给 bossboss 汇总后给出最终答案。你在运行时会发现两个子任务并不一定是并行执行的框架默认是串行委派这对大多数任务已经足够如果你要真正并行加速需要自己在外层用并发逻辑去驱动这一点我会在第五节聊到。3. task08 实战拆解完整的“收集—分析—报告”流水线3.1 任务需求从一段很模糊的描述开始进入正题。task08 我给自己定的任务是这样给定一组新闻文章 URL自动抓取正文内容提炼每个方案的技术特点最后生成一份对比分析报告。听起来需求很清晰但真实业务里的需求通常只有一句话“你帮我把这几篇关于边缘AI推理成本的文章读一下整理个对比报告给我。”具体怎么拆分、需要哪些工具、最终输出什么格式全要我自己设计。这正是多智能体系统最该发挥作用的地方与其把这一个复杂任务交给单个智能体不如拆成“谁负责读”“谁负责分析”“谁负责汇总”三个角色。每个角色只需要做好一件事模型生成代码的负担小了出错的概率也大幅下降。我在这里定义的目标输出是一份 Markdown 报告包含每个方案的核心理念、关键指标、成本差异外加一张对比表格。3.2 工具层先把你需要的“手”准备好在写任何 Agent 之前我习惯先把工具层准备好。工具是智能体的“手”如果把工具设计得模糊、臃肿后面再怎么调模型都白搭。这个任务里我需要两类能力一类是抓取网页正文另一类是把内容写入本地文件。抓取要用到网络请求和 HTML 解析所以需要提前装好 requests 和 beautifulsoup4。抓取工具要特别注意两点一是只保留正文文本把 script、style、导航、页脚这些噪声统统去掉否则大段 HTML 喂给模型会严重拖慢响应、烧掉上下文窗口二是对返回内容做长度截断我通常截到 6000 字符足够模型提取信息又不会把上下文塞满。下面是我在这个任务里实际使用的工具代码import requests from bs4 import BeautifulSoup Tool def fetch_webpage(url: str) - str: 抓取指定URL的正文内容去除导航、页脚、脚本等无关内容。 适合用于读取新闻文章、博客和技术文档页面。 headers {User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)} try: resp requests.get(url, headersheaders, timeout20) resp.raise_for_status() except Exception as e: return f抓取失败: {e} resp.encoding resp.apparent_encoding soup BeautifulSoup(resp.text, html.parser) for tag in soup([script, style, nav, footer, header]): tag.decompose() text soup.get_text(separator\n, stripTrue) return text[:6000] Tool def write_markdown(filepath: str, content: str) - str: 将Markdown格式的内容写入指定文件。适合在最终报告生成完成后落盘。 with open(filepath, w, encodingutf-8) as f: f.write(content) return f已写入 {filepath}3.3 组装多智能体职责划分是灵魂工具准备好后我开始组装智能体。这一步是整个任务的核心也是 deepagents 最擅长的部分。我把流水线分成三条角色research_agent 负责从 URL 抓取原文做初步的信息保留analysis_agent 负责对原文进行结构化提炼产出对比维度和要点boss 负责把最终报告组装成 Markdown 并写入文件。我在代码里写清了每个 Agent 的角色定位这不只是给人看的模型也会把 role 和工具 docstring 一起放进 system prompt 里。所以角色怎么写非常关键我总结成一句话角色描述要写“这个智能体负责什么、在什么情况下会被调用”而不是写“这是一个很强大的智能体”。research_agent Agent( nameresearch_agent, role资料收集员负责抓取URL对应的网页正文提取原文核心段落保留数据、指标、结论等关键信息。, tools[fetch_webpage], model_idQwen/Qwen2.5-72B-Instruct, ) analysis_agent Agent( nameanalysis_agent, role分析员负责阅读资料提炼每个方案的技术亮点、成本指标和适用场景输出对比要点和表格框架。, tools[], model_idQwen/Qwen2.5-72B-Instruct, ) boss Agent( nameboss_agent, role项目经理负责将整体任务拆解为资料收集、对比分析两个子任务并最终将分析结果整合为Markdown报告。, tools[write_markdown], managed_agents[ ManagedAgent( agentresearch_agent, nameresearcher, description当需要读取URL内容、收集网页资料时使用这个子智能体。, ), ManagedAgent( agentanalysis_agent, nameanalyst, description当需要对资料进行提炼、对比、生成分析结论时使用这个子智能体。, ), ], model_idQwen/Qwen2.5-72B-Instruct, )3.4 跑一次任务并学会读路由日志组装完成后执行阶段其实很简单关键在于怎么判断这次执行到底好不好。我建议第一次运行就把return_agent_routeTrue打开这样 run 返回的不只是最终结果还有一个完整路由记录。执行代码大概是下面这样为了演示我用了 example.com 的占位 URL你替换成真实链接即可。task ( 请阅读 https://example.com/article1 和 https://example.com/article2 两篇文章 对比它们关于边缘AI推理成本的方案差异输出一份带对比表格的Markdown报告 并保存到 report.md。 ) result, route boss.run(task, return_agent_routeTrue) print(result) print(route)运行结束后我通常会先看 result 是否达到了交付标准再看 route 还原整个过程。路由日志大致会记录类似“boss 把‘抓取文章1的正文’派发给 researcherresearcher 完成后把原文摘要返回boss 再派发给 analyst 做对比分析analyst 输出对比要点boss 最后调用 write_markdown 落盘”这样的链路。如果我在 route 里看到某个子智能体从头到尾没有被调用过说明主智能体判断“我自己干也行”这时候你就得反思是子智能体的 description 写得不到位还是主模型太强导致不愿意委派。看到这里你应该能理解为什么我说 deepagents 的“路由可控”对实际项目很重要了。你可以通过日志准确地判断系统有没有按你预期的方式运行而不是盯着一个黑盒猜。这个能力在框架选型的时候几乎被所有人忽视但等到你要排查生产环境问题、要给客户解释“为什么 AI 会这么干”的时候它就成了救命稻草。注意排查路由问题的时候先确认工具是不是只挂在了子智能体上。只要主智能体手里也有同样的工具它就大概率不会走委派路线。4. 高频踩坑记录与排查技巧4.1 子智能体形同虚设主智能体把活全揽了这个坑我踩过很多次也是 deepagents 新手最常见的问题。你会发现在某些任务里不管你怎么设置子智能体主智能体都倾向于自己调工具解决根本不去调用 ManagedAgent。原因通常有三个一是主模型能力太强它觉得没必要把任务分出去二是子智能体的 description 写得太模糊模型不知道在什么场景下该用它三是工具直接暴露在了主智能体上它当然就近使用。解决办法也很直接第一把专用工具只挂在子智能体上主智能体不要重复持有第二description 里明确写“当……时使用”甚至写反例“不要用它来做……”第三如果你希望某个子智能体必须在某类任务中被调用可以把流程拆成两条 run 串行执行第一条强制让子智能体产出中间结果第二条再由主智能体接手。我在 task08 里就是让 research_agent 先跑完并输出摘要再交给 analysis_agent这样职责不会被绕过。4.2 上下文越积越长子智能体来回传递全文另一个高频问题是上下文膨胀。子智能体完成任务后通常会通过 final answer 把结果传回给主智能体如果子智能体把抓取到的全文原封不动返回几个子任务一叠加上下文很快就被塞满了。模型在长上下文下不仅响应慢而且容易丢掉前面的信息输出质量明显下降。我常用的对策有三个一是抓取工具返回前就做截断只保留前 40006000 字符二是让子智能体在返回前先把内容“压缩”成结构化 summary比如每条 100200 字的关键信息点三是给子智能体的 prompt 里明确写“只返回提炼结果不要返回原文”。这个习惯养成之后你会发现整个流水线的稳定性和速度都上了一个台阶。4.3 网络工具不稳定抓不到内容别急着怪模型在真实场景里很大比例的失败并不来自智能体逻辑而是来自工具本身。网页抓取最容易翻车目标网站可能有反爬机制、可能要求特定 UA、可能是编码不标准导致的乱码也可能是页面内容是 JS 动态渲染的requests 根本拿不到。遇到抓取结果为空的时候先别急着调 prompt先在工具层做一层兜底。我的做法是给 fetch 工具加上自定义 User-Agent并用resp.apparent_encoding来规避编码问题如果目标页面是动态渲染的我干脆换一个思路让智能体优先用搜索工具配合摘要获取信息而不是死磕一个 URL。工具层稳定了智能体的成功率才能稳定这个优先级大家一定不要搞反。4.4 一个速查表留给后面踩坑的你自己为了让这篇文章更有实用价值我把这段时间遇到的高频问题整理成一张速查表你遇到类似现象时可以直接对照排查现象可能原因处理建议子智能体从不被调用description 模糊、主智能体持有工具、主模型过强细化 description、工具只挂在子智能体、拆成串行 run任务在某个步骤反复循环目标不清晰、模型陷入自问自答明确子任务边界、调低 max_operations 强制中断、换更强的模型抓取到的内容为空或乱码反爬、编码、动态渲染加 UA、设置 apparent_encoding、换搜索工具兜底上下文迅速膨胀子智能体返回原文、工具返回过长工具层截断、要求子智能体返回摘要、减少中转结果格式不符合预期prompt 没有给出输出格式约束在任务描述里给出明确的 Markdown 或 JSON 结构示例调用成本飙升max_operations 设太大、模型反复试错设定合理上限、先在小样本上调通流程这张表不一定覆盖所有情况但排查思路是通用的先看工具再看路由最后才看 prompt 和模型。如果你把顺序搞反了大概率会在模型 prompt 上调半天也找不到真正的问题。5. 进阶实践把 deepagents 从“能跑”用到“好用”5.1 工具描述就是智能体的“说明书”值得花时间打磨很多人在定义工具时只写一句“查询天气”然后就指望模型会用。但真实经验是工具的 docstring 决定了智能体的工具选择准确率。我在 deepagents 项目里对 docstring 的要求是第一句说清楚工具做什么第二句写清楚“什么时候使用”第三句写清楚“什么时候不要用”。例如 fetch_webpage 的 docstring我专门加了“适合用于读取新闻文章、博客和技术文档页面”这样模型就不会拿它去查数据库。你想想看模型选择工具的本质是文本匹配工具描述写得越像用户任务的投影被正确选中的概率就越高。这个道理和搜索引擎做 SEO 是一样的只不过你的关键词是“任务意图”。我见过太多人把工具描述写成给同事看的接口注释把“docstring”当成了“开发文档”其实它更应该是写给学生看的“使用手册”。工具 docstring 写得越像“任务意图的投影”模型选对的概率越高。这个经验值多少钱都不换。5.2 并行加速串行委派不够时怎么办deepagents 默认的任务委派是串行的boss 一次只能把任务交给一个子智能体。如果你的流程里多个子任务之间没有依赖关系比如要同时读五篇文章串行就会显得慢。我这里分享一个我实际在用的并行模式在主智能体外面包一层 Python 并发逻辑把“文章清单”拆成多份用线程池同时跑多个 boss.run()最后再汇总结果。from concurrent.futures import ThreadPoolExecutor def process_one(url): task f阅读 {url}提炼关键信息为结构化要点。 res, route boss.run(task, return_agent_routeFalse) return res urls [https://example.com/1, https://example.com/2, https://example.com/3] with ThreadPoolExecutor(max_workers3) as pool: results list(pool.map(process_one, urls))这种做法的前提是你的模型接口支持并发请求并且你不会触发限流。线程数建议控制在 35不要盲目加大否则 API 层会替你做流控反而各种报错。并行之后整个流水线的耗时能压到原来的三分之一左右对批量任务效果非常明显。5.3 我最近在试的新方向你可以直接抄作业深挖一段时间后我的体会是deepagents 的价值不在“多智能体”本身而在于它把多智能体协作变成了一个可以工程化、可调试、可替换模块的体系。最近我把它接到了两个新场景里效果不错这里分享给你。第一个是“RAG 查询 报告生成”的组合。我把一个子智能体做成纯查询者只负责从向量数据库取文档另一个子智能体做成纯写作者负责把检索结果改写成特定风格的报告。这样知识库的增删改只影响查询者报告模板的调整只影响写作者两边解耦得很干净。第二个是“定时触发 邮件通知”的自动化boss 负责每天读取业务数据快照调用分析子智能体产出日报再写回数据库或发送到内部群聊。这套东西搭建起来很快稳定运行了几周中间几乎没有因为智能体之间的协作问题需要紧急干预。如果你也想做一个类似的多智能体系统我的建议是先别一上来就画一张包含十几个智能体的大图。从两个子智能体起步跑通主流程再一点点加角色。每加一个角色都要问自己一个问题这个角色到底带来了什么新的能力如果它只是在重复主智能体已有的能力那就砍掉。毕竟多智能体系统的复杂度是乘法增长的少而精永远比多而杂更可控。最后分享一个小技巧作为收尾我在每次给主智能体加新子智能体时都会跑一条专门设计的路由测试用例只让它输出“选择哪个子智能体、为什么选择它”的推理过程而不是直接跑全流程。这个测试一般不到一分钟却能提前暴露大量委派错误。用这种方式迭代你的多智能体系统会越用越顺而不是越用越乱。
