环境准备
CrewAI 要求 Python 3.10 ~ 3.13，包管理用的是 uv（Rust 写的超快 Python 包管理器，CrewAI CLI 内部依赖它）。
# 确认 Python 版本
python3 --version # 需要 3.10+
# 安装 CrewAI（会自动安装 uv）
pip install crewai
# 带内置工具包一起装
pip install 'crewai[tools]'
# 验证
crewai version
安装完你会得到一个 crewai 命令行工具，它能帮你生成项目骨架、跑 Crew、训练 Agent。
创建第一个项目
CrewAI 提供脚手架命令，一行搞定项目结构：
crewai create crew my_research_team
cd my_research_team
生成的目录结构：
my_research_team/
├── pyproject.toml # 项目依赖
├── .env # API Key 放这里
├── README.md
├── src/
│ └── my_research_team/
│ ├── __init__.py
│ ├── main.py # 入口：kickoff()
│ ├── crew.py # Crew 定义（@CrewBase 装饰器）
│ ├── config/
│ │ ├── agents.yaml # Agent 配置
│ │ └── tasks.yaml # Task 配置
│ └── tools/
│ └── custom_tool.py
CrewAI 的一个设计亮点是 YAML 配置 + Python 代码分离：Agent 和 Task 的角色描述写在 YAML 里，编排逻辑写在 Python 里。运营同事改 YAML 调角色描述，开发同事改 Python 调逻辑，互不干扰。
配置 Agent 和 Task
打开 config/agents.yaml，定义你的 Agent 团队：
researcher:
role: "Senior Tech Researcher"
goal: "找到关于 {topic} 最新、最准确的信息"
backstory: >
你是一个资深技术研究员，擅长从海量信息中提取关键洞察。
你的研究结果会被团队其他成员引用，所以准确性至关重要。
writer:
role: "Tech Blog Writer"
goal: "把研究结果写成一篇通俗易懂的中文技术博客"
backstory: >
你是一个技术博客写手，文风直接不啰嗦。
你的读者是有一定基础的开发者，不需要过度解释基础概念。
再打开 config/tasks.yaml：
research_task:
description: >
对 {topic} 做一次全面调研，覆盖：最新进展、核心功能、
和竞品的区别、社区评价。输出结构化的调研报告。
expected_output: "一份包含 10 个要点的调研报告，每个要点附信息来源"
agent: researcher
writing_task:
description: >
基于调研报告，写一篇 1500 字的中文技术博客。
要求：有代码示例、有对比表格、语气轻松但专业。
expected_output: "一篇可以直接发布的 Markdown 格式博客文章"
agent: writer
配置 API Key
在 .env 文件里填入你的 LLM API Key：
# 默认用 OpenAI
OPENAI_API_KEY=sk-xxxxxxxx
# 也可以用 Anthropic Claude
ANTHROPIC_API_KEY=sk-ant-xxxxxxxx
CrewAI 默认使用 GPT-4o，但你可以在 Agent 配置里指定任何支持的模型（后面高级章节会讲多模型混用）。
启动你的第一个 Crew
# 安装依赖
crewai install
# 运行！
crewai run
终端会实时打印每个 Agent 的思考过程和输出：
[Researcher] 🔍 Starting research on "CrewAI framework"...
[Researcher] I'll search for the latest information...
[Researcher] ✅ Task completed. Found 10 key insights.
[Writer] ✍️ Writing blog post based on research...
[Writer] ✅ Blog post completed. 1,523 words.
第一次跑可能要等 1-2 分钟（取决于你的 LLM 响应速度）。输出会保存在终端里，你也可以在 crew.py 里配置输出到文件。
常见新手问题
Q: 必须用 OpenAI 吗？ 不是。CrewAI 支持 OpenAI、Anthropic、Google Gemini、本地 Ollama 模型等。后面第四章会讲怎么切换。
Q: crewai create crew 和 crewai create flow 有什么区别？
crew 创建一个 Agent 团队项目；flow 创建一个包含多个 Crew 的工作流项目。新手先从 crew 开始。
Q: YAML 里的 {topic} 是什么？
占位符。运行时通过 crew.kickoff(inputs={"topic": "CrewAI"}) 传入实际值。
