#安装与环境

依据 官方 Installation（请以该页为准）。CrewAI 用 uv 管理 CLI 与项目依赖；库本身也可以用 pip install crewai。

#环境要求

• Python >=3.10 且 <3.14
• uv（官方推荐）或 pip
• 至少一个 LLM Provider 的 API Key

检查版本：

python3 --version

Windows 若默认是 5.1 PowerShell，可用本机已装的 PowerShell 7（pwsh）。

#编码 Agent Skills（可选）

在 Cursor / Claude Code / Codex 等环境：

npx skills add crewaiinc/skills

没有 npx 时跳过即可，直接读 docs.crewai.com 与 llms.txt。

#官方路径：安装 uv 与 CLI

macOS / Linux：

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

安装 CrewAI 全局 CLI：

uv tool install crewai
uv tool update-shell   # 若提示不在 PATH
uv tool list           # 应看到 crewai
crewai version
crewai create --help

更新 CLI：uv tool install crewai --upgrade。这只升级全局工具；项目虚拟环境里的包见官方「Upgrading CrewAI in a project」。

Windows 编译错误 chroma-hnswlib / 找不到 float.h：安装 Visual Studio Build Tools，勾选 Desktop development with C++。

#备选：pip 安装库

脚本或已有 venv：

python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS / Linux: source .venv/bin/activate
pip install -U crewai
pip install 'crewai[tools]'   # Serper、文件、RAG 等工具包 crewai_tools

验证：

python -c "from crewai import Agent, Task, Crew; print('ok')"

项目里用 uv 时：uv add crewai 或 uv add 'crewai[tools]'。部分 Provider 有 extra，例如 uv add "crewai[openai]"；走 LiteLLM 的其它厂商见官方 LLMs：uv add 'crewai[litellm]'。

#API Key

不要把密钥写进代码。 使用 .env（已加入 .gitignore）。

OPENAI_API_KEY=sk-...
MODEL=openai/gpt-4o-mini
SERPER_API_KEY=...

from dotenv import load_dotenv
load_dotenv()

模型标识为 provider/model-id（如 openai/gpt-4o-mini、anthropic/claude-sonnet-4-6）。也可用 from crewai import LLM：LLM(model="openai/gpt-4o-mini")。

#创建项目

JSON-first Crew（当前默认）：

crewai create crew my_research_crew
cd my_research_crew
crewai install
crewai run

结构要点：agents/*.jsonc 定义 Agent；crew.jsonc 定义任务顺序、process、默认 inputs。{placeholder} 由 inputs 或 CLI 提示填充。

经典 Python / YAML（crew.py + config/agents.yaml）：

crewai create crew my_research_crew --classic

Flow 项目（官方 Quickstart 推荐的生产入口）：

crewai create flow latest-ai-flow
cd latest_ai_flow
crewai install
crewai run

额外依赖：uv add <package-name>。CrewAI 内部包可能使用 exclude-newer；你的直接依赖不受影响。

#企业选项（了解即可）

• CrewAI AMP（SaaS）：托管控制台，可无代码搭建
• CrewAI Factory：自托管容器

本教程聚焦本地 SDK / CLI。

#常见问题

crewai 命令找不到？ 运行 uv tool update-shell 并重开终端。

Python 3.14？ 官方当前要求 <3.14，请改用 3.12 / 3.13。

只要写脚本、不要脚手架？ pip install crewai 后直接 from crewai import Agent, Task, Crew 即可，见 快速上手。

#下一步

• 快速上手
• Agent 智能体