crewAIInc/crewAI · 上手攻略

• 仓库：crewAIInc/crewAI
• 链接：https://github.com/crewAIInc/crewAI
• 分类：ai · agent（多 Agent 编排框架）
• 作者：Jay
• 更新：2026-07-07

这是什么

CrewAI 是一个用于编排角色扮演、自主 AI Agent 的 Python 框架，通过促进协作式智能，让多个 Agent 无缝协作处理复杂任务。它的定位是「让开发者从第一天起就能构建生产级多 Agent 工作流」。

CrewAI 有两个核心抽象：

• Crews（团队）：一群有角色定义、目标和背景故事的 AI Agent，协作完成复杂任务，追求自治和协作智能。
• Flows（流程）：事件驱动的自动化工作流，提供精确的执行控制，适合需要条件分支、状态管理的生产场景。

两者可以组合使用——Flow 中调用 Crew，Crew 中嵌入 Flows。

截至 2026 年 6 月最新版本，Stars 55k+，社区认证开发者超过 10 万。

解决什么问题

构建多 Agent 系统有几个常见痛点：

• Agent 间缺乏结构化协作：简单让几个 Agent 互相调用容易失控，没有角色分工、任务依赖的管理机制
• 工作流和自治难以兼得：纯自主 Agent 系统难以做精确的条件控制；纯工作流系统又缺乏 Agent 的自适应能力
• 生产级功能缺失：观测性、安全性、记忆管理、Guardrails 等都是上线后才发现要加

CrewAI 从一开始就提供了： - 角色驱动的 Agent 设计（role、goal、backstory） - Crew + Flow 双模式 - 内置 memory、guardrails、工具调用 - 可选的商业控制平面（CrewAI AMP Suite）

快速安装

前提条件 - Python ≥ 3.10 且 < 3.14 - UV 包管理器（推荐，文档明确使用 uv pip）

# 基础安装
uv pip install crewai

# 含额外工具的完整安装
uv pip install 'crewai[tools]'

⚠️ 安装报错 ModuleNotFoundError: No module named 'tiktoken'？执行： bash uv pip install 'crewai[embeddings]'

报错 Failed building wheel for tiktoken？确保安装了 Rust 编译器（tiktoken 依赖 Rust）： bash curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

验证安装

uv pip show crewai

核心用法

1. 用 CLI 创建项目（推荐）

crewai create crew <project_name>

生成标准项目结构：

my_project/
├── pyproject.toml
├── .env
└── src/
 └── my_project/
     ├── main.py      ← 入口
     ├── crew.py      ← 定义 Crew
     ├── tools/
     │   └── custom_tool.py
     └── config/
         ├── agents.yaml  ← 定义 Agent
         └── tasks.yaml   ← 定义 Task

2. 定义 Agent（YAML 方式）

# config/agents.yaml
researcher:
  role: Market Research Analyst
  goal: Research the latest AI trends
  backstory: Expert at finding and synthesizing information
  verbose: true
  tools:
    - browse_and_summarize

writer:
  role: Content Writer
  goal: Write compelling content based on research
  backstory: Skilled at converting research into clear narratives

3. 定义 Task

# config/tasks.yaml
research_task:
  description: Research top 5 AI trends in 2026
  expected_output: A concise summary of findings
  agent: researcher

write_task:
  description: Write a blog post about the research findings
  expected_output: A 800-word blog post
  agent: writer

4. 定义 Crew 并运行

# src/my_project/crew.py
from crewai import Agent, Crew, Task, Process

researcher = Agent(config_path="config/agents.yaml", role="researcher")
writer = Agent(config_path="config/agents.yaml", role="writer")

research_task = Task(config_path="config/tasks.yaml", description="research_task")
write_task = Task(config_path="config/tasks.yaml", description="write_task",
                  context=[research_task])  # 依赖顺序

crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, write_task],
    process=Process.hierarchical,  # 或 Process.sequential
)

result = crew.kickoff()
print(result)

# src/my_project/main.py
from my_project.crew import research_crew

if __name__ == "__main__":
    result = research_crew.kickoff()

5. Flows 模式（事件驱动）

from crewai import Flow, Listen, Start, Route
from crewai import Agent, Task

flow = Flow()

researcher = Agent(role="Researcher", goal="Find AI news")
writer = Agent(role="Writer", goal="Summarize findings")

@flow.listen(Start())
def research_step():
    return Task(description="Research AI trends", agent=researcher)

@flow.listen("research_step")
def write_step(event):
    return Task(description="Write summary", agent=writer)

# 触发
flow.plot()  # 可视化流程图
result = flow.kickoff()

6. 连接你的 LLM

CrewAI 默认使用环境变量中的模型，可以通过 .env 配置：

# .env
OPENAI_API_KEY=sk-...
# 或
ANTHROPIC_API_KEY=sk-ant-...

或在代码中指定：

crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, write_task],
    process=Process.hierarchical,
    manager_agent=Agent(
        role="Manager",
        goal="Coordinate crew work",
        llm="gpt-4o"  # 指定 LLM
    )
)

典型适用场景

• 自动化内容生产管线：研究 Agent 收集信息 → 写作 Agent 生成内容，无需人工介入
• 多角色数据分析：一个 Agent 负责爬取数据、一个负责清洗、一个负责可视化
• 企业级工作流自动化：Flow 模式适合需要审批节点、条件分支的复杂业务流程
• 客服/销售 Agent 团队：不同角色（客服、销售、技术支持）分工协作处理用户请求
• 研究综述自动化：多个专家 Agent 并行研究不同子主题 → 汇总 Agent 整合输出

坑与注意

1. Python 版本严格限制：仅支持 Python 3.10–3.13，Python 3.9 或更早版本不兼容。3.14 暂未支持。

2. crewai create 是交互式命令：运行时会提示输入项目名，建议直接 crewai create crew my_project 在非交互模式下使用（部分版本）。

3. tiktoken 安装失败：这是 macOS/Linux 上常见问题，确保 Rust 工具链已安装：rustc --version。

4. Flow 和 Crew 的选择：如果任务有明确先后顺序，用 Process.sequential；如果需要动态委托，用 Process.hierarchical（会生成一个 manager agent）。

5. AMP 商业版与开源版区别：开源版 CrewAI 本身免费；CrewAI AMP Suite（控制平面、观测性）是商业产品，按需选择。

6. 工具注册：自定义工具需要正确注册到 Agent，否则 Agent 不会调用；参考 官方工具文档。

7. 输出不确定性：LLM 生成的内容有随机性，关键任务建议配合 output_pydantic 或 output_json 做结构化输出约束。

8. 学习曲线：agents.yaml / tasks.yaml YAML 配置 + crew.py 的组合对新手有一定认知负担，建议先跑通官方 Quickstart 再深度定制。

与同类对比

CrewAI 的优势在于开箱即用的多 Agent 协作和Flow 工作流，上手成本低于 LangGraph，但深度定制能力略弱于 LangChain/LangGraph。

一句话推荐结论

如果你想快速构建有角色分工的多 Agent 系统，不需要学复杂的 DAG 语法，CrewAI 是目前最简洁的选型——Crew + Flow 双模式覆盖了协作与编排两大场景，社区活跃度高，生产案例丰富。