crewai-mas-demo

企业级多智能体设计实战

参透 CrewAI 底层逻辑，攻克多 Agent 落地难题

本仓库是《企业级多智能体设计实战》在线视频课程的配套示例代码仓库。

📚 课程简介

这是一门专为致力于构建生产级、高可靠 AI 应用的研发人员和架构师设计的实战课程。 如果对课程或者代码有疑问，欢迎通过我的个人微信加入微信群一起学习讨论: xiaohan_chat

你将获得

• 告别"野路子"demo：掌握 MAS 核心设计模式
• 手把手教学：构建、调试、部署多智能体系统
• 生产环境稳定可用：企业级 AI 应用治理体系
• 4 大高价值场景实践案例：自己动手实现 XiaoPaw

课程特色

✅ 无需魔法，低成本上手：全程兼容 DeepSeek、Kimi、通义千问等国内优质大模型接口
✅ 真实生产级案例：拒绝"贪吃蛇"类玩具案例，提供贴近真实生产环境的场景
✅ 架构思维优先：不是框架使用手册，而是 AI 时代的"建筑学"
✅ 工程化实践：测试评估、可观测性、容灾设计等生产级治理体系

🎯 课程结构

架构思维篇：AI 时代的设计模式（4 课）

建立 AI 应用开发的全局认知框架，理解从 Prompt 到 Multi-Agent 的底层演进逻辑。

• 01 | 拨开迷雾：AI 应用开发的四种架构范式
• 02 | 解构智能体：Agent 的解剖学与 ReAct 范式
• 03 | Multi-Agent 系统：Agent、Task、Process 的协作美学
• 04 | 架构师的决断：AI 应用开发选型工具

工程落地篇：从0构建生产级多智能体系统

从零开始构建生产级的多智能体系统，掌握工具集成、上下文管理、协作设计模式。

先导准备（2 课）

• 05 | 工程全景图：构建企业级多智能体系统的"施工蓝图"
• 06 | 工欲善其器：课程学习的基础代码环境准备

模块一：运行你的第一个企业级 Multi-Agent（5 课）

• 07 | 定义Agent：从"提示词工程"到"人设工程"
• 08 | 定义Task：从"步骤控制"到"契约驱动"
• 09 | 定义Process：任务调度与信息传递
• 10 | 多模态模型：让你的Agent拥有"眼睛"
• 11 | 项目实战1：小红书爆款笔记生成项目

模块二：工具大全，赋予Agent与物理世界交互的能力（6 课）

• 12 | 工具设计哲学：从 API 到 Agent Tool 的范式跃迁
• 13 | 自定义工具封装：构建 Tools 的五步标准SOP
• 14 | MCP协议：标准化定义工具接口
• 15 | Skills协议：面向Agent的工具升级
• 16 | 王牌超能力：代码解释器与无头浏览器
• 17 | 项目实战2：能力篇——XiaoPaw 飞书本地工作助手（上）

模块三：上下文管理让Agent拥有记忆，突破Token限制（5 课）

• 18 | 记忆管理的使用：Short-term、Long-term & Entity Memory
• 19 | 自定义管理上下文：Step_Callback与数据流观测
• 20 | 知识库的使用与Embedding：RAG在CrewAI中的实现
• 21 | 超越信息的知识：通过动态沉淀skill让你的agent自主进化
• 22 | 项目实战3：记忆篇——XiaoPaw 长记忆助手

模块四：协作与设计模式，掌握多智能体协作体系（7 课）

• 23 | Orchestrator范式：任务层的主 Agent + 子 Agent
• 24 | 认知升级：从任务列表到数字团队
• 25 | 团队角色体系：分工设计与行为规范
• 26 | 任务链与信息传递：数字员工的协作协议
• 27 | Human as 甲方：如何设计 Agent 团队的人类介入点
• 28 | 数字员工的自我进化：让 Agent 团队越用越好
• 29 | 项目实战4：Agent 小队完成真实项目需求

模块五：企业级加固，确保系统安全可控（4 课）

• 30 | 提高健壮性：Replay、Test与Retry策略
• 31 | Guardrails：输入输出的安全护栏
• 32 | Hook：全链路监控与埋点
• 33 | 项目实战5：系统加固你的XiaoPaw 飞书工作助手

生产交付篇：全生命周期工程化（7 课）

从技术实现转向生产交付，关注需求分析、测试评估、可观测性、合规治理。

• 34 | 需求边界：如何使用"AI适用性评估表"识别高ROI场景？
• 35 | 场景演练：面向10万行代码库的"文档自动维护专家"架构拆解
• 36 | 持续集成（CI/CD）：基于GitOps的Knowledge库自动更新流水线
• 37 | 自动化测试（Eval）：引入LLM-as-a-Judge构建AI系统的"单元测试"
• 38 | 全链路可观测性：集成LangTrace实现Agent思考路径的可视化追踪
• 39 | 生产合规：Prompt版本管理、灰度发布与PII数据脱敏策略
• 40 | 组织进化：从Agent开发者到AI系统架构师的能力跃迁

📁 项目结构

crewai_mas_demo/
├── requirements.txt                    # Python 依赖包列表
│
├── llm/                                # 自定义 LLM 实现（课程06）
│   ├── __init__.py                    # 模块初始化
│   ├── aliyun_llm.py                  # 阿里云通义千问 LLM 实现（核心组件）
│   └── test_*.py                      # LLM 测试用例
│
├── tools/                              # 自定义工具（课程13）
│   ├── __init__.py                    # 模块初始化
│   ├── baidu_search.py                # 百度搜索工具（课程13示例）
│   ├── intermediate_tool.py           # 中间结果保存工具（课程07辅助工具）
│   ├── add_image_tool_local.py        # 本地图片加载工具（课程10核心工具）
│   ├── fixed_directory_read_tool.py   # 目录读取工具（课程13示例）
│   └── test_*.py                      # 工具测试用例
│
├── m1l2/                               # 课程02、07示例代码
│   ├── m1l2_agent.py                  # 单 Agent 调研示例（课程07）
│   ├── m1l2_raw_agent.py              # 原生 Agent 实现（课程02）
│   └── *.md                            # 示例输出文件
│
├── m1l3/                               # 课程09示例代码
│   ├── m1l3_multi_agent.py            # Multi-Agent 协作示例
│   └── *.md                            # 示例输出文件
│
├── m2l2/                               # 课程06示例代码
│   └── m2l2_llm_openai.py             # LLM 配置示例
│
├── m2l3/                               # 课程07示例代码
│   └── m2l3_agent.py                  # Agent 直接执行任务示例
│
├── m2l4/                               # 课程08示例代码
│   └── m2l4_task.py                   # Task 定义与结构化输出示例
│
├── m2l5/                               # 课程09示例代码
│   └── m2l5_crew.py                    # Sequential Process 多任务执行示例
│
├── m2l6/                               # 课程10示例代码
│   └── m2l6_agent.py                  # 多模态视觉分析示例
│
├── m2l8/                               # 课程19示例代码
│   ├── m2l8_context.py                # API 请求级上下文管理
│   └── m2l8_tools_call.py             # 工具调用 Hook 示例
│
├── m2l9/                               # 课程14示例代码
│   └── m2l9_mcp.py                     # MCP 服务器集成示例
│
├── m2l10/                              # 课程16示例代码（代码解释器 & 无头浏览器）
│
├── m2l16/                              # Skills 生态课程演示（课程16）
│   └── skills/                         # Skills 清单与技能文件
│
├── m2l17/                              # 课程17示例代码（项目实战2）
│
├── m2l22/                              # 课程22示例代码（项目实战3，同 xiaopaw-with-memory）
│
├── m3l19/                              # 课程19示例代码（上下文生命周期管理）
│
├── m3l20/                              # 课程20示例代码（文件系统记忆）
│
├── m3l21/                              # 课程21示例代码（搜索驱动的记忆系统）
│
├── m4l23/                              # 课程23示例代码（Orchestrator 范式）
│
├── m4l25/                              # 课程25示例代码（团队角色体系）
│
├── m4l26/                              # 课程26示例代码（任务链与信息传递）
│   ├── m4l26_manager.py               # Manager Crew（分配+验收）
│   ├── m4l26_pm.py                    # PM Crew（读邮件+写产品文档）
│   └── tools/mailbox_ops.py           # 三态邮箱状态机
│
├── m4l27/                              # 课程27示例代码（Human as 甲方）
│   ├── m4l27_sop_setup.py             # 时点A：SOP 制定入口
│   ├── m4l27_run.py                   # 时点B：任务执行入口（3个人工确认节点）
│   ├── m4l27_manager.py               # Manager 五个 Crew
│   └── tools/mailbox_ops.py           # 三态邮箱状态机（含 mark_done + reset_stale）
│
├── m4l28/                              # 课程28示例代码（数字员工的自我进化）
│
└── （定稿）上线素材｜企业级多智能体设计实战.md  # 课程大纲

🚀 快速开始

环境准备

• Python 3.10+
• 通义千问 API Key（必需）：访问 阿里云 DashScope 获取
• 百度搜索 API Key（必需）：访问 百度智能云 获取

💡 提示：本课程全程使用国内可访问的大模型接口，无需科学上网。

安装与配置

# 1. 克隆仓库
git clone <repository-url>
cd crewai_mas_demo

# 2. 创建虚拟环境（推荐）
python3 -m venv venv
source venv/bin/activate  # Linux/macOS
# 或 venv\Scripts\activate  # Windows

# 3. 安装依赖
pip install -r requirements.txt

# 4. 配置 API Key（二选一）
# 方式一：环境变量（推荐）
export QWEN_API_KEY="your-qwen-api-key-here"
export BAIDU_API_KEY="your-baidu-api-key-here"  # 可选

# 方式二：创建 .env 文件
# 在项目根目录创建 .env 文件，内容如下：
# QWEN_API_KEY=your-qwen-api-key-here
# BAIDU_API_KEY=your-baidu-api-key-here

启动 AIO-Sandbox 沙盒环境（用于 MCP / Skills 示例）

部分示例（如课程14 MCP、课程16 Skills 生态）需要本地启动 AIO-Sandbox 容器，提供沙盒执行环境：

cd crewai_mas_demo

# 启动沙盒（推荐后台运行）
docker compose -f sandbox-docker-compose.yaml up -d

# 不再需要时关闭沙盒
docker compose -f sandbox-docker-compose.yaml down

说明：

• 沙盒 MCP 端点：http://localhost:8022/mcp
• 本地挂载目录：
  • ./workspace/data 挂载为沙盒内 /workspace/data（只读，输入文件）
  • ./workspace/output 挂载为沙盒内 /workspace/output（读写，输出文件）
  • ./skills 挂载为沙盒内 /mnt/skills（只读，Skill 资源）

沙盒启动后，可以通过curl命令请求tools/list，检查是否成功：

curl -X POST http://localhost:8022/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":1}'

运行示例

示例 1：原生 Agent 实现（课程02）

理解 Agent 的核心原理和 ReAct 范式。

cd m1l2
python3 m1l2_raw_agent.py

学习要点：

• Agent 的本质：循环调用 LLM 和执行工具
• ReAct 范式：Reasoning → Acting → Observation
• 工具调用机制：解析 LLM 输出并执行工具
• 对话历史管理：维护 LLM 上下文

对应课程：02｜解构智能体：Agent 的解剖学与 ReAct 范式

---

示例 2：单 Agent 调研（课程07，推荐新手入门）

学习如何定义 Agent 的"人设"。

cd m1l2
python3 m1l2_agent.py

学习要点：

• Agent 的 Role、Goal、Backstory 定义（人设工程）
• 工具集成（搜索、网页抓取、文件写入）
• ReAct 循环的实际运行过程
• Task 和 Crew 的创建

输出结果：

• 控制台：Agent 的思考过程（Thought/Action/Observation）
• 文件：m1l2/极客时间-最终报告.md

对应课程：07｜定义Agent：从"提示词工程"到"人设工程"

预期时间：约 2-5 分钟

---

示例 3：Agent 直接执行任务（课程07）

演示 Agent.kickoff() 直接与 Agent 交互。

cd m2l3
python3 m2l3_agent.py

学习要点：

• Agent.kickoff() 的使用方法
• 无需创建 Task 和 Crew 的简单场景
• IntermediateTool 的使用

对应课程：07｜定义Agent：从"提示词工程"到"人设工程"

---

示例 4：Task 定义与结构化输出（课程08）

学习"契约驱动"的任务设计。

cd m2l4
python3 m2l4_task.py

学习要点：

• Pydantic 模型定义数据结构（契约）
• Task 的 output_pydantic 参数
• Task 的 context 参数实现任务依赖
• Mock 上游任务输出

对应课程：08｜定义Task：从"步骤控制"到"契约驱动"

---

示例 5：Multi-Agent 协作（课程09）

学习多 Agent 协作和任务调度。

cd m1l3
python3 m1l3_multi_agent.py

学习要点：

• 多 Agent 协作（Researcher、Searcher、Writer、Editor）
• Sequential Process 实现
• 任务依赖关系（context 参数）
• Agent 委托机制（allow_delegation）

输出结果：

• 控制台：多个 Agent 的协作过程
• 文件：m1l3/极客时间平台全面调研报告-*.md（大纲、步骤1-6、最终报告）

对应课程：09｜定义Process：任务调度与信息传递

预期时间：约 5-10 分钟

---

示例 6：Sequential Process 多任务流程（课程09）

演示多任务的顺序执行和数据传递。

cd m2l5
python3 m2l5_crew.py

学习要点：

• 多个 Task 的定义和依赖关系
• Sequential Process 确保任务顺序执行
• 任务之间的数据传递（context 和 inputs）
• 结构化输出的链式传递

对应课程：09｜定义Process：任务调度与信息传递

---

示例 7：多模态视觉分析（课程10）

让 Agent 具备"看"的能力。

cd m2l6
python3 m2l6_agent.py

学习要点：

• 多模态 Agent 配置（AddImageToolLocal）
• 图片处理流程（读取 → Base64 → 多模态模型）
• 结构化输出（Pydantic 模型）
• 视觉分析报告的生成

对应课程：10｜多模态模型：让你的Agent拥有"眼睛"

---

示例 8：上下文管理与 Hook（课程19）

学习 API 请求级上下文管理和工具调用拦截。

cd m2l8
python3 m2l8_tools_call.py

学习要点：

• Hook 机制（before_tool_call、after_tool_call）
• 上下文变量（contextvars）的使用
• 文件路径安全校验和重定向
• 多租户工作空间隔离

对应课程：19｜自定义管理上下文：Step_Callback与数据流观测

---

示例 9：MCP 协议集成（课程14）

学习如何通过 MCP 协议集成外部工具服务。

cd m2l9
python3 m2l9_mcp.py

学习要点：

• MCP 服务器配置（HTTP 方式）
• 工具过滤器（Tool Filter）的使用
• 多租户支持（通过 headers 传递 user_id）
• 工具缓存（cache_tools_list）

对应课程：14｜MCP协议：标准化定义工具接口

常见问题

问题	解决方案
ModuleNotFoundError: No module named 'crewai'	pip install -r requirements.txt
ValueError: API Key 未提供	检查环境变量：echo $QWEN_API_KEY（Linux/macOS）或 echo $env:QWEN_API_KEY（Windows）
No module named 'llm'	确保在示例目录下运行：cd m1l2 && python3 m1l2_agent.py

🛠️ 核心组件

自定义 LLM（llm/aliyun_llm.py）

基于 CrewAI BaseLLM 的阿里云通义千问实现，完全兼容 CrewAI 接口，支持 Function Calling 和多地域配置。

from llm import aliyun_llm

llm = aliyun_llm.AliyunLLM(
    model="qwen-plus",
    api_key=os.getenv("QWEN_API_KEY"),
    region="cn",  # 支持 "cn", "intl", "finance"
)

自定义工具（tools/）

课程13的示例代码展示了如何按照五步标准SOP封装自定义工具。

百度搜索工具（baidu_search.py）

支持网页、视频、图片等多种资源类型，演示完整的工具封装流程。

from tools import BaiduSearchTool

agent = Agent(
    role="网络调研专家",
    tools=[BaiduSearchTool()],
    # ...
)

功能特点：

• 支持时间筛选（week/month/semiyear/year）
• 支持指定站点搜索
• 完整的错误处理和日志记录
• 格式化的搜索结果输出

其他工具

• IntermediateTool（intermediate_tool.py）：中间结果保存工具，支持 Agent 的"慢思考"模式
• AddImageToolLocal（add_image_tool_local.py）：本地图片加载工具，支持多模态 Agent
• FixedDirectoryReadTool（fixed_directory_read_tool.py）：目录读取工具，修复了原版本的路径处理问题

📖 学习路径

第一阶段：基础入门（课程02-06）

1. 理解 Agent 本质（课程02）

   • 运行 m1l2/m1l2_raw_agent.py，理解 ReAct 范式
   • 掌握 Agent 的核心工作原理

2. 环境准备（课程06）

   • 配置 LLM 环境（llm/aliyun_llm.py）
   • 了解自定义 LLM 的实现方式

第二阶段：核心能力（课程07-10）

3. 定义 Agent（课程07）

   • 运行 m1l2/m1l2_agent.py 和 m2l3/m2l3_agent.py
   • 学习 Role、Goal、Backstory 的"人设工程"
   • 掌握工具集成方法

4. 定义 Task（课程08）

   • 运行 m2l4/m2l4_task.py
   • 学习"契约驱动"的任务设计
   • 掌握 Pydantic 结构化输出

5. 定义 Process（课程09）

   • 运行 m1l3/m1l3_multi_agent.py 和 m2l5/m2l5_crew.py
   • 学习多 Agent 协作和任务调度
   • 掌握任务依赖关系

6. 多模态能力（课程10）

   • 运行 m2l6/m2l6_agent.py
   • 学习如何让 Agent 具备"看"的能力
   • 掌握图片处理和多模态模型集成

第三阶段：工具与上下文（课程12-19）

7. 工具封装（课程13）

   • 学习 tools/baidu_search.py 的实现
   • 掌握五步标准SOP封装工具
   • 理解工具设计的最佳实践

8. MCP 协议（课程14）

   • 运行 m2l9/m2l9_mcp.py
   • 学习如何集成外部工具服务
   • 掌握工具过滤器和多租户支持

9. 上下文管理（课程19）

   • 运行 m2l8/m2l8_tools_call.py
   • 学习 Hook 机制和上下文变量
   • 掌握多租户数据隔离

第四阶段：实战项目（课程11、17、22、29、33）

• 项目实战1（课程11）：小红书爆款笔记生成项目
• 项目实战2（课程17）：XiaoPaw 飞书工作助手（上）
• 项目实战3（课程22）：XiaoPaw 飞书工作助手（下）
• 项目实战4（课程29）：全栈软件开发团队项目
• 项目实战5（课程33）：系统加固你的XiaoPaw 飞书工作助手

第五阶段：生产交付（课程34-40）

学习需求分析、测试评估、可观测性、合规治理等生产级实践。

🔧 开发指南

代码注释说明

本仓库的所有 Python 代码都包含详细的课程关联注释，遵循统一的标准：