第 5 篇把内容流水线重构成了 Flow 编排,流程的硬控制已经握在手里;但回看 Crew 自带的两种 Process,还有一半我们始终没启用——hierarchical。前五篇的每一次 kickoff 都走 sequential:任务顺序由列表决定、分派写死在 Task 的 agent 字段里,写手的活永远不会派给研究员。这份确定性是优点,也是天花板:当"下一步该谁干、干几轮"需要看着办时,写死的流程就不灵了。
本篇是《CrewAI 由浅入深》第 6 篇、进阶收官:讲透 hierarchical 的经理派活机制,并把散落前五篇的观测手段收拢成一套系统的调试方法——多角色系统越自动,出问题时越要会看。全文按"机制 → 上手 → 委派循环 → 调试工具箱 → 三层排查 → 成本账 → 双跑实测"展开,版本口径同前五篇:PyPI 上的 CrewAI v1.15.41,2026 年 11 月。
1、层级流程是什么
Process 枚举只有两个值:sequential 与 hierarchical。后者在Processes 官方文档里的描述是——CrewAI 创建一个经理 Agent,由它给成员分派任务、验证产出、评估完成度,直到全部任务完结。一句话立住对照:sequential 是你提前排好流水线,hierarchical 是雇一位调度员现场派活。
两种流程的形状对比如下:
解读这张图:顺序流程里的箭头来自任务列表的顺序,成员之间的信息靠上下文自动传递——第 1 篇的三角色跑的就是它;层级流程的中心换成经理,派活从它出、产出到它验收,成员之间不再直接传话。换来的是三种顺序流程给不出的能力:按角色能力动态认领任务、验收不过打回重做、中途改派换人。代价同样明显——经理是多出来的一整个角色,每轮委派与验收都是一次模型推理,而且执行路径不再由你决定。
所以官方从未把 hierarchical 当成更高级的默认项:两种策略没有高下,只有任务形状合不合。选型判断本篇第 7 节用双跑实测给出,这里先把机制上手。
2、最小配置跑通层级流程
启用门槛只有一条:process 换成 Process.hierarchical 的同时,必须二选一配 manager_llm 或 manager_agent,缺了直接启动报错——第 1 篇第 6 节埋过的坑,现在正面填上。最小配置如下:
from crewai import Crew, LLM, Process
crew = Crew(
agents=[researcher, writer, reviewer],
tasks=[research_task, write_task, review_task],
process=Process.hierarchical, # 层级流程
manager_llm=LLM(model="deepseek/deepseek-chat"),
verbose=True, # 经理每次派活与验收都打印
)
result = crew.kickoff(inputs={"topic": "CrewAI 层级流程"})
print(result.token_usage)
解读四个要点。其一,manager_llm 是经理的大脑,传模型名字符串或 LLM 实例皆可;它只管调度,与成员各自挂什么模型互不相干——这个解耦是第 6 节省成本的关键。其二,任务不再依赖 agent 字段预派:经理按成员的角色档案(role、goal、backstory)动态分派,建议干脆不写,把分派权完全交给经理。其三,经理默认由框架用 manager_llm 自动组装;想自定义经理的人设、目标甚至工具,用 manager_agent 传入一个自己写的 Agent。其四,verbose=True 在层级流程里的价值比顺序流程更大——经理的每一次派活、验收、打回全在日志里,这是观察委派机制的唯一窗口。
3、经理的委派循环
机制层面,kickoff 之后经理进入一个"规划 → 派活 → 验收"的循环。它面前摆着三样东西:未完工的任务清单、每个成员的角色档案与工具清单、已完成任务的产出。每一轮它做一次推理——下一步干什么、派给谁、附带什么指令;被派的成员执行完交活,经理对照 Task 的 expected_output 验收,不满意就打回重做或改派他人,直到判定整个清单完结。
从机制能推出四个结论。分派是动态的:同一件活可能被拆给两个人,也可能中途换人。expected_output 的地位升级了:从"给模型的验收参考"变成"经理的验收标准",写得含糊,打回次数直线上升。开销是结构性的:每轮委派与验收各一次模型推理,任务清单与历史产出还反复进入经理上下文,第 6 节算这笔账。路径不可预测:sequential 跑五次路径一致,hierarchical 跑五次可能五种分派顺序。
这个特性正是社区争议的源头。GitHub 仓库的 issue 区对 hierarchical 的批评集中在两点:抽象重,多出的经理层让规模化场景下的调试难度陡增;报错不露根因,异常被经理的流程层层包装,用户看到的常是一句笼统的"任务失败",真正的原因埋在几层之下。批评成立,但不等于不能用——应对就两条:调试手段工具化,排查顺序方法化。这正是下半场的主题。
4、调试工具箱
先盘家底。CrewAI 的调试设施分三层:代码内开关看现场、落盘日志供回溯、CLI 命令做复现(参数细节见Crews 概念文档)。清单如下:
| 工具 | 典型用法 | 解决的问题 |
|---|---|---|
verbose |
Crew 与 Agent 分别开启 | 实时观察派活与角色执行 |
output_log_file |
传 True 落盘 logs.txt,或传路径 | 运行后回溯全程,免刷屏 |
tasks_output |
遍历 CrewOutput 逐任务输出 | 定位哪个环节产出跑偏 |
crewai replay |
加 -t 任务号重放指定任务 | 只重跑出错环节,省 token |
crewai test |
加 -n 次数连跑出对比报告 | 量化输出稳定性与路径漂移 |
CLI 命令在 crewai create crew 脚手架项目里的形态如下:
crewai test -n 3 # 同一输入连跑 3 次,生成对比报告
crewai replay -t a1b2c3d4 # 从指定任务起重放最近一次执行
crewai log-tasks-outputs # 列出上次执行各任务的输出
用法上有个先后链条:先开 output_log_file 跑全程留档——文件名以 .json 结尾时落盘的就是结构化 JSON 日志,方便脚本处理;复盘时用 crewai log-tasks-outputs 找到出错任务;再用 crewai replay -t 任务号 从断点续跑,上下文保留,不必每次从头烧全流程。crewai test 的价值在层级流程下尤其大——几次运行的报告一对比,经理每次怎么分派、路径怎么漂移,一目了然。
5、从外向内三层排查法
工具箱解决"用什么看",排查法解决"按什么顺序看"。CrewAI 报错的通病上一节提过:根因要么压在栈回溯最底部的原始异常里,要么根本不报错、只是产出不对。应对是把系统想象成三层洋葱,从外向内剥,每清零一层再进下一层:
- 外层,环境与配置:密钥、模型名、版本、process 配套
- 中层,流程与任务:占位符、上下文传递、验收标准
- 内层,角色与提示词:人设、工具描述、模型能力
外层排"能不能跑"。kickoff 前后就炸的,九成是配置:hierarchical 忘配 manager_llm 是本篇新增的头号坑;其余是密钥失效、LiteLLM 的 provider 前缀写错、Python 版本越界(>=3.10 且 <3.13)。读栈的纪律只有一条:翻到最底部的原始异常再下判断——CrewAI 包装后的异常消息常常只是一句"任务执行失败",那是包装纸,不是根因。
中层排"流程对不对"。跑通了但产出不对,用 verbose 加 tasks_output 逐环节检查,第 1 篇的方法在层级流程同样适用,只是检查单位从"任务"变成了"委派轮次"。高频病因三个:占位符没填——任务描述里的 {topic} 在日志里原样出现就是证据;上下文断层——打回重做时该带的产出没进新指令;验收标准含糊——expected_output 写成"一份好报告",经理的验收全凭感觉,轮次跟着失控。
内层排"角色行不行"。前两层清零后仍持续掉链子的环节才归角色管:研究员总查不到东西,先改工具描述;写手总跑题,先收紧 goal 与 expected_output 的约束;整体能力不足,换模型。到这一层才值得动提示词——跳过前两层直接改提示词,是多角色系统里最常见的 token 焚烧。
调试多角色系统的纪律:先问配置,再问流程,最后才问提示词。
6、token 成本账
hierarchical 的开销来自三处:经理每轮委派与验收各一次推理;任务清单、成员档案与历史产出在经理上下文里反复出现,委派轮次越多滚得越大;动态分派的副作用是同一件活可能被做两遍——打回与改派都算重做。系列三角色场景实测,hierarchical 比 sequential 多烧约 18% 的 token;三角色尚且如此,成员越多、轮次越多,超支越狠。
缓解三招,头一招最立竿见影:给经理换小模型。经理干的是读清单、派人、对标准的调度活,不是创作——manager_llm 单独挂一个便宜快的模型,成员照用强模型,与第 2 篇 function_calling_llm 的分工是同一个思路。示例如下:
crew = Crew(
agents=[researcher, writer, reviewer], # 成员各自挂强模型
tasks=[research_task, write_task, review_task],
process=Process.hierarchical,
manager_llm=LLM(model="deepseek/deepseek-chat"), # 经理换小模型
)
解读:这份配置与第 2 节只差注释里点破的事实——经理与成员的模型各自独立指定、互不牵连,省钱就省在把调度活从强模型手里拿走。第二招收敛验收标准:经理的打回多半源于 expected_output 不可判定,把"一份好报告"改写成"800 字、三个小节、每条结论带来源",验收一次过,轮次立减。第三招最诚实:分工天然固定的场景退回 sequential;需要循环、上限与硬校验的,别在 Process 里找,上 Flow——第 5 篇的审核路由,本质就是不要经理的"代码版验收",一次 Python 判断顶经理一整轮推理。
7、双跑对比实测
实验设置:同一需求——围绕主题出一份 500 字调研快讯,成员仍是研究员(带搜索工具)、写手、审核员;sequential 按第 1 篇组装,hierarchical 按第 2 节组装,各跑三次。对比如下:
| 维度 | sequential | hierarchical |
|---|---|---|
| 产出质量 | 三次均一次过关 | 两次过关,一次打回两轮 |
| token 消耗 | 基准 | 约多 18% |
| 耗时 | 基准 | 更长,每轮派活验收都是往返 |
| 路径稳定性 | 三次路径一致 | 三次分派顺序各不相同 |
| 计划外动作 | 无 | 追加过一轮数字复核 |
两个观察值得展开。其一,质量侧没有出现"层级更聪明"的碾压:三角色、三任务的小场景里分工本来就清晰,经理的调度空间不大,它的价值要到"该谁干不明确"的任务形状才兑现。其二,那轮数字复核是 hierarchical 的真实收益——经理验收时怀疑快讯里的年份,追加派回研究员二次查证,这种计划外的一轮 sequential 写不出来;反面是同批实测里一次纯属浪费的打回:嫌措辞不精彩让写手重写,快讯还是那个快讯。收益与浪费同源,都来自经理的裁量权——用它,就要接受它的随机性。
选型结论一句话收拢:分工固定的流水线用 sequential;任务形状多变、需要现场判断"接下来谁干什么"的用 hierarchical;要循环、上限与硬校验的,上 Flow。
8、总结
本文讲完了 CrewAI 流程模型的另一半:hierarchical 让一个经理 Agent 接管分派,kickoff 后进入"规划、派活、验收"的循环,expected_output 升级为经理的验收标准;上手只需 process=Process.hierarchical 加 manager_llm(或自定义的 manager_agent),忘配直接报错。调试上,verbose 与 output_log_file 看现场,crewai replay -t 从断点续跑,crewai test -n 量化路径漂移,排查按"配置、流程、提示词"从外向内三层剥。成本上,经理每轮推理叠加上下文滚雪球,三角色场景约多 18% 的 token,头号缓解是给经理换小模型。双跑实测的结论很朴素:动态分派买来的是裁量权与随机性,分工清晰时不必付这笔钱。
三个练习留给读者:
- 把第 1 篇的三角色 Crew 改成 hierarchical 双跑,开 verbose 对比两种日志里派活环节的差异
- 故意不配 manager_llm 触发一次报错,读到最底部的原始异常;再给经理换小模型,对比 token_usage
- 在脚手架项目里用 crewai test -n 3 各跑两种流程,对照报告观察分派路径的稳定性
进阶篇到此收官,源码篇从第 7 篇开始进入 CrewAI 内部:kickoff 之后的执行管线、任务与上下文的组装、Process 的分发逻辑——本文那些"报错不露根因"的现象,到源码里都能找到发生的位置与包装的层级。对于仍在两种 Process 之间犹豫的工程师,建议照第 7 节的双跑自己实验一次:两份 verbose 日志读下来,经理值不值这 18%,你会比读任何文档都清楚。

