根据 CrewAI 的官方仓库，这是一个用于编排**多角色自主 AI 代理（Crews）和事件驱动工作流（Flows）**的 Python 框架。以下是根据其文档整理的完整部署与使用教程。

🧭 核心概念与选择

CrewAI 提供了两种互补的抽象，你可以根据任务复杂度选择或组合使用：

概念 核心思想 适用场景
Crews（代理团队） 模拟团队协作，由多个拥有特定角色（Role）、**目标（Goal）和工具（Tools）的自主 AI 代理组成，通过任务（Task）**驱动，自主决策和协作。 需要创造性、灵活性和多角度分析的复杂任务，如撰写研究报告、制定营销策略、头脑风暴。
Flows（工作流） 提供精确、事件驱动的控制流，通过 @start、@listen、@router 等装饰器定义步骤、状态管理和条件分支。 需要严格顺序、确定性逻辑和状态管理的生产级流程，如数据处理管道、自动化报告生成、与现有系统集成。

官方建议：将 Crews 和 Flows 结合使用，用 Flow 搭建工作流的骨架，在需要自主决策的节点调用 Crew，实现“可控的自主性”。

📦 安装与环境准备

1. 前提要求

  • Python 版本：需要 Python >= 3.10 且 < 3.14。
  • 包管理器：项目强烈推荐使用 UV（一个快速的 Python 包管理器）。你也可以使用 pip。

2. 安装 CrewAI

1
2
3
4
5
# 使用 UV（推荐）
uv pip install crewai

# 如果需要包含内置工具的额外依赖
uv pip install 'crewai[tools]'

3. （可选）安装 CrewAI CLI 工具

CLI 工具可以快速创建项目脚手架。

1
crewai install  # 安装 CLI（如果尚未安装）

🚀 快速上手：创建并运行你的第一个 Crew

官方推荐通过 CLI 创建标准项目结构，然后进行配置。

第1步：创建新项目

1
2
crewai create crew my_ai_team
cd my_ai_team

这将生成以下标准结构：

1
2
3
4
5
6
7
8
9
10
my_ai_team/
├── .env                     # 存放 API 密钥
├── pyproject.toml           # 项目依赖
└── src/my_ai_team/
    ├── main.py              # 项目入口
    ├── crew.py              # 定义 Crew 逻辑
    ├── tools/               # 自定义工具
    └── config/
        ├── agents.yaml      # 代理角色定义
        └── tasks.yaml       # 任务定义

第2步：配置代理 (config/agents.yaml)

用 YAML 定义你的代理团队。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
researcher:
  role: >
    {topic} 高级数据研究员
  goal: >
    发掘关于 {topic} 的前沿发展
  backstory: >
    你是一位资深研究员，擅长挖掘 {topic} 领域的最新动态，并以清晰简洁的方式呈现。
    
reporting_analyst:
  role: >
    {topic} 报告分析师
  goal: >
    基于研究结果，创建关于 {topic} 的详细报告
  backstory: >
    你是一位一丝不苟的分析师，能将复杂数据转化为清晰易懂的报告。

第3步：定义任务 (config/tasks.yaml)

为代理分配具体任务。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
research_task:
  description: >
    对 {topic} 进行深入研究。确保找到所有有趣且相关信息。
  expected_output: >
    一份包含10个要点的最相关信息列表。
  agent: researcher  # 指定由哪个代理负责

reporting_task:
  description: >
    根据研究结果，展开每个主题，撰写一份完整的报告。
  expected_output: >
    一份详尽的报告，包含主要章节和完整信息，格式为 Markdown。
  agent: reporting_analyst
  output_file: report.md  # 结果将输出到此文件

第4步：组装 Crew (src/my_ai_team/crew.py)

在 Python 代码中组装代理和任务。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
from crewai import Agent, Crew, Process, Task
from crewai.project import CrewBase, agent, crew, task
# 假设你有一个搜索工具
from crewai_tools import SerperDevTool

@CrewBase
class MyAiTeamCrew():
    """我的 AI 团队 Crew"""

    @agent
    def researcher(self) -> Agent:
        return Agent(
            config=self.agents_config['researcher'],
            verbose=True,
            tools=[SerperDevTool()]  # 赋予研究工具
        )

    @agent
    def reporting_analyst(self) -> Agent:
        return Agent(
            config=self.agents_config['reporting_analyst'],
            verbose=True
        )

    @task
    def research_task(self) -> Task:
        return Task(config=self.tasks_config['research_task'])

    @task
    def reporting_task(self) -> Task:
        return Task(
            config=self.tasks_config['reporting_task'],
            output_file='report.md'
        )

    @crew
    def crew(self) -> Crew:
        return Crew(
            agents=self.agents,  # 自动注入
            tasks=self.tasks,    # 自动注入
            process=Process.sequential,  # 顺序执行
            verbose=True,
        )

第5步：设置 API 密钥并运行

在项目根目录的 .env 文件中添加你的 LLM API 密钥（如 OpenAI）及任何工具所需的 API 密钥（如 Serper.dev）。

1
2
OPENAI_API_KEY=sk-...
SERPER_API_KEY=...

最后，运行你的 Crew：

1
2
3
crewai run
# 或使用 python 直接运行
python src/my_ai_team/main.py

你将在控制台看到代理的思考过程，并在项目根目录得到生成的 report.md 文件。

🔧 进阶用法：使用 Flows 实现精确控制

当需要更复杂的工作流（如条件分支、状态管理）时，使用 Flows。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
from crewai.flow.flow import Flow, listen, start, router, or_
from pydantic import BaseModel

# 1. 定义状态
class MarketState(BaseModel):
    sentiment: str = "neutral"
    confidence: float = 0.0

class AnalysisFlow(Flow[MarketState]):
    # 2. 起始步骤
    @start()
    def fetch_data(self):
        self.state.sentiment = "analyzing"
        return {"sector": "tech", "timeframe": "1W"}

    # 3. 监听前一步，执行 Crew
    @listen(fetch_data)
    def run_analysis(self, market_data):
        # 在此创建并运行你的 Crew...
        result = "分析结果" # 模拟
        self.state.confidence = 0.85
        return result

    # 4. 路由：根据结果分支
    @router(run_analysis)
    def decide_next(self):
        if self.state.confidence > 0.8:
            return "high_confidence"
        return "low_confidence"

    # 5. 监听特定路由结果
    @listen("high_confidence")
    def high_conf_action(self):
        print("执行高置信度策略")

    @listen(or_("low_confidence"))
    def low_conf_action(self):
        print("请求额外分析")

# 运行 Flow
flow = AnalysisFlow()
flow.kickoff()

📋 常用 CLI 命令

命令 说明
crewai create crew <项目名> 创建新的 Crew 项目脚手架
crewai run 在项目目录下运行 Crew
crewai install 安装项目依赖（使用 UV）
crewai update 更新 CrewAI 包

💡 最佳实践与故障排查

  • 依赖问题：如遇到 tiktoken 安装失败，可尝试 uv pip install 'crewai[embeddings]' 或手动安装 uv pip install tiktoken --prefer-binary。
  • 模型配置：默认使用 OpenAI。可通过在 Agent 或 Crew 中设置 llm 参数连接到其他模型（如本地 Ollama、Anthropic Claude 等）。参考官方 LLM Connections 文档。
  • 生产部署：对于企业级需求，官方提供 CrewAI AMP Suite，增加了管理、可观测性、安全性和支持服务，支持云和本地部署。
  • 遥测：CrewAI 会收集匿名使用数据以改进项目。不会收集提示词、任务描述等敏感内容。你可以在环境变量中设置 OTEL_SDK_DISABLED=true 来关闭遥测。

总结

CrewAI 的核心价值在于将复杂的 AI 任务拆解为由多个专家代理协作完成的流程。对于初学者，推荐从 CLI 创建项目 -> 编辑 YAML 配置代理和任务 -> 运行 Crew 这个标准路径开始，快速体验多代理协作。当你的流程需要更严谨的控制时，再引入 Flows 来编排这些 Crew，构建从实验到生产的完整自动化管道。