CrewAI 实战:把多 Agent 协作做成"搭积木"的框架
GitHub 上 5.7 万 Star 的 crewAIInc/crewAI 是个有意思的项目。它不教你写状态机,也不跟你聊对话哲学,而是把多 Agent 协作这件事压成三个概念:Agent(有角色人设的 LLM 调用)、Task(带依赖的任务)、Crew(团队)。再加一个 Process 参数决定执行方式。整个框架的体感,更像在写配置文件而不是写程序。
它解决什么问题
单 Agent 在长链条任务上有三面墙:
- 上下文窗口爆掉:研究-分析-写作这种流程塞进一个 prompt,token 撑爆
- 规划能力塌方:复杂任务拆解,LLM 直接给你跳步骤
- 工具调用混乱:搜索、计算、写文件混在一起,错一个全崩
AutoGen 偏对话式,Agent 之间靠 chat history 推,管控粒度粗;LangGraph 图状灵活,但要先学会画状态机。CrewAI 走中间路线——角色分工+任务链,Python 或 YAML 声明就能跑。本质是把多 Agent 协作从"写状态机"降级到"写 YAML 配置"。
怎么用
pip install crewai 装一下,准备 OpenAI 或 Anthropic 的 API Key。下面这段最小例子:定义一个 Researcher 和一个 Writer,串起来写一篇博客。
from crewai import Agent, Task, Crew, Process
from crewai_tools import SerperDevTool
import os
os.environ["OPENAI_API_KEY"] = "your-key"
os.environ["SERPER_API_KEY"] = "your-serper-key"
search_tool = SerperDevTool()
researcher = Agent(
role="研究员",
goal="搜集某主题的最新行业数据",
backstory="你是一名资深行业分析师,擅长从公开资料中提炼关键数字",
tools=[search_tool],
verbose=True
)
writer = Agent(
role="撰稿人",
goal="把数据写成 500 字短报告",
backstory="你是一名科技媒体编辑,文风简洁、结论先行",
verbose=True
)
task1 = Task(
description="搜索 2024 年中国 AI Agent 行业的融资数据",
expected_output="5 条关键融资事件,每条含公司名、金额、投资方",
agent=researcher
)
task2 = Task(
description="基于上面的数据,写一篇 500 字的行业短评",
expected_output="中文短评,结构清晰,含数据引用",
agent=writer,
context=[task1]
)
crew = Crew(
agents=[researcher, writer],
tasks=[task1, task2],
process=Process.sequential
)
result = crew.kickoff()
print(result)
跑起来你会看到 Researcher 先调搜索工具,再把结果交给 Writer。context=[task1] 这一行是核心——上游 Task 的输出自动塞进下游 Agent 的上下文,不用你手动管理。整个流程 32 行 Python 就跑通了。
它怎么工作
核心抽象分四层:
1. Agent:role + goal + backstory + tools + llm,是带"人设"的 LLM 调用单元。backstory 不是装饰——它会被拼进 system prompt,影响 Agent 的行为风格。
2. Task:description + expected_output + agent + context。context 是个列表,写明依赖哪些上游 Task,这些 Task 的输出会被注入到本 Task 的 prompt 里。任务结果靠 context 字段自动传递。
3. Crew:把 Agent 和 Task 装一起,配 Process 决定执行方式。
4. Process:分三种——
- sequential:顺序执行,最常用
- hierarchical:自动派生一个 Manager Agent 做委派,等于内建了"主管-执行"两层组织架构
- async:并行/异步触发
hierarchical 模式最值得展开。它启动时会动态 spawn 一个 Manager LLM,由它来决定哪个 Task 派给哪个 Agent、何时执行。本质上 CrewAI 把"项目管理"这层逻辑写死在框架里——你不用自己实现调度,只要设个开关。但代价也很明显:多烧一次 LLM 调用,token 成本几乎翻倍。小任务别开。
它哪里好 / 哪里不好
好的地方:
- YAML + Python 双声明,对不熟状态机的同学友好
- 5.7 万 Star,社区活跃,issue 响应快
- hierarchical 模式开箱即用,省去自己写调度逻辑
不好的地方:
- 国产模型适配要自己写 LLM wrapper,官方文档这块薄
- 长任务链路调试时,上下文传递链路不透明,出问题排查累
- 相比 LangGraph,图状控制和条件分支弱,复杂业务逻辑会被 Process 的三种模式框死
- 工具调用虽然支持,但 Function Calling 的错误处理比较粗糙
横向比:LangGraph 灵活但要自己画图;AutoGen 对话式但缺乏任务边界;CrewAI 介于两者,落地体感更像搭积木,代价是天花板低。
我试了下
跑了一个三 Agent 场景:Researcher 搜资料 → Analyst 整理数据 → Writer 写报告,sequential 模式,全用 gpt-4o-mini。
实测数据:
- 启动到第一次输出大约 12 秒(含 3 次 LLM 调用)
- 总 token 消耗约 4500 tokens(不算工具调用)
- 代码量:32 行 Python
对比单 Agent 直接 prompt 让它"搜索-分析-写报告":单 Agent 方案代码只有 8 行,但输出质量明显差——分析环节经常跳过,writer 环节把数据搞错。多 Agent 的隔离确实换来质量,前提是 LLM 够强。
踩到的坑:
- hierarchical 模式 Manager Agent 会多消耗一次 LLM 调用,token 成本几乎翻倍
- verbose=True 默认输出很啰嗦,生产环境记得关掉
- 工具调用失败时,CrewAI 重试机制比较弱,建议自己在外层包一层容错
谁该用
适合:
- 想快速搭多 Agent Demo / POC 的团队
- 业务流程天然是"分工协作"形态(研究-分析-写作、需求-开发-测试)
- 不想从零写状态机和上下文管理的工程师
不适合:
- 需要精细条件分支和循环控制的复杂逻辑(用 LangGraph)
- 对成本敏感的高频调用场景(多 Agent = 多倍 LLM 调用)
- 国产模型为主的项目(除非愿意写自定义 LLM 适配层)
- 生产级长链路任务(调试可观测性不够)
CrewAI 的定位很清晰:把多 Agent 这件事的门槛砍到最低。它不是最强的框架,但可能是 30 分钟内能跑起来的那个。如果你的场景是"几个 Agent 分工干一件事",它值得一试;如果你的场景是"复杂的条件分支+状态管理",老实上 LangGraph。