用裸 SDK 写单 Agent,工具循环已经不成问题:messages 列表、tool call 分发、重试兜底,一个 while 全能装下。真正的麻烦出在职责上——同一个 Agent 既调研、又写作、还审核,提示词越堆越长,模型在三种身份间来回切换,每多兼一份职责,输出质量就被稀释一分。人类的解法很老:分工。调研交给研究员、成稿交给写手、把关交给审核员,各自带着各自的上下文做各自擅长的事。
CrewAI 把这套分工直接做成了框架的一等公民。《CrewAI 由浅入深》共 9 篇(入门 3 篇、进阶 3 篇、源码 3 篇),本篇是第 1 篇:从安装到跑通一个"研究员 → 写手 → 审核员"的三角色 Crew,并把 Agent、Task、Crew 三要素的心智模型立住。全文按"定位 → 安装 → 编码 → 运行 → 心智模型 → 踩坑"展开。
1、CrewAI 定位与版本现状
CrewAI 由 crewAIInc 公司开发,源码在 GitHub 仓库,截至 2026 年 11 月约 60.9k star,PyPI 最新版 v1.15.41(2026-11-13 发布)。它的核心主张一句话讲完:别画流程图,去组建团队。你不编排节点与边,而是写"岗位描述"——每个 Agent 有角色、目标、背景故事,每个 Task 有职责与交付物,Crew 把两者装进一个 Process 里自动流转。
这与 LangGraph 的图式编排(完整打法见本站 LangGraph 系列)是两种正交的心智:LangGraph 的世界由节点与边构成,控制流显式画在图上,精确但琐碎;CrewAI 的世界由岗位与任务构成,控制流交给 Process 粗粒度策略,省心但对流转细节的控制弱一档。在多 Agent 框架谱系里,CrewAI 是最"角色中心"的一派——AutoGen 主打对话协作,LangGraph 主打图编排,它则把"团队"这个隐喻贯彻到了 API 命名层。对比如下:
| 维度 | CrewAI | LangGraph |
|---|---|---|
| 心智模型 | 组建团队 | 画流程图 |
| 基本单元 | 角色化 Agent 与 Task | 节点函数与边 |
| 控制流 | Process 粗粒度策略 | 显式图结构 |
| 擅长场景 | 分工明确的协作流水线 | 精确控制流转的工作流 |
两种心智力气往不同的方向使。用 LangGraph,你手里攥着每一跳的走向,代价是三节点的小流程也要写 builder;用 CrewAI,你交出流转的控制权,换来的是"写岗位描述就能跑"的开发速度。经验上:流程形状固定、角色分工天然清晰的任务(调研成稿、翻译审校、代码评审),CrewAI 十几行就能起跑;流程本身多变、要按状态动态路由的,再考虑下沉到图。
版本现状需要交代一句,免得与网上旧资料对不上号。经典四件套 Crew、Agent、Task、Process 从未标记 legacy,至今仍是一等公民;但官方叙事已转向 Flows 优先——官方文档明言"For any production-ready application, start with a Flow"。两者不冲突:Flows 是外层的工作流骨架,Crew 是骨架里的协作单元,本系列第 4 篇专门讲;本篇先把经典 Crew 模型吃透,它是后面一切的地基。
2、安装与脚手架
环境要求:Python >=3.10 且 <3.13。库本体用 pip 安装即可:
pip install crewai
装完的包自带 crewai 命令行工具(官方安装文档另推荐 uv tool install crewai 的独立安装方式)。用脚手架起一个项目,命令如下:
crewai create crew blog_crew
命令执行后生成的目录结构如下(摘自官方安装文档):
blog_crew/
├── .gitignore
├── knowledge/
├── pyproject.toml
├── README.md
├── .env
└── src/
└── blog_crew/
├── __init__.py
├── main.py
├── crew.py
├── tools/
│ ├── custom_tool.py
│ └── __init__.py
└── config/
├── agents.yaml
└── tasks.yaml
各文件的分工如下:
| 文件 | 职责 |
|---|---|
agents.yaml |
声明 Agent 的角色、目标与背景 |
tasks.yaml |
声明 Task 的描述与交付物 |
crew.py |
组装 Crew 并挂接配置 |
main.py |
入口:准备输入并启动 |
.env |
存放模型密钥等环境变量 |
tools |
自定义工具目录 |
脚手架推荐把角色与任务写进 YAML,这个选择留到第 3 节末尾评价。首次运行前在项目根目录执行 crewai install 装依赖,之后 crewai run 一条命令即可跑通。
3、第一个多角色 Crew
任务设定:给一个主题,产出一份可发布的博客终稿。流水线三个人——研究员查资料、写手成稿、审核员把关。这三个岗位恰好覆盖了内容生产的三种能力(检索、表达、判断),互相之间的交付物都能用自然语言描述清楚,是练手多角色协作最合适的形状。本文采用直接代码定义的写法,比 YAML 流派少一层间接,心智模型更直给。
3.1、定义三个 Agent
Agent 的三个核心字段:role 是岗位头衔,goal 是这个岗位追求什么,backstory 给模型一段"人设"。三段文字会被拼进系统提示词,直接塑造这个角色的行为倾向。示例如下:
from crewai import Agent, Crew, Task, Process
researcher = Agent(
role="资深技术调研员",
goal="围绕主题收集准确、最新的关键事实与数据",
backstory="十年科技行业调研经验,擅长定位信息源并交叉验证",
verbose=True,
)
writer = Agent(
role="技术专栏写手",
goal="把调研结果写成结构清晰、观点明确的技术博客",
backstory="长期为工程团队撰稿,行文重逻辑与实例,讨厌空话",
verbose=True,
)
reviewer = Agent(
role="审稿编辑",
goal="把关事实准确性与可读性,输出修订终稿",
backstory="挑剔的技术编辑,容不下含糊结论与无出处数字",
verbose=True,
)
解读:三个 Agent 各自带一份独立上下文。研究员不需要知道写作规范,写手不需要懂调研方法论——每个角色的提示词只装它这个岗位该装的东西,这正是分工在提示词工程上的价值。
3.2、定义三个 Task
Task 的两个关键字段:description 描述这件活怎么干,expected_output 约定交付物长什么样——后者作为验收标准传给模型,写得越具体输出越稳定。示例如下:
research_task = Task(
description="针对主题 {topic} 收集 3~5 条关键事实,"
"每条注明来源与时间,剔除不可靠信息。",
expected_output="一份带来源标注的要点清单",
agent=researcher,
)
write_task = Task(
description="基于调研要点写一篇 800 字左右的博客初稿,"
"包含引言、正文与结论。",
expected_output="Markdown 格式的博客初稿",
agent=writer,
)
review_task = Task(
description="审核初稿:核对事实、修正表述,返回修订终稿。",
expected_output="修订后的博客终稿(Markdown)",
agent=reviewer,
)
两个细节值得注意。其一,description 里的 {topic} 是占位符,运行时由 kickoff 的 inputs 填充。其二,顺序流程中上一个 Task 的输出会自动成为下一个 Task 的上下文——写手拿到的就是研究员那份要点清单,不需要手工传递。
默认传递之外还可以显式控制:Task 有个 context 参数,接收前置任务的列表,指定"这件活要参考谁的产出"。默认行为够用时不用碰它;当流水线分叉再汇合(比如两个调研任务汇给一个写手)时,用它精确圈定上下文来源。
3.3、组装 Crew 并启动
最后把人和活装进 Crew。Process.sequential 声明顺序执行,它其实就是默认值,显式写出只为可读。示例如下:
crew = Crew(
agents=[researcher, writer, reviewer],
tasks=[research_task, write_task, review_task],
process=Process.sequential, # 顺序执行,默认值
verbose=True,
)
result = crew.kickoff(inputs={"topic": "CrewAI 多角色协作"})
print(result.raw)
kickoff 一声令下,框架按 tasks 列表顺序逐个执行:研究员先动,产出写进上下文;写手接着读上下文干活;审核员最后收尾。整个协作你只写了岗位描述与任务说明——流程本身一行都没写。
回头看第 2 节的脚手架:YAML 流派把 role、goal 等字段挪进 agents.yaml、tasks.yaml,crew.py 里用 @agent、@task、@crew 装饰器组装,字段含义完全一致。团队规模大了以后配置与代码分离更好维护,入门阶段直接写代码反而更清楚。
4、运行与输出结构
在脚手架项目里 crewai run 启动(首次先 crewai install),纯脚本场景直接 python main.py。kickoff 返回的不是字符串,而是一个 CrewOutput 对象(详见Crews 概念文档),主要属性如下:
| 属性 | 说明 |
|---|---|
raw |
最终任务的输出文本 |
tasks_output |
每个 Task 的输出列表 |
token_usage |
全程 token 消耗统计 |
pydantic |
结构化输出时的 Pydantic 对象 |
json_dict |
结构化输出时的字典形态 |
取值示例如下:
result = crew.kickoff(inputs={"topic": "CrewAI 多角色协作"})
print(result.raw) # 终稿全文
for t in result.tasks_output: # 每个环节各产出什么
print(t.agent, "→", t.raw[:50])
print(result.token_usage) # 花了多少 token
调试时最有用的是 tasks_output:终稿不满意,逐个环节检查是调研没查到、写手跑偏还是审核漏改——多角色流水线把"输出质量问题"定位成了"某个角色的问题",这是单 Agent 长提示词给不了的排查粒度。生产环境还可以给 Crew 传 output_log_file=True,把全程日志落盘成 logs.txt 供事后排查。
kickoff 其实是一族方法:kickoff_for_each 接一组输入批量跑(比如十个主题各出一份终稿)、kickoff_async 异步启动不阻塞主线程。排查工具也有配套——crewai replay -t <task_id> 能从最近一次执行中的指定任务重放,上下文保留,不必每次都从头烧 token。
另外表格里的 pydantic 与 json_dict 平时为空,只有给最终 Task 配了 output_pydantic(传 Pydantic 模型)或 output_json=True 时才有值:框架会约束模型按 schema 交付,下游代码直接拿结构化对象,不用再解析一段自由文本。
5、三要素心智模型
把本篇的经验收拢成一句话:Agent 是"谁",Task 是"做什么",Crew 是"团队章程"。Agent 只定义身份与倾向,不定义流程;Task 只定义一件活与交付标准,并把活派给某个 Agent;Crew 圈定成员名单、任务清单与执行策略,是团队层面的章程。三要素的边界整理成表:
| 要素 | 回答的问题 | 关键字段 |
|---|---|---|
| Agent | 谁来干 | role、goal、backstory |
| Task | 干什么、交什么 | description、expected_output |
| Crew | 怎么组队、怎么流转 | agents、tasks、process |
这张表也是排错顺序表:输出跑偏先查 Task 的 expected_output 写没写清,风格不对再调 Agent 的 backstory,流转错了才动 Crew。整条流水线画出来:
解读这张图:三个角色之间的两条依赖来自 tasks 列表的顺序,而非手工连线;章程(subgraph)只决定"按什么策略流转",不插手每个岗位内部怎么干。想换流转策略,改的只是章程——比如换成 hierarchical 让经理 Agent 动态派活(需配 manager_llm)——岗位描述一个字不用动。这套"身份与流程分离"的设计,是 CrewAI 全部高级能力的支点。
6、常见坑
模型没配对,报错在最前面。Agent 不指定 llm 时默认走 OpenAI 系模型,OPENAI_API_KEY 没配会直接启动失败。换其他厂商的模型时用 LiteLLM 的 provider 前缀写法,密钥放 .env(脚手架已内置加载)。示例如下:
from crewai import LLM
llm = LLM(
model="deepseek/deepseek-chat", # provider/model 格式
api_key="sk-xxx",
)
researcher = Agent(
role="资深技术调研员",
goal="围绕主题收集准确、最新的关键事实",
backstory="十年调研经验,擅长交叉验证信息源",
llm=llm, # 该角色单独用这个模型
)
不同角色可以挂不同模型——重活给强模型、杂活给便宜模型,成本立省一截。
verbose 日志又长又香。verbose=True 会打印每个角色的完整思考与执行过程,调试期是救命稻草,稳定后是刷屏噪音,按阶段开关即可。Python 版本也常被忽略:CrewAI 要求 >=3.10 且 <3.13,用 3.13 的环境装包时就会失败。
层级流程忘配经理。本篇通篇用顺序流程,试层级流程(Process.hierarchical)时必须同时配 manager_llm 或 manager_agent,否则启动直接报错——没有经理,派活这件事没人负责。这个坑在官方文档 Processes 页写得明确,动手改练习三时先记住它。
7、总结
本文从零跑通了一个三角色 Crew:Agent 用 role、goal、backstory 定义"谁",Task 用 description 与 expected_output 定义"做什么",Crew 用 Process 把两者装成一条顺序流水线,kickoff 返回带 raw、tasks_output、token_usage 的 CrewOutput。框架替你做了三件脏活——岗位提示词的拼装、任务间上下文的传递、执行日志与 token 的记账——你付的对价只是把单 Agent 的长提示词拆成几份岗位描述。版本现状也交代了:经典 Crew 模型未过时,但官方主干叙事已是 Flows,本系列第 4 篇正面讲。
三个练习留给读者:
- 换一个自己领域的主题重跑,对照 verbose 日志观察要点清单如何流到写作环节
- 把
expected_output改成固定小节结构(如"背景、要点、结论"),观察输出稳定性变化 - 把
process换成 hierarchical 并配manager_llm,观察经理 Agent 如何派活
对于想上手多角色协作的工程师,建议先按本文把顺序流水线原样跑通再谈其他——角色分工的直觉建立之后,工具、记忆、层级流程都只是往这副骨架上添肉。

