开源AI代理实战：用CrewAI构建多智能体自动化工作流

最近半年AI 代理AI Agent的概念被频繁提起。很多人已经从“用 ChatGPT 聊天”的阶段进入“让 AI 自动完成一整条任务链路”的阶段。但真正动手时很多人会发现单个 Agent 的能力始终有限处理复杂任务时经常断档而从头搭建一套完善的 Agent 系统又要面对模型接入、工具调用、任务编排、上下文管理等一堆问题。如果你也卡在这里不妨把目光转向开源 AI 代理项目。这篇文章会围绕开源 AI 代理、多智能体协作和自动化工作流展开从基础概念讲到完整实战。内容包括AI 代理解决了什么问题、主流开源框架的差异、如何用几行代码搭建一个能自动完成“选题 - 检索资料 - 写稿 - 审核”的 AI 内容团队以及如何接入本地模型保护数据安全。新手可以把它当作第一份 AI Agent 入门教程有经验的开发者也可以直接跳到实战章节复用代码。1. 背景与核心概念1.1 什么是 AI 代理AI AgentAI 代理是一个能够感知环境、做出决策并执行动作的智能体。传统的大语言模型LLM只能根据用户的提问生成文本回复它本身不具备调用外部工具、读取实时数据、执行多步骤任务的能力。AI 代理则是在大语言模型之上增加了一个循环机制接收任务、拆解步骤、调用工具、检查结果、调整策略直到任务完成。用一个通俗的例子来理解普通 ChatGPT你问“帮我查一下北京市明天的天气”它只能告诉你“我无法实时查询天气请打开天气 App”。AI 代理你下达同一个指令后Agent 会调用一个天气 API获取数据再自动整理成一段回复给你。所以AI 代理的价值不在于“更聪明”而在于“更能做事”。它把大模型从聊天机器人变成了自动化流程的执行者。1.2 从单 Agent 到多智能体协作单个 Agent 虽然能完成简单任务但在复杂业务场景中会遇到几个问题上下文过长一个 Agent 需要同时负责数据分析、文案撰写和代码编写上下文很快就会超过模型窗口限制。角色冲突写代码的模型和审查代码的模型如果是同一套提示词审查效果会大打折扣。任务串行低效复杂的调研任务经常需要并行处理多个方向单 Agent 只能一步步执行。多智能体协作Multi-Agent Collaboration的思路是把一个复杂任务拆分成多个子任务交给不同角色的 Agent 并行处理最后再汇总结果。举例来说一个 AI 内容团队可以这样分工策划 Agent负责选题和文章大纲。资料 Agent负责检索资料、收集数据。作者 Agent负责撰写初稿。审核 Agent负责逻辑检查、事实核对和润色。每个 Agent 有自己的角色设定、知识背景和工作目标。通过任务编排器Orchestrator统一调度最终形成一条自动化工作流。1.3 开源 AI 代理的优势与适用场景开源 AI 代理项目的核心优势有三个成本可控框架本身免费模型可以选开源模型或本地部署模型避免按 Token 付费的压力。数据私密可以完全离线运行敏感数据不会经过第三方 API。可扩展任何环节都可以改代码按业务需求定制 Agent 的行为。适用场景非常广自动化日报生成、客服工单分类与回复、代码仓库审查、竞品信息收集、研究报告撰写、企业知识库问答等。可以说凡是“需要大模型 外部工具 多步骤处理”的事情都可以用 AI 代理来做。2. 核心概念拆解一个 Agent 是怎么工作的在进入实战之前先拆解一个 Agent 的内部结构。理解这些组件以后你在配置开源项目时就不会觉得参数是魔法数字了。2.1 Agent 的五大核心组件模型ModelAgent 的大脑负责理解任务、生成决策。常见选择有 OpenAI 的 GPT 系列、Anthropic 的 Claude以及开源模型 Qwen、Llama、DeepSeek 等。指令Instructions / Persona即系统提示词定义 Agent 的角色与行为边界。工具ToolsAgent 能调用的外部能力如搜索引擎、计算器、代码解释器、API 接口。记忆Memory短期记忆保存当前任务的中间状态长期记忆保存历史知识。规划Planning把复杂任务拆解成可执行步骤的能力。2.2 多智能体协作的常见模式编排者 - 工人模式Orchestrator - Worker一个主管 Agent 负责任务分解与结果汇总多个工作 Agent 分头执行。流水线模式PipelineAgent 按顺序接力上一个 Agent 的输出是下一个 Agent 的输入。辩论模式Debate多个 Agent 围绕一个问题各自提出观点再互相质疑最终收敛出更高质量的结论。层级模式Hierarchical多级 Agent 结构上层负责策略下层负责执行。不同开源框架对上述模式的支持程度不同。接下来看看目前主流的开源项目怎么选。3. 主流开源 AI 代理框架选型3.1 开源生态现状AI 代理领域的开源项目可以用“爆发式增长”来形容。目前社区讨论度较高的框架包括框架核心特点适合场景CrewAI基于角色的 Agent 协作API 简单直观快速搭建多 Agent 工作流AutoGen微软出品支持多 Agent 对话与代码执行复杂推理与研究任务LangGraph基于图结构编排 Agent 流程可控性强生产级复杂流程MetaGPT模拟软件公司流程内置产品经理/架构师/工程师角色自动化软件开发Dify可视化编排支持工作流画布业务人员快速搭建 AI 应用以上各框架都有活跃的社区。如果你刚开始接触建议从 CrewAI 入手因为它的抽象层级最贴近“创建角色、安排任务”的自然思路代码量也最少。3.2 为什么推荐从 CrewAI 开始CrewAI 的设计理念是一支“AI 团队”Crew。你可以把不同角色定义为不同 Agent再把任务分配给它们。看一段最小示例from crewai import Agent, Task, Crew, Process # 定义 Agent researcher Agent( role高级研究员, goal收集并整理某领域的最新进展, backstory你是一名专业的研究员擅长从资料中提取关键信息, verboseTrue ) # 定义 Task research_task Task( description搜索并总结开源 AI 代理在 2024 年的代表性项目, agentresearcher, expected_output一份包含项目名称、特点、Star 数的清单 ) # 组成 Crew crew Crew( agents[researcher], tasks[research_task], processProcess.sequential # 按顺序执行 ) result crew.kickoff() # 启动工作流 print(result)这段代码是理解 CrewAI 的最佳入口Agent 定义角色Task 定义任务Crew 把两者组合起来执行。后续所有复杂功能都是在这三个核心类上叠加。4. 环境准备与版本说明4.1 环境准备本文实战部分以 Python 3.10 为例操作系统不限Windows / macOS / Linux 均可。主要依赖如下Python 3.10 或更高版本CrewAI 及相关依赖大模型 API 或本地模型服务版本需要根据你的项目实际情况调整本文示例以常见环境为例重点演示配置思路。安装 CrewAI 时建议使用虚拟环境避免污染全局 Python 环境。# 创建并激活虚拟环境Windows 示例 python -m venv venv venv\Scripts\activate # macOS / Linux 示例 # source venv/bin/activate # 安装 CrewAI pip install crewai如果你的网络环境访问 PyPI 较慢可以临时使用国内镜像源pip install crewai -i https://pypi.tuna.tsinghua.edu.cn/simple4.2 模型接入说明CrewAI 默认支持 OpenAI 格式的 API。你既可以直接使用 OpenAI 的接口也可以使用兼容 OpenAI 协议的国内模型服务还可以通过 Ollama 接入本地模型。本文实战部分会提供两种方式。使用 API Key 时建议通过环境变量注入不要硬编码在代码里export OPENAI_API_KEYsk-你的密钥Windows 下使用set OPENAI_API_KEYsk-你的密钥5. 完整实战搭建一个自动化 AI 内容创作团队这一节是全文的核心。我们要搭建一个三角色协作的 AI 内容团队资料研究员Researcher负责检索指定主题的资料输出事实清单。内容作者Writer基于事实清单撰写技术文章初稿。审核编辑Editor检查文章逻辑、补充缺失内容并润色。整条工作流自动执行从选题到成稿无需人工干预。这个案例可以直接迁移到技术日报生成、产品文案产出、竞品分析报告等场景。5.1 创建项目结构ai_crew_demo/ ├── .env # 存放环境变量 ├── agents.py # 定义 Agent 角色 ├── tasks.py # 定义任务 ├── main.py # 主流程入口 └── requirements.txt # 依赖清单5.2 添加依赖与配置先准备requirements.txtcrewai python-dotenv然后在项目根目录创建.env文件OPENAI_API_KEY你的密钥 OPENAI_MODEL_NAMEgpt-4o-mini注意gpt-4o-mini是目前 OpenAI 中性价比相对较高、适合跑通流程的模型。如果你的模型供应商不同请按实际情况修改OPENAI_MODEL_NAME。5.3 定义 Agent 角色文件路径agents.pyfrom crewai import Agent researcher Agent( role高级资料研究员, goal围绕用户给定的主题收集事实准确、来源可靠的信息并整理成结构化要点, backstory你有十余年行业研究经验擅长在海量信息中快速定位高质量内容。 你输出的所有内容都必须有明确依据不能凭空编造。, verboseTrue ) writer Agent( role技术文章作者, goal根据研究员提供的资料要点撰写一篇逻辑清晰、通俗易懂的技术文章初稿, backstory你是一名资深技术博主擅长把复杂概念讲清楚。你注重文章结构、 代码示例和实用性写作风格自然流畅。, verboseTrue ) editor Agent( role内容审核编辑, goal对文章初稿进行逻辑检查、事实核对和文字润色输出最终可发布版本, backstory你是一名严谨的编辑对表达准确性和逻辑一致性有极高要求。 你会指出文中不确定的内容并给出修改建议。, verboseTrue )这里解释两个关键点role和goal会共同构成系统提示词。写得越具体Agent 的行为越稳定。backstory用来补充角色的背景设定它会影响模型生成时的语气与思维模式。5.4 定义任务文件路径tasks.pyfrom crewai import Task from agents import researcher, writer, editor research_task Task( description研究主题「开源 AI 代理框架的选型与对比」。 请收集 3-5 个主流开源框架的基本信息包括核心特点、适用场景、社区活跃度 并总结为一个事实清单。, agentresearcher, expected_output一份 Markdown 格式的事实清单包含每个框架的核心信息和适用建议。 ) write_task Task( description根据研究阶段的事实清单撰写一篇 3000 字左右的技术文章。 文章需要包含背景介绍、核心概念解释、框架对比表格、代码示例、常见问题。 风格要贴近技术博客不要使用营销口吻。, agentwriter, expected_output一篇结构完整的 Markdown 格式技术文章初稿。 ) edit_task Task( description对文章初稿进行审核和润色。重点检查逻辑是否通顺、章节是否完整、 代码示例是否正确、是否有明显的事实错误。最终输出一份可发布的版本。, agenteditor, expected_output一篇经审核后可发布的 Markdown 格式文章。 )expected_output是一个容易被忽略但对结果质量影响很大的参数。它告诉 Agent“你要交付什么格式的东西”如果没有它模型可能会随便丢一段话出来。5.5 编写主流程文件路径main.pyimport os from dotenv import load_dotenv from crewai import Crew, Process # 加载 .env 中的 API Key load_dotenv() from agents import researcher, writer, editor from tasks import research_task, write_task, edit_task # 组成 AI 团队 content_crew Crew( agents[researcher, writer, editor], tasks[research_task, write_task, edit_task], processProcess.sequential, # 顺序执行 verboseTrue ) if __name__ __main__: result content_crew.kickoff() print(\n 最终输出 \n) print(result)Process.sequential表示按任务列表顺序执行。CrewAI 还支持Process.hierarchical层级模式但层级模式需要额外指定 manager Agent对新手来说先在顺序模式下跑通比较合适。5.6 运行与验证在项目根目录运行python main.py第一次运行时CrewAI 会下载需要的模型配置并依次执行任务。如果一切正常你会看到类似下面的输出[2024-XX-XX XX:XX:XX] [INFO]: Task 1/3 started. [2024-XX-XX XX:XX:XX] [INFO]: Task 2/3 started. [2024-XX-XX XX:XX:XX] [INFO]: Task 3/3 started. 最终输出 # 开源 AI 代理框架选型与对比 ...整个执行过程从“研究 - 写作 - 审核”自动完成。你也可以调整 keyword关键词来生成不同主题的文章这比每次从零开始写提示词高效得多。5.7 接入本地模型用 Ollama 实现数据私密有些公司的项目数据不能离开内网这时可以把模型切换到本地部署的 Ollama。安装 Ollama 后先拉取一个模型例如 Qwen通义千问的开源版本ollama pull qwen2.5:7b然后用环境变量指定 CrewAI 使用本地模型export OPENAI_API_BASEhttp://localhost:11434/v1 export OPENAI_API_KEYollama # Ollama 不校验 key但需要占位 export OPENAI_MODEL_NAMEqwen2.5:7bWindows 下使用set OPENAI_API_BASEhttp://localhost:11434/v1 set OPENAI_API_KEYollama set OPENAI_MODEL_NAMEqwen2.5:7b之后运行python main.py整个流程会在本地完成。需要注意本地模型的推理速度取决于显卡性能7B 级别模型在纯 CPU 环境下会比较慢建议至少使用 16GB 内存并优先用 GPU 推理。6. 进阶为 Agent 添加工具调用6.1 工具的作用当前示例中的三个 Agent 都是靠模型自身知识在“写文章”并没有真正去检索资料。要让 Agent 自动联网搜索、访问数据库或调用内部接口需要给它挂载工具。CrewAI 中工具的抽象非常简单本质上就是“一个可被模型调用的函数”。先安装官方工具包pip install crewai-tools6.2 给研究员添加搜索能力CrewAI 官方提供了SerperDevTool需要 Serper API Key也有WebsiteSearchTool等网页检索工具。示例思路如下from crewai_tools import SerperDevTool search_tool SerperDevTool() researcher Agent( role高级资料研究员, goal围绕用户给定的主题通过互联网搜索收集准确、可靠的信息, backstory你擅长使用搜索工具快速检索高质量资料。, tools[search_tool], verboseTrue )这样研究员在执行任务时模型会自动决定是否调用搜索工具、搜索什么关键词、如何解读返回结果。工具调用机制的原理是CrewAI 会把工具的名称、描述和参数结构注入给模型模型根据任务需要“请求”调用工具框架再执行工具并把结果返回给模型。这个过程对大模型有额外的 Token 消耗但对结果质量提升非常明显。6.3 自定义工具如果没有找到现成的工具也可以把任意 Python 函数变成 Agent 工具from crewai_tools import tool tool(获取今日沪深300指数) def get_index_price(): 调用内部行情接口返回今日沪深300指数的收盘价和涨跌幅。 # 这里放置你的实际调用逻辑 data {index: 沪深300, close: 3980.55, change_pct: 0.82} return str(data)把自定义工具加进tools列表即可。要注意的是函数的 docstring 会被模型作为工具说明所以必须写得明确完整模型才知道何时调用它。7. 常见问题与排查思路以下是搭建开源 AI 代理项目时最高频的几类问题我按“现象 - 原因 - 方案”的方式整理成表。问题现象常见原因解决思路执行时报OpenAIConnectionErrorAPI Key 未设置、网络不通或代理冲突检查.env文件与环境变量确认 API Base 是否正确模型返回内容与预期差距大提示词中的角色、目标或输出格式不够具体重写role、goal、backstory并细化expected_output任务执行到一半中断上下文窗口超限、API 限流或 Token 不足减小任务颗粒度换成长上下文模型降低单次输入内容量CrewAI 安装失败Python 版本过低或依赖冲突确认 Python 版本不低于 3.10使用干净虚拟环境重装本地模型响应极慢无 GPU、模型规模过大或内存不足使用更小的量化模型如 qwen2.5:3b调整 ollama 的并发参数多个 Agent 输出互相矛盾角色职责边界不清晰为每个 Agent 的项目范围确认项目范围邮箱里要明确“不许做什么”7.1 提示词相关的核心坑多智能体协作项目里80% 的“模型不听话”问题出在提示词没有写清楚边界。写提示词时的三个建议给 Agent 设定禁止行为。例如“不要编造统计数据如果没有找到数据就明确说明”。给 Task 提供参考格式。例如“输出必须是 Markdown 表格包含列名”。给 Agent 限定信息来源优先级。例如“优先采用开源社区官方文档的信息其次才是第三方博客”。7.2 Token 消耗怎么控制使用 API 模型时多 Agent 协作的 Token 消耗会成倍增长。控制成本的手段有尽量使用 mini 或轻量模型做信息筛选。对于固定格式的任务使用结构化输出而不是自由文本对话。在任务描述中直接要求“用简洁语言不要长篇解释”。定期检查日志中每次任务的 Token 用量找到消耗大户并优化其提示词。8. 最佳实践与工程建议8.1 从简单流程开始再逐步扩展刚开始搭建多智能体项目时建议先用两个 Agent 跑通一个最简单的顺序任务比如“资料整理 摘要输出”确认模型接入、Token 消耗、输出格式都没问题再逐渐增加角色和并行流程。一上来就搭五个 Agent 的复杂系统排错成本会非常高。8.2 配置与代码分离模型名称、API Base、API Key、温度参数等都属于环境配置应该统一放在.env或配置中心不要散落在各个脚本中。这样每次切换模型或环境时不需要改动核心代码。8.3 日志与可观测性生产环境的多智能体系统必须记录完整日志。CrewAI 提供了详尽的执行日志建议至少保留以下信息每个 Agent 的执行时间与状态。每个 Task 的输入、输出摘要。工具调用记录哪个工具、传入什么参数、返回什么结果。Token 消耗统计。有了这些日志你能在 Agent 行为异常时快速定位是提示词的问题、工具的问题还是模型选择的问题。8.4 安全与权限边界这个部分容易被忽略但在工程化落地时很重要API Key 必须严格保密。不要把密钥提交到 Git 仓库建议使用环境变量或密钥管理服务。工具权限最小化。Agent 调用的搜索工具、数据库工具、内部接口权限范围应该刚好满足任务需求不要让 Agent 有权限执行破坏性操作。对 Agent 输出做二次审核。尤其是面向用户的自动化内容建议保留“人工审核”节点避免模型幻觉导致错误信息流出。涉及数据库写入、文件删除、订单操作等场景必须让 Agent 走“生成 SQL / 生成操作指令”的链路由人工或受控服务执行不能让 Agent 直接连生产库操作。8.5 版本锁定与依赖管理开源项目迭代很快CrewAI 每两三个月就可能发布破坏性更新。建议在requirements.txt中锁定版本号crewai0.30.0 crewai-tools0.0.10 python-dotenv1.0.0升级框架版本时先看官方 changelog 中是否有 Breaking Change再在测试环境完整回归。8.6 测试你的 AgentAgent 的输出具有不确定性所以不能像测普通函数一样断言精确结果。推荐的做法是建立一组固定测试用例覆盖正常场景、边缘场景、拒绝场景。每次修改提示词后跑一遍测试集用人工确认结果质量是否下降。为关键输出增加结构性校验比如必须是合法 JSON、必须包含特定字段。9. 总结与学习路线到这里你应该已经理解了“开源 AI 代理”的核心概念并且能动手搭建一个最简单的多智能体协作工作流。回顾一下全文的核心内容AI 代理 大模型 工具调用 记忆 规划它的价值在于自动执行任务。多智能体协作把复杂任务拆分给不同角色效率高也更贴近真实业务流程。开源框架中CrewAI 适合快速上手AutoGen 和 LangGraph 适合更复杂、更底层的编排需求。通过 Agent - Task - Crew 三个核心对象可以搭出“研究 - 写作 - 审核”的自动化内容流水线。本地模型如 Ollama Qwen可以解决数据隐私问题。给 Agent 挂载工具后它能真正联网检索、访问接口而不只是靠训练知识回答问题。接下来可以按这个顺序继续深入阅读 CrewAI 官方文档重点看Process.hierarchical和Memory模块。学习 LangGraph理解有状态流程图对 Agent 编排的价值。尝试接入企业内部 API做一个真正能自动执行业务操作的 Agent。如果要做生产级系统建议研究 Dify 这类可视化编排平台把 Agent 能力产品化。最后提醒一句AI 代理很强但它不是银弹。它做得好的是“确定性流程 大模型判断”的结合做不好的是完全开放、没有边界约束的长链路任务。解决这个问题没有捷径就是把角色定义清楚、任务拆分到位、日志记录完整然后基于反馈不断迭代提示词。希望这篇文章能帮你迈出打造专属 AI 团队的第一步。建议你边读边动手把示例代码跑通再改成自己的业务场景。如果你在实战中遇到其他问题欢迎在评论区留言交流。