CrewAI 快速入门

像搭剧组一样写代码:定角色、分任务,几个 AI 员工自己就能把活干完。

这是什么?适合谁?

CrewAI 是一个用 Python 写「AI 团队」 的开源框架。它的设计灵感来自现实中的工作团队——每个人都有角色(role)、目标(goal) 和背景故事(backstory),各自分到任务(task),在流程(process) 的安排下协同完成一项大工作。框架名字里的 Crew 就是「团队」的意思。

和单 Agent 框架(比如 AutoGPT)不同,CrewAI 强调的是多 Agent 协作:一个 Agent 写出来的稿子可以交给另一个 Agent 审校,审校完再交给第三个 Agent 翻译,最后由汇总 Agent 出终稿。这种「流水线式」的协作方式,在写作、研究、市场分析、代码审查等任务上比单 Agent 表现更稳,因为每个 Agent 都可以专注自己擅长的那一步。

从技术角度看,CrewAI 构建在 LangChain 之上,自带记忆、工具调用、任务委派、文件读写等模块。它提供了顺序流程(sequential) 和分层流程(hierarchical) 两种默认编排模式:顺序流程让 Agent 按列表顺序一个个执行任务,分层流程会自动创建一个「管理者 Agent」来动态分配任务给其他 Agent。两种模式分别对应了「流水线工厂」和「小组长带队员」两种工作方式。

适合谁?如果你已经熟悉 Python 基础语法,想用几十行代码搭一个能跑通的多 Agent 流水线,CrewAI 的学习曲线相对友好;如果你想做长链条的内容生成(比如研究报告、深度文章、跨语言翻译),CrewAI 的设计跟这种场景天然契合;如果你追求极简、不想自己写 Agent 之间的消息路由代码,选 CrewAI 比直接用 LangGraph 更省事。

不适合纯小白入门——你需要会装 Python 包、写简单 Python 文件、配置 API key;也不适合需要重型工作流编排(带分支、循环、条件判断)的工业级项目,这种情况下 LangGraph 或 OpenClaw 更合适。

准备工作

开始之前,请准备以下几样:

1. Python 3.10 及以上版本:访问 https://www.python.org/downloads/ 下载安装,Windows 用户记得在安装时勾选「Add Python to PATH」。
2. pip 包管理器:Python 3.10+ 自带 pip,可以在终端里输入 pip --version 验证。
3. 大模型 API Key:CrewAI 本身不绑定模型,你可以接 OpenAI、Anthropic、Ollama 本地模型,甚至国内的 DeepSeek、月之暗面 Kimi 等兼容 OpenAI 接口的服务。推荐先用 OpenAI 或 DeepSeek 试水。
4. 一个顺手的代码编辑器:VS Code 即可。

环境变量方面,建议在系统或 shell 里设置 OPENAI_API_KEY(或对应厂商的 key),CrewAI 会自动读取。

3 步快速上手

第 1 步:安装 CrewAI

打开终端,推荐用 pipx 或 venv 创建一个干净的虚拟环境,避免污染全局 Python:

python -m venv .venv
source .venv/bin/activate   # Windows PowerShell 用: .venv\Scripts\Activate.ps1
pip install crewai crewai-tools

crewai 是核心包,crewai-tools 提供一组开箱即用的工具(网页搜索、文件读写、代码执行等)。安装完成后,在终端输入 crewai --version 验证是否成功。

第 2 步:写一个最小可运行示例

在你喜欢的工作目录下新建一个 research_crew.py 文件,粘贴以下代码:

import os
os.environ["OPENAI_API_KEY"] = "sk-..."  # 也可以从环境变量读

from crewai import Agent, Task, Crew, Process

researcher = Agent(
    role="研究员",
    goal="搜集关于主题的权威信息",
    backstory="你是一位严谨的研究员,擅长从公开资料中提炼事实。",
    verbose=True,
)

writer = Agent(
    role="撰稿人",
    goal="把研究员提供的事实写成一段流畅的短文",
    backstory="你是一位资深科技写作者,文风简洁。",
    verbose=True,
)

task1 = Task(
    description="研究 2026 年 AI Agent 领域的三个主要趋势,每条趋势用一句话总结。",
    expected_output="三条带来源的趋势总结。",
    agent=researcher,
)

task2 = Task(
    description="根据上面研究员的结果,写一段 200 字的中文导读。",
    expected_output="200 字中文短文。",
    agent=writer,
)

crew = Crew(
    agents=[researcher, writer],
    tasks=[task1, task2],
    process=Process.sequential,
)

result = crew.kickoff()
print(result)

这个示例定义了两个 Agent——研究员和撰稿人,串行执行两个任务。注意把 OPENAI_API_KEY 换成你自己的 key,或者提前在环境变量里设好。

第 3 步:跑起来

在终端里运行:

python research_crew.py

你会看到 CrewAI 打印每个 Agent 的思考过程(verbose=True 开启的日志),最后输出最终的 result。如果一切顺利,你会在终端看到一段 200 字左右的中文导读——这就是你的「AI 团队」协作产出的成果。

第一次跑可能会因为模型调用或网络问题中断,重试一次通常就好;如果报错说找不到 key,先 echo $OPENAI_API_KEY(Windows 用 echo %OPENAI_API_KEY%)确认环境变量已生效。

常见踩坑

1. 「装了 crewai 但命令行找不到」:通常是 PATH 或虚拟环境没激活,先 which python(Windows 用 where python)确认当前 Python 路径在 .venv 里。
2. 「Agent 之间的输出对不上」:CrewAI 顺序流程中,后一个 Task 默认会自动拿到前一个 Task 的输出作为上下文,如果你不想这样,可以在 Task 里显式设置 context=[]。
3. 「Token 消耗爆炸」:开了 verbose=True 后你会直观看到每个 Agent 都在反复读自己的 backstory,verbose 日志会显著增加 token 消耗,生产环境建议关掉。
4. 「分层流程卡住」:Process.hierarchical 模式会自动创建一个 manager Agent,如果用 gpt-3.5-turbo 这种弱模型,manager 分配任务的逻辑可能不稳定,建议用 gpt-4o 或更强的模型。
5. 「工具调用一直失败」:CrewAI 工具需要单独的安装(比如 crewai-tools[search]),并且要正确传入 tools=[...] 参数;同时检查 key 是否在环境变量里。
6. 「输出语言不是中文」:部分模型默认会输出英文,在 Agent 的 goal 或 Task 的 description 里显式写明「请用中文输出」,效果立竿见影。

初级用法

• 三 Agent 流水线:研究员 → 审校员 → 翻译员,跑一次就能拿到「英文研究稿 + 审校意见 + 中文译稿」三件套。
• 接 Ollama 本地模型:把 OPENAI_API_KEY 留空,改用 Ollama 的本地端点(base_url="http://localhost:11434/v1"),无需付费也能跑。
• 加自定义工具:在 tools=[...] 里传一个继承自 BaseTool 的 Python 类,Agent 就能在任务里调用你的函数。

高级玩法

• 混合流程:一个 Crew 里用顺序流程,另一个 Crew 用分层流程,再让第一个 Crew 的结果作为第二个 Crew 的输入,实现「流水线 + 小组长」的复合编排。
• 接外部 API 做工具:把公司的内部知识库、CRM、数据库包成 CrewAI 的 Tool,让 AI 团队直接读写业务数据,适合做企业级自动化。
• 用 YAML 配置替代 Python 代码:CrewAI 支持把 Agent / Task 写在 agents.yaml 和 tasks.yaml 里,跟代码分离,方便非工程师维护 Agent 的「人设」。

小技巧

1. Backstory 写具体一点:backstory="你擅长..." 比 backstory="你是一个 AI" 明显更好,模型会基于 backstory 调整语气和侧重。
2. expected_output 一定要写:它相当于给 Agent 一个「验收标准」,不写的话 Agent 容易交付出你没预期到的格式。
3. 小任务优先:跑 CrewAI 不需要一上来就搭复杂团队,先跑 2 个 Agent + 2 个 Task 的最小版,确认链路通了再扩展。
4. 善用 allow_delegation=True:在分层流程里,manager Agent 可以把任务委派给其他 Agent,这是 Hierarchical 模式区别于 Sequential 的关键能力。
5. 保存 kickoff 结果:crew.kickoff() 返回的 result 对象可以直接 .export_to_file("output.md"),方便后续归档。

参考链接

• CrewAI 官方网站
• CrewAI GitHub 仓库
• CrewAI 官方文档
• CrewAI 示例库
• CrewAI Tools 子仓库

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。如有错误或过时信息，请通过 contact@magicnetworld.com 反馈。