从零上手多智能体框架：三Agent协作搞定调研报告

昨天在GitHub上刷到一个多智能体框架，Star数已经到了5.9万，点开Issues区，中文问题占了将近一半。多数人不是不想用，而是卡在同一个地方：不知道该怎么把多个Agent调到一张桌子上，让它们各自干活、互相配合，最终产出一个完整成果。

我自己上手这个框架花了三天，前两天基本都在跟API Key、环境变量、上下文传递、工具注册这些事较劲。等真正跑通第一个多Agent流程后，回头再看，其实核心概念就那么几个，难点多半出在“没理解框架的协作模型”就开始写代码，导致Agent之间互相抢上下文、任务衔接不上。

这篇文章就是基于我这几天实操过程整理出来的中文上手教程。我会以目前社区里最流行的多智能体框架之一为例，带你从环境准备、概念理解开始，逐步写一个三个Agent协作完成调研报告的Demo，再对照实际运行日志解释内部执行逻辑。文章后半部分还会给出5个高频问题的避坑清单，以及从Demo走向生产环境时我会做的几个改造。

适合的读者有两类：一类是刚接触多智能体、想把GitHub上那些开源项目跑起来的新手；另一类是已经会调单个LLM API、但面对多Agent协作时不知道如何设计任务和角色的开发者。看完这篇，你应该能搭出一个可以扩展的实际项目骨架。

1. 先弄明白：多智能体框架到底在解决什么问题？

1.1 一个Agent搞不定的三个真实场景

先说结论：如果你只是做“用户问一句，模型答一句”，确实没有必要上多智能体框架。直接调ChatCompletion接口，又快又便宜。但当你遇到下面这类场景，单Agent的局限性就会非常明显。

第一类场景是“一次任务需要多种能力”。比如让AI写一篇行业调研报告，它既要搜索最新数据，又要理解业务逻辑，还要组织语言、设计图表，最后还要检查错别字和逻辑漏洞。如果所有事情都丢给一个Agent，它的系统提示词会变得特别臃肿——又要会搜索、又要会写作、又要会审校，反而什么都做不好。而且每轮对话都得带着巨大的上下文，Token消耗直接起飞。

第二类场景是“不同环节需要不同的上下文和风格”。比如数据分析Agent只需要看结构化数据，不需要读营销文案；编辑Agent则需要拿到成稿，做语言润色。如果让一个Agent全程处理，它的上下文会被无关信息占满，影响判断质量。多Agent可以把任务切成多个条目，每个条目的上下文只包含它需要的那部分。

第三类场景是需要人工审批的流程。比如生成营销文案，审核Agent发现某个合规风险，不能让模型自动改了直接发布，必须停下来等人工确认。这种“带分支、带暂停、可干预”的流程，用单Agent就很难实现，因为你没法在它的自洽循环里插入一个“人”。多智能体框架的Task模型天然支持这类节点。

1.2 框架的核心：编排、角色、工具、记忆

多智能体框架不是把几个Agent塞在一起，它真正做的事情是“编排”。我习惯用一支小团队来类比：框架本身是项目经理，Agent是不同岗位的员工，工具是员工手里的办公软件，记忆是团队共享的文档库，而编排规则决定了任务是从上到下派发、还是小组讨论、还是指定一个人牵头。

• 编排（Orchestration）：决定Agent之间的调用顺序和条件分支。是串行执行，还是并行执行，还是在某个条件下进入人工审核？框架通过流程图或任务依赖机制来管理。
• 角色（Role）：每个Agent有自己的系统提示词，相当于岗位说明书。比如“研究员”的指令是搜索资料并整理数据，“写手”的指令是根据提纲写稿。角色划分越清晰，协作越稳定。
• 工具（Tools）：Agent调用外部能力的方式，比如网页搜索、API请求、代码执行、数据库查询。没有工具的Agent只能靠模型内置知识，有了工具才能接触真实世界。
• 记忆（Memory）：短期记忆保证Agent在同一个任务内记住对话历史，长期记忆让它跨任务保留用户偏好或项目背景。记忆能显著减少重复输入，但也不可滥用，否则上下文膨胀。

1.3 5.9万Star级别框架的三个共性

Star数能冲到5.9万，说明这个项目不只是“能跑”，而是真的解决了大量开发者的痛点。我对比过几个主流实现，发现它们都有三个共性：

第一，标准化Agent定义。不管底层调用哪个大模型，框架都让你用Role、Goal、Backstory、Tools这些字段统一描述Agent。好处是代码可读性强，团队协作时能快速对齐。

第二，任务依赖与结果传递。框架会自动把上一个Task的输出结构化成下一个Task的输入，开发者不用手动拼接字符串。这个能力看起来不起眼，却是多Agent能稳定工作的基础。

第三，生态工具集成。从搜索、网页抓取到Excel处理，框架通常都会预置一批常用工具，因为Agent在实际项目中必须能读写外部数据。如果你没有这部分，Agent只能生成“计划”，不能产生“结果”。

不同框架的差异主要在执行模型上：比如AutoGen倾向于让多个Agent以群聊模式自主对话，CrewAI用Process定义串行或层级流程，LangGraph则把流程建模成状态图。无论哪种形式，底层都是“任务输入—Agent处理—结果传递—下一步决策”这条链路。理解了这条链路，换框架成本并不高。

2. 上手前要准备的五件事

2.1 Python环境：版本别太高也别太低

我建议使用Python 3.10到3.12之间的版本。太老的版本可能缺少新版语法支持，太新的版本又容易撞上某些依赖库还没适配。不要直接装在系统全局环境里，否则后面前后安装的包互相打架，你会后悔的。

创建虚拟环境并激活：

python3 -m venv venv source venv/bin/activate # Windows下用 venv\Scripts\activate

激活后，终端提示符前面会出现(venv)，这就对了。后面所有依赖都装在这个环境里，就算项目搞坏了，删掉venv目录重来就行。这一步一定要做，多Agent项目依赖的东西远比单接口多。

2.2 拿到模型API Key，或者准备一台本地模型

多Agent框架本身不包含大模型，它只是调度层，真正的推理能力来自外部模型。绝大多数框架默认兼容OpenAI的API协议，所以你至少需要一个可用的Key。

我建议先把Key放在.env文件里，由框架自动读取。这样代码里不出现密钥，方便分享，也方便切换。比如：

OPENAI_API_KEY=sk-xxxxxxxx OPENAI_MODEL_NAME=gpt-4o-mini

如果你更倾向本地模型，也可以使用Ollama这类工具启动本地模型，再把API地址指向本地服务。不过要注意，本地小模型的工具调用能力普遍弱于大厂API，执行多Agent流程时比较容易出现“Agent不按指令调用工具”的情况。新手阶段，先老老实实用一个稳定的云端模型，跑通了再去折腾本地部署。

2.3 安装框架本体

我这次用的是CrewAI风格的多智能体库，安装命令是：

pip install crewai crewai-tools

其中crewai是主框架，crewai-tools是官方维护的工具集合，包含Search、ScrapeWebsite、FileRead等常用工具。如果你的项目不需要预置工具，也可以只装crewai，自定义工具会更灵活。

安装的时间取决于网络和Python环境。装完验证一下：

python -c "import crewai; print(crewai.__version__)"

能输出版本号，就说明框架核心装好了。

2.4 目录结构规划

不要把所有代码塞进一个main.py，多Agent项目跑起来后，Agent定义、任务定义、工具定义会迅速膨胀。这是我的一个参考结构：

multi-agent-demo/ ├── .env ├── main.py # 入口，负责读取配置和启动工作流 ├── agents.py # 所有Agent定义 ├── tasks.py # 所有Task定义 ├── tools.py # 自定义工具与外部工具封装 └── output/ # Agent生成的中间文件与最终报告

这样做的好处是，改Agent定义时不用去翻任务代码，加新任务时也不用担心污染现有Agent。很多人写多Agent项目写乱，起因就是所有东西揉在一个文件里，到后面连自己都找不到哪里改了。

2.5 验证环境：让一个Agent先开口说话

在开始多Agent之前，先跑一个最简单的单Agent，验证整条链路是通的。下面这段代码如果输出结果正常，才说明Key、环境变量、模型调用都没问题：

from crewai import Agent test_agent = Agent( role="测试助手", goal="用一句话介绍自己", backstory="你是一个刚被创建出来的助手，热情且简洁。", verbose=True ) result = test_agent.kickoff("请做一下自我介绍。") print(result)

注意，不同版本的框架调用方式可能略有差异，有的用kickoff，有的用run，还有的需要通过Crew启动。如果这一步报错，先看报错信息是网络问题、认证问题还是模型不存在，把错误喂给搜索引擎或直接查官方Issue，通常都能解决。

3. 实战：让三个Agent协作完成一份调研报告

3.1 任务拆解：研究员、写作员、编辑员

我们的目标不是写一个Hello World，而是完成一个有点实际意义的任务：生成一份“开源多智能体框架生态调研报告”，要求包含目前在社区活跃度较高的几个项目对比、各自特点、如何选型。

我把任务拆成三步：

串行流程是最容易理解的多Agent协作方式：研究员先干，干完把结果交给写作员，写作员写完交给编辑员。这种模式的好处是每个Agent的输入边界清晰，token开销可控，新手跑通率最高。后面进阶时，再考虑让研究员和写作员并行工作。

3.2 定义Agent：Role、Goal、Backstory怎么写才好

很多新手把Agent的backstory随便写一句“你是一个助手”，结果跑出来的内容又空又泛。好的Agent定义应该像招聘JD一样具体：角色是什么、目标是什么、擅长什么、不能做什么。

下面是我这次用的三个Agent定义，你可以直接参考：

from crewai import Agent researcher = Agent( role="资深开源情报研究员", goal="搜索并整理多智能体框架的社区数据，输出结构化的事实清单", backstory=( "你有10年开源社区观察经验，擅长从GitHub Star数、Issue活跃度、" "Release频率、文档质量等维度评价一个开源项目。" "你的输出必须注明数据来源，不允许编造。" ), verbose=True ) writer = Agent( role="技术调研报告撰写者", goal="根据研究员提供的资料，写出一篇逻辑清晰、语言流畅的调研报告", backstory=( "你是一名科技媒体资深编辑，擅长把复杂技术概念讲得通俗易懂。" "你会先列出大纲，再按章节填充内容，并在结尾给出选型建议。" ), verbose=True ) editor = Agent( role="严谨的终审编辑", goal="检查报告中的逻辑漏洞、事实错误与表达问题，输出修订建议", backstory=( "你对文字质量要求极高，会逐句检查是否通顺，逐段检查是否连贯，" "会质疑数据来源的可靠性，并给出具体修改意见。" ), verbose=True )

注意这里的verbose=True，打开后框架会打印每个Agent在执行过程中的思考步骤。新手阶段建议全部打开，你会看到Agent是如何调用工具、如何生成中间结果的，这对理解原理非常有帮助。等跑稳定了，再关掉以降低日志噪音。

3.3 定义Task：明确输入输出和期望结果

Task定义是整个流程里最容易出问题的地方。很多人只写一句“写一篇调研报告”，模型拿到手根本不知道标准是什么。我在写Task时一定会包含四个要素：任务描述、期望输出、明确的上下文来源、关联的Agent。

from crewai import Task research_task = Task( description=( "围绕'开源多智能体框架生态'这个主题，整理出当前社区活跃度最高的" "3-5个开源多智能体框架。对每个框架，给出Star数区间、核心设计思想、" "适合场景、典型缺点。" ), expected_output="一份Markdown格式的框架对比清单，每个框架200字左右，包含数据来源。", agent=researcher ) write_task = Task( description=( "基于研究员提供的框架对比清单，扩写为一篇完整调研报告。" "报告需要包含：引言、框架对比表、选型建议、未来趋势。" "语言要适合技术管理者阅读。" ), expected_output="一份不少于1500字的Markdown调研报告。", agent=writer, context=[research_task] # 依赖研究员的输出 ) review_task = Task( description=( "对写作员生成的调研报告进行终审。重点检查：" "1. 是否有事实层面的疑点；2. 段落衔接是否流畅；" "3. 选型建议是否与前面的论证一致；" "4. 是否存在夸大或模糊表述。" ), expected_output="终审意见，包括问题列表和直接可用的修改建议。", agent=editor, context=[write_task] )

context这个参数很关键，它告诉框架：这个Task的输入来自哪个Task的输出。没有这一层依赖关系，写作员拿到的是一个随机上下文，根本不知道要基于什么写作，产出的报告会天马行空。

3.4 定义Crew并启动流程

Agent和Task都准备好了，最后一道工序是定义Crew，把它当成“一个项目组”。它需要知道有哪些成员、要执行哪些任务、按什么顺序执行。

from crewai import Crew, Process crew = Crew( agents=[researcher, writer, editor], tasks=[research_task, write_task, review_task], process=Process.sequential, # 串行执行 verbose=True ) result = crew.kickoff() print("最终输出：\n", result)

如果你只想让最终终稿作为结果，可以在Crew配置里调整输出Task，或者直接检查review_task的输出。实际跑起来后，控制台会依次打印每个Agent的执行日志，类似：

[研究员]: 正在搜索开源多智能体框架的社区数据... [研究员]: 已生成对比清单，共5个框架。 [写作员]: 正在根据资料撰写报告... [写作员]: 报告已完成，约1800字。 [编辑员]: 正在终审，发现问题3处...

这些日志不是噪音，它们是观测Agent行为最直接的手段。

3.5 运行结果与内部执行逻辑

我在实测中，三个Agent跑完大概花了4分钟左右，主要用于研究员搜索资料和写作员撰写长报告。最终报告确实比单Agent生成的更结构化，因为研究员先给了事实清单，写作员不需要同时承担“找资料”和“写作”两个任务，报告里关于Star数的表述也更加谨慎。

从内部逻辑看，这套流程可以拆成四步：

1. 框架读取Crew配置，识别出3个Agent和3个Task。
2. 根据Tasks的依赖关系，构建执行顺序。研究员Task没有依赖，先执行。
3. 研究员完成输出后，框架把输出封装成上下文，传给写作员Task，写作员执行。
4. 写作员输出传给编辑员，编辑员执行完成后，整个Crew流程结束。

这中间有一个容易被忽略的点：Agent之间的传递不是简单的“文本拼接”，框架会把前一个Task的expected_output以结构化消息的形式附加到下一个Agent的上下文里。这也是为什么expected_output一定要写得具体，它会直接影响后续Agent能拿到什么质量的信息。

4. 给Agent装工具和记忆：从Demo到能干活

4.1 工具注册：搜索、网页抓取、代码执行

没有工具的Agent只能依赖模型训练时见过的知识，回答上限很低。真正要想让Agent产出“当前可用的信息”，必须让它能搜索网页、读取文档、运行代码。

在CrewAI里，工具注册有两种方式。一种是用官方预置工具：

from crewai_tools import SerperDevTool, ScrapeWebsiteTool search_tool = SerperDevTool() scrape_tool = ScrapeWebsiteTool() researcher_with_tools = Agent( role="资深开源情报研究员", goal="搜索并整理多智能体框架的社区数据", backstory="你是开源社区观察者，擅长通过搜索引擎和网页抓取收集信息", tools=[search_tool, scrape_tool], verbose=True )

另一种是自定义工具，适用于访问内部API或处理私有格式。比如我写了一个简单的工具，用来读取某个本地文件里的配置信息：

from crewai_tools import BaseTool from pydantic import BaseModel, Field class FileReadInput(BaseModel): file_path: str = Field(description="要读取的文件路径") class MyFileReader(BaseTool): name: str = "file_reader" description: str = "读取指定路径的文本文件内容，用于获取内部资料。" args_schema: type[BaseModel] = FileReadInput def _run(self, file_path: str) -> str: with open(file_path, "r", encoding="utf-8") as f: return f.read()

自定义工具的关键是写好description和args_schema。模型是根据工具描述来决定“什么时候调用这个工具”的，描述越准确，调用率越高。如果工具描述含糊，模型可能会把它当装饰，完全不用。

4.2 记忆系统：短期上下文与长期知识库

多Agent框架的记忆分两层。短期记忆就是当前任务运行期间的消息历史，框架自动管理，你不需要手工干预。长期记忆则需要配置外部存储，比如向量数据库。

在CrewAI里，开启长期记忆很简单：

crew = Crew( agents=[researcher, writer, editor], tasks=[research_task, write_task, review_task], memory=True, process=Process.sequential, verbose=True )

开启后，框架会把过去的任务输入输出存入本地存储，下次执行相似任务时，Agent可以调用历史知识。这个能力在跑“周期性报告”时很有用，比如每周生成一次行业周报，Agent能参考上周的数据和结论，保持风格一致。

但我建议新手不要一开始就开记忆，原因有两个：一是记忆模块需要额外的存储配置，会牵扯精力；二是Agent的上下文会显著变长，Token消耗翻倍。先把流程跑通，确认稳定了，再加上记忆做增强。

4.3 人工审核与Human-in-the-Loop

很多实际项目不允许模型全自动输出，尤其是营销文案、财务报告、医疗建议。多Agent框架里，你可以通过Task的停靠点实现人工审核。

目前大多数框架对人工介入的支持还比较原始，一种简单做法是在一个Task的description里明确要求“生成后暂停，输出草稿，等待人工确认”。更优雅的写法是利用框架自带的ask_human_human_input之类的能力，但不是所有框架都有。如果不确定，可以自己用回调函数模拟：

在CrewAI中，如果希望某个Task执行前或执行后暂停，可以在自定义工具里加一个input()，让终端停下来等你确认。生产环境则建议对接一个小的审批UI，而不是依赖控制台输入。本质上，多智能体框架的Task边界足够清晰，所以人工介入节点可以设计在任意两个Task之间。

5. 高频问题与避坑指南

5.1 API Key没生效？环境变量加载顺序

多Agent框架通常不会自动加载.env文件，需要你手动执行from dotenv import load_dotenv; load_dotenv()，或者在启动时使用--env-file类参数。很多新手把Key直接写在代码里，运行倒正常，但一旦把代码提交到GitHub，Key就泄露了，很危险。

建议所有敏感信息统一走环境变量，并且在.gitignore里忽略.env文件。如果发现调用时报AuthenticationError，第一反应不是去框架的Issue区，而是先检查.env文件是否被正确加载：

import os from dotenv import load_dotenv load_dotenv() print("OPENAI_API_KEY:", os.getenv("OPENAI_API_KEY")[:6] + "..." if os.getenv("OPENAI_API_KEY") else "None")

输出前几个字符能确认加载是否成功，又不泄露完整Key。

5.2 中文回答质量差？把Backstory写具体

最开始我写的Backstory是“你是一个有用的助手”，结果Agent输出大段空话。后来我把每个Agent的岗位JD写得像真人招聘一样详细，效果立刻改善。中文提示词质量差，多数不是模型中文能力不行，而是你没有告诉模型“你到底要什么风格、什么角度、什么限制”。

一个技巧：给Agent加“负面约束”。比如研究员Agent的Backstory里写明“不允许编造数据，必须注明来源”，编辑Agent则写“如果发现来源不明，请在报告中明确标注存疑”。这些约束能大幅减少模型胡说八道的概率。

5.3 Token消耗太快？三个控制手段

多Agent项目的Token消耗是单Agent的倍数级，尤其是串行流程里，每个Agent都要收到前面Agent的完整输出。三个控制手段：

一是限制输出长度。在Task的expected_output里写“控制在200字以内”，模型会尽量压缩，虽然不一定严格，但比没有强。

二是给Agent设置max_iter或max_rpm，限制重复思考和每分钟请求数。Agent有时会在一次任务里反复调用工具，消耗翻倍。

三是使用更便宜的模型。把研究员、编辑员这类“中间环节”用的模型设置为GPT-4o mini之类的高性价比型号，只在最终成稿环节启用更强模型。目前主流框架都支持按Agent指定llm参数，可以细分控制。

5.4 Agent互相顶嘴或无限循环？设置终止条件

多Agent群聊模式下，两个Agent可能就一个观点互相辩论十几轮，Token烧完却还没产出结论。串行流程相对安全，因为它有明确的任务边界。但如果你用了群聊或层级流程，必须设置最大轮次和结束条件。

在CrewAI这类框架里，可以通过限制max_iter来防止单个Agent无限循环：

Agent( role="研究员", goal="...", backstory="...", max_iter=5 )

还有的框架允许指定stop_condition，比如“当两个Agent达到一致时停止”。最笨但有效的方法是设一个全局的轮次上限，超过后直接取当前最新输出，避免程序卡死。

5.5 并发限流与重试

当多个Agent并行执行时，API请求会同时打出去，很容易触发限流。解决办法是设置max_rpm（每分钟请求数）和max_tokens，让框架自动限速。如果仍然报429，可以用指数退避重试策略，但多数框架内置了重试，不需要自己写。

我遇到过一种奇怪情况：所有Agent都在同一个线程里，却因为工具内部发送了并发HTTP请求，触发了速率限制。解决方案是给工具调用加一个全局的threading.Lock()，确保工具内部请求也串行化。这不算框架bug，但确实是一个很容易忽视的坑。

下面是一个问题速查表：

6. 进阶建议：从本地跑到生产环境

6.1 把串行流程改造成并行流程

串行流程适合新手，但效率低下。以调研报告为例，研究员需要先搜索资料，写作员才能动笔，编辑员最后审校，天然是串行的。但如果你做的是“市场分析 + 竞品分析 + 用户反馈总结”这类多维度独立任务，完全可以让三个Agent同时开工。

在支持并行执行的框架里，通常是把Task的context依赖去掉，让它们彼此独立，然后配置process=Process.hierarchical或使用异步执行。需要提醒的是，并行意味着同时消耗多个API请求，成本也会随之上涨。生产环境建议先做小流量压测，再逐步放开。

6.2 给流程加日志和追踪

多Agent系统最大的难点是“不可控”。你看着它跑完了，但这中间到底发生了什么？为什么最终结果和预期不一样？我强烈建议在生产环境接入完善的日志系统。

至少需要记录以下几类信息：

• 每个Task的输入输出摘要，不要存完整Prompt，存储摘要即可。
• 每个Agent的tool调用记录，包括工具名、输入参数、返回状态。
• 每个Task的耗时和Token消耗。
• 最终结果的版本号，方便回溯。

有些框架自带Dashboard，但如果你用的是轻量库，可以通过verbose输出重定向到日志文件，再配一个简单的监控脚本。多Agent系统上线前，先让它在测试环境跑至少几个星期，积累足够日志，你才能知道哪些环节容易出错。

6.3 模型分级：让便宜模型做简单任务

不是所有Agent都需要用最贵的旗舰模型。研究员搜索资料，调用工具为主，推理复杂度不算高，用中等模型完全够。写作员需要高质量成文，可以用大模型。编辑员如果只是检查逻辑，也可以用中等模型，但如果你想让它做深度润色，再用大模型。

这样分级后，我实测Token成本可以降到原来的四分之一左右。具体做法是给每个Agent指定独立llm对象：

from langchain_openai import ChatOpenAI gpt4o = ChatOpenAI(model="gpt-4o", temperature=0.3) gpt4omini = ChatOpenAI(model="gpt-4o-mini", temperature=0.2) researcher.llm = gpt4omini writer.llm = gpt4o

成本只是模型选择的一部分，还要考虑延迟。如果某个Agent要搜索十几个网页，用便宜模型也能大幅缩短总耗时时长，因为它需要的推理能力并不高。

6.4 参与开源社区：看Issues比看文档更有效

到了这一步，你已经能自己构建多Agent项目了，接下来就是深水区。我的建议是去GitHub上好好利用Issues区，而不是只翻README和Examples。

星数5.9万的项目，Issues里一定积累了非常多的真实使用场景和坑。搜“中文”“Agent loop”“tool not found”这些关键词，往往能找到比官方文档更贴近你面临问题的答案。参与社区不只是提问，你可以先看别人提的issue，遇到自己踩过的坑，直接在下面补充复现步骤和解决方案，这也是给开源社区做贡献。

我自己的习惯是：每周花一小时去刷这类框架的Release Note，记录API变更，然后主动更新自己项目的依赖。因为多智能体框架迭代很快，可能几周不升版本，就错过了重要的性能优化或bug修复。

最后分享一个心得：别一上来就追求大而全的复杂架构。多智能体项目最容易翻车的地方不是模型能力，而是任务边界模糊。每个Agent的职责定义得足够清晰、每个Task的输入输出足够明确，系统自然稳定。先跑通一个简单的三Agent串行Demo，加上工具和记忆，再逐步拆分成更细的角色，这个路径比一开始就设计十个Agent要靠谱得多。