先问大家一个问题当你需要写一份行业调研报告、竞品分析或者技术选型方案时通常是怎么做的我猜大概是在搜索引擎里翻十几页开五六个网页标签一边复制关键数据一边在文档里拼凑结论。这个过程是不是特别消耗精力而最近两三年大模型变得越来越强很多人开始尝试让 AI 来帮自己完成这类“深度研究”任务也就是Deep-Research。但实际尝试过你就会发现单次调用大模型它能帮你整理资料、写段落却很难像研究员一样系统性地完成“明确问题 → 拆解任务 → 多路检索 → 交叉验证 → 输出报告”的完整闭环。因为单靠一次对话模型既记不住太多上下文也缺少自主调用搜索工具、持续迭代结果的机制。于是Deep-Research 多智能体开发成了目前 AI 应用领域一个很受关注的方向。它的核心思路是把一次复杂的研究任务拆解成多个角色分工协作——有 Agent 负责规划问题有 Agent 负责搜索检索有 Agent 负责总结写稿。每个 Agent 像团队里的不同成员各司其职再通过一套协作机制串联起来。这篇文章会从零开始带大家搭一个能跑通的 Deep-Research 多智能体项目包含环境准备、核心代码、常见坑点和工程化建议。无论你是刚接触 Agent 开发的新手还是已经在做 AI 应用落地的开发者都应该能从里面找到可以直接复用的内容。1. 为什么 Deep-Research 需要“多智能体”在开始写代码之前先花点时间搞清楚一个问题为什么普通的单次大模型对话做不了 Deep-Research1.1 单 Agent 的瓶颈过去我们做 AI 问答应用最常见的架构就是“用户提问 → 拼 Prompt → 调用大模型 → 返回回答”。这种模式在简单问答场景够用但放到深度研究场景会遇到几个明显的瓶颈上下文有限研究报告类任务往往需要阅读几十篇网页、文档单次对话的上下文窗口装不下。缺少工具调用大模型本身不具备实时检索能力它训练时的知识有截止日期无法获取最新信息。任务跨度太长完成一份调研报告从问题拆解到资料收集再到报告撰写中间有大量中间步骤。如果让一个 Agent 从头做到尾很容易在中途“跑偏”遗忘最初的目标。结果难以验证大模型生成的内容表面看起来很有条理但可能是“一本正经地胡说八道”。在单 Agent 模式下缺少交叉验证的环节生成质量全凭运气。1.2 多智能体如何解决这些问题多智能体Multi-Agent系统的思路不是让一个 Agent 变得更“全能”而是把任务拆分成多个子任务分别交给不同的 Agent让它们通过某种协作方式完成整体目标。这种设计参考了真实团队的分工方式。比如要让一个研究小组完成竞品分析报告需要有人想清楚“到底要研究哪些维度”有人负责“搜集各维度资料”有人负责“整理成结构化报告”。多智能体系统就是把这种分工搬到代码里Planner Agent负责理解用户需求把大问题拆解成可执行的小问题。Search Agent负责调用搜索引擎或内部知识库获取最新信息。Writer Agent负责把搜集到的资料整理成逻辑清晰的内容。Critic Agent负责检查生成内容的质量指出遗漏或错误。每个 Agent 都有自己的 Prompt、模型参数和工具集。它们之间通过消息传递或共享状态来协作。这样做的直接好处是每个 Agent 的任务边界清晰Prompt 可以写得更精准。可以在不同环节使用不同模型比如规划用推理强的模型写作用文笔好的模型。搜索、总结、校验可以并行或循环执行提升效率和稳定性。1.3 多智能体的四种交互模式在深入代码之前先了解一个重要的基础概念也是这次搜索热词里很多人关心的点多智能体的交互模式。根据智能体之间的协作方式业界通常把它们分为四种典型模式。模式协作方式适用场景优缺点星型模式一个中心 Agent 调度其他多个 Agent任务边界清晰有明确的总控者结构简单、易管理但中心节点可能成为瓶颈链式模式Agent 按顺序执行前一个的输出是后一个的输入流程固定的流水线任务实现简单但一旦某环节出错错误会向后传递网状模式Agent 之间可以相互通信、自由协作复杂开放任务没有固定流程灵活性强但设计和调试难度较大主从共享模式多个 Agent 共享一块记忆/黑板通过黑板协作协作型任务需要共享上下文信息同步方便但要处理并发读写问题Deep-Research 任务通常是链式和星型的组合规划 Agent 拆解任务然后把每个子问题分发给搜索 Agent搜索完成后由写作 Agent 汇总。这种结构既保留了流程的稳定性又让每个环节足够独立。2. 多智能体开发的环境准备与版本说明了解了基础概念接下来进入实操部分。我们以 Python 环境为例从零搭建一个可运行的 Deep-Research 多智能体项目。2.1 开发环境清单由于多智能体开发涉及的框架迭代很快下面列出的版本是写这篇文章时的常见组合实际使用时请根据最新版本调整组件版本建议作用操作系统Windows 10/11、macOS、Ubuntu 20.04开发环境Python3.10 或 3.11Agent 开发的主流 Python 版本大模型 APIOpenAI 兼容接口 / DeepSeek / 通义千问等提供推理能力核心框架langchain / langgraph版本见下文简化 Agent 编排开发工具VS Code 或 PyCharm编写和调试代码包管理pip 或 poetry管理 Python 依赖2.2 安装依赖先创建一个项目目录并初始化 Python 虚拟环境mkdir deep-research-agent cd deep-research-agent python3 -m venv venv source venv/bin/activate # Windows 下使用 venv\Scripts\activate然后安装核心依赖pip install langchain langchain-openai langgraph python-dotenv pip install duckduckgo-search # 免费搜索示例可按需换成其他搜索模块这里需要解释一下langchain是一个帮助大模型应用开发的框架封装了调用模型、处理 Prompt 的通用逻辑langgraph是基于图结构编排 Agent 流程的库对多智能体开发支持很友好duckduckgo-search用于演示调用搜索工具实际项目中可以根据数据源换成 Bing 搜索 API、SerpAPI 或内部搜索引擎。版本需要根据你的项目实际情况调整。目前 langchain 和 langgraph 的 API 变动比较频繁如果安装后运行报错第一优先检查版本兼容性。2.3 项目结构下面是我推荐的 Demo 项目结构它按功能拆分文件方便后续扩展deep-research-agent/ ├── .env # 存放 API Key 等敏感信息 ├── main.py # 程序入口 ├── agents/ │ ├── __init__.py │ ├── planner.py # 规划 Agent │ ├── search_agent.py # 搜索 Agent │ └── writer.py # 写作 Agent ├── tools/ │ ├── __init__.py │ └── search_tools.py # 搜索工具封装 └── state.py # 共享状态定义3. 从最小示例开始一个能跑通的 Agent为了让新手先建立信心我们不看复杂架构先写一个最简单的 Agent用户输入问题模型直接回答。这个最小示例会帮我们确认环境配置正确、API Key 可用。3.1 配置大模型 API在项目根目录创建.env文件OPENAI_API_KEYsk-你的密钥 OPENAI_API_BASEhttps://api.deepseek.com/v1 # 如果使用 DeepSeek 或其他兼容接口本文示例以 OpenAI 兼容接口为例重点演示配置思路。如果你使用其他大模型服务商只需确认它提供 OpenAI 兼容的接口即可。3.2 编写最小 Agent创建quickstart.pyimport os from dotenv import load_dotenv from langchain_openai import ChatOpenAI # 加载环境变量 load_dotenv() # 初始化大模型 llm ChatOpenAI( modeldeepseek-chat, openai_api_keyos.getenv(OPENAI_API_KEY), openai_api_baseos.getenv(OPENAI_API_BASE), temperature0.3, ) # 直接对话 response llm.invoke(请用一句话介绍什么是多智能体系统) print(response.content)运行验证python quickstart.py如果一切正常你会看到模型输出的内容。这个示例虽然简单但确认了三件事Python 环境没问题、依赖安装成功、API 配置可用。很多多智能体项目“跑不起来”都是卡在这些最基础的环境问题上。4. 搭建 Deep-Research 多智能体核心框架接下来进入正题实现一个能完成“深度研究”的多智能体系统。我们的目标任务是用户给出一个研究主题系统自动完成检索、总结、生成结构化报告。4.1 设计 Agent 协作流程在写代码前先明确流程。整个深度研究过程分成三个阶段规划阶段Planner Agent 接收用户问题分析需要研究的子问题列表输出 3 到 5 个具体的搜索方向。检索阶段针对每个子问题Search Agent 调用搜索工具获取相关内容。写作阶段Writer Agent 汇总所有搜索结果生成结构化报告。这个设计借鉴了链式模式流程清晰、容易调试。如果你需要更复杂的场景可以在写作阶段再加一个 Critic Agent 做质量检查这里先保留最小闭环。4.2 定义共享状态多智能体协作的关键是共享状态。我们用 langgraph 的TypedDict来定义状态结构# state.py from typing import TypedDict, List class ResearchState(TypedDict): query: str # 用户输入的研究主题 plan: List[str] # 规划阶段的子问题列表 search_results: List[dict] # 搜索结果列表 report: str # 最终生成的研究报告这个状态会在整个 Agent 图Agent Graph中传递。每个节点可以读取和更新状态最终产出report。4.3 实现 Planner AgentPlanner 的作用是“拆题”。我们通过 Prompt 让模型生成子问题列表# agents/planner.py from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate import os PLANNER_PROMPT ChatPromptTemplate.from_messages([ (system, 你是一个资深研究员。请把用户的研究主题拆解成 3 到 5 个具体的子问题 这些子问题需要覆盖主题的关键方面并适合通过网络搜索获取信息。 每个子问题单独一行不要添加编号。), (human, 研究主题{query}) ]) def create_planner_agent(): llm ChatOpenAI( modeldeepseek-chat, openai_api_keyos.getenv(OPENAI_API_KEY), openai_api_baseos.getenv(OPENAI_API_BASE), temperature0.2, ) chain PLANNER_PROMPT | llm return chain这里使用 Pipeline 操作符|这是 langchain 的一种链式调用语法Prompt 模板先生成消息再传给大模型。4.4 实现 Search AgentSearch Agent 的核心是让大模型有能力调用工具。在 langgraph 中我们可以用tool装饰器定义一个搜索函数然后把它绑定到模型上# tools/search_tools.py from duckduckgo_search import DDGS def web_search(query: str, max_results: int 5) - str: 调用搜索引擎检索信息返回格式化后的文本结果。 with DDGS() as ddgs: results list(ddgs.text(query, max_resultsmax_results)) if not results: return 没有搜索到相关结果。 formatted [] for i, r in enumerate(results, 1): formatted.append( f[{i}] 标题{r.get(title, )}\n f内容{r.get(body, )}\n f链接{r.get(href, )} ) return \n\n.join(formatted)然后创建 Search Agent# agents/search_agent.py import os from langchain_openai import ChatOpenAI from langchain_core.tools import tool from tools.search_tools import web_search def create_search_agent(): llm ChatOpenAI( modeldeepseek-chat, openai_api_keyos.getenv(OPENAI_API_KEY), openai_api_baseos.getenv(OPENAI_API_BASE), temperature0.1, ) llm_with_tools llm.bind_tools([web_search]) return llm_with_tools这里的关键是bind_tools。它把工具的信息函数名、参数描述传给大模型让模型在必要时决定调用哪个工具。4.5 实现 Writer AgentWriter 负责把搜索结果整理成连贯的报告。为了让输出更稳定我们在 Prompt 中强调报告结构# agents/writer.py from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate import os WRITER_PROMPT ChatPromptTemplate.from_messages([ (system, 你是一名专业的研究报告撰写者。请根据提供的检索资料撰写一份结构清晰的研究报告。 报告需要包含引言、主体分析、结论三个部分。 引用资料时请注明来源链接。), (human, 研究主题{query}\n\n检索资料\n{results}) ]) def create_writer_agent(): llm ChatOpenAI( modeldeepseek-chat, openai_api_keyos.getenv(OPENAI_API_KEY), openai_api_baseos.getenv(OPENAI_API_BASE), temperature0.4, ) chain WRITER_PROMPT | llm return chain4.6 用 langgraph 编排 Agent 流程有了三个 Agent最后一步是通过 langgraph 把它们串起来。这里需要写一个入口文件main.py# main.py import os from dotenv import load_dotenv load_dotenv() from langgraph.graph import StateGraph, END from state import ResearchState from agents.planner import create_planner_agent from agents.search_agent import create_search_agent from agents.writer import create_writer_agent # 创建各 Agent planner create_planner_agent() search_agent create_search_agent() writer create_writer_agent() # 定义节点函数 def plan_node(state: ResearchState) - dict: response planner.invoke({query: state[query]}) lines [line.strip() for line in response.content.split(\n) if line.strip()] return {plan: lines} def search_node(state: ResearchState) - dict: from tools.search_tools import web_search results [] for sub_query in state[plan]: content web_search(sub_query) results.append({query: sub_query, content: content}) return {search_results: results} def write_node(state: ResearchState) - dict: combined \n\n.join( f子问题{item[query]}\n资料{item[content]} for item in state[search_results] ) response writer.invoke({query: state[query], results: combined}) return {report: response.content} # 构建图 graph StateGraph(ResearchState) graph.add_node(plan, plan_node) graph.add_node(search, search_node) graph.add_node(write, write_node) graph.set_entry_point(plan) graph.add_edge(plan, search) graph.add_edge(search, write) graph.add_edge(write, END) app graph.compile() # 运行 def run_research(query: str): result app.invoke({query: query, plan: [], search_results: [], report: }) return result[report] if __name__ __main__: report run_research(2025年多智能体在金融风控领域的应用趋势) print(report)这样一个完整的 Deep-Research 多智能体 Demo 就能运行了。整个流程是用户输入主题 → Planner 输出 3 到 5 个子问题 → Search Agent 逐个搜索 → Writer 汇总输出报告。运行方式python main.py需要注意的是由于搜索到的资料质量不受代码控制最终报告的实际效果会受检索结果影响。如果某个子问题搜索不到结果Writer 可能会根据既有知识“编”内容这是一个需要在工程化阶段解决的问题。5. 进阶模块设计让 Agent 更可靠上面的 Demo 是“最小可用版本”但离生产环境还有一定距离。这里补充几个重要的进阶设计按重要性排序。5.1 增加上下文记忆多智能体协作中最容易丢失的就是长期记忆。目前上面的 Demo 在每个节点都只传入当前阶段的信息一旦任务变复杂比如需要基于上一轮搜索结论做第二轮检索就需要引入记忆机制。在 langgraph 中可以用MemorySaver保存检查点from langgraph.checkpoint import MemorySaver memory MemorySaver() app graph.compile(checkpointermemory) config {configurable: {thread_id: research-001}} result app.invoke( {query: query, plan: [], search_results: [], report: }, configconfig )有了记忆后同一个thread_id下的多轮对话可以共享历史状态这对后续做“追问式研究”很有用。5.2 加入 Critic Agent 做质量反馈生成报告之后可以用一个 Critic Agent 检查报告是否存在明显错误或遗漏。如果质量不达标可以重新触发搜索或写作节点def critic_node(state: ResearchState) - dict: critique_prompt f请评估以下报告的信息覆盖度和事实准确性\n\n{state[report]}\n\n如果发现明显不足请列出具体问题否则回复通过。 response critic_agent.invoke(critique_prompt) # 如果未通过可以设置 state[needs_revision] True return {critique: response.content}这种“生成 → 批判 → 再生成”的循环能明显提升报告质量代价是增加调用次数和延迟。5.3 将工具接入 MCP 生态在搜索热词中“MCP 多智能体”也是最近讨论度很高的话题。MCP 是用来规范大模型与外部工具之间通信的开放协议。如果你想让自己的多智能体系统能够连接更丰富的工具比如数据库查询、企业内部 API、文件读取可以考虑把工具封装成 MCP 服务然后在 Agent 中通过 MCP 客户端调用。这种做法的优势是工具可以被多个 Agent 复用不需要每个 Agent 单独实现工具逻辑。不过 MCP 的配置相对复杂建议先把基础 Demo 跑通再逐步接入 MCP。6. 常见问题与排查思路多智能体开发目前还很新框架 API 变动快踩坑是常态。下面整理几个高频问题。问题现象常见原因解决思路调用大模型 API 报 401 或 403API Key 错误、环境变量未加载检查.env文件确认load_dotenv()在代码开头被调用模型返回内容为空temperature 设置过高、上下文过长被截断降低 temperature检查输入 token 是否超出限制搜索结果为空搜索模块被目标网站拦截、关键词太特殊更换搜索关键词检查网络环境替换搜索 APIAgent 流程卡住或超时某个节点调用时间过长没有设置超时给模型调用加timeout参数为搜索设置max_results限制报告内容逻辑断裂搜索结果顺序混乱或每个子问题结果太少在搜索节点中增加摘要步骤先压缩资料再传给 Writerlanggraph 报 API 变更错误框架版本升级导致接口不兼容锁定 langgraph 版本参考对应版本的官方文档排查时建议按“环境 → 依赖 → 模型 → 工具 → 流程”的顺序快速定位。绝大多数问题发生在环境或依赖兼容性上先把最小示例跑通再逐步叠加功能。7. 工程化最佳实践从 Demo 到生产环境中间还有不小距离。以下是我在项目中总结的一些过来人经验。7.1 配置与密钥管理不要在代码中硬编码 API Key、数据库连接串等敏感信息。推荐使用环境变量或配置中心统一管理并通过.env文件在本地开发时加载。生产环境更进一步建议使用密钥管理服务比如云厂商的 KMS 或 Vault。7.2 日志与可观测性多智能体系统涉及多个环节链路很长。一旦某一步输出异常很难回溯。务必在每个节点增加日志记录至少包含以下信息当前节点名称。输入输出的关键字段。模型调用耗时和 token 消耗。工具调用的参数和返回状态。有了这些日志你才能在问题发生时快速定位到具体环节。7.3 成本控制多智能体系统比单 Agent 调用更频繁、token 消耗更大。建议从下面几个角度控制成本使用更小的模型处理简单任务把复杂任务留给强模型。对搜索结果先做压缩总结再传给 Writer。设置单次任务的调用预算超过后自动终止。7.4 安全检查与权限控制如果 Agent 系统需要连接到企业内部系统或数据库必须强调最小权限原则。给每个 Agent 分配独立的 API Key 或权限角色避免一个 Agent 被提示注入攻击后连带暴露其他系统的权限。同时对 Agent 生成的报告内容要做敏感信息过滤防止泄露内部数据。7.5 测试与评估多智能体的输出具有随机性建议建立一套基于代表性问题的回归测试集。每次修改 Prompt 或模型参数把测试集跑一遍人工抽检输出质量变化。有条件的团队可以引入基于 LLM 的自动评估工具用评分模型判断输出质量。8. 总结与学习路线这篇文章围绕 Deep-Research 多智能体开发走完了从概念到代码再到工程化的全过程。你已经掌握了其中最核心的一环如何用 langgraph 编排多个 Agent 协同完成深度研究任务。下一步可以按下面路线继续深入继续熟悉 langgraph尝试给流程增加条件分支比如“搜索无结果时调整关键词重试”或者循环执行直到质量过关。扩展工具集把搜索扩展到新闻 API、学术数据库、内部知识库让 Agent 具备更多信息源。研究更复杂的交互模式从链式/星型模式开始逐步尝试网状模式和主从共享模式。关注 MCP 生态了解 MCP 协议把工具接入标准化为后续 Agent 能力扩展打好基础。最后提醒一句多智能体开发还处于快速演进阶段保持对最新框架动态的关注很重要同时别忘了回到问题本身——你的业务里到底哪些任务适合拆给多个 Agent 协作完成从一个小而具体的场景切入往往比一开始就设计宏大架构更容易落地。如果这篇文章对你有帮助欢迎收藏备用也欢迎在评论区留下你在多智能体开发中遇到的问题。