★ FEATURED ARTICLE 1. 项目背景某创业公司的技术负责人张哥每周五都要花两个小时整理团队周报——翻看 Jira、Git 提交记录、Slack 频道讨论再汇总成一份本周进展 风险 下周计划的文档发给管理层。流程不复杂但极其琐碎而且很容易漏掉重要信息比如某个同事在群里随口提的一个阻塞问题没记到 Jira 里。张哥尝试过让 GPT-4 直接生成周报。他写了一段很长的 prompt把本周的原始素材一股脑丢进去。结果模型输出了一份看起来对的周报——措辞专业、排版工整但仔细一看有两个已完成的任务被遗漏了一个被拖延的原因被写成了资源不足实际是第三方 API 改了接口没人通知。模型没有核查的能力它只能基于你给的信息做重组不能去追问和验证。这就是 Crew 要解决的问题Crew 不是单个 Agent 的容器而是一套让多个 Agent 按照既定流程协作的编排引擎。在 CrewAI 里你可以定义一个由任务收集员“进展分析师”“风险分析师”报告撰写员组成的小团队各司其职、互相校验最终产出一份可靠度更高的周报。本章的目标是让读者掌握 Crew 的完整配置——包括 Process 选择、kickoff 调用、结果获取以及如何设计一个可调试、可复盘的团队协作流程。2. 项目设计小胖拿着手机刷着美食推荐“大师我一直有个疑问——前面几章我们都在建 Agent 和 Task但到底什么时候该拆多个 Agent什么时候只用一个 Agent 多搞几个 Task”大师“好问题。我的经验法则是如果多个 Task 需要不同的专业视角或知识背景就拆 Agent如果只是同一个思路的不同步骤用一个 Agent 就行。比如周报生成——收集任务进展和识别风险需要两种不同的思维方式一个是’发生了什么’一个是’这意味着什么’。前者偏客观记录后者偏主观判断。用一个 Agent 做这两件事它可能在识别风险时不够敏感。”小白翻着笔记本“那 Crew 的 Process 参数——Sequential 和 Hierarchical——到底怎么选我看文档说 Sequential 是默认的。”大师“Sequential Process 的核心逻辑是’按 Task 列表的顺序串行执行’。Task 1 做完交给 Task 2Task 2 做完交给 Task 3——像流水线。适用场景是任务之间有明确的先后依赖关系比如调研→分析→出报告。”小白“那 Hierarchical 呢”大师“Hierarchical Process 会给 Crew 自动创建一个 Manager Agent。这个 Manager 不再按固定顺序执行而是基于目标动态分配任务——它可能先让 Agent A 和 Agent B 并行工作然后让 Agent C 汇总两个人的结果。适用场景是任务之间的依赖关系不明确、需要动态协调的复杂情况。但代价也很明显——Manager Agent 本身也消耗 Token加上动态调度的不确定性成本会显著增加。”小胖“这不就跟公司管理一样嘛Sequential 就是流水线——每个人做自己那一步做完传给下一个。Hierarchical 就是开个 project manager——他动态分配任务谁闲着就给谁活。”大师笑了“小胖这次的比方很到位。我再补充一点——在基础知识还不够的时候我建议只用 Sequential。Hierarchical 虽然灵活但 Manager Agent 的决策质量依赖于模型能力而且在任务较少时反而浪费 Token。只有当你对 Agent 行为和输出质量有足够信心时才切换到 Hierarchical。”小白“说到 kickoff我注意到有两种调用方式——直接kickoff()和kickoff(inputs{...})。有什么区别”大师“kickoff()是无参数启动所有 Task 描述和 Agent 定义里已经包含了全部信息。kickoff(inputs{})是带参数启动你可以在运行时传入动态变量。比如kickoff(inputs{project: 用户系统重构, week: W23})——Task 描述里的{project}和{week}会被替换。这使得同一个 Crew 可以处理不同输入。”小白“那 kickoff 的返回值呢我怎么拿到最终结果”大师“kickoff()返回一个CrewOutput对象它有三个常用属性result.raw是最终输出的纯文本result.json_dict是 JSON 格式如果配置了结构化输出result.tasks_output是每个 Task 的输出列表可逐个追溯。”小胖“如果我报错怎么办怎么知道是哪个 Task 出的问题”大师“开verboseTrue——每个 Agent 的思考过程、Task 的输入输出都会打印出来。但现在还有一个更好的工具叫 CrewAI 的 telemetry可以生成结构化的运行报告。不过那是中级篇的内容了。入门阶段verbose 日志加上 output_file 就够了——每个 Task 输出一个文件逐文件检查。”技术映射总结Crew 是容器Process 是容器内的调度策略。Sequential 像流水线——确定的输入流转顺序可预测的成本。Hierarchical 像项目管理——动态的任务分配灵活但成本不可控。选择哪种取决于你对可预测性和灵活性的权衡。3. 项目实战3.1 实战目标实现一个周报自动生成 Crew包含 4 个 Agent 和 4 个 Task从任务列表生成进展摘要、风险清单和下周计划输出一份结构化的周报文档。3.2 环境准备weekly-report-crew/ ├── .env ├── main.py ├── agents.py ├── tasks.py ├── crew.py ├── test_data.py # 模拟的原始素材 └── outputs/依赖同第 2 章。3.3 分步实现步骤1准备模拟数据目标提供一份真实感的周报原始素材。# test_data.pyimportjson WEEKLY_RAW_DATA{project:用户中心重构,week:W23,team_members:[张三,李四,王五,赵六],raw_materials: ## Jira 本周已完成 - [DONE] UC-101 用户登录页面重构 (张三, 2天) - [DONE] UC-102 手机号验证码登录接口 (李四, 3天) - [DONE] UC-103 密码重置流程优化 (王五, 1天) ## Jira 进行中 - [IN PROGRESS] UC-104 用户权限管理页面 (张三, 进度60%, 卡在接口联调) - [IN PROGRESS] UC-105 OAuth2.0 集成 (李四, 进度30%, 文档不全) ## Jira 未开始 - [TODO] UC-106 用户行为埋点 - [TODO] UC-107 多语言支持 ## Git 提交摘要 - feature/user-login: 5 commits, 张三 - feature/sms-verify: 8 commits, 李四 (含2次回滚) - fix/password-reset: 2 commits, 王五 ## 团队沟通摘要 (来自Slack) - 张三反馈UC-104的后端接口字段名和文档不一致已跟后端确认预计下周二能联调 - 李四咨询OAuth2.0的第三方文档中文版缺失可能需要看英文版进度会延迟1-2天 - 王五提到UC-103上线后发现一个边界bug已紧急修复并回滚 - 赵六新人本周主要在熟悉代码和跑测试用例 ,risk_signals:[UC-104接口联调受阻依赖后端团队排期,UC-105第三方文档不完整需要额外研究时间,短信验证码服务商合同下月到期需提前续约,团队新人赵六尚未正式分配任务]}步骤2定义 4 个 Agent目标为周报生成设计分工明确的角色。# agents.pyfromcrewaiimportAgentdefcreate_agents(llm):创建周报生成小队的4个AgentcollectorAgent(role任务信息收集员,goal从原始素材中提取所有已完成、进行中和未开始的任务不遗漏、不捏造,backstory(你是团队的项目助理负责每天从Jira、Git和聊天记录中整理任务进展。你对信息有强迫症式的精确要求——大概完成了必须改成已完成80%剩余部分卡在后端接口。你的原则是只记录不评价。),llmllm,verboseTrue,allow_delegationFalse,max_iter10)progress_analystAgent(role进展分析师,goal评估本周各项任务的完成质量、进度偏差和阻塞原因,backstory(你在咨询公司做过3年项目审计擅长从任务数据中读出表面完成和真正交付的差距。你关注三件事延期风险、质量信号回滚次数、Bug数量、团队负载。你的座右铭一个完成的任务如果带着两个回滚它的完成需要打个问号。),llmllm,verboseTrue,allow_delegationFalse,max_iter10)risk_analystAgent(role风险分析师,goal识别本周工作中的潜在风险评估影响和紧急程度给出应对建议,backstory(你在互联网公司做过5年风险管理见过太多小事变大事的案例。你的风险嗅觉很敏锐——接口字段不一致在你眼里不是小问题而是没有API契约管理的系统性风险信号。你评估风险不只靠直觉每个风险都回答三个问题可能发生什么、概率多大、影响范围。),llmllm,verboseTrue,allow_delegationFalse,max_iter12)report_writerAgent(role周报撰写员,goal将进展、风险和计划整合成一份结构清晰、重点突出的周报,backstory(你曾是老板助理深知管理层看周报的耐心不超过3分钟。你的周报公式是开篇一句话总结本周亮点风险红灯下周关键任务。你用词精确、结构固定让管理者30秒就能建立全局认知。你从不美化问题——延迟就是延迟风险就是风险。),llmllm,verboseTrue,allow_delegationFalse,max_iter8)returncollector,progress_analyst,risk_analyst,report_writer步骤3定义 4 个 Task目标将周报生成拆成可独立完成的步骤。# tasks.pyfromcrewaiimportTaskdefcreate_tasks(collector,progress_analyst,risk_analyst,report_writer,raw_data):创建周报生成的4个Task# Task 1: 任务信息收集collect_taskTask(descriptionf 请从以下原始素材中提取和整理本周任务信息 【原始素材】{raw_data[raw_materials]}【整理要求】 1. 已完成任务列出任务编号、名称、负责人、实际耗时 2. 进行中任务列出任务编号、名称、负责人、当前进度%、阻塞原因如有 3. 未开始任务列出任务编号、名称、优先级、前置依赖 【严禁行为】 - 禁止编造素材中没有的任务 - 禁止推测进度数据如素材未提供 - 如果信息不完整标注[待确认]不要自行补齐 ,expected_output(# 本周任务状态\n## 已完成n项\n| 编号 | 名称 | 负责人 | 耗时 | 备注 |\n|------|------|--------|------|------|\n## 进行中n项\n| 编号 | 名称 | 负责人 | 进度 | 阻塞/备注 |\n|------|------|--------|------|----------|\n## 待开始n项\n| 编号 | 名称 | 优先级 | 前置依赖 |\n|------|------|--------|---------|),agentcollector,output_fileoutputs/01_task_status.md)# Task 2: 进展分析progress_taskTask(description 基于任务状态报告分析本周进展 1. 整体完成率按计划应完成多少实际完成多少 2. 质量信号 - 有回滚的任务意味着质量和测试问题 - 超耗时的任务意味着复杂度低估或阻塞 3. 团队负载分析每人本周产出的量化评估 4. 进度偏差哪些任务延期原因是什么对整体计划的影响 ,expected_output(# 本周进展分析\n## 完成率\n- 计划完成n项 / 实际完成n项 / 完成率x%\n## 质量信号\n| 信号 | 相关任务 | 严重度 | 说明 |\n|------|---------|--------|------|\n## 团队负载\n| 成员 | 完成任务 | 进行中 | 产出评估 |\n|------|---------|--------|---------|\n## 进度偏差\n| 任务 | 计划 | 实际 | 偏差原因 | 影响 |\n|------|------|------|---------|------|),agentprogress_analyst,context[collect_task],output_fileoutputs/02_progress_analysis.md)# Task 3: 风险分析risk_taskTask(descriptionf 基于任务状态和进展分析识别本周风险 【已知风险信号】{chr(10).join(f-{s}forsinraw_data[risk_signals])}【深度分析要求】 1. 判断每个风险信号的严重程度高/中/低和紧急程度 2. 识别可能存在的沉默风险——数据中没明确说但隐含的问题 提示新人未分配任务 两个关键任务受阻 3. 给出每个风险的应对建议和责任人建议 ,expected_output(# 风险评估报告\n## 风险清单\n| # | 风险 | 严重度 | 紧急度 | 可能后果 | 建议应对 |\n|---|------|--------|--------|---------|--------|\n| 1 | ... | // | // | ... | ... |\n## 沉默风险\n- 识别至少1个潜在风险\n## 风险趋势\n- 相比上周风险是增加/减少/持平),agentrisk_analyst,context[collect_task,progress_task],output_fileoutputs/03_risk_report.md)# Task 4: 周报撰写report_taskTask(descriptionf 综合前三步所有信息撰写一份管理层周报项目名{raw_data[project]}周期{raw_data[week]}【周报结构要求】 1. 一句话总结30字以内 2. 本周亮点2-3条选最有价值的 3. 风险警示按严重度排序最高3条 4. 下周关键任务3-5项含负责人和预估耗时 5. 需要的支持/决策如有 【风格要求】 - 精炼管理层阅读时间不超过2分钟 - 诚实延期和风险不粉饰 - 可操作每条建议有明确的责任方 ,expected_output(# {project} 周报 - {week}\n\n## 一句话总结\n本周xxx下周重点是xxx。\n\n## 本周亮点\n1. ✅ xxx\n2. ✅ xxx\n\n## 风险警示\n| 等级 | 风险 | 建议 |\n|------|------|------|\n| | ... | ... |\n\n## 下周关键任务\n| 优先级 | 任务 | 负责人 | 预计耗时 |\n|-------|------|--------|---------|\n\n## 需要的支持\n- 列出一项或写暂无),agentreport_writer,context[collect_task,progress_task,risk_task],output_fileoutputs/04_weekly_report.md)return[collect_task,progress_task,risk_task,report_task]步骤4组装 Crew目标使用 Sequential Process 组装周报生成小队。# crew.pyfromcrewaiimportCrew,Process,LLMfromagentsimportcreate_agentsfromtasksimportcreate_tasksfromtest_dataimportWEEKLY_RAW_DATAimportosdefcreate_weekly_report_crew():创建周报生成CrewllmLLM(modelos.getenv(MODEL_NAME,gpt-4o-mini),temperature0.3,timeout120,max_retries2)collector,progress_analyst,risk_analyst,report_writercreate_agents(llm)taskscreate_tasks(collector,progress_analyst,risk_analyst,report_writer,WEEKLY_RAW_DATA)crewCrew(agents[collector,progress_analyst,risk_analyst,report_writer],taskstasks,processProcess.sequential,# 使用顺序执行模式verboseTrue# memoryTrue # 基础篇暂不启用到第9章再展开)returncrew步骤5主入口目标运行 Crew 并获取结构化输出。# main.pyfromdotenvimportload_dotenv load_dotenv()fromcrewimportcreate_weekly_report_crewimportosdefmain():# 确保输出目录存在os.makedirs(outputs,exist_okTrue)print(正在生成周报...\n)crewcreate_weekly_report_crew()# 方式1: 无参数 kickoffresultcrew.kickoff()print(\n*60)print(周报已生成)print(*60)# 获取结果的不同方式print(f\n【最终输出预览前500字】\n{result.raw[:500]}...)# 查看每个Task的输出摘要print(f\n【Task输出详情】)fori,task_outputinenumerate(result.tasks_output):print(f Task{i1}:{task_output.agent_role})print(f 输出长度:{len(task_output.raw)}字)print(f 输出文件: outputs/0{i1}_*.md)# 检查输出文件print(f\n【输出文件清单】)forfinsorted(os.listdir(outputs)):filepathos.path.join(outputs,f)sizeos.path.getsize(filepath)print(f{f}:{size}bytes)if__name____main__:main()3.4 运行结果python main.py典型输出正在生成周报... [2026-06-04 15:00:00][DEBUG]: Working Agent: 任务信息收集员 [2026-06-04 15:00:00][INFO]: Starting Task: 请从以下原始素材中提取... [2026-06-04 15:01:20][INFO]: Task completed successfully. [2026-06-04 15:01:20][DEBUG]: Working Agent: 进展分析师 [2026-06-04 15:01:20][INFO]: Starting Task: 基于任务状态报告... [2026-06-04 15:02:45][INFO]: Task completed successfully. [2026-06-04 15:02:45][DEBUG]: Working Agent: 风险分析师 [2026-06-04 15:02:45][INFO]: Starting Task: 基于任务状态和进展分析... [2026-06-04 15:04:10][INFO]: Task completed successfully. [2026-06-04 15:04:10][DEBUG]: Working Agent: 周报撰写员 [2026-06-04 15:04:10][INFO]: Starting Task: 综合前三步所有信息... [2026-06-04 15:05:30][INFO]: Task completed successfully. 周报已生成 【最终输出预览前500字】 # 用户中心重构 周报 - W23 ## 一句话总结 本周完成3个核心功能迭代权限管理和OAuth集成遇到阻塞下周需解决联调瓶颈。 ## 本周亮点 1. ✅ 用户登录页面重构完成张三2天高质量交付 2. ✅ 手机号验证码登录接口上线李四交付后经2次回滚修复稳定 3. ✅ 密码重置流程优化完成王五发现边界bug并紧急修复 ... 【Task输出详情】 Task 1: 任务信息收集员 输出长度: 645 字 输出文件: outputs/01_task_status.md Task 2: 进展分析师 输出长度: 782 字 输出文件: outputs/02_progress_analysis.md Task 3: 风险分析师 输出长度: 568 字 输出文件: outputs/03_risk_report.md Task 4: 周报撰写员 输出长度: 534 字 输出文件: outputs/04_weekly_report.md 【输出文件清单】 01_task_status.md: 2800 bytes 02_progress_analysis.md: 3400 bytes 03_risk_report.md: 2500 bytes 04_weekly_report.md: 2200 bytes3.5 对比如果只用 1 Agent 1 Task为了体现 Crew 协作的价值同样的素材如果只用一个 Agent 一个 Task# 单Agent单Task版本对照组single_agent_crewCrew(agents[Agent(role周报员,goal写一份周报,backstory你是一个写周报的人,llmllm)],tasks[Task(descriptionf请根据以下素材写一份周报{raw_data[raw_materials]},expected_output一份周报)],processProcess.sequential,verboseTrue)输出质量对比维度4 Agent 4 Task1 Agent 1 Task任务覆盖率100%所有任务都被列出约70%漏掉部分任务风险识别3个明确风险 1个沉默风险1个模糊风险提示可追溯性每步可独立审查无法追溯分析过程Token消耗~15000~4000耗时~5分钟~1分钟可用性可直接发送给管理层需要人工补充3.6 测试验证# test_weekly_crew.pyimportpytestfromcrewaiimportLLMfromagentsimportcreate_agentsfromtasksimportcreate_tasksfromtest_dataimportWEEKLY_RAW_DATAimportospytest.fixturedefllm():returnLLM(modelgpt-4o-mini)deftest_all_agents_created(llm):agentscreate_agents(llm)assertlen(agents)4roles[a.roleforainagents]assert任务信息收集员inrolesassert进展分析师inrolesassert风险分析师inrolesassert周报撰写员inrolesdeftest_tasks_have_proper_context(llm):collector,progress,risk,writercreate_agents(llm)taskscreate_tasks(collector,progress,risk,writer,WEEKLY_RAW_DATA)assertlen(tasks)4# Task 1: 无context依赖asserttasks[0].context[]# Task 2: 依赖Task 1assertlen(tasks[1].context)1# Task 3: 依赖Task 1 Task 2assertlen(tasks[2].context)2# Task 4: 依赖Task 1 Task 2 Task 3assertlen(tasks[3].context)3deftest_output_directory():os.makedirs(outputs,exist_okTrue)assertos.path.exists(outputs)deftest_raw_data_complete():验证测试数据包含所有必需字段assertprojectinWEEKLY_RAW_DATAassertweekinWEEKLY_RAW_DATAassertlen(WEEKLY_RAW_DATA[risk_signals])4assertUC-101inWEEKLY_RAW_DATA[raw_materials]deftest_each_agent_has_unique_role(llm):agentscreate_agents(llm)roles[a.roleforainagents]assertlen(roles)len(set(roles)),Agent角色不应重复pytest test_weekly_crew.py-v# 5 passed4. 项目总结4.1 优点与缺点维度Crew多Agent协作单Agent多Task纯Prompt专业度高各Agent有独立专业视角中视角单一但流程清晰低完全依赖prompt输出质量高互相校验减少遗漏中高少了一次交叉验证中低依赖使用者经验成本高多次LLM调用 context传递中多次LLM调用但context较轻低单次调用调试难度中verbose逐Task排查低Task粒度更细高无法定位问题步骤可复用性中Crew整体可复用高每个Task可独立复用低扩展性高增减Agent灵活高增减Task灵活低4.2 适用场景推荐使用多 Agent Crew 的场景需要多视角交叉验证的报告生成周报、复盘、评审一个任务需要不同专业知识背景如法律财务技术输出质量要求高且允许一定延迟非实时场景企业级知识工作流有审批和质量管控需求可审计和可追溯的AI应用不推荐使用的场景实时聊天或交互场景多Agent延迟太高极其简单的数据处理过度设计4.3 注意事项Process选型基础阶段建议全部使用 Sequential避免 Manager Agent 带来的不确定性和额外成本。Agent数量控制4个Agent已经足够覆盖大多数基础场景。超过6个Agent时Token传递成本会急剧上升。Verbose日志开发阶段开启生产阶段关闭。verbose日志包含完整的Prompt内容泄露到生产日志中可能带来安全风险。kickoff的返回值result.raw只包含最后一个Task的输出。如果你需要中间结果使用result.tasks_output[i].raw。4.4 常见踩坑经验案例1Crew运行到第3个Task时报context too long现象前2个Task正常第3个开始报错或输出截断。根因前序Task的累积输出超过了模型的上下文窗口gpt-4o-mini约128K但实际有效利用率远低于理论值。解决在每个Task的expected_output中限制输出长度或在中间Task中要求Agent做摘要而非全量传递。案例2结果result.raw竟然是None现象Crew运行日志显示成功但result.raw返回None。根因最后一个Task没有输出正确的raw格式或者所有Task都只写了output_file最终返回为空。解决检查最后一个Task的expected_output是否配置正确确保Agent确实生成了内容。案例34个Agent的输出风格差异极大现象Task1用中文Task2突然用英文Task3的格式完全不是expected_output指定的样子。根因Agent的backstory中存在角色定位差异模型基于不同的人设选择了不同的表达习惯。解决在Agent的backstory中统一语言要求如始终使用中文或者在LLM初始化时指定语言偏好。4.5 思考题如果项目周报的素材不仅来自Jira和Slack还包括GitHub Issues和Confluence文档——你需要增加Agent还是修改现有Agent增加Agent的决策标准是什么本章使用Sequential Process实现流水线式的周报生成。如果改为Hierarchical Process让Manager Agent动态决定’先分析风险再收集补充信息’还是’先全面收集再统一分析’会带来什么好处和风险你在什么情况下会选择这种方案答案将在后续章节揭晓。延伸阅读与资源10倍开发者的 Dify 魔法书从零构建全栈 AI 应用后端工程师转型AI第一课-Ollama 与私有化大模型实战大型语言模型(LLM) vLLM 高性能推理落地实战Agent开发之LlamaIndex 实战修炼与源码进阶大语言模型Transformers 实战修炼与源码剖析
阅读完成 · 觉得有帮助？
