ai-agent-crewai

<p align="center">
  <img src="assets/banner.png" alt="AI Multi-Agent Orchestration" width="600" />
</p>

<h1 align="center">ai-agent-crewai</h1>

<p align="center">
  使用 <a href="https://crewai.com/">CrewAI</a> 框架学习和实践多智能体编排（Multi-Agent Orchestration）
</p>

<p align="center">
  <img src="https://img.shields.io/badge/Python-3.10~3.13-blue?logo=python&logoColor=white" />
  <img src="https://img.shields.io/badge/CrewAI-Framework-purple?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCI+PHRleHQgeT0iMTgiIGZvbnQtc2l6ZT0iMTYiPvCfpJY8L3RleHQ+PC9zdmc+" />
  <img src="https://img.shields.io/badge/Package_Manager-uv-green?logo=astral&logoColor=white" />
</p>

---

## 环境要求

- **Python** >=3.10, <3.14
- **[uv](https://github.com/astral-sh/uv)** — CrewAI 推荐的包管理器（比 pip 快 10-100x）

## 快速安装

```bash
# 1. 安装 uv（macOS/Linux）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. 安装 CrewAI CLI
uv tool install crewai

# 验证安装
uv tool list
```

## 创建第一个 Crew 项目

```bash
# 脚手架生成项目
crewai create crew my_first_crew
cd my_first_crew

# 安装依赖
crewai install

# 运行
crewai run
```

<details>
<summary>📂 生成的项目结构</summary>

```
my_first_crew/
├── src/my_first_crew/
│   ├── config/
│   │   ├── agents.yaml      # 智能体定义（角色、目标、背景）
│   │   └── tasks.yaml        # 任务定义（描述、期望输出）
│   ├── crew.py               # Crew 编排逻辑
│   ├── main.py               # 入口文件
│   └── tools/                # 自定义工具
├── pyproject.toml
└── .env                      # API Keys
```

</details>

---

## 核心概念速览

<p align="center">
  <img src="assets/concepts.png" alt="Core Concepts: Agent → Task → Crew → Flow" width="560" />
</p>

### 1. Agent（智能体）

自主实体，具有角色、目标和背景故事。

```yaml
# agents.yaml
researcher:
  role: "{topic} Senior Data Researcher"
  goal: "Uncover cutting-edge developments in {topic}"
  backstory: "You're a seasoned researcher with a knack for uncovering the latest developments..."
```

> 关键参数：`role` `goal` `backstory` `llm` `tools` `memory` `verbose` `allow_delegation` `max_iter` `reasoning`

### 2. Task（任务）

分配给智能体的具体工作单元。

```yaml
# tasks.yaml
research_task:
  description: "Conduct thorough research about {topic}..."
  expected_output: "A list with 10 bullet points of relevant information"
  agent: researcher
  output_file: report.md
```

### 3. Crew（团队）

将智能体和任务组合在一起协作。

```python
from crewai import Agent, Crew, Process, Task
from crewai.project import CrewBase, agent, crew, task

@CrewBase
class MyCrew():
    @agent
    def researcher(self) -> Agent:
        return Agent(config=self.agents_config['researcher'], tools=[SerperDevTool()])

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

    @crew
    def crew(self) -> Crew:
        return Crew(agents=self.agents, tasks=self.tasks, process=Process.sequential, verbose=True)
```

### 4. Flow（工作流）

事件驱动的编排层，用于连接多个 Crew、管理状态和控制执行流程。

```python
from crewai.flow.flow import Flow, listen, start

class MyFlow(Flow):
    @start()
    def initialize(self):
        return "start data"

    @listen(initialize)
    def process(self, data):
        # 可以在这里调用 Crew
        result = MyCrew().crew().kickoff(inputs={"topic": data})
        return result.raw
```

> 核心装饰器：`@start()` 入口方法 · `@listen(method)` 监听触发 · `@router(method)` 条件路由 · `and_()` / `or_()` 组合条件

### 5. Tools（工具）

智能体可以使用的外部能力（搜索、API 调用、文件操作等）。

```bash
uv add crewai-tools
```

---

## 学习路线

<p align="center">
  <img src="assets/roadmap.png" alt="Learning Roadmap" width="400" />
</p>

| 阶段 | 内容 | 资源 |
|:---:|------|------|
| **1. 入门** | 安装 + 跑通第一个 Crew | [Quickstart](https://docs.crewai.com/en/quickstart) |
| **2. 基础** | 理解 Agent / Task / Crew 参数 | [Agents](https://docs.crewai.com/en/concepts/agents) · [Tasks](https://docs.crewai.com/en/concepts/tasks) · [Crews](https://docs.crewai.com/en/concepts/crews) |
| **3. 工具** | 学习内置工具 + 自定义工具 | [Tools](https://docs.crewai.com/en/concepts/tools) |
| **4. 进阶** | Flow 编排多 Crew 工作流 | [Flows](https://docs.crewai.com/en/concepts/flows) |
| **5. 实战** | 跑通官方示例项目 | [crewAI-examples](https://github.com/crewAIInc/crewAI-examples) |
| **6. 深入** | Memory / Knowledge / RAG | [Memory](https://docs.crewai.com/en/concepts/memory) · [Knowledge](https://docs.crewai.com/en/concepts/knowledge) |

---

## 实战案例：用 CrewAI 改造 Meeting Agent

> 基于 [ava-agent/meeting-agent](https://github.com/ava-agent/meeting-agent) — 一站式 AI 会议策划平台

### 现状问题

meeting-agent 有 4 个 AI 角色（议程、演讲稿、海报、伴手礼），但它们**完全独立运行、互不感知**：

```
现状：4 个独立 LLM 调用 → Promise.all() 并行 → 各自输出，风格不统一
```

### CrewAI 改造方案

<p align="center">
  <img src="assets/case-meeting.png" alt="Meeting Agent CrewAI Architecture" width="560" />
</p>

用 CrewAI 将 4 个独立角色重构为**协作式 Crew**，Agent 之间共享上下文、链式传递输出：

```yaml
# agents.yaml
agenda_planner:
  role: "会议策划专家"
  goal: "根据会议信息生成结构化议程，包含时间块、议题和负责人"
  backstory: "你是一位拥有10年大型会议策划经验的专家..."

speech_writer:
  role: "演讲稿撰写专家"
  goal: "根据议程内容撰写开场白和主题演讲稿"
  backstory: "你是一位资深演讲稿撰写者，擅长根据议程上下文创作..."

poster_designer:
  role: "平面设计师"
  goal: "根据议程和演讲主题输出海报设计方案（配色、布局、文案）"
  backstory: "你是一位创意设计师，能从会议内容中提炼视觉主题..."

gift_consultant:
  role: "活动策划顾问"
  goal: "根据会议类型、预算和参会人群推荐伴手礼方案"
  backstory: "你是一位活动策划顾问，熟悉各类商务礼品..."

qa_reviewer:
  role: "质量审核专家"
  goal: "审核所有输出的一致性、专业性和完整性"
  backstory: "你是一位严谨的质量审核员..."
```

```yaml
# tasks.yaml — 链式依赖，上游输出自动注入下游
agenda_task:
  description: "为 {meeting_type} 生成详细议程：{title}，{duration}，{attendees}人参会"
  expected_output: "结构化议程表，含时间、议题、负责人、形式"
  agent: agenda_planner

speech_task:
  description: "根据以上议程，撰写开场致辞和主旨演讲稿"
  expected_output: "完整演讲稿，markdown 格式，含时长标注"
  agent: speech_writer
  context: [agenda_task]          # 引用议程输出

poster_task:
  description: "根据议程和演讲主题，输出海报设计方案"
  expected_output: "设计brief：主题、配色方案、布局描述、核心文案"
  agent: poster_designer
  context: [agenda_task, speech_task]  # 引用议程+演讲

gift_task:
  description: "根据会议类型和预算 {budget}，推荐伴手礼方案"
  expected_output: "3套方案：经济/标准/精品，含品名、单价、总预算"
  agent: gift_consultant

review_task:
  description: "审核以上所有输出，检查一致性和完整性"
  expected_output: "审核报告：通过/需修改，附具体修改建议"
  agent: qa_reviewer
  context: [agenda_task, speech_task, poster_task, gift_task]
```

### 改造前 vs 改造后

| 维度 | 改造前 | CrewAI 改造后 |
|------|--------|-------------|
| Agent 间依赖 | 零，各自独立 | 链式：议程→演讲→海报→伴手礼→审核 |
| 输出一致性 | 风格可能不一致 | 共享 context，风格统一 |
| 质量保障 | 无 | QA Agent 审核，不合格则重新生成 |
| 流程适配 | 固定流程 | Flow 按会议类型（年会/技术分享/发布会）走不同路径 |
| 可扩展性 | 加角色需改代码 | YAML 加配置即可 |

### 用 Flow 编排不同会议类型

```python
from crewai.flow.flow import Flow, start, listen, router

class MeetingFlow(Flow):
    @start()
    def classify_meeting(self):
        """识别会议类型"""
        return classify(self.state.meeting_data)

    @router(classify_meeting)
    def route_by_type(self, meeting_type):
        if meeting_type == "annual_gala":
            return "full_planning"        # 年会：全套 5 Agent
        elif meeting_type == "tech_talk":
            return "light_planning"       # 技术分享：议程+演讲 2 Agent
        return "standard_planning"

    @listen("full_planning")
    def run_full_crew(self):
        return FullMeetingCrew().crew().kickoff(inputs=self.state.meeting_data)

    @listen("light_planning")
    def run_light_crew(self):
        return LightMeetingCrew().crew().kickoff(inputs=self.state.meeting_data)
```

---

## 常用 CLI 命令

| 命令 | 说明 |
|------|------|
| `crewai create crew <name>` | 创建新 Crew 项目 |
| `crewai create flow <name>` | 创建新 Flow 项目 |
| `crewai install` | 安装项目依赖 |
| `crewai run` | 运行项目 |
| `crewai test` | 测试 Crew |
| `crewai log-tasks-outputs` | 查看任务输出日志 |

---

## 学习资源

**官方资源**

| 资源 | 链接 |
|------|------|
| 官方文档 | [docs.crewai.com](https://docs.crewai.com/en/introduction) |
| GitHub 仓库 | [crewAIInc/crewAI](https://github.com/crewAIInc/crewAI) |
| 完整示例项目 | [crewAI-examples](https://github.com/crewAIInc/crewAI-examples) |
| 快速上手 Demo | [crewAI-quickstarts](https://github.com/crewAIInc/crewAI-quickstarts) |
| 官方博客 | [blog.crewai.com](https://blog.crewai.com/) |
| 社区论坛 | [community.crewai.com](https://community.crewai.com/) |

**教程与文章**

- [Build your First CrewAI Agents（官方博客）](https:/

[truncated…]