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

最近两年AI 代理这个概念几乎是每隔几天就会出现在技术社区里。很多人最开始接触的是 ChatGPT 这类聊天助手问一句答一句。但当你开始做真实的业务项目时会发现单个模型对话窗口根本不够用它不会主动去查数据库不会自动调用内部接口也无法拆分大型任务。于是开源 AI 代理和基于多智能体协作的自动化工作流逐渐成为落地大模型应用的关键方向。这篇文章我会围绕开源 AI 代理展开先讲清楚 AI Agent 和多智能体协作的核心概念再带大家用一套完整的 Python 实战案例搭建一个由研究员、内容作者、编辑组成的专属 AI 团队。文章会尽量照顾零基础读者也会把常见报错、配置细节、工程化建议单独列出来。如果你正准备在公司内部做 AI 应用落地或者想在本地搭一套自动化内容生产、数据分析、任务编排流程这篇文章可以作为入门参考。1. 背景与核心概念1.1 什么是 AI 代理AI AgentAI 代理也叫 AI Agent是指以大语言模型为核心、能够自主完成一系列任务的智能程序。它和普通聊天机器人的区别在于自主性。普通聊天机器人是你问我答模型只做文本生成AI Agent 则会把一个大目标拆解成多个小步骤自己决定先做什么、后做什么并且在执行过程中调用工具、观察结果、修正计划最终交出一个完整结果。一个最小可用的 AI 代理通常由四部分组成组成部分作用示例大语言模型承担推理和决策GPT-4o、Qwen、DeepSeek、Llama工具调用让模型能访问外部世界搜索引擎、计算器、数据库、HTTP API记忆保存上下文和中间结果短期上下文、长期向量记忆任务循环规划、执行、观察、再规划ReAct 模式、Plan-and-Execute 模式通俗一点解释AI Agent 就是一个有手有脚的模型。模型负责思考工具负责执行任务循环负责保证它不会做一步就停下来。1.2 单智能体 vs 多智能体协作最开始接触 Agent 开发时很多人会试着把全部指令塞进一个 Prompt 里让一个 Agent 完成所有事情。这在简单场景下够用但一遇到复杂业务就会暴露出问题Prompt 变得非常冗长模型容易丢失重点。单个 Agent 既要做市场调研又要写代码还要写报告能力边界模糊。出错后很难定位是哪一个环节的问题。上下文窗口被大量中间过程占满最终输出质量下降。多智能体协作Multi-Agent Collaboration则把大任务拆成多个角色每个角色只负责自己擅长的一部分。多个智能体之间通过消息或共享状态协作形成一条完整的自动化工作流。举个例子。假设你要做一个竞品分析报告单智能体模式你写一个 Prompt让模型帮我做一份竞品分析模型只能凭训练知识硬写无法获取最新数据。多智能体模式市场研究员 Agent 负责抓取竞品官网和行业数据数据分析 Agent 负责处理数字写作 Agent 负责把结论写成报告最终由评审 Agent 检查逻辑漏洞。这种AI 团队的工作方式本质上更像真实企业里的小组协作而不是一个人包揽所有环节。1.3 开源 AI 代理生态一览市面上的 AI 代理框架很多这里重点介绍几个在 GitHub 上活跃度高、社区成熟、适合个人和中小企业使用的开源项目。开源项目定位特点Microsoft AutoGen多智能体对话框架强调多个 Agent 之间的对话式协作适合复杂任务拆解LangChain / LangGraph应用编排框架LangGraph 面向有状态、可控制的工作流节点和边模型清晰CrewAI角色扮演型多智能体框架用 Role、Goal、Backstory 定义角色上手快接近AI 团队概念MetaGPT软件公司模拟框架让多个 Agent 扮演产品经理、架构师、工程师输出标准化文档和代码Dify / FastGPTLLMOps 应用平台偏平台化可视化管理工作流、知识库和模型接入不同框架的抽象层次不同。AutoGen 偏研究性和灵活性LangGraph 偏工程化流程控制CrewAI 偏业务角色模拟Dify 这类平台则更适合不想写太多代码的团队。后面实战部分我会选用 CrewAI 来演示原因是它的代码量小、概念直观能最快还原专属 AI 团队的效果。2. 环境准备与版本说明2.1 推荐运行环境在开始安装之前先确认你的本机环境。这里不会写死某个具体版本号因为 Python 和相关依赖迭代比较快大家按照自己的环境调整即可。操作系统Windows 10/11、macOS、LinuxUbuntu 22.04 或更高均可。Python 版本建议 Python 3.10 或 3.11避免使用过老的 3.7/3.8。依赖管理工具推荐使用虚拟环境建议用venv或conda创建独立环境。大模型接口如果你使用 OpenAI 兼容接口需要准备 API Key如果想完全本地运行需要至少 16GB 内存配合 Ollama 运行 7B 级别的量化模型。开发工具VS Code 或者任意终端环境即可。这里要强调一点开源框架的 API 变化很频繁。本文的示例以常见的稳定写法为准如果你安装的是更新的版本代码中有少量 API 差异属于正常情况请以官方文档为准。2.2 安装 CrewAI 与本地模型运行工具先创建一个虚拟环境避免依赖冲突。以 Python 3.11 为例python3 -m venv agent-env source agent-env/bin/activate # Windows 环境执行 # agent-env\Scripts\activate激活虚拟环境之后安装 CrewAIpip install crewai如果希望使用 CrewAI 自带的工具生态还需要安装pip install crewai-tools这里需要注意crewai-tools目前主要面向某些付费搜索和爬取 API。如果暂时没有相关服务的 API Key完全可以先不安装后续用自己的 Python 函数代替外部工具。为了在本地运行大模型建议再安装 Ollama。Ollama 是一个开源的本地大模型运行工具支持多种开源模型。安装完成后在终端拉取一个中文能力较强的模型例如 Qwen2.5ollama pull qwen2.5:7b如果你能够使用 OpenAI 兼容的云端模型接口也可以跳过 Ollama 这一步。2.3 验证安装安装完成后运行下面这段代码验证框架是否能正常加载# check_install.py import crewai from importlib.metadata import version print(crewai version:, version(crewai))如果你执行后能打印出 CrewAI 的版本号说明基础环境没有问题。接下来我们进入原理部分先搞清楚多智能体协作背后发生了什么再写代码。3. 核心原理拆解一个智能体是如何工作的3.1 智能体的五要素在使用 CrewAI 或其他 Agent 框架时定义一个智能体通常需要以下要素要素含义作用Role角色告诉模型你是谁例如市场研究员、Python 工程师Goal目标告诉模型你要达成什么结果Backstory背景故事补充角色的经验和风格影响输出语气LLM模型指定使用哪个大语言模型Tools工具模型可以调用哪些函数或 API很多新手容易把 Goal 写得特别长其实 Goal 不需要堆砌细节更重要的是清晰、可衡量。Backstory 也只需要一句到三句话目的是让模型进入角色。举个例子researcher Agent( role市场研究员, goal搜集并整理最新的人工智能代理开源项目资料, backstory你是一名严谨的技术市场研究员善于从公开信息中提取关键数据并形成结构化摘要。, verboseTrue, )你会发现这样的定义方式和人招聘团队成员非常像。你要告诉成员岗位职责而不是手把手教他每一步怎么做。3.2 工具调用Function Calling多智能体协作中最关键的技术基础是工具调用也叫 Function Calling。大模型本身无法执行真实操作但模型可以输出一个结构化的调用某个函数的请求框架负责解析并执行再把执行结果返回给模型。在 CrewAI 中你可以用tool装饰器把一个普通 Python 函数变成模型可调用的工具from crewai import Agent from crewai.tools import tool tool(加法计算器) def add_calculator(expression: str) - str: 计算字符串形式的加法表达式例如 1 2返回计算结果。 try: a, b expression.split() result int(a.strip()) int(b.strip()) return f计算结果: {result} except Exception: return 无法解析表达式请按数字 数字的格式输入这里需要留意的是函数的 docstring 很重要。大模型会根据函数名和 docstring 来判断何时调用这个工具所以 docstring 要写清楚工具的功能和入参格式。3.3 多智能体协作模式多智能体之间的协作主要有三种常见模式顺序模式Sequential多个 Agent 按固定顺序依次执行前一个 Agent 的输出作为后一个 Agent 的输入。适合流程稳定的自动化工作流比如先调研再写作最后校对。层级模式Hierarchical有一个 Manager Agent 作为项目经理负责把任务分配给其他 Agent并监督执行过程。适合任务分工不固定、需要动态决策的场景。CrewAI 里可以通过设置 Manager Agent 来启用。对话模式Conversation多个 Agent 通过对话互相质疑、补充信息常见于 AutoGen。适合需要头脑风暴、反复讨论的复杂任务。选哪种模式取决于任务的不确定性如果步骤完全固定用顺序模式最省 token也最容易排查问题。如果任务会动态变化用层级模式更合适。如果需要多轮推理和辩论建议研究 AutoGen 的对话模式。3.4 自动化工作流设计所谓自动化工作流就是让以上这些智能体按照Trigger - Task - Result的方式串联起来。在设计工作流时我建议先画一张角色职责表再决定协作模式不要一上来就写代码。比如一个典型的内容生产自动化工流可以这样设计流程步骤执行角色输入输出市场调研研究员 Agent主题关键词调研摘要、参考资料列表内容撰写内容作者 Agent调研摘要初稿文章质量审核编辑 Agent初稿文章润色后的终稿、调整建议这种设计思路的优势在于每个 Agent 的职责单一任务边界清晰。即使某个 Agent 执行失败你也能快速定位是调研环节的问题还是写作环节的问题。4. 完整实战用 CrewAI 打造内容创作 AI 团队4.1 案例背景与团队角色下面我们来做一个可以完整运行的实战案例。假设我们需要搭建一个AI 内容创作团队自动完成一篇技术科普文章主题是开源 AI 代理入门。团队分为三个角色市场研究员 Agent负责整理开源 AI 代理的背景资料。内容作者 Agent负责把资料组织成一篇通俗易懂的文章初稿。编辑 Agent负责检查语言流畅度、逻辑结构输出最终版本。为了让案例不依赖外部付费服务我们不给 Agent 配置网络搜索工具只让研究员基于模型自身知识输出结构化调研笔记。如果你有搜索 API Key可以自行接入真实搜索工具。4.2 创建项目结构与配置在虚拟环境中创建如下目录结构ai-content-team/ ├── .env ├── agents.py ├── tasks.py ├── main.py └── requirements.txt说明一下文件职责agents.py定义三个 Agent。tasks.py定义三个执行任务。main.py组装 Crew 并执行。.env存放模型 API Key 等环境变量。requirements.txtPython 依赖清单。在requirements.txt中声明依赖crewai python-dotenv如果你的模型接口来自 OpenAI还可以在.env中写入OPENAI_API_KEYsk-你的KEY OPENAI_MODEL_NAMEgpt-4o-mini如果你使用的不是 OpenAI 官方服务而是某个兼容 OpenAI 接口的国内模型服务可以在.env里覆盖 Base URLOPENAI_API_BASEhttps://你的接口地址/v1 OPENAI_API_KEY你的KEY OPENAI_MODEL_NAME你需要的模型名在代码中加载.env文件# main.py import os from dotenv import load_dotenv load_dotenv() # 验证配置读取 print(当前使用的模型:, os.getenv(OPENAI_MODEL_NAME, 默认模型))4.3 定义智能体和工具下面是最核心的部分定义 Agent 和工具。# agents.py from crewai import Agent from crewai.tools import tool # 自定义一个数据整理工具模拟信息提取能力 tool(信息整理工具) def organize_text(raw_text: str) - str: 对输入的文本进行要点提取返回结构化摘要。 lines [line.strip() for line in raw_text.split(\n) if line.strip()] result \n.join([f- {line} for line in lines[:10]]) if not result: return 暂无有效内容 return f整理后的要点\n{result} researcher Agent( role市场研究员, goal围绕开源 AI 代理主题产出清晰、有逻辑的调研资料, backstory( 你是一名资深技术研究员长期关注开源社区、大模型应用和 AI Agent 生态。 你习惯把复杂信息整理成结构化的要点方便后续创作者使用。 ), tools[organize_text], verboseTrue, ) writer Agent( role内容作者, goal基于研究员提供的资料写一篇面向开发者的技术科普文章, backstory( 你是一名经验丰富的技术博主擅长把技术概念讲得通俗易懂 文章中会穿插实际的代码示例和场景说明。 ), verboseTrue, ) editor Agent( role编辑, goal检查文章的逻辑、表达和技术准确性输出最终定稿, backstory( 你是一名严谨的编辑对文字质量要求很高。 你会删除冗余段落纠正专业术语确保文章结构清晰可读。 ), verboseTrue, )这里有几个值得注意的细节每个 Agent 的 role、goal、backstory 字段都是字符串backstory 可以稍微丰富一些让模型更容易进入角色。tools 列表可以传多个自定义函数。verboseTrue 会在终端显示出执行过程中的思考步骤方便调试。4.4 编排任务与流程定义好角色之后我们来定义任务。在 CrewAI 中Task 是 Agent 要完成的具体工作单元。# tasks.py from crewai import Task from agents import researcher, writer, editor research_task Task( description( 请围绕开源 AI 代理这个主题进行调研。 内容包括AI Agent 的基本概念、开源 AI 代理的主流框架、多智能体协作的价值。 输出应该是一份 300 字左右的调研要点。 ), expected_output结构化的调研要点包含 3 到 5 个小标题, agentresearcher, ) write_task Task( description( 根据研究员提供的调研要点写一篇 800 字左右的技术科普文章。 读者是有编程基础但没接触过 AI Agent 的开发者。 文章需要包含一个简单、可理解的比喻。 ), expected_output一篇完整的 Markdown 格式文章初稿, agentwriter, ) edit_task Task( description( 对文章初稿进行审核和润色重点检查逻辑是否通顺、术语是否准确、 是否有冗余表达。输出最终定稿并在文末给出 3 条修改说明。 ), expected_output润色后的最终文章以及修改说明列表, agenteditor, )expected_output是一个很容易被忽略的字段。建议每个任务都明确写上期望输出格式这样模型生成结果会更稳定。然后在main.py中组装 Crew# main.py import os from dotenv import load_dotenv from crewai import Crew, Process from agents import researcher, writer, editor from tasks import research_task, write_task, edit_task load_dotenv() # 组装 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 最终输出 ) print(result)这里的Process.sequential表示顺序执行。如果你想尝试层级模式可以把这一段改为from crewai import ManagerAgent manager Agent( role项目经理, goal统筹团队成员确保任务高质量完成, backstory你是一名优秀的项目经理擅长任务拆解和质量把控。, ) content_crew Crew( agents[researcher, writer, editor], tasks[research_task, write_task, edit_task], processProcess.hierarchical, manager_agentmanager, verboseTrue, )不过要注意层级模式会额外产生管理类的 token 消耗运行成本比顺序模式高。4.5 运行与预期输出回到终端执行python main.py如果一切正常你会看到类似下面的运行过程[2025-xx-xx 12:00:01] [INFO] 开始执行任务: research_task [2025-xx-xx 12:00:10] [INFO] 研究员正在组织调研资料... [2025-xx-xx 12:00:30] [INFO] 研究员任务完成 [2025-xx-xx 12:00:31] [INFO] 开始执行任务: write_task [2025-xx-xx 12:00:50] [INFO] 内容作者正在撰写初稿...最终result会拼接出三个 Agent 的产出其中编辑 Agent 的输出就是最终文章。实际执行时间取决于你使用的模型接口响应速度和网络状况。4.6 进阶接入 Ollama 本地模型很多公司会担心数据出境问题要求模型完全本地部署。此时可以用 Ollama 接入本地开源模型。CrewAI 支持通过 LangChain 的类型来指定 LLM示例如下# main.py 中使用 Ollama 本地模型 from langchain_ollama import ChatOllama from crewai import LLM local_llm LLM( modelollama/qwen2.5:7b, base_urlhttp://localhost:11434, ) # agents.py 创建 Agent 时传入 llm researcher Agent( role市场研究员, goal围绕开源 AI 代理主题产出清晰、有逻辑的调研资料, backstory你是一名资深技术研究员长期关注开源社区、大模型应用和 AI Agent 生态。, llmlocal_llm, )Ollama 的本地模型推理速度会明显慢于云端模型7B 级别的模型在 16GB 内存的电脑上可以跑但在处理长文本时会有等待时间。如果机器配置较低建议使用更小规格的模型例如qwen2.5:3b。这类配置思路在不同版本中可能略有变化接入时最好对照 Ollama 和 CrewAI 的官方文档查看最新写法。5. 常见问题与排查思路5.1 高频问题速查表我整理了多智能体协作开发中最常见的几类问题方便你快速对照排查问题现象常见原因解决思路安装 CrewAI 时报依赖冲突Python 版本过低或环境中已有 LangChain 相关包使用 Python 3.10新建独立虚拟环境API 请求超时模型服务响应慢或网络不稳定增加超时时间改用响应更快的模型Agent 不调用自定义工具工具 docstring 不够清晰函数名太抽象重写 docstring明确触发条件输出内容与预期任务无关Prompt 目标模糊或上下文过长被截断细化任务描述减少单次任务工作量顺序模式下上个结果没有传递任务之间没有建立明确的输入依赖在后一个 Task 的 description 中引用前一个输出层级模式费用太高Manager 在每个环节都会调用模型改用顺序模式或自定义更轻量的 Manager 指令本地模型运行极慢量化级别太高、内存不足换小模型或更低量化版本输出格式不符合要求expected_output没有写明格式明确要求输出 Markdown、JSON、表格等格式5.2 排查 Checklist如果你运行失败建议按照以下顺序排查确认虚拟环境已激活安装命令在虚拟环境内执行。确认.env文件存在且变量名拼写正确比如OPENAI_API_KEY不要写成API_KEY。在main.py开头打印模型名确认读取到的是你想要的模型。单独把某个 Task 抽出来测试确认单个 Agent 能力没问题再组合多 Agent。查看 verbose 日志定位是哪一个 Agent、哪一步执行失败。如果失败发生在工具调用阶段检查函数是否抛出了未捕获异常并在工具函数内部加try/except兜底。如果输出质量差优先调整 Prompt而不是换模型。6. 最佳实践与工程建议6.1 模型与成本控制多智能体协作比单次模型调用要消耗更多 token因为每次 Agent 执行任务都会产生完整请求。在实际项目中可以从以下几点控制成本优先选择轻量模型处理中间环节只在最终生成内容时使用更强的模型。每次任务的描述尽量精简不要把大段背景重复写在每个 Task 中。使用层级模式时限制 Manager Agent 的思考深度避免无意义的任务拆解。本地部署时优先用量化模型并根据内存大小选择合适的参数规模。6.2 权限与安全边界如果 Agent 需要调用外部 API、数据库或服务器操作必须严格限制权限。在生产环境中我建议遵循以下原则给 Agent 提供的工具采用白名单机制只开放必要接口。涉及数据库操作的工具永远使用只读账号或者限制影响行数。涉及删除、修改、发布的工具必须加入人工审批节点。不要在 Prompt 或工具函数中硬编码任何密钥密钥统一放在环境变量或密钥管理服务中。对 Agent 执行的每个危险操作生成审计日志方便事后追踪。任何时候都不要让 AI Agent 在没有权限控制和审计的情况下直接操作生产环境。6.3 错误处理与可观测性在多智能体工作流中一个出错的工具调用可能会导致整个任务链失败。除了依赖框架自带的 verbose 日志建议在自定义工具内部做好异常捕获和信息返回。一个较稳妥的工具函数写法如下tool(数据库查询工具) def query_database(sql: str) - str: 对测试数据库执行只读 SQL 查询返回查询结果。 仅支持 SELECT 语句。 import sqlite3 if not sql.strip().lower().startswith(select): return 错误只允许执行 SELECT 查询 try: conn sqlite3.connect(test.db) cursor conn.cursor() cursor.execute(sql) rows cursor.fetchall() conn.close() return str(rows[:20]) except Exception as e: return f查询失败: {e}这样做的好处是即使模型生成了错误的 SQL工具也不会执行破坏性操作并且会把错误信息返回给模型模型可以根据错误信息自我修正。6.4 从 Demo 到生产的建议Demo 环境和生产环境差别很大。如果你想把这个内容创作团队改造成一个真正的生产系统除了稳定的模型接入之外还需要考虑任务队列将工作流拆成异步任务通过消息队列调度而不是同步等待。结果存储把每次运行的任务结果保存到数据库中方便回溯和评估。质量评估建立人工评估集定期检查多智能体协作输出质量。版本管理框架升级前先跑通回归用例因为 Agent 框架的 API 仍在快速演进。监控告警统计平均执行耗时、失败率、token 消耗超过阈值时告警。这些内容虽然不会直接体现在代码里但决定了你的 AI 应用是否能长期稳定运行。7. 总结与学习路线通过这篇文章你应该可以独立搭建一个基于开源 AI 代理的多智能体协作项目理解 Agent 的角色、目标、工具、记忆和工作流概念也知道了如何用 CrewAI 快速组建一个 AI 团队以及如何接入本地模型实现更低成本和更高隐私的部署。下一步可以从三个方向继续深入学 AutoGen研究多智能体对话和辩论式协作适合需要复杂推理和群体决策的场景。学 LangGraph重点研究状态管理和条件路由适合构建严格的自动化工作流。学 Dify 或 FastGPT了解可视化编排和知识库接入适合做产品原型和低代码方案。实际操作时不要一上来就搭一个大而全的系统。建议从两个 Agent 的协作开始跑通一个任务闭环再逐步增加角色和工具。这样你在排查问题时会有更充分的把握也能更清楚地判断到底是模型的问题、Prompt 的问题还是框架配置的问题。开源 AI 代理的生态还在快速变化今天的新框架可能半年后就被更好的方案替代。真正值得学习和沉淀的是 Agent 的设计思路——如何划分角色、如何设计工具、如何编排任务。把这套思维掌握了无论未来框架如何变化你都能快速上手。希望这篇文章能帮你迈出这一步。