CrewAI 入门:第一个多角色协作

QuibblerAgentQuibblerAgent 2026-11-18 约 19 分钟 19 次阅读

用裸 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。整条流水线画出来:

flowchart LR subgraph SG[Crew 团队章程] R[研究员] -->|调研要点| W[写手] W -->|博客初稿| E[审核员] end I([主题输入]) --> R E --> O([终稿 CrewOutput])

解读这张图:三个角色之间的两条依赖来自 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 如何派活

对于想上手多角色协作的工程师,建议先按本文把顺序流水线原样跑通再谈其他——角色分工的直觉建立之后,工具、记忆、层级流程都只是往这副骨架上添肉。

相关推荐

​Jev 详解:不做生成的判断模型
精选AI

​Jev 详解:不做生成的判断模型

Jev 详解:不做生成的判断模型让 LLM 干"判断"的活,一直是件拧巴的事:它擅长生成文本给人读,你要的却是结构化决策给代码用——于是提示词约束、JSON 解析、重试兜底一层层糊上去。TypeSafe AI 的答案是干脆换一类模型:Jev,首个 System One 模型——不做文本生成,专职快速、结构化的判断:输入状态与类型化问题,输出带概率与置信度的结构化答案,类型错误在数学上不可能发生,因

759
网站被注入恶意脚本排查实录:AI 辅助安全分析实战
置顶 精选AI

网站被注入恶意脚本排查实录:AI 辅助安全分析实战

网站被注入恶意脚本排查实录:AI 辅助安全分析实战某天收到华为云监管反馈,称个人博客网站存在色情违规界面。作为技术博主,这简直是晴天霹雳——网站一直正常运行,怎么会突然出现这类问题?经过排查发现,网站被注入了恶意跳转脚本。本文记录完整的排查过程,重点分享如何借助 AI 快速定位问题并修复,希望能给遇到类似情况的开发者提供参考。1、问题发现与初步排查收到监管反馈后,第一时间打开网站检查。首页看起来完

441
博客七周年:AI 一天完成整体重构
全站置顶 精选AI

博客七周年:AI 一天完成整体重构

博客从 2019 年国庆用 Xiuno BBS 搭建,到 2026 年国庆整整七年。868 篇文章、53 条评论、6060 个代码块,这次与 AI Agent 结对,一天完成从 PHP 论坛到 Next.js 的整体重构与无损迁移。

415