在 AI 应用从“单模型对话框”走向“自动化业务流程”的今天只靠一个 Prompt 调大模型已经很难满足真实项目的需求。尤其在内容生产、数据分析、客户运营这类场景中往往需要多个具备不同职责的智能体配合一个负责梳理需求一个负责查询知识库一个负责撰写结果一个负责检查质量。如果这些步骤全部塞进同一个 Prompt不仅逻辑混乱而且后续维护成本极高。这也是 CrewAI 这类多智能体编排框架越来越受关注的原因。本文将围绕 CrewAI 多智能体系统开发展开重点拆解智能体定义、任务编排和自动化工作流构建。文章会从核心概念讲起再逐步落到环境和代码最后给出一个可直接扩展的实战案例以及常见的排查思路。无论你是刚接触 AI 智能体开发的新手还是已经在用 LangChain 想了解多智能体编排的开发者都能在这篇文章里找到可以落地的内容。1. 什么是 CrewAI为什么要做多智能体编排1.1 从“单个大模型”到“智能体团队”过去我们在开发 AI 应用时通常是一个 Prompt 把需求描述清楚然后让大模型直接输出结果。这种模式在简单问答、文本改写、摘要生成等场景下完全够用但一旦业务流程变复杂问题就会暴露出来单个 Prompt 过长模型容易丢失指令输出不稳定多个职责混在一起比如“既要检索又要总结还要判断情感”模型经常顾此失彼无法复用角色能力写好的“数据分析师”提示词很难拆开独立维护无法对中间过程做精细控制例如先审核数据再生成文章。多智能体系统的思路是把复杂的业务目标拆解成多个子任务由不同的 AI 智能体分别承担。每个智能体有独立的角色、目标、背景故事和工具多个智能体之间再通过任务依赖关系协作最终像一个“虚拟团队”一样完成整个流程。1.2 CrewAI 的定位CrewAI 是一个基于 Python 的多智能体编排框架你可以把它理解成“智能体团队的操作系统”。它不关心底层具体接入了哪个大模型而是提供了一套标准化的抽象Agent定义智能体的角色、行为方式、可用工具Task定义需要完成的具体任务Crew把智能体和任务组合起来并控制协作的方式Process任务执行流程支持顺序执行、分层执行等Tool智能体可以调用的外部能力例如搜索、计算、数据库查询。这种设计带来的直接好处是你可以像搭积木一样构建 AI 应用。业务变化时只需要调整任务链或替换某个智能体不需要重写整套流程。1.3 常见应用场景从目前社区的实践来看CrewAI 最适合以下几类场景内容自动化生产策划编辑智能体、资料检索智能体、文案撰写智能体、校对审核智能体协作完成一篇文章数据分析报告生成数据查询智能体负责取数数据分析师智能体负责洞察报告撰写智能体负责输出结论营销活动支持市场调研智能体收集信息策略智能体设计活动方案文案智能体生成各渠道物料研发辅助需求分析智能体梳理需求代码生成智能体编写代码代码审查智能体检查质量客户运营客服智能体先响应质检智能体再检查工单分类智能体负责后续流转。在 2025 年 AI 智能体开发人才需求快速增长的背景下掌握智能体定义和任务编排能力已经是从事 AI 应用开发非常重要的基本功。而 CrewAI 正是这个方向上手曲线相对平滑的框架之一。2. 环境准备安装 CrewAI 与项目结构设计2.1 运行环境要求CrewAI 本质上是一个 Python 包安装方式非常简单。本文示例主要使用 CrewAI 的常规用法不针对任何特定版本编写代码。为了减少兼容问题建议读者保持 Python 3.10 及以上版本并先创建独立的虚拟环境。# 创建虚拟环境 python -m venv crewai-env # 激活虚拟环境 # Windows crewai-env\Scripts\activate # macOS / Linux source crewai-env/bin/activate安装 CrewAI 主库pip install crewai如果你需要使用工具集例如让智能体访问搜索引擎或读取网站内容可以一并安装pip install crewai[tools]安装完成之后可以用下面的命令验证版本python -c import crewai; print(crewai.__version__)这里需要说明一点CrewAI 的版本迭代比较快不同版本之间 API 可能有小幅度调整。如果你安装的是较新版本运行示例时如果遇到属性名变化以官方文档对应版本为准。2.2 模型接入说明CrewAI 本身不提供大模型能力它默认会读取环境变量中的模型配置。最常用的方式是接入 OpenAI 兼容接口。为了安全建议把密钥写入本地.env文件不要硬编码在代码中。pip install python-dotenv在项目根目录创建.env文件OPENAI_API_KEY你的密钥 OPENAI_API_BASE你的模型服务地址 OPENAI_MODEL_NAMEgpt-4o-mini如果你使用的是国内大模型服务或本地部署模型只需要把OPENAI_API_BASE和OPENAI_MODEL_NAME改成自己服务的对应值。CrewAI 底层的langchain生态已经兼容了大量 OpenAI 协议接口。2.3 示例项目结构为了便于后续维护建议按下面的结构组织代码crewai_demo/ ├── .env ├── requirements.txt ├── main.py # 入口文件负责组装并运行 Crew └── agents.py # 定义智能体在一个人工智能体项目中这种拆分的好处非常明显agents.py专注智能体定义任务变化时不需要反复修改这里的代码main.py专注流程编排负责把不同智能体与任务串联起来。接下来我们按照实战路径一步步实现。3. 核心概念拆解Agent、Task、Crew、Process3.1 Agent智能体的“人设”在 CrewAI 中Agent是最基础的执行单元。它不只是一个大模型实例还包含角色设定、行为约束、可调用工具和委托能力。先看一个最简单的智能体定义from crewai import Agent researcher Agent( role高级技术调研员, goal围绕指定主题收集最新、准确的技术资料, backstory你有超过 10 年的技术研究经验擅长从海量信息中筛选出高质量、可验证的内容。, verboseTrue, allow_delegationFalse )这里的关键参数含义如下role智能体的角色名用于让模型理解自己当前的身份goal智能体的总目标所有任务上下文都会结合这个目标backstory角色背景故事用于增强大模型对场景的理解让输出更稳定verbose是否输出执行过程的中间日志调试时建议开启allow_delegation是否允许该智能体把子任务委托给其他智能体。在实际开发中role、goal、backstory描述得越具体最终输出质量通常越高。因为大模型需要足够清晰的“上下文锚点”来保持一致的行为模式模糊的人设会导致每一步输出都不够稳定。3.2 Task智能体的“待办事项”Task描述了一个具体的执行单元包括任务说明、期望输出、负责执行的智能体以及可选工具。from crewai import Task research_task Task( description调研 AI Agent 在 2025 年的发展趋势整理出 5 个关键方向。, expected_output一份包含 5 个关键方向的列表每个方向包含简短说明和背景依据。, agentresearcher )expected_output是容易被忽视但非常重要的参数。它告诉大模型“什么样才算做完”能够显著减少输出跑偏的问题。多智能体场景下前一个任务的输出就是后一个任务的输入如果输出格式不明确下游任务质量就会受到直接影响。3.3 Crew把人和事组织起来Crew在整个框架中的作用相当于“调度中心”。它负责把 Agent 和 Task 组合起来并决定任务执行方式。from crewai import Crew research_crew Crew( agents[researcher], tasks[research_task], verboseTrue )当调用kickoff()时Crew 会按照编排好的方式把任务分配给对应智能体执行并收集结果result research_crew.kickoff(inputs{topic: AI Agent 发展趋势}) print(result)inputs参数可以用来向任务描述中动态注入变量。例如描述中写了{topic}运行时就可以通过inputs{topic: 实际主题}替换。这种机制让任务模板可复用也是构建通用工作流的基础。3.4 Process流程的编排方式Process是 CrewAI 中控制任务顺序的一组枚举值。常见的包括Process.sequential顺序执行一个任务完成后再执行下一个任务Process.hierarchical分层执行由 Manager Agent 负责规划和委派任务。顺序执行最容易理解from crewai import Process crew Crew( agents[agent_a, agent_b], tasks[task_one, task_two], processProcess.sequential )分层执行则适合任务依赖复杂、需要动态规划的场景。使用时通常需要设置manager_llm或提供manager_agentcrew Crew( agents[agent_a, agent_b], tasks[task_one, task_two], processProcess.hierarchical, manager_llmgpt-4o-mini )在分层模式下Manager 会先分析任务列表再决定哪个智能体在什么时间执行什么任务。这种机制更接近真实团队的管理模式但也会增加 Token 消耗因此项目早期建议先从顺序执行开始。3.5 Tool智能体的“外部能力”很多时候智能体不能只靠模型内部知识完成工作需要访问外部信息或执行计算。CrewAI 的Tool封装了这类能力可以理解为大模型的“手和脚”。CrewAI Tools 提供了搜索、网页抓取、文件读写等常用工具from crewai_tools import SerperDevTool search_tool SerperDevTool()你也可以自己定义一个简单的函数工具from crewai_tools import tool tool(计算器) def calculator(expression: str) - str: 计算字符串形式的数学表达式。 return str(eval(expression))需要注意的是eval在真实生产环境中存在安全风险。如果只是在本地学习示例中使用问题不大但生产环境一定要对输入做严格白名单校验或者改用ast模块解析表达式避免恶意代码注入。4. 完整实战构建“调研 写作 校对”多智能体工作流这一节我们做一个真实可扩展的案例让多个 AI 智能体协同完成一篇技术调研文章。整体流程分三步调研智能体收集资料输出结构化的调研要点写作智能体基于调研结果撰写文章校对智能体检查文章准确性、可读性和逻辑问题给出修改建议。4.1 定义智能体打开agents.py编写三个智能体# agents.py from crewai import Agent def create_researcher(): return Agent( role资深技术调研员, goal围绕指定主题收集并整理可信、高质量的技术资料, backstory( 你是一名深耕人工智能领域多年的调研专家 擅长阅读技术文档、行业报告和开源项目资料 能够快速提取关键信息并给出结构化总结。 ), verboseTrue, allow_delegationFalse ) def create_writer(): return Agent( role技术文章作者, goal根据调研结果撰写结构清晰、通俗易懂的技术文章, backstory( 你是一名拥有丰富写作经验的技术博主 擅长把复杂的技术概念拆解成读者容易理解的内容 文章风格注重逻辑性和实用性。 ), verboseTrue, allow_delegationFalse ) def create_reviewer(): return Agent( role内容审核编辑, goal检查文章的技术准确性、逻辑连贯性和表达清晰度, backstory( 你是一名严谨的内容审核编辑 既懂技术又对文字质量有很高要求 在给修改建议时会明确说明问题和修改思路。 ), verboseTrue, allow_delegationFalse )4.2 定义任务打开tasks.py编写三个任务# tasks.py from crewai import Task def create_research_task(agent, topic): return Task( description( f调研主题{topic}\n 你需要围绕该主题整理关键技术点、典型应用场景、 工具链和行业趋势并输出调研简报。 ), expected_output( 一份结构化的调研简报包含\n 1. 关键概念解释\n 2. 主流实现方式\n 3. 参考工具或框架列表\n 4. 值得关注的趋势 ), agentagent ) def create_write_task(agent): return Task( description( 根据调研简报撰写一篇面向开发者的技术教程文章。 文章需要包含章节结构、通俗讲解和可操作的示例。 ), expected_output( 一篇完整的 Markdown 文章字符串 标题清晰、分段合理、包含代码示例。 ), agentagent, context[] ) def create_review_task(agent): return Task( description( 审阅写作智能体生成的文章重点检查\n 1. 技术信息是否准确\n 2. 文章结构是否清晰\n 3. 表达是否存在歧义\n 4. 代码示例是否具备可操作性\n 输出具体的修改建议不要重写整篇文章。 ), expected_output( 问题清单和逐条修改建议 每条建议包含原文位置、问题说明、修改建议。 ), agentagent )细心的读者可能注意到了create_write_task中context我暂时留了空列表。这里需要解释一个关键机制在 CrewAI 中任务之间的数据传递并不只靠代码变量而是在工作流里通过context建立依赖关系。我们马上会说明如何让写作任务拿到调研任务的结果。4.3 组装 Crew 并运行打开main.py# main.py import os from dotenv import load_dotenv from crewai import Crew, Process from agents import create_researcher, create_writer, create_reviewer from tasks import create_research_task, create_write_task, create_review_task # 加载 .env 中的模型配置 load_dotenv() # 1. 创建智能体 researcher create_researcher() writer create_writer() reviewer create_reviewer() # 2. 创建任务 research_task create_research_task(researcher, AI Agent 多智能体协作技术) write_task create_write_task(writer) # 关键点让写作任务依赖调研任务的结果 write_task.context [research_task] review_task create_review_task(reviewer) # 3. 创建 Crew crew Crew( agents[researcher, writer, reviewer], tasks[research_task, write_task, review_task], processProcess.sequential, verboseTrue ) # 4. 运行工作流 result crew.kickoff() # 5. 输出结果 print( 工作流执行结果 ) print(result)执行命令python main.py4.4 预期执行过程因为设置了verboseTrue运行过程中你的终端里会看到类似下面的日志调研智能体开始工作输出调研简报写作智能体收到调研简报开始撰写文章校对智能体审阅文章输出修改建议最终汇总结果打印出来。这里必须说明一个容易踩坑的地方如果你没有把research_task放到write_task的context中那么写作智能体可能只凭借自己的角色背景知识写作根本看不到前一步的调研结果。这在多智能体编排里是最常见的问题之一任务之间看似已经按顺序放入列表但数据依赖没有显式声明导致下游任务缺少上游上下文。5. 进阶实现带 FeedBack 的自动化工作流上面的案例只完成了单向流程调研、写作、校对。真实项目中我们往往需要“校对不过就返回修改”的循环机制。CrewAI 本身支持任务输出反馈但要让这个流程稳定运行我们需要在工作流层面设计反馈闭环。5.1 反馈闭环的设计思路一种实现思路是把“校对任务”的结果拿回来与“写作任务”一起运行第二轮。伪代码逻辑如下# 伪代码反馈循环示例 max_rounds 2 for round_index in range(max_rounds): result crew.kickoff() review_output review_task.output.raw if 无需修改 in review_output: break # 把修改建议重新注入写作任务描述 write_task.description f这是上一轮文章{write_result}\n这是审核意见{review_output}\n请根据意见修改。在业务开发中这种“轮次控制”比直接把所有反馈全部堆在一个 Prompt 里更可靠。原因在于每一次迭代都有独立的大模型上下文模型不会因为信息过长而遗漏关键修改点。就实践而言两到三轮是一个比较合理的成本控制区间无限循环会让 Token 消耗和响应时间都变得不可控。5.2 让工具参与工作流如果想要调研智能体真正去搜索互联网而不只是依赖模型内部知识可以在创建 Task 时给调研 Task 传入toolsfrom crewai_tools import SerperDevTool search_tool SerperDevTool() research_task Task( description调研 AI Agent 多智能体协作技术尽可能补充最近的实践案例。, expected_output结构化调研简报, agentresearcher, tools[search_tool] )这样当模型认为内部知识不足时就会触发搜索工具获取新信息。给不同 Task 配置不同工具是多智能体系统比单体 Prompt 灵活的核心体现写作任务不需要搜索工具但可能需要一个“关键词提取工具”而调研任务则需要搜索和网页读取工具每个工具的启用范围都可以精确控制。6. 常见问题与排查思路下面整理了多智能体开发过程中最常遇到的问题。问题现象常见原因解决思路智能体没有拿上游任务的结果未配置context或任务依赖在 Task 中显式声明context先打印上游output.raw验证任务输出格式混乱无法解析expected_output不够具体在期望输出中明确要求 JSON 或 Markdown 结构并给出示例报错找不到 API Key.env未加载或变量名错误确认安装python-dotenv检查变量名与模型服务商要求一致角色之间行为重叠输出同质化Agent 的 role、goal、backstory 区分度不足尽量让能力边界清晰例如一个专门查资料一个专门写作长时间不返回且 Token 消耗巨大任务过于复杂或循环太多限制max_round拆分任务调用轻量级模型处理中间步骤搜索工具报 401 错误第三方工具密钥未配置或额度不足检查对应工具平台账号密钥或者暂时移除工具仅用内置知识调试6.1 排查逻辑链遇到问题先不要急着改代码按下面的顺序排查先看任务之间数据是否打通打印上一个 Task 的output.raw再查模型返回内容是否符合预期临时提高verboseTrue观察大模型中间输出然后查是否是工具层问题去掉所有工具只让模型基于上下文运行看问题是否消失最后分析成本与性能如果任务链路过长优先考虑拆分独立 Crew 或使用缓存。6.2 一个很常见的 JSON 解析误区当你要把智能体输出接入下游系统时通常会让模型输出 JSON。很多人在expected_output里只写了一句话“输出 JSON”结果模型偶尔会在 JSON 最外层加 Markdown 代码块标记导致解析失败。更推荐的方式是在任务描述里给出一个明确的 JSON 模板expected_output( 一个 JSON 对象格式如下\n {summary: 总结内容, keywords: [关键词1, 关键词2]} )实践表明给出结构示例能显著提高模型输出的规范性。开发者在写任务描述时要把自己当成一个项目经理而不是简单地把指令丢给智能体。7. 最佳实践与工程建议7.1 从简单流程开始再增加智能体数量很多初学 CrewAI 的人会陷入一个误区一上来就定义五个智能体、十个任务结果互相依赖关系极其复杂出了问题很难排查。我的建议是先实现一条只有两个任务的最小闭环跑通后再逐步增加角色。多智能体不是目的业务结果才是目的。能用一个智能体和一个任务解决的问题就不要强行拆成多智能体。频繁的上下文切换会带来额外的 Token 消耗也可能引入不稳定的中间输出。7.2 为角色和能力设置清晰边界在真实项目中智能体的边界设计直接决定了工作流能否稳定运行。你需要明确调研智能体只负责收集资料不负责给结论写作智能体只负责基于给定资料写作不负责查证事实审核智能体只负责提出问题不直接替代作者做修改所有输出格式在任务描述中固定不允许随意变更。职责边界越清楚每个任务的输出就越专一后续维护和扩展也就越容易。边界模糊时一个智能体很容易在长上下文中被“带偏”甚至在回答里夹带另一个角色的任务内容。7.3 任务描述要具体到可验证给智能体布置任务时模糊表达是最大的敌人。比如不推荐“写一篇关于 AI 的文章。”推荐“写一篇面向后端开发者的 AI Agent 入门文章要求包含 300 字概念解释、一个环境安装步骤、一个完整代码示例和常见问题表格。”任务结果应该具备“可验证性”。如果你自己都不知道怎样算完成模型自然更不知道。7.4 成本控制与缓存策略多智能体系统往往会调用多次大模型接口成本控制和响应时间是生产环境必须考虑的问题。在开发阶段可以先用参数较小的模型验证流程正确性再切换更强的模型做最终效果测试。同时可以使用cacheTrue让 CrewAI 在运行过程中缓存中间结果减少重复调用。另外在输出最终答案前如果某个任务的输入和上一轮完全一致可以考虑在应用层加入一层缓存判断而不是每次都驱动整条 Crew 重跑。7.5 日志、可观测性与安全生产环境中的多智能体应用必须记录完整执行日志。建议记录以下信息每个 Agent 的输入和输出摘要每个 Task 的执行顺序和时间工具调用情况大模型 Token 消耗每次运行的整体耗时。如果智能体需要访问外部系统或执行重要操作必须遵循最小权限原则。不要让智能体拥有过高权限的 API Key更不要把密钥库的信息直接写进 Prompt。涉及生产数据变更时一定要人工审批确认。8. 总结与下一步学习路线本文围绕 CrewAI 多智能体系统开发从核心概念、环境搭建、智能体定义、任务编排到完整实战案例完整走通了一条基于“调研、写作、校对”的自动化内容生产流程。现在你已经能理解 Agent、Task、Crew、Process、Tool 这五个核心元素的作用也能通过 context 建立任务之间的数据依赖还能针对常见多智能体开发问题进行排查。下一步建议你从这几个方向继续深入在 CrewAI 项目中接入不同大模型比较输出效果与 Token 成本差异在实战案例中增加真实搜索工具让调研智能体获取时效性内容定义一个 Manager Agent熟悉分层执行与任务动态分配尝试把多智能体的最终输出接入后端服务或消息队列形成完整的自动化业务流程研究如何为多智能体流程设计测试数据集保证每次发布前能稳定验证。AI 智能体的开发方式还在快速演进框架本身的 API 也可能持续调整。相比死记硬背某个版本的参数深入理解“角色定义—任务拆解—流程编排—工具接入”这条主线才是能够应对各类新框架的核心能力。如果本文对你有帮助建议收藏备用后续自己动手搭建一条多智能体工作流时再回来对照每一个步骤。 CrewAI多智能体编排实战：从Agent定义到自动化工作流
在 AI 应用从“单模型对话框”走向“自动化业务流程”的今天只靠一个 Prompt 调大模型已经很难满足真实项目的需求。尤其在内容生产、数据分析、客户运营这类场景中往往需要多个具备不同职责的智能体配合一个负责梳理需求一个负责查询知识库一个负责撰写结果一个负责检查质量。如果这些步骤全部塞进同一个 Prompt不仅逻辑混乱而且后续维护成本极高。这也是 CrewAI 这类多智能体编排框架越来越受关注的原因。本文将围绕 CrewAI 多智能体系统开发展开重点拆解智能体定义、任务编排和自动化工作流构建。文章会从核心概念讲起再逐步落到环境和代码最后给出一个可直接扩展的实战案例以及常见的排查思路。无论你是刚接触 AI 智能体开发的新手还是已经在用 LangChain 想了解多智能体编排的开发者都能在这篇文章里找到可以落地的内容。1. 什么是 CrewAI为什么要做多智能体编排1.1 从“单个大模型”到“智能体团队”过去我们在开发 AI 应用时通常是一个 Prompt 把需求描述清楚然后让大模型直接输出结果。这种模式在简单问答、文本改写、摘要生成等场景下完全够用但一旦业务流程变复杂问题就会暴露出来单个 Prompt 过长模型容易丢失指令输出不稳定多个职责混在一起比如“既要检索又要总结还要判断情感”模型经常顾此失彼无法复用角色能力写好的“数据分析师”提示词很难拆开独立维护无法对中间过程做精细控制例如先审核数据再生成文章。多智能体系统的思路是把复杂的业务目标拆解成多个子任务由不同的 AI 智能体分别承担。每个智能体有独立的角色、目标、背景故事和工具多个智能体之间再通过任务依赖关系协作最终像一个“虚拟团队”一样完成整个流程。1.2 CrewAI 的定位CrewAI 是一个基于 Python 的多智能体编排框架你可以把它理解成“智能体团队的操作系统”。它不关心底层具体接入了哪个大模型而是提供了一套标准化的抽象Agent定义智能体的角色、行为方式、可用工具Task定义需要完成的具体任务Crew把智能体和任务组合起来并控制协作的方式Process任务执行流程支持顺序执行、分层执行等Tool智能体可以调用的外部能力例如搜索、计算、数据库查询。这种设计带来的直接好处是你可以像搭积木一样构建 AI 应用。业务变化时只需要调整任务链或替换某个智能体不需要重写整套流程。1.3 常见应用场景从目前社区的实践来看CrewAI 最适合以下几类场景内容自动化生产策划编辑智能体、资料检索智能体、文案撰写智能体、校对审核智能体协作完成一篇文章数据分析报告生成数据查询智能体负责取数数据分析师智能体负责洞察报告撰写智能体负责输出结论营销活动支持市场调研智能体收集信息策略智能体设计活动方案文案智能体生成各渠道物料研发辅助需求分析智能体梳理需求代码生成智能体编写代码代码审查智能体检查质量客户运营客服智能体先响应质检智能体再检查工单分类智能体负责后续流转。在 2025 年 AI 智能体开发人才需求快速增长的背景下掌握智能体定义和任务编排能力已经是从事 AI 应用开发非常重要的基本功。而 CrewAI 正是这个方向上手曲线相对平滑的框架之一。2. 环境准备安装 CrewAI 与项目结构设计2.1 运行环境要求CrewAI 本质上是一个 Python 包安装方式非常简单。本文示例主要使用 CrewAI 的常规用法不针对任何特定版本编写代码。为了减少兼容问题建议读者保持 Python 3.10 及以上版本并先创建独立的虚拟环境。# 创建虚拟环境 python -m venv crewai-env # 激活虚拟环境 # Windows crewai-env\Scripts\activate # macOS / Linux source crewai-env/bin/activate安装 CrewAI 主库pip install crewai如果你需要使用工具集例如让智能体访问搜索引擎或读取网站内容可以一并安装pip install crewai[tools]安装完成之后可以用下面的命令验证版本python -c import crewai; print(crewai.__version__)这里需要说明一点CrewAI 的版本迭代比较快不同版本之间 API 可能有小幅度调整。如果你安装的是较新版本运行示例时如果遇到属性名变化以官方文档对应版本为准。2.2 模型接入说明CrewAI 本身不提供大模型能力它默认会读取环境变量中的模型配置。最常用的方式是接入 OpenAI 兼容接口。为了安全建议把密钥写入本地.env文件不要硬编码在代码中。pip install python-dotenv在项目根目录创建.env文件OPENAI_API_KEY你的密钥 OPENAI_API_BASE你的模型服务地址 OPENAI_MODEL_NAMEgpt-4o-mini如果你使用的是国内大模型服务或本地部署模型只需要把OPENAI_API_BASE和OPENAI_MODEL_NAME改成自己服务的对应值。CrewAI 底层的langchain生态已经兼容了大量 OpenAI 协议接口。2.3 示例项目结构为了便于后续维护建议按下面的结构组织代码crewai_demo/ ├── .env ├── requirements.txt ├── main.py # 入口文件负责组装并运行 Crew └── agents.py # 定义智能体在一个人工智能体项目中这种拆分的好处非常明显agents.py专注智能体定义任务变化时不需要反复修改这里的代码main.py专注流程编排负责把不同智能体与任务串联起来。接下来我们按照实战路径一步步实现。3. 核心概念拆解Agent、Task、Crew、Process3.1 Agent智能体的“人设”在 CrewAI 中Agent是最基础的执行单元。它不只是一个大模型实例还包含角色设定、行为约束、可调用工具和委托能力。先看一个最简单的智能体定义from crewai import Agent researcher Agent( role高级技术调研员, goal围绕指定主题收集最新、准确的技术资料, backstory你有超过 10 年的技术研究经验擅长从海量信息中筛选出高质量、可验证的内容。, verboseTrue, allow_delegationFalse )这里的关键参数含义如下role智能体的角色名用于让模型理解自己当前的身份goal智能体的总目标所有任务上下文都会结合这个目标backstory角色背景故事用于增强大模型对场景的理解让输出更稳定verbose是否输出执行过程的中间日志调试时建议开启allow_delegation是否允许该智能体把子任务委托给其他智能体。在实际开发中role、goal、backstory描述得越具体最终输出质量通常越高。因为大模型需要足够清晰的“上下文锚点”来保持一致的行为模式模糊的人设会导致每一步输出都不够稳定。3.2 Task智能体的“待办事项”Task描述了一个具体的执行单元包括任务说明、期望输出、负责执行的智能体以及可选工具。from crewai import Task research_task Task( description调研 AI Agent 在 2025 年的发展趋势整理出 5 个关键方向。, expected_output一份包含 5 个关键方向的列表每个方向包含简短说明和背景依据。, agentresearcher )expected_output是容易被忽视但非常重要的参数。它告诉大模型“什么样才算做完”能够显著减少输出跑偏的问题。多智能体场景下前一个任务的输出就是后一个任务的输入如果输出格式不明确下游任务质量就会受到直接影响。3.3 Crew把人和事组织起来Crew在整个框架中的作用相当于“调度中心”。它负责把 Agent 和 Task 组合起来并决定任务执行方式。from crewai import Crew research_crew Crew( agents[researcher], tasks[research_task], verboseTrue )当调用kickoff()时Crew 会按照编排好的方式把任务分配给对应智能体执行并收集结果result research_crew.kickoff(inputs{topic: AI Agent 发展趋势}) print(result)inputs参数可以用来向任务描述中动态注入变量。例如描述中写了{topic}运行时就可以通过inputs{topic: 实际主题}替换。这种机制让任务模板可复用也是构建通用工作流的基础。3.4 Process流程的编排方式Process是 CrewAI 中控制任务顺序的一组枚举值。常见的包括Process.sequential顺序执行一个任务完成后再执行下一个任务Process.hierarchical分层执行由 Manager Agent 负责规划和委派任务。顺序执行最容易理解from crewai import Process crew Crew( agents[agent_a, agent_b], tasks[task_one, task_two], processProcess.sequential )分层执行则适合任务依赖复杂、需要动态规划的场景。使用时通常需要设置manager_llm或提供manager_agentcrew Crew( agents[agent_a, agent_b], tasks[task_one, task_two], processProcess.hierarchical, manager_llmgpt-4o-mini )在分层模式下Manager 会先分析任务列表再决定哪个智能体在什么时间执行什么任务。这种机制更接近真实团队的管理模式但也会增加 Token 消耗因此项目早期建议先从顺序执行开始。3.5 Tool智能体的“外部能力”很多时候智能体不能只靠模型内部知识完成工作需要访问外部信息或执行计算。CrewAI 的Tool封装了这类能力可以理解为大模型的“手和脚”。CrewAI Tools 提供了搜索、网页抓取、文件读写等常用工具from crewai_tools import SerperDevTool search_tool SerperDevTool()你也可以自己定义一个简单的函数工具from crewai_tools import tool tool(计算器) def calculator(expression: str) - str: 计算字符串形式的数学表达式。 return str(eval(expression))需要注意的是eval在真实生产环境中存在安全风险。如果只是在本地学习示例中使用问题不大但生产环境一定要对输入做严格白名单校验或者改用ast模块解析表达式避免恶意代码注入。4. 完整实战构建“调研 写作 校对”多智能体工作流这一节我们做一个真实可扩展的案例让多个 AI 智能体协同完成一篇技术调研文章。整体流程分三步调研智能体收集资料输出结构化的调研要点写作智能体基于调研结果撰写文章校对智能体检查文章准确性、可读性和逻辑问题给出修改建议。4.1 定义智能体打开agents.py编写三个智能体# agents.py from crewai import Agent def create_researcher(): return Agent( role资深技术调研员, goal围绕指定主题收集并整理可信、高质量的技术资料, backstory( 你是一名深耕人工智能领域多年的调研专家 擅长阅读技术文档、行业报告和开源项目资料 能够快速提取关键信息并给出结构化总结。 ), verboseTrue, allow_delegationFalse ) def create_writer(): return Agent( role技术文章作者, goal根据调研结果撰写结构清晰、通俗易懂的技术文章, backstory( 你是一名拥有丰富写作经验的技术博主 擅长把复杂的技术概念拆解成读者容易理解的内容 文章风格注重逻辑性和实用性。 ), verboseTrue, allow_delegationFalse ) def create_reviewer(): return Agent( role内容审核编辑, goal检查文章的技术准确性、逻辑连贯性和表达清晰度, backstory( 你是一名严谨的内容审核编辑 既懂技术又对文字质量有很高要求 在给修改建议时会明确说明问题和修改思路。 ), verboseTrue, allow_delegationFalse )4.2 定义任务打开tasks.py编写三个任务# tasks.py from crewai import Task def create_research_task(agent, topic): return Task( description( f调研主题{topic}\n 你需要围绕该主题整理关键技术点、典型应用场景、 工具链和行业趋势并输出调研简报。 ), expected_output( 一份结构化的调研简报包含\n 1. 关键概念解释\n 2. 主流实现方式\n 3. 参考工具或框架列表\n 4. 值得关注的趋势 ), agentagent ) def create_write_task(agent): return Task( description( 根据调研简报撰写一篇面向开发者的技术教程文章。 文章需要包含章节结构、通俗讲解和可操作的示例。 ), expected_output( 一篇完整的 Markdown 文章字符串 标题清晰、分段合理、包含代码示例。 ), agentagent, context[] ) def create_review_task(agent): return Task( description( 审阅写作智能体生成的文章重点检查\n 1. 技术信息是否准确\n 2. 文章结构是否清晰\n 3. 表达是否存在歧义\n 4. 代码示例是否具备可操作性\n 输出具体的修改建议不要重写整篇文章。 ), expected_output( 问题清单和逐条修改建议 每条建议包含原文位置、问题说明、修改建议。 ), agentagent )细心的读者可能注意到了create_write_task中context我暂时留了空列表。这里需要解释一个关键机制在 CrewAI 中任务之间的数据传递并不只靠代码变量而是在工作流里通过context建立依赖关系。我们马上会说明如何让写作任务拿到调研任务的结果。4.3 组装 Crew 并运行打开main.py# main.py import os from dotenv import load_dotenv from crewai import Crew, Process from agents import create_researcher, create_writer, create_reviewer from tasks import create_research_task, create_write_task, create_review_task # 加载 .env 中的模型配置 load_dotenv() # 1. 创建智能体 researcher create_researcher() writer create_writer() reviewer create_reviewer() # 2. 创建任务 research_task create_research_task(researcher, AI Agent 多智能体协作技术) write_task create_write_task(writer) # 关键点让写作任务依赖调研任务的结果 write_task.context [research_task] review_task create_review_task(reviewer) # 3. 创建 Crew crew Crew( agents[researcher, writer, reviewer], tasks[research_task, write_task, review_task], processProcess.sequential, verboseTrue ) # 4. 运行工作流 result crew.kickoff() # 5. 输出结果 print( 工作流执行结果 ) print(result)执行命令python main.py4.4 预期执行过程因为设置了verboseTrue运行过程中你的终端里会看到类似下面的日志调研智能体开始工作输出调研简报写作智能体收到调研简报开始撰写文章校对智能体审阅文章输出修改建议最终汇总结果打印出来。这里必须说明一个容易踩坑的地方如果你没有把research_task放到write_task的context中那么写作智能体可能只凭借自己的角色背景知识写作根本看不到前一步的调研结果。这在多智能体编排里是最常见的问题之一任务之间看似已经按顺序放入列表但数据依赖没有显式声明导致下游任务缺少上游上下文。5. 进阶实现带 FeedBack 的自动化工作流上面的案例只完成了单向流程调研、写作、校对。真实项目中我们往往需要“校对不过就返回修改”的循环机制。CrewAI 本身支持任务输出反馈但要让这个流程稳定运行我们需要在工作流层面设计反馈闭环。5.1 反馈闭环的设计思路一种实现思路是把“校对任务”的结果拿回来与“写作任务”一起运行第二轮。伪代码逻辑如下# 伪代码反馈循环示例 max_rounds 2 for round_index in range(max_rounds): result crew.kickoff() review_output review_task.output.raw if 无需修改 in review_output: break # 把修改建议重新注入写作任务描述 write_task.description f这是上一轮文章{write_result}\n这是审核意见{review_output}\n请根据意见修改。在业务开发中这种“轮次控制”比直接把所有反馈全部堆在一个 Prompt 里更可靠。原因在于每一次迭代都有独立的大模型上下文模型不会因为信息过长而遗漏关键修改点。就实践而言两到三轮是一个比较合理的成本控制区间无限循环会让 Token 消耗和响应时间都变得不可控。5.2 让工具参与工作流如果想要调研智能体真正去搜索互联网而不只是依赖模型内部知识可以在创建 Task 时给调研 Task 传入toolsfrom crewai_tools import SerperDevTool search_tool SerperDevTool() research_task Task( description调研 AI Agent 多智能体协作技术尽可能补充最近的实践案例。, expected_output结构化调研简报, agentresearcher, tools[search_tool] )这样当模型认为内部知识不足时就会触发搜索工具获取新信息。给不同 Task 配置不同工具是多智能体系统比单体 Prompt 灵活的核心体现写作任务不需要搜索工具但可能需要一个“关键词提取工具”而调研任务则需要搜索和网页读取工具每个工具的启用范围都可以精确控制。6. 常见问题与排查思路下面整理了多智能体开发过程中最常遇到的问题。问题现象常见原因解决思路智能体没有拿上游任务的结果未配置context或任务依赖在 Task 中显式声明context先打印上游output.raw验证任务输出格式混乱无法解析expected_output不够具体在期望输出中明确要求 JSON 或 Markdown 结构并给出示例报错找不到 API Key.env未加载或变量名错误确认安装python-dotenv检查变量名与模型服务商要求一致角色之间行为重叠输出同质化Agent 的 role、goal、backstory 区分度不足尽量让能力边界清晰例如一个专门查资料一个专门写作长时间不返回且 Token 消耗巨大任务过于复杂或循环太多限制max_round拆分任务调用轻量级模型处理中间步骤搜索工具报 401 错误第三方工具密钥未配置或额度不足检查对应工具平台账号密钥或者暂时移除工具仅用内置知识调试6.1 排查逻辑链遇到问题先不要急着改代码按下面的顺序排查先看任务之间数据是否打通打印上一个 Task 的output.raw再查模型返回内容是否符合预期临时提高verboseTrue观察大模型中间输出然后查是否是工具层问题去掉所有工具只让模型基于上下文运行看问题是否消失最后分析成本与性能如果任务链路过长优先考虑拆分独立 Crew 或使用缓存。6.2 一个很常见的 JSON 解析误区当你要把智能体输出接入下游系统时通常会让模型输出 JSON。很多人在expected_output里只写了一句话“输出 JSON”结果模型偶尔会在 JSON 最外层加 Markdown 代码块标记导致解析失败。更推荐的方式是在任务描述里给出一个明确的 JSON 模板expected_output( 一个 JSON 对象格式如下\n {summary: 总结内容, keywords: [关键词1, 关键词2]} )实践表明给出结构示例能显著提高模型输出的规范性。开发者在写任务描述时要把自己当成一个项目经理而不是简单地把指令丢给智能体。7. 最佳实践与工程建议7.1 从简单流程开始再增加智能体数量很多初学 CrewAI 的人会陷入一个误区一上来就定义五个智能体、十个任务结果互相依赖关系极其复杂出了问题很难排查。我的建议是先实现一条只有两个任务的最小闭环跑通后再逐步增加角色。多智能体不是目的业务结果才是目的。能用一个智能体和一个任务解决的问题就不要强行拆成多智能体。频繁的上下文切换会带来额外的 Token 消耗也可能引入不稳定的中间输出。7.2 为角色和能力设置清晰边界在真实项目中智能体的边界设计直接决定了工作流能否稳定运行。你需要明确调研智能体只负责收集资料不负责给结论写作智能体只负责基于给定资料写作不负责查证事实审核智能体只负责提出问题不直接替代作者做修改所有输出格式在任务描述中固定不允许随意变更。职责边界越清楚每个任务的输出就越专一后续维护和扩展也就越容易。边界模糊时一个智能体很容易在长上下文中被“带偏”甚至在回答里夹带另一个角色的任务内容。7.3 任务描述要具体到可验证给智能体布置任务时模糊表达是最大的敌人。比如不推荐“写一篇关于 AI 的文章。”推荐“写一篇面向后端开发者的 AI Agent 入门文章要求包含 300 字概念解释、一个环境安装步骤、一个完整代码示例和常见问题表格。”任务结果应该具备“可验证性”。如果你自己都不知道怎样算完成模型自然更不知道。7.4 成本控制与缓存策略多智能体系统往往会调用多次大模型接口成本控制和响应时间是生产环境必须考虑的问题。在开发阶段可以先用参数较小的模型验证流程正确性再切换更强的模型做最终效果测试。同时可以使用cacheTrue让 CrewAI 在运行过程中缓存中间结果减少重复调用。另外在输出最终答案前如果某个任务的输入和上一轮完全一致可以考虑在应用层加入一层缓存判断而不是每次都驱动整条 Crew 重跑。7.5 日志、可观测性与安全生产环境中的多智能体应用必须记录完整执行日志。建议记录以下信息每个 Agent 的输入和输出摘要每个 Task 的执行顺序和时间工具调用情况大模型 Token 消耗每次运行的整体耗时。如果智能体需要访问外部系统或执行重要操作必须遵循最小权限原则。不要让智能体拥有过高权限的 API Key更不要把密钥库的信息直接写进 Prompt。涉及生产数据变更时一定要人工审批确认。8. 总结与下一步学习路线本文围绕 CrewAI 多智能体系统开发从核心概念、环境搭建、智能体定义、任务编排到完整实战案例完整走通了一条基于“调研、写作、校对”的自动化内容生产流程。现在你已经能理解 Agent、Task、Crew、Process、Tool 这五个核心元素的作用也能通过 context 建立任务之间的数据依赖还能针对常见多智能体开发问题进行排查。下一步建议你从这几个方向继续深入在 CrewAI 项目中接入不同大模型比较输出效果与 Token 成本差异在实战案例中增加真实搜索工具让调研智能体获取时效性内容定义一个 Manager Agent熟悉分层执行与任务动态分配尝试把多智能体的最终输出接入后端服务或消息队列形成完整的自动化业务流程研究如何为多智能体流程设计测试数据集保证每次发布前能稳定验证。AI 智能体的开发方式还在快速演进框架本身的 API 也可能持续调整。相比死记硬背某个版本的参数深入理解“角色定义—任务拆解—流程编排—工具接入”这条主线才是能够应对各类新框架的核心能力。如果本文对你有帮助建议收藏备用后续自己动手搭建一条多智能体工作流时再回来对照每一个步骤。