开源社区 5.9万 Star 的多智能体框架我花了三个晚上跑通了官方 Demo又用两天把文档里的核心概念捋了一遍。这篇教程不打算重复 README 里已经写得很清楚的内容而是想把手把手跑通的过程、最容易卡住的地方、以及框架内部那些官方文档没明说但实际写代码时必须知道的细节一次性讲透。适合刚接触多智能体开发、想快速上手但又被各种抽象术语劝退的朋友也适合已经在用其他 Agent 框架、想横向对比选型的开发者。1. 多智能体框架到底解决了什么问题先聊一个很多人没想清楚的问题既然 LangChain、LlamaIndex 这些单智能体工具链已经很成熟了为什么还要单独搞一个多智能体框架我个人的理解是单智能体模式的瓶颈不在能不能干活而在一个大脑忙不过来。1.1 单智能体模式的三个痛点第一个痛点是上下文窗口的物理上限。OpenAI 的 GPT-4 系列上下文做得很长但实际用起来几十万 token 的窗口塞满了历史对话和中间结果模型处理速度会肉眼可见地下降而且关键信息容易被淹没。你让一个智能体既读文档、又查数据库、还要调用外部 API最后再把结果汇总成报告它很容易捡了芝麻丢西瓜。第二个痛点是工具冲突。当智能体手里同时握着检索器、计算器、代码解释器、浏览器工具时它经常不知道该先调哪个。我见过一个案例智能体为了让计算结果更精确连续调了五次计算器把同样的函数执行了五遍浪费大量 token 和时间。第三个痛点是职责不分。现实中的团队分工是产品经理负责需求拆解、算法工程师负责模型调优、测试工程师负责验证。单智能体把这些角色全压在一个模型上既当裁判又当运动员很难保证每个环节的质量。提示多智能体框架的核心思路就是分而治之——让每个智能体只做一件事再用一个调度机制把结果串起来。这和写代码时拆模块、拆服务是同一个哲学。1.2 多智能体框架的典型工作模式业内常见的模式有三种我直接举生活化的例子流水线模式就像工厂流水线A 智能体负责原材料质检B 智能体负责加工C 智能体负责包装。代表框架有 Microsoft 的 AutoGen 里的两智能体对话模式。编排模式相当于项目经理带一帮专家项目经理不干活只负责拆任务、派活、收集结果。比如 CrewAI 里的 Process 流程以及今天要讲的这个框架里的 Plan-and-Execute 模式。辩论模式多个智能体扮演不同立场互相提问、反驳、收敛最后得出一个综合结论。像 LangGraph 里可以实现的多角色辩论场景。这个 5.9 万 Star 的框架属于比较全面的类型三种模式都支持但默认上手的姿势更接近编排模式。这也是为什么它被很多企业和高校拿来当多智能体教学的首选框架——概念清楚、扩展性好社区资源也多。1.3 为什么偏偏它拿了 5.9 万 StarStar 数量说明不了绝对实力但能反映社区认可度。这个框架火起来有几点实实在在的原因API 设计非常贴近直觉。不需要学一堆新概念Agent、Task、Process三个核心类就能跑通一个完整的多智能体应用。中文社区支持好。官方文档有中文版Discord 和 GitHub Discussions 里经常有中文回答对国内开发者非常友好。底层兼容性强。不管是 OpenAI、Azure OpenAI还是本地跑的 Ollama都能通过统一的模型接口接入不用改业务代码。自带可视化监控。可以在网页上实时看到每个智能体在做什么、当前走到了哪一步、有没有报错排查问题非常直观。所以说选它来写这篇教程不只是因为它 Star 高更因为它最容易让新手在最短时间内看到效果。2. 上手前必须搞懂的四个核心理念直接装依赖、跑代码其实很快但如果不理解框架的抽象模型后面改需求一定会绕弯路。我建议花十五分钟把这一节看完成本很低收益很大。2.1 Agent不是一个人而是一段带工具的代码很多新手以为 Agent 就是一个 AI 助手其实在这个框架里Agent 更像是一个配置好的处理单元。它声明了自己的角色Role、目标Goal、可以使用的工具Tools、以及背后的语言模型LLM。比如一个代码审查员 Agent可以配成角色资深代码审查员目标找出代码中的潜在风险和不良实践工具GitHub 工具、代码静态分析工具模型gpt-4o 或 claude-sonnet关键点在于Agent 之间不能直接互相调用对方的函数只能通过任务结果传递信息。这个设计避免了智能体之间过度耦合让整个系统像微服务一样可替换、可测试。2.2 Task明确输入输出和边界Task 是分配给某个 Agent 的具体工作单元。它必须包含描述Description、指定的执行者Agent、期望的输出格式Expected Output。好的 Task 描述要像给下属布置工作一样清晰不能说处理一下数据而应该说将调研报告中的用户痛点部分提取出来整理成 5 条要点每条不超过 50 字。这里有三个容易踩的坑没有指明输出格式。框架会根据预期输出做后处理如果你不写清楚它可能给你一段散文而不是结构化 JSON。任务边界模糊。一个 Task 里塞了太多子目标Agent 会迷失方向。没有设置上下文依赖。有些 Task 需要前一个 Task 的结果必须用context参数显式声明依赖。2.3 Process决定智能体怎么协作这是框架的核心配置项。它有三个取值sequential按顺序执行前一个任务的输出作为后一个任务的上下文。适合流程固定的场景比如写大纲 - 扩写章节 - 润色排版。hierarchical由一个管理 Agent 动态分配任务。管理 Agent 会先拆解任务再分给合适的执行 Agent最后汇总结果。适合需求不明确、需要灵活调整的场景。consensus多个 Agent 并行处理相同任务最后投票或评分选出最佳结果。适合需要质量保障的场景比如文案生成、方案评审。默认情况下很多人用sequential就能跑通但真实项目里hierarchical更常见因为它能发挥多智能体的真正价值——让一个 LLM 去做规划其他 LLMs 去做执行。2.4 工具与协作Agent 手里的武器库框架支持通过tool装饰器把任意 Python 函数变成智能体可以调用的工具。你可以写一个def get_weather(city: str) - str函数加上装饰器和描述框架就会在 Agent 需要时自动把函数信息注入给模型模型决定调用后框架会执行并把结果返回给模型。这就引出了多智能体协作的一个关键工具不是给框架用的是给 Agent 用的。每个 Agent 都有自己独立的工具列表你在定义 Agent 时传入的tools参数就是一个白名单。如果某个 Agent 不需要访问外部网络就不要给它配网络工具这样可以限制幻觉和误操作。注意工具描述越详细模型越知道什么时候该用它。例如get_weather的描述可以写成根据城市名称查询当前实时天气城市名必须是中文如北京这样模型就不会把英文城市名传进来。3. 中文环境下的安装与环境配置理论部分聊完开始动手。先说明我的实验环境方便你对照Windows 11 Python 3.10.11 VS Code全程没有用 Docker。如果你用 Mac 或 Linux命令大同小异。3.1 安装过程与版本锁定我建议新建一个干净的虚拟环境避免和现有项目的中文依赖冲突。终端执行python -m venv multiagent_env source multiagent_env/bin/activate # Windows 上是 multiagent_env\Scripts\activate pip install --upgrade pip然后安装框架本体注意指定版本。以 0.8.x 版本为例写文章时最新稳定版pip install framework-name0.8.2如果你已经装过旧版本最好先卸载再装因为 0.7 到 0.8 之间有些 API 改了名字。装完验证一下python -c import framework_name; print(framework_name.__version__)能正常打印版本号说明装好了。另外你还需要准备一个 LLM API 的密钥。这个框架支持通过环境变量或者.env文件读取。我习惯用.env文件把敏感信息隔离在代码之外OPENAI_API_KEY你的密钥 OPENAI_API_BASEhttps://api.openai.com/v1如果用的是国内可直连的兼容接口比如某些中转服务或本地部署的模型服务就在OPENAI_API_BASE里填对应的 Base URL 就行。这个框架走的是统一 OpenAI SDK 风格接口所以大部分兼容服务都能直接替换。3.2 配置模型的两种方式对比框架支持两种配置模型的方式全局统一配置在创建 Agent 时不传llm参数框架会自动读取环境变量里的默认模型。适合所有 Agent 都用同一个模型的场景。每个 Agent 单独配置创建 Agent 时显式传入llm_config每个智能体可以不同模型。比如管理 Agent 用 gpt-4o 保证规划能力执行 Agent 用 gpt-4o-mini 省成本。我强烈建议用第二种方式理由很实际省钱规划类任务不复杂不需要强模型执行类任务如果涉及长文档分析用强模型更稳妥。可观测当某个 Agent 输出质量不高时你一眼就能看出是哪个模型的问题方便调参。from framework_name import Agent, Task, Process, Crew manager Agent( role项目经理, goal拆解用户需求分配任务汇总最终报告, backstory你是经验丰富的IT项目经理擅长将复杂问题拆解为可执行的子任务, llmgpt-4o ) writer Agent( role技术文档撰写员, goal根据材料撰写清晰易懂的中文技术博客, backstory你是一名技术博主写作风格轻松务实擅长用类比解释复杂概念, llmgpt-4o-mini )注意backstory这个参数它会在系统提示词里作为角色背景信息注入对模型输出风格影响很大。建议写得具体一些越具体越不容易跑偏。4. 一个完整的中文多智能体案例从需求到产出现在进入最关键的实操环节。我会带你把一个中文技术文章选题策划 文章大纲生成的任务跑通。这个案例覆盖了多智能体最核心的流程规划、执行、整合。4.1 案例需求拆解假设我们要做一个智慧农业设备相关的内容营销任务。如果只用一个 Agent让它写一篇文章常见问题是文章结构空洞、缺乏专业细节。用多智能体就可以这样拆Agent A市场研究员上网搜集 2025 年智慧农业设备的热门趋势输出 5 条关键趋势每条附带来源。Agent B技术专家基于市场研究员找到的趋势分析技术难点和解决方案输出技术要点。Agent C内容主编综合 A 和 B 的输出设计文章大纲和标题输出一份包含 3 个备选标题和 5 个章节的大纲。这个流程是一个典型的hierarchical过程需要管理 Agent 统筹。但为了让新手先理解我会用sequential实现效果相同、逻辑更简单。4.2 编写 Agent 和 Task第一步定义三个 Agent。注意两个细节一是tools参数搜索类任务给 Agent A 配浏览器搜索工具二是allow_delegation设置为了简单先都设为False。from framework_name import Agent, Task, Crew, Process researcher Agent( role智慧农业市场研究员, goal研究智慧农业设备的最新趋势和市场规模, backstory你是农业科技领域的分析师擅长搜索行业报告洞察技术发展趋势。, tools[search_tool, web_scrape_tool], verboseTrue, allow_delegationFalse ) tech_expert Agent( role智慧农业技术专家, goal解析智慧农业设备的关键技术难点及解决路径, backstory你是农业物联网方向的资深工程师熟悉传感器、无人机和智能灌溉系统。, verboseTrue, allow_delegationFalse ) editor Agent( role科技内容主编, goal输出结构清晰的智慧农业设备文章大纲, backstory你是科技媒体主编擅长把技术内容转化为读者爱看的故事。, verboseTrue, allow_delegationFalse )第二步定义三个任务并指定输出格式。这里我要求输出 JSON 数组方便后处理task1 Task( description搜集2025年智慧农业设备领域的5个热门趋势包括市场规模、代表公司、技术关键词。 结果必须用JSON数组输出每一项包含trend、evidence、source_url三个字段。, expected_output包含5条趋势的JSON数组, agentresearcher ) task2 Task( description基于市场趋势分析对应的核心技术难点如传感器功耗、通信距离、数据分析精度等 并给出可能的解决路径。用JSON数组输出每项包含tech_challenge、solution、related_trend三个字段。, expected_output包含5-8个技术难点的JSON数组, agenttech_expert, context[task1] ) task3 Task( description综合前两轮结果为面向行业决策者的智慧农业设备文章设计大纲。 输出必须为JSON对象包含three_titles和outline两个字段outline是包含5个章节的数组。, expected_output一个JSON对象包含标题和大纲, agenteditor, context[task1, task2] )注意task2和task3里的context参数它是一个任务列表表示执行此任务时把列表里任务的结果作为上下文传给 Agent。这个参数特别重要很多新手忘了写结果 Agent 在真空中自由发挥。4.3 组装 Crew 并运行最后一步把 Agent 和 Task 组装到一个 Crew 里设置流程类型crew Crew( agents[researcher, tech_expert, editor], tasks[task1, task2, task3], processProcess.sequential, verboseTrue ) result crew.kickoff(inputs{topic: 智慧农业设备}) print(result)这里的inputs参数很有意思它是一个字典用来给任务描述里的变量占位符赋值。你在description里可以写关于{topic}的调研运行时框架会把inputs里的值填充进去这样同一个 Task 模板就能复用到不同主题上非常灵活。运行之后控制台会打印每个 Agent 的思考过程和输出结果。第一次跑大概需要一两分钟因为要等好几个 LLM 调用。看到最终 result 是一个 JSON 字符串就说明流程通了。4.4 结果验证与格式修正如果你发现输出的 JSON 不合法比如多了一个逗号或者字段名变了不要直接改代码靠运气。我推荐一个技巧在 Task 的expected_output里写清楚必须是严格的JSON不要markdown代码块标记同时在 Agent 的backstory里加一句你擅长输出结构化的JSON数据不会输出任何解释文字。模型对提示词里的必须不要这类强约束非常敏感这样写能大幅提高格式正确率。如果还是不行可以在Crew里配置一个输出 JSON 的output_pydantic对象让框架用 Pydantic 校验强制修正。5. 让框架真正跑起来的进阶技巧把上面的基础案例跑通之后很多人会觉得自己学会了。但实际做项目时你很快会遇到能跑但不好用的问题。下面这些技巧是我反复试错后总结出来的每个都能省下你半天调试时间。5.1 管理好上下文别让无关信息干扰只负责某个角色的 Agent在hierarchical模式下管理 Agent 会把一个大任务拆成多个子任务每个子任务都会携带一部分上下文。问题就出在这里如果管理 Agent 把全部资料都塞给执行 Agent其他 Agent 会被大量无关信息干扰输出质量反而变差。解决办法是手动控制Task的context只放必要的上游任务。比如在上面的案例里技术专家只需要看市场研究员的结果不需要看主编的后台设定。你可以在创建 Task 时通过contextNone来避免继承全局上下文。但要注意在某些框架版本里层级流程会自动拼接上下文所以你需要查看当前版本源码里的_aggregate_tasks逻辑确认哪些上下文会被传递。实操心得我一般会在每个 Task 的description第一句写明你只需要关心以下输入中的XXX部分忽略其他内容这是最轻量有效的上下文隔离方案。5.2 工具调用的失败重试与降级真实世界的工具调用不是 100% 成功。比如网络请求超时、返回 403、或者搜索结果为空。默认情况下Agent 会因为工具失败而抛出异常导致整个流程中断。解决方法有两种在函数内部捕获所有异常返回一个兜底字符串tool(safe_search) def safe_search(query: str) - str: try: return search_engine.search(query) except Exception as e: return 搜索失败请尝试使用通用知识回答。在 Agent 配置里设置max_iter和max_retry让框架在工具调用失败后自动重试。不过重试会消耗更多 token建议对不稳定的工具只重试一次。5.3 处理中文输入输出的常见坑中文环境有几个特别容易出现的问题我在这里集中说明编码问题Windows 控制台默认编码可能是 GBK运行框架时如果打印中文报错先执行chcp 65001换到 UTF-8。token 计算偏差中文文本的 token 密度比英文高同样的模型上下文限制中文输入会更早触顶。所以任务描述和输出长度要适当压缩。prompt 里的中英文标点有些模型会把和,混淆如果你把中文逗号写进了 JSON 里严格模式下会解析失败。我习惯在expected_output里提醒不要使用全角标点。模型对中文角色的理解backstory越长角色感越强输出语气越稳定。如果你发现 Agent 说话一股百科味把backstory改成朋友聊天风格效果立竿见影。5.4 用回调机制做流程监控框架提供了回调函数可以在每个 Task 开始、结束时触发。我用这个功能做团队协作时的日志记录def task_callback(task): print(f任务[{task.description[:30]}...]完成) crew Crew(..., callbacks[task_callback])如果是写自动化脚本我会把回调里的事件写入本地日志文件方便后续审计。尤其当多智能体应用跑在服务器上时实时监控每个 Agent 的决策过程对排查问题非常有价值。6. 常见问题速查表这一节是我把社区里大家问得最多的十几个问题整理成了速查表看到对应的报错直接对号入座。现象可能原因解决办法安装后 import 失败版本冲突或装了不同主版本卸载重装指定版本 0.8.x运行时提示找不到模型接口.env文件没被加载检查.env是否在项目根目录并在代码里显式load_dotenv()Agent 互相之间不传结果Task的context参数忘了设置给后置任务加上context[前置任务]输出的 JSON 有多余文字模型没被严格约束在expected_output里写严格JSON不要markdown工具调用总是超时网络代理或对方接口慢在 tool 函数里设置timeout参数并加重试管理 Agent 分配任务混乱角色描述不够清晰细化goal和backstory明确职责边界上下文太长导致内存溢出单个任务塞了太多历史结果精简 Task 描述只保留必要上下文中文输出乱码控制台编码问题换 UTF-8 终端或sys.stdout.reconfigure(encodingutf-8)多次运行结果差异很大LLM 的 temperature 设置过高在 agent 的llm_config里设置temperature0.2想用本地模型但报错本地模型命名不兼容使用 Ollama 等 OpenAI 兼容层确认模型名正确6.1 一个必踩的坑verbose 模式与密钥泄露你必须注意verboseTrue时框架会把完整的提示词和工具调用日志打印出来。如果你的 prompt 里包含了数据库连接字符串、API 密钥或者其他敏感信息这些信息会直接出现在终端或日志文件里。我在早期开发时就踩过这个坑差点把公司内部配置泄露到共享日志平台。建议的做法是生产环境一律verboseFalse。日志记录前使用正则把密钥、密码替换成***。若需要调试单独在本地开一个环境不要在生产环境开启详细日志。6.2 关于 token 成本控制的一些想法多智能体框架最大的隐性成本是 token 消耗它不像单智能体那样一次对话一次计费而是每个 Agent 每秒都在思考。一个简单的三步流程可能消耗你单次调用的 10 倍 token。控制成本有几个实际手段使用小型模型做执行类Agent。比如gpt-4o-mini或deepseek-chat规划类任务单独用强模型。限制 Agent 的最大迭代次数。在配置里把max_iter设为 3防止 Agent 陷入无意义的自我反思循环。复用历史结果。如果两个任务基于同一个上游数据就别让两个 Agent 分别去检索原始数据而是把上游结果作为上下文传给它们。拆分子任务时不要过度。三个智能体能解决的问题就不要拆成七个。6.3 从顺序流程到层级流程的迁移心得当你跑通sequential后强烈建议再花半小时试试hierarchical。因为真实项目里任务的依赖关系往往是动态的——管理 Agent 需要根据中间结果调整后续步骤。切换到hierarchical只需要改两处Crew的processProcess.hierarchical。指定一个manager_agent或者让框架自动创建默认管理 Agent。但要注意层级流程下Task里的agent字段可以留空由管理 Agent 动态指派。这意味着你之前写的指定 Agent逻辑要改掉否则管理 Agent 会直接使用你指定的 Agent从而失去调度意义。我在迁移时遇到的另一个问题是管理 Agent 可能把同一个任务分配给多个 Agent导致结果重复。解决办法是在 Task 的description里加一句这个任务只能由一个Agent执行如果已经有人执行过了不要重复分配。7. 实战扩展让多智能体框架接入本地模型很多同学因为 API 成本问题想用本地模型跑多智能体。这个需求完全可以满足但要区分两种本地本地通过 Ollama 跑开源模型这需要你的电脑配置能跑得动 7B 或更小参数量的模型效果上适合验证流程不适合复杂业务。本地访问公司内网部署的模型服务如果服务端兼容 OpenAI 接口同样可以无缝接入。以 Ollama 为例先安装并拉取模型ollama pull qwen2.5:7b然后启动一个 OpenAI 兼容服务ollama serve此时 Ollama 默认在http://localhost:11434/v1开放了一个兼容 OpenAI 的接口。在框架里配置from framework_name import LLMConfig local_llm LLMConfig( modelqwen2.5:7b, base_urlhttp://localhost:11434/v1, api_keyollama # 随意填写但必须存在 )然后把local_llm传给 Agent。实测下来7B 模型在简单任务上比如格式转换、摘要能跑通但在需要多步推理和工具调用的任务上效果明显弱于 API 版本。如果你追求稳定的输出质量建议还是用商业模型如果只是学习和流程验证本地模型完全够用。还有一个细节本地模型对中文的支持差异很大Qwen 系列在中文上表现不错Llama 3.1 系列则需要更强的 prompt 引导。你可以通过修改backstory里的语言风格来引导输出比如请用口语化中文回答避免书面语。8. 从跑通 Demo 到落地项目我的几点经验最后把这段时间折腾这个框架的体会做个分享不是总结就是一些踩坑后的直觉。先用起来再理解原理。其实这个框架的很多概念光看文档很难有体感。比如hierarchical流程里管理 Agent 的调度策略文档里只有一张流程图真跑一遍看它怎么把任务 A 拆成 B、C又怎么处理 D 报错你才明白为什么要这样设计。第二个体会是多智能体不是银弹。如果你的任务本身很简单比如把一段文本翻译成英文单智能体足够硬套多智能体只会增加延迟和成本。多智能体真正发光发热的场景是那些没有标准答案、需要多步骤判断、不同环节需要不同知识背景的任务比如行业调研、复杂报告生成、跨领域知识问答。第三个体会是对 Agent 的 prompt 要像对人一样尊重。这不是玄学而是因为 LLM 对角色一致性很敏感。你给一个 Agent 设置的身份是严谨的财务分析师它输出的语气和决策逻辑就是会跟创意文案不一样。多智能体协作时角色之间的信息传递也处处体现这种一致性。所以花时间打磨每个 Agent 的role、goal、backstory长期来看收益最大。第四个经验是关于测试的。多智能体应用比传统应用更难测因为同样的输入可能产生不同的输出。我在自己项目里建立了一套黄金答案回归测试每次修改 Agent 配置后跑一批固定问题把关键字段的通过率记录下来。这样能快速判断修改是变好还是变差。最后讲个小技巧如果你想让 Agent 输出更像真人可以在backstory里给它写一段人格化经历。比如让市场研究员的背景是你曾经在农业公司做过三年产品经理亲眼看过传感器在田间的部署问题输出立刻会多出很多实战细节比干巴巴的设定强得多。这个技巧在生成内容类任务里特别好用建议你试试。多智能体框架的上手曲线比想象中平滑但天花板也比你想象中高。希望这篇教程能帮你跨过第一道门槛接下来你踩的坑、总结出的调参经验都会成为这个领域最有价值的积累。