上周五凌晨两点我盯着终端里一行诡异的报错发呆——CrewAI 跑出来的结果里两个 Agent 居然互相覆盖了对方的输出字段。一个负责写技术文档的 Researcher把另一个负责代码审查的 Reviewer 的结论给吞了。这不是 bug是我没搞清楚 CrewAI 的角色隔离机制。如果你也遇到过“多智能体协作时A 干了 B 的活”或者“最终结果里某个 Agent 的输出莫名其妙消失了”那这篇笔记就是为你写的。角色分配别把 Agent 当函数用很多人刚接触 CrewAI 时习惯把每个 Agent 当成一个独立的 API 调用——定义角色、给个 prompt、扔进去跑。这其实是在用单智能体的思维做多智能体协作。CrewAI 的角色分配核心在于职责边界。不是“这个 Agent 负责写代码”而是“这个 Agent 在什么场景下、以什么身份、对什么类型的输入做出响应”。我踩过的一个坑给两个 Agent 都设置了allow_delegationTrue结果它们互相把任务甩给对方陷入了死循环。正确的做法是给每个 Agent 一个明确的“领地”。比如# 这里踩过坑不要用模糊的 role 描述researcherAgent(role技术调研员,goal从给定技术文档中提取关键信息,backstory你只负责阅读和总结不参与任何代码编写或决策,allow_delegationFalse# 别让它把活甩给别人)backstory字段不是装饰品。CrewAI 的底层会用这个字段来约束 Agent 的行为边界。如果你写“你是一个全能的工程师”那它就会试图干所有事包括抢别人的活。任务委派不是发指令是签合同任务委派最容易出问题的地方在于上下文传递。我见过最典型的错误把一个大任务拆成几个子任务然后每个子任务都重新加载一遍完整的上下文。结果 Agent 们各自为政输出之间毫无关联。CrewAI 的任务委派机制更像是一种“契约”——每个 Task 不仅定义了要做什么还定义了依赖什么和产出什么。task1Task(description分析用户提供的日志文件提取所有错误码,expected_output一个包含错误码及其出现次数的字典,agentresearcher)task2Task(description基于错误码字典生成修复建议,expected_output每个错误码对应的修复步骤列表,agentfixer,context[task1]# 别这样写把 task1 的整个输出塞进去)注意context参数。很多人以为这里传的是“前一个任务的输出”其实传的是前一个任务的完整执行记录包括中间思考过程。如果你的 Agent 的 prompt 里没有明确告诉它“只关注最终输出忽略思考过程”它可能会被上下文里的废话带偏。我习惯在expected_output里明确指定输出格式并且在description里加一句“只输出最终结果不要包含推理过程”。这能省掉很多后期解析的麻烦。结果聚合最容易被忽视的环节多智能体协作的最终输出往往不是某个 Agent 的单独结果而是多个 Agent 输出的组合体。CrewAI 默认会把所有 Agent 的输出按顺序拼接但实际场景中我们需要的是结构化聚合。举个例子一个写代码的 Agent 和一个写测试的 Agent它们的输出应该合并成一个完整的项目文件而不是两段独立的文本。我踩过的一个大坑用Crew的output属性直接拿结果发现两个 Agent 的输出字段名冲突了。CrewAI 内部用 Agent 的名字作为 key如果你两个 Agent 名字相似比如coder_agent和tester_agent解析时很容易搞混。解决方案是显式定义输出处理器defaggregate_results(outputs):# 这里踩过坑不要假设 outputs 的顺序codeoutputs.get(coder_agent,)testsoutputs.get(tester_agent,)returnf# 代码\n{code}\n\n# 测试\n{tests}crewCrew(agents[coder,tester],tasks[code_task,test_task],output_processoraggregate_results)注意output_processor这个参数。CrewAI 的较新版本支持自定义聚合函数但文档里写得很隐晦。如果你用的是旧版本可能需要手动遍历crew.tasks来收集结果。调试技巧让 Agent 开口说话多智能体协作最头疼的问题是黑盒——你不知道哪个 Agent 在哪个环节出了问题。我的经验是在 Agent 的backstory里加一句“在每次输出前先输出当前任务的名称和你的角色”。debug_agentAgent(role调试助手,backstory你会在每次输出前打印[DEBUG] 当前任务: xxx, 角色: xxx,...)这样在最终输出里你能看到每个 Agent 的执行轨迹。如果某个 Agent 的输出缺失看日志就能定位到是它没执行还是执行了但结果被覆盖了。另一个实用技巧给每个 Task 设置verboseTrue。CrewAI 会打印出 Agent 的思考过程虽然信息量大但排查“为什么这个 Agent 没按预期工作”时非常有用。个人经验别迷信“多智能体一定比单智能体好”。我见过太多项目明明一个 Agent 加一个精心设计的 prompt 就能搞定非要拆成三四个 Agent结果引入了一堆协调问题。CrewAI 的真正价值在于角色隔离——当你的任务确实需要不同专业背景的知识时才值得用多智能体。比如一个 Agent 负责读技术文档另一个负责写代码第三个负责测试。如果只是把同一个任务拆成几步那用 pipeline 模式比多智能体更稳定。最后记得给每个 Agent 设置max_iter参数。默认情况下Agent 可能会无限循环思考尤其是当任务描述不够清晰时。我一般设成 3-5 次超过就强制输出当前结果。宁可结果不完美也比卡死强。