CrewAI + FastAPI 实战：搭建多Agent协作应用

什么是 CrewAI

随着大模型能力的成熟，单一模型对话已经无法满足复杂业务场景的需求，「多智能体协作」逐渐成为 AI 应用开发的新范式。多智能体系统（Multi-Agent System）的兴起，本质上源于单一大模型的固有局限——即便是 GPT-4 这类顶级模型，在面对需要长链推理、跨领域知识整合或超长上下文处理的任务时，依然容易出现「幻觉」、遗忘中间步骤或推理深度不足等问题。多智能体架构通过任务分解与专业化分工，将复杂问题拆解为多个可管理的子任务，每个 Agent 专注于自身擅长的领域，从而显著提升整体输出质量。

CrewAI 正是这一趋势下的代表性框架——它专为构建多 Agent 系统而设计，让多个具有不同角色和目标的 Agent 共同协作，完成原本难以独立处理的复杂任务。值得一提的是，CrewAI 构建于 LangChain 生态之上，但专注于解决 LangChain 在多 Agent 编排上的复杂性问题：LangChain 提供了底层的 LLM 调用、工具集成和链式推理能力，CrewAI 则在此之上封装了更高层的「角色扮演」抽象，使开发者无需深入理解底层 Agent 循环机制即可快速构建协作系统。

其核心思路是：将一个复杂任务拆解后，分配给不同的 Agent，每个 Agent 借助自身特定的技能和工具完成各自职责，最终汇聚成整体目标。这种设计非常像现实中的项目团队——每个人各司其职，共同交付完整成果。

本文梳理 CrewAI 的核心概念，并演示如何结合 FastAPI 对外提供 API 服务，最终打造一个可调用的多 Agent 应用。

CrewAI 的五大核心概念

理解 CrewAI，关键在于吃透它的几个核心抽象。

Agent（智能体）

Agent 是一个自主可控的执行单元，可以执行任务、做出决策并与其他 Agent 协作交流，类比于团队中的一员。它的关键属性包括：

• 角色（role）：定义 Agent 在团队中承担的职能
• 目标（goal）：Agent 要实现的具体目标
• 背景故事（backstory）：为 Agent 提供上下文，塑造其行为风格

背景故事（backstory）并非装饰性文字——它本质上是写入系统提示词（System Prompt）的角色设定，直接影响大模型的输出风格和决策偏好。精心设计的 backstory 能够有效激活模型在特定领域的知识储备，使其表现更接近领域专家。

Task（任务）

Task 是分配给 Agent 的具体工作单元，需要提供执行所需的所有细节。核心属性包括任务描述、分配的 Agent、期望输出、可用工具列表等。你可能没注意到，Task 支持 context 属性，即可以将上一个任务的输出作为下一个任务的输入，从而实现任务链式传递。输出既可以是结构化格式，也可以直接写入指定格式的文件（如 txt、md）。

Process（流程）

Process 负责协调 Agent 执行任务，类似团队中的项目经理。目前提供两种机制：

• 顺序流程（Sequential）：按照任务列表预定顺序执行，前一个任务的输出作为下一个任务的上下文
• 分层流程（Hierarchical）：指定一个「管理者 Agent」监督任务的计划、授权与验证，任务不预先分配，而是根据各 Agent 能力动态调度

分层流程在底层实现了类似 ReAct（Reasoning + Acting）的推理循环——管理者 Agent 持续观察子 Agent 的执行结果，动态决定下一步的任务分配策略，这也是为什么分层流程需要单独指定一个能力较强的 manager_llm。

Crew（团队）

Crew 代表一组协作完成任务的 Agent 集合，定义了任务的执行策略、Agent 的协作方式和整体工作流。主要属性包括任务列表（tasks）、Agent 列表（agents）和 process。如果采用分层流程，还需通过 manager_llm 指定管理者 Agent 所使用的大模型。

Pipeline（流水线）

Pipeline 是更高层的编排结构，允许多个 Crew 顺序或并行执行。它涉及 Stage（阶段）、Run（运行实例）、Trace（执行轨迹跟踪）等概念，适合构建更复杂的多阶段工作流。Pipeline 中并行执行的多个 Crew 之间相互独立，各自拥有独立的 Agent 和 Task，最终由 Pipeline 汇总各阶段结果，非常适合需要同时从多个维度分析同一问题的场景。

官方入门案例解析

为便于理解，教程采用了官方入门案例，功能是围绕某个主题自动生成一份研究报告。

案例定义了两个 Agent：

• 研究员：角色是对某主题的高级数据研究员，目标是探索该主题的前沿发展，背景设定为「擅长发现最新进展、以简洁明了方式呈现信息的资深研究员」
• 报告分析员：角色是根据数据分析结果创建详细报告，背景设定为「一丝不苟、擅长将复杂数据转化为简洁报告的分析师」

对应地定义了两个 Task：研究任务（对主题进行深入研究，输出包含十个要点的清单，分配给研究员）和报告任务（基于十个要点扩展为完整报告，输出 Markdown 文件，分配给报告分析员）。两个任务通过 context 串联，形成「先研究、后成文」的流水线。

环境准备与多模型接入

实战前的准备工作分为几块，其中大模型接入的灵活性是本教程的一大亮点——支持 GPT、非 GPT 云端模型以及本地开源模型三种方案。

开发环境

使用 Anaconda 提供 Python 虚拟环境，PyCharm 作为集成开发工具，Python 版本选择 3.11。

三种大模型接入方案

• GPT 模型：通过代理方式接入
• 非 GPT 云端模型：借助 One-API（OpenAI 接口管理分发系统） 统一管理国产模型。One-API 是一个开源的 API 中间件，其核心价值在于将不同厂商的大模型 API 统一适配为 OpenAI 格式——由于 OpenAI 的 API 规范已成为行业事实标准，国内主流模型厂商（阿里、讯飞、智谱等）均提供了兼容接口，One-API 作为中间层可统一管理多个 API-Key、实现负载均衡并监控用量和费用。以阿里通义千问为例，在 One-API 中创建渠道、绑定百炼平台的 API-Key，再生成令牌得到统一的 API-Key，代码中直接调用即可无缝切换千问、讯飞星火、智谱等国产模型
• 本地开源模型：使用 Ollama 部署。Ollama 是目前最主流的本地大模型运行框架之一，基于 llama.cpp 实现高效的 CPU/GPU 混合推理，支持一行命令拉取并运行 Llama、Mistral、Gemma、Qwen 等数十种开源模型，显著降低了本地部署的硬件门槛。对于数据隐私敏感的企业场景，Ollama 提供了完全离线的推理能力，所有数据不出本地网络。可预装通义千问2、Llama 3.1（8B）、Gemma2 等主流开源模型

这种「一套代码、多种模型」的架构设计，让开发者在测试和生产环境之间切换时非常方便。

CrewAI + FastAPI 实战搭建

整体分两步走：先跑通官方模板，再封装成 API 服务。

第一步：跑通官方模板

通过 CrewAI 提供的脚手架指令创建工程模板，生成的项目结构清晰：config 目录下存放 agents.yaml 和 tasks.yaml 两个配置文件，另有 main.py（入口）和 crew.py（创建 Crew 的核心脚本）。

配置好 .env 中的 API URL、API-Key 和模型名称后，执行 crewai install 安装依赖，再执行 crewai run 即可启动。运行完成后，项目根目录会生成一份 report.md 报告文件。

从执行日志可以清晰看到协作过程：研究员 Agent 首先拉取该主题的前沿信息，CrewAI 新建执行链一步步引导其完成工作；研究员完成后，报告分析员 Agent 接手，根据上文提供的信息撰写报告，最终输出到 Markdown 文件。

第二步：封装为 FastAPI 服务

FastAPI 是基于 Python 的现代异步 Web 框架，基于 Starlette 和 Pydantic 构建，原生支持异步 IO（async/await）。在 AI 服务场景中，大模型推理往往耗时数秒乃至数十秒，FastAPI 的异步特性可以在等待模型响应期间继续处理其他请求，显著提升服务并发能力；其自动生成的 OpenAPI 文档也便于前端团队快速集成。

在官方模板基础上引入 FastAPI，让 CrewAI 能够对外提供标准化接口服务。核心逻辑包括：

1. 模型配置：代码中预置了千问 Max、GPT-4o mini、Llama 3.1 三套配置，通过一个标志位切换当前使用的模型
2. 应用初始化：使用 FastAPI 的生命周期钩子（Lifespan），在启动时根据标志位加载对应大模型的环境变量，结束时执行清理
3. POST 接口：接收用户传入的 topic，调用 run 函数触发 Crew 的 kickoff 方法执行，最后将报告结果通过流式或非流式两种方式返回给请求端

通过独立的 api_test.py 脚本向 localhost:8012 发送 POST 请求，即可测试整套服务。返回结果与本地运行完全一致，说明封装成功。

三种模型实测对比

用同一个问题分别测试三种模型，结论颇具参考价值：

• GPT-4o mini：效果最佳，严格按要求输出 10 条信息，速度也较快
• 通义千问 Max：效果不错，但输出了 15 条（未严格遵守 10 条要求），速度略慢于 GPT-4o mini
• Llama 3.1（7B 本地）：效果最弱，研究阶段仅找到 3 条信息，最终报告内容明显不足，且受限于本地硬件资源运行较为吃力

这一结果背后有清晰的技术原因：模型的指令遵循能力（Instruction Following）与参数规模高度相关。7B 参数级别的本地模型在指令遵循、格式控制和复杂推理方面普遍弱于大参数或闭源商业模型——大参数模型在 RLHF（基于人类反馈的强化学习）阶段能够学习到更细粒度的指令边界。在 Agent 系统中，指令遵循能力尤为关键：Agent 需要精确按照系统提示词定义的角色和输出格式行事，任何偏差都可能破坏任务链的完整性，导致后续 Agent 接收到质量不达标的上下文输入。

这一对比揭示了一个关键的工程实践要点：构建 Agent 应用时，模型选型必须经过充分评估。小参数本地模型虽然免费且隐私可控，但在复杂任务中往往力不从心，建议在硬件条件允许时优先选用参数更大的模型（如 32B 以上的本地模型，或直接使用云端商业模型）。

总结

CrewAI 为多 Agent 应用开发提供了一套清晰的抽象体系——从 Agent、Task 到 Process、Crew、Pipeline，层层递进地支持从简单到复杂的编排需求。结合 FastAPI，开发者可以快速将 Agent 能力封装为标准 API 对外服务，融入现有系统。

真正决定应用效果的，除了框架的合理设计，更在于底层大模型的能力选型。GPT、国产云端模型、本地开源模型各有取舍，需要在成本、隐私、性能之间寻找平衡点——云端商业模型指令遵循能力强但存在数据出境风险，本地开源模型隐私可控但对硬件要求较高且效果存在上限。对于想要入门多 Agent 开发的开发者而言，CrewAI 的低门槛与高灵活性无疑是一个理想的起点。

核心要点