CrewAI：角色驱动多智能体协作框架安装与使用指南
| 项目名称 | crewAIInc/crewAI |
| 仓库地址 | https://github.com/crewAIInc/crewAI |
| 官方网站 | https://www.crewai.com/ |
| 官方文档 | https://docs.crewai.com/ |
| 最新更新时间 | 2026-10-22（持续活跃更新） |
| 项目定位 | 角色扮演式多智能体协作框架，把任务拆成"团队"由不同 AI Agent 分工完成 |
| 开源协议 | MIT |
一、项目背景
真实世界的复杂任务——写一份行业报告、做一次市场调研、开发一个小程序——从来不是一个人能干完的。需要产品经理定义需求、研究员找资料、写手组织内容、编辑校对。Multi-Agent 框架的核心问题就是：怎么让 LLM 像一个"虚拟公司"那样分工协作？
CrewAI 由 CrewAI Inc. 公司开源，主打"角色驱动"：你定义一个个 Role（角色），每个角色有自己的 Goal（目标）、Backstory（背景故事）、Tools（工具），然后把多个角色组成一个 Crew（团队），让他们按 Sequential（顺序）或 Hierarchical（层级）模式完成任务。相比 AutoGen 的"自由对话"，CrewAI 更像一个标准化的"虚拟员工调度系统"，业务人员也能上手配置。
CrewAI 在 2024-2025 年迅速崛起，GitHub Star 数已超过 3 万，成为和 LangGraph、AutoGen 并列的三大主流 Agent 框架之一。它还提供了 CrewAI Enterprise 云平台、CrewAI Studio 可视化编排界面，以及配套的 CLI 工具链，从原型到生产一条龙。
二、核心特性
- 角色抽象：每个 Agent 有 role / goal / backstory，LLM 会自动据此调整语气与行为。
- 任务抽象：Task 可分配给指定 Agent，带 expected_output 明确交付物。
- 两种流程：Sequential（顺序流水线）与 Hierarchical（经理-员工层级）。
- 丰富工具生态：内置 SerperDev、SerpApi、WebsiteSearch、FileRead、DirectoryRead 等 100+ 工具。
- Flow 编排：Crew 之外更细粒度的状态机，处理分支、循环、人工审批。
- CLI 脚手架：
crewai create一键生成项目骨架，crewai run直接跑。 - crews / flows 可序列化：支持导出为 YAML，方便版本管理与多人协作。
- 多模型后端：OpenAI、Azure、Anthropic、Ollama、Groq、DeepSeek、本地 vLLM。
三、环境要求
- Python：3.10 – 3.12（强烈推荐用
uv管理）。 - uv：CrewAI 官方推荐的 Python 包管理器。
- 操作系统：Linux / macOS / WSL2。
- LLM API Key：至少一个 OpenAI / DeepSeek 等兼容 Key。
- （可选）搜索 API Key：SerperDev / Tavily 等做网络搜索时需要。
四、详细部署步骤
第一步：安装 uv（如已装可跳过）
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env
uv --version第二步：安装 CrewAI CLI
uv tool install crewai
# 如果 PATH 提示找不到，执行：
uv tool update-shell
# 验证
crewai version第三步：创建新项目
crewai create crew my_first_crew
cd my_first_crew
# 目录结构：
# my_first_crew/
# ├── crew.py # 主逻辑
# ├── crews/ # 多个 Crew 定义（YAML）
# ├── tasks/ # 任务定义（YAML）
# ├── agents.py # Agent 定义
# └── .env # API Keys第四步：配置 API Key
cat > .env <<'EOF'
OPENAI_API_KEY=sk-xxxx
# 如果用 DeepSeek：
# OPENAI_API_BASE=https://api.deepseek.com/v1
# MODEL=deepseek-chat
# 可选：网络搜索
# SERPER_API_KEY=xxx
EOF第五步：定义 Agent 与 Task
编辑 crewai-express/config/agents.yaml：
researcher:
role: >
资深行业研究员
goal: >
收集关于 {topic} 的最新行业动态与关键数据
backstory: >
你在咨询公司工作了 10 年，擅长从海量信息中提炼核心观点。
writer:
role: >
技术博客写手
goal: >
把研究员收集到的素材写成一篇通俗易懂的中文博客
backstory: >
你是一个有 5 年经验的技术编辑，写过 100+ 篇爆款文章。编辑 crewai-express/config/tasks.yaml：
research_task:
description: >
调研主题：{topic}。找出最近 3 个月的 3-5 个关键事件。
expected_output: >
一份要点清单，每个要点包含事件、时间、影响。
agent: researcher
write_task:
description: >
根据研究员的要点清单，写一篇 800 字博客。
expected_output: >
一篇结构完整的 Markdown 博客，带标题与小标题。
agent: writer
context: [research_task]第六步：运行
# 安装依赖
crewai install
# 跑起来
crewai run按提示输入主题，例如"AI 编程助手"，就能看到 researcher 开始搜索、writer 开始写稿。
纯 Python 方式（不用 CLI）
pip install crewai
from crewai import Agent, Task, Crew, Process
researcher = Agent(
role="资深行业研究员",
goal="收集关于 AI Agent 的最新动态",
backstory="10 年咨询经验",
verbose=True,
llm="gpt-4o-mini",
)
writer = Agent(
role="技术博客写手",
goal="把素材写成博客",
backstory="5 年编辑经验",
verbose=True,
llm="gpt-4o-mini",
)
t1 = Task(description="调研 AI Agent 最新动态", expected_output="要点清单", agent=researcher)
t2 = Task(description="写成 800 字博客", expected_output="Markdown 博客", agent=writer, context=[t1])
crew = Crew(
agents=[researcher, writer],
tasks=[t1, t2],
process=Process.sequential,
verbose=True,
)
result = crew.kickoff(inputs={"topic": "AI Agent"})
print(result)层级模式（有"经理"Agent）
crew = Crew(
agents=[researcher, writer],
tasks=[t1, t2],
process=Process.hierarchical,
manager_llm="gpt-4o", # 由一个 Manager Agent 决定下一步派给谁
verbose=True,
)Docker 部署
crewai install # 在项目根目录
crewai package # 生成 Dockerfile 与 docker-compose.yml
docker compose up -d五、进阶生产部署
5.1 把 Crew 包成 API
from fastapi import FastAPI
from my_first_crew.main import MyCrew
app = FastAPI()
@app.post("/run")
def run(topic: str):
result = MyCrew().crew().kickoff(inputs={"topic": topic})
return {"output": result.raw}5.2 成本控制
- 开发期用 gpt-4o-mini，生产再切大模型；
- 在 tasks.yaml 里写清楚 expected_output，避免 Agent 反复返工；
- 用
crewai train n跑训练模式，让 Agent 自己迭代 Prompt。
5.3 与外部工具集成
CrewAI 支持自定义工具：
from crewai.tools import BaseTool
class MyDBTool(BaseTool):
name = "query_db"
description = "查询业务数据库"
def _run(self, sql: str) -> str:
return db.query(sql)六、使用方法示例
查看任务上下文：
result = crew.kickoff()
print(result.raw) # 最终输出
print(result.tasks_output[0].raw) # 第一个任务的中间结果
print(result.token_usage) # Token 消耗异步运行：
result = await crew.kickoff_async(inputs={"topic": "..."})典型任务示例：
- 市场调研：研究员搜资料 → 分析师做对比 → 写手出报告。
- 内容生产：选题策划 → 资料收集 → 初稿 → 编辑润色。
- 数据处理：数据工程师清洗 → 分析师建模 → 可视化师出图。
默认账号密码：CrewAI 本身是 Python 框架，没有 Web 登录页。CrewAI Enterprise / Studio 云平台才需要注册账号，本地自托管无需登录。
七、常见问题（FAQ）
Q1：crewai create 报 chroma-hnswlib 编译错误？
这是已知问题。执行 pip install cmake 后重装，或换 Python 3.11；也可以临时用 crewai create --no-git 跳过。
Q2：Agent 不调用搜索工具？
检查 (1) 是否在 Agent 定义里加了 tools=[SerperDevTool()]；(2) 任务描述里是否明确要求"联网搜索"；(3) 模型是否支持 function calling（gpt-4o-mini、deepseek-chat 都支持）。
Q3：怎么让 Agent 之间共享上下文？
用 Task 的 context=[上一个任务] 字段，CrewAI 会自动把上游任务输出注入下游 Prompt。
Q4：跑一次要花多少钱？
两个 Agent、两个任务、用 gpt-4o-mini 大约几毛到一块钱人民币；换 gpt-4o 可能十几元。生产建议先在小模型上调试 Prompt，再切大模型。
Q5：Crew 和 Flow 选哪个？
任务是线性流水线（A→B→C）用 Crew；需要分支、循环、人工审批、条件跳转时用 Flow（CrewAI 1.0 新增）。
Q6：支持国产模型吗？
支持。在 .env 里把 OPENAI_API_BASE 改成 DeepSeek/通义/Kimi 的兼容地址，MODEL 填对应模型名即可。
Q7：CrewAI Studio 是什么？
CrewAI 官方出的可视化编排工具，拖拽即可定义 Agent 与任务，自动生成 YAML。适合不写代码的业务同学。