Deep-Research 多智能体开发简单说就是让多个 AI Agent 分工协作自动完成资料检索、交叉验证、内容组织最后产出一份结构化调研报告。这个方向现在热度很高但真正的门槛不是跑通一个 Demo而是怎么设计任务链路、接入真实工具、控制上下文和稳定性。我最近从零搭了一套 Deep-Research 多智能体流程下面把环境准备、最小实现、参数选择、批量任务和排查思路拆开讲。如果你有一定编程基础想接触 AI Agent 开发这篇文章可以直接当第一份实操参考。我不会只讲概念更多会写“先做什么、再看什么、失败后查哪里”。1. 先搞清楚Deep-Research 多智能体开发到底在解决什么问题1.1 单 Agent 做调研为什么越做越乱很多人第一次接触 Agent 开发会先让一个模型直接回答“请帮我调研某个技术方案”。单条任务看起来能跑但一旦问题变复杂立刻会出现几个问题模型上下文窗口有限。调研一个主题可能要读 20 篇文档几十万字塞不进去最后模型只记得开头和结尾。单 Agent 只会沿着一条路径往下走。发现某个信息不够时不会主动拆问题、换关键词、查多个来源。很容易编造来源和数字。模型没有真实检索能力凭训练记忆输出看起来合理实际不可查。中间过程不可控。你不知道它看了哪些资料也不知道结论推给谁出了问题很难排查。Deep-Research 要解决的就是这个问题把“研究一个主题”变成“一组有分工、有顺序、可验证的 Agent 协作任务”。1.2 多 Agent 系统的基本分工方式我的建议是先记住一个类比多 Agent 不是让多个模型聊聊天而是把一次调研拆成一个“小型研究小组”。Agent 角色职责输入输出Planner拆解调研目标生成子任务列表用户问题结构化任务清单Researcher执行搜索、抓取、读取文档子任务原始资料集合Analyst提取观点、对比信息、查重查漏原始资料结构化分析结果Writer生成最终报告分析结果Markdown / JSON 报告Reviewer检查引用、补缺、纠正错误报告草稿修改建议或终稿实际项目不一定五个角色全要。最少可以保留三个Planner、Researcher、Writer。能力再弱一点的场景Planner 和 Writer 可以合并但迭代起来会比较费劲。我推荐第一版先做三 Agent跑通后再把 Reviewer 加上。1.3 多智能体的四种交互模式“多智能体的四种交互模式”是很多人在选架构时容易卡住的地方。这里直接给结论串行流水线。Agent A 输出给 Agent BB 给 C适合任务有严格先后依赖。比如先搜索、再分析、最后写作。并行扇形。一个 Planner 发出多个子任务多个 Researcher 同时执行最后汇总。适合查多个关键词、读多个网页。分层管理。一个上层 Agent 管理多个下层 Agent下层 Agent 可以继续拆分任务。适合任务复杂、层级清晰的项目。协商辩论模式。两个或者多个 Agent 就同一个问题给出判断互相质疑最后收敛结论。适合验证结论、降低偏误。选择原则很简单先跑串行再给搜索步骤加并行最后才考虑协商模式。不要一上来就设计成复杂分层调试成本会翻倍。1.4 不是只有大厂框架才能做经常有人问Agent 开发到底该从语言模型开始还是从框架开始我的看法是先把 Agent 理解成一组组件模型负责理解和生成。工具负责获取外部信息比如搜索、抓取、读文件。控制循环负责决定调用谁、按什么顺序调用、结果是否满足要求。语言上Python 生态最全适合做数据处理和工具接入。Java 后端团队可以看 LangChain4j。前端同学做 Web 应用或插件可以用 TypeScript 方案。核心不是框架而是上面三个组件能不能串起来。2. 开发机准备系统、模型、依赖怎么配2.1 Ubuntu 24.04 Desktop 还是 Server做 Deep-Research 多智能体开发如果只想安装一个系统我更推荐 Ubuntu 24.04 Desktop。原因不是 Server 不好而是开发阶段你需要频繁看日志、看截图、调试浏览器自动化、查看 PDF 和 HTML。Desktop 自带图形环境和常用工具省去很多折腾。如果你的目标是部署成服务跑在远程服务器上Server 更合适。它占用资源少、没有图形栈适合 7x24 小时运行任务队列。有一种更实用的组合本地用 Desktop 开发调试生产环境用 Server 部署。两边系统一致环境差异会小很多。2.2 Python 环境和最小依赖建议使用 Python 3.10 或 3.11。不要用最新的 Python 3.13 跑所有项目部分依赖兼容不及时报错会浪费很多时间。创建独立环境conda create -n deepresearch python3.11 -y conda activate deepresearch基础依赖可以这样安装pip install requests beautifulsoup4 lxml pydantic pandas pip install openai # 很多兼容模型接口也用这个 SDK pip install playwright playwright install chromium这里说下为什么要装这些requests 和 beautifulsoup4 用于网页抓取和正文提取。pydantic 用于定义 Agent 输入输出结构比直接传字典更稳。openai SDK 不只用于 OpenAI 官方接口很多云厂商和本地推理服务都提供 OpenAI 兼容接口。playwright 用于渲染动态页面。很多调研对象是 JS 渲染的普通请求拿不到正文最好提前装好 Chromium。2.3 模型怎么接入最省事开发阶段建议先固定一个模型不要搞多模型切换。优先选你已有的、能调用、返回稳定的模型接口。只要接口是 OpenAI 兼容格式代码可以统一用同一个客户端。核心配置项有几个base_url指向模型服务地址。api_key本地模型可以填任意非空值。model模型名称以服务端列表为准。temperature调研类任务建议 0 到 0.3不要太高。max_tokens决定单次回复长度。调研拆解和摘要任务通常设置 1000 到 4000。如果本地有条件也可以用 Ollama 或 vLLM 跑开源模型。但我要提醒一句本地小模型适合调试流程不一定适合最终报告质量。不要因为本地跑通一个 7B 模型就断定全流程没问题。2.4 硬件底线和资源配置如果你调用远程 API开发机配置不需要太高。8GB 内存、普通 CPU 也能跑流程瓶颈在网络和模型服务端。如果你要在本地跑模型情况不同。7B 到 14B 量化模型建议 16GB 内存起步或 8GB 以上显存。更大参数模型需要更多显存。判断标准很简单单次推理的响应时间能不能接受上下文会不会经常超限。第一次开发我总是建议把资源预算压到最低模型用小一点的、并发调成 1、搜索请求间隔放慢。先把流程跑通再逐步升级。3. 从一条任务开始搭最小可运行的多 Agent 流程3.1 先跑一个单 Agent 基线不要一上来就写多 Agent 调度器。先确认“模型能不能按我的格式返回结果”。这一步可以写一个最简单的函数from openai import OpenAI client OpenAI( base_urlhttp://localhost:11434/v1, # 以你的实际服务地址为准 api_keylocal, ) def call_llm(system: str, user: str) - str: resp client.chat.completions.create( modelqwen2.5:7b, # 以实际可用模型为准 messages[ {role: system, content: system}, {role: user, content: user}, ], temperature0.2, ) return resp.choices[0].message.content print(call_llm(你是调研助手, 请列出三个搜索关键词))这里最核心的是验证三件事接口通不通、模型能不能被中文指令驱动、返回内容能不能被程序正常接收。3.2 设计最小状态结构多 Agent 系统不需要一开始就用复杂框架。可以用一个字典维护所有中间状态state { question: 调研开源 OCR 工具选型, subtasks: [], raw_materials: [], report: , }每个 Agent 做的事情就是读 state 的一部分调用模型或工具把结果写回 state。这比直接用框架更容易理解出了问题也能看到数据在哪个环节丢的。3.3 Planner 到 Writer 的最小链路一个最小可运行的链路包含三个节点。Planner 的职责是把用户问题拆成 3 到 5 个子任务PLANNER_SYSTEM 你是一个调研任务拆解器。请把用户问题拆成不超过5个子任务。 每个子任务输出为JSON数组字段包括 id、keyword、goal。 只输出JSON不要解释。 Researcher 负责执行搜索。第一版可以先用一个搜索接口把返回结果截取摘要保存下来不要直接抓正文避免网页结构问题拖住进度。Writer 基于 raw_materials 组织报告WRITER_SYSTEM 你是调研报告写作者。根据提供的资料生成结构化Markdown报告。 包含背景、方案对比、优劣势、建议。 每条结论末尾标注来源编号。 这样组合起来就是一个最小多 Agent 流程。虽然看起来简单但它已经具备“拆任务、搜资料、写报告”三个关键动作。3.4 第一次跑通的判断标准第一版不要追求报告专业。判断标准只有四条流程没有报错能从用户问题一路走到报告生成。每个中间结果都写入文件比如outputs/subtasks.json、outputs/raw.json。模型输出能够被解析没有出现 JSON 截断或格式混乱。报告中能看到至少一个真实来源标题或链接。如果这四条都满足说明链路已经通了。接下来才有资格谈优化质量。4. 让结果变可信真实工具、搜索验证和 MCP 接入4.1 模型自带知识不等于调研纯靠模型生成的内容本质是“根据训练数据预测答案”不是真正调研。你问“某个工具 2025 年是否支持新格式”模型可能还在回答老版本的信息。所以要解决两个问题工具层模型必须能调用真实搜索、抓取、读取 API。验证层报告里的每个来源都要能回传至少保留标题、URL、时间和正文片段。工具接入是 Deep-Research 多智能体里最容易被低估的部分。很多项目效果差不是模型不行而是搜索工具返回了一堆导航链接正文没抓到模型没素材可用。4.2 一个搜索和抓取任务怎么设计我一般把搜索和抓取分成两个动作。搜索动作接收 keyword返回若干条结果包含标题、链接、摘要。这一步适合用搜索 API 完成。不要直接把关键字拼进爬虫搜索引擎对专有名词和长句的召回效果通常不好。抓取动作接收 URL返回页面正文。这一步要注意先试着用 requests 抓查返回的 Content-Type。动态页面再用 playwright 渲染。清理导航、脚本、广告标签。限制单页大小避免把几十 MB 内容塞进上下文。每个抓取结果保存成固定结构{ url: https://example.com/doc, title: 文档标题, content: 清洗后的正文文本, timestamp: 2025-01-01 12:00:00 }4.3 用 MCP 标准化工具层MCPModel Context Protocol这几年在 Agent 开发里出现频率很高。它的作用可以理解成把工具封装成标准服务Agent 通过统一协议调用而不是每个 Agent 各自写死函数。对于多智能体系统MCP 的直接收益有三个工具复用。同一个搜索服务可以被 Researcher、Reviewer 等多个 Agent 共用。接口解耦。工具更新时Agent 端不需要跟着改。权限可控。工具服务层可以统一控制频率、配额、日志。语言生态上Python 和 Node 都有对应 SDKJava 后端可以关注 LangChain4j 对 MCP 的接入方式。不过要注意MCP 只是让工具调用更规范它不能提升模型自身能力。工具服务器写不好协议再标准也没用。4.4 报告输出必须带来源多 Agent 系统最怕的就是“看起来专业、实际不可查”。所以从第一版开始就要强制输出来源编号。可以在 Researcher 阶段给每条资料一个 indexWriter 生成报告时明确引用[1]、[2]最后额外输出 references 列表。验证方式很直接抽 3 个引用人工打开链接确认内容存在、标题一致、关键信息对得上。只要引用经不起抽查就说明调研链路还有问题不要急着上线给用户看。5. 批量任务和产品化从能跑到能用5.1 单条任务跑通后不要急着加复杂 UI很多开发者跑通一个 Demo 后第一反应是去做前端界面。我的建议相反先把输入输出规范化。给每个任务生成一个任务 ID固定输出目录记录开始时间、模型、工具调用次数、token 消耗、结束时间。有了这套基础数据后面才能做批量测试和质量评估。推荐目录结构outputs/ task_20250101_001/ question.txt subtasks.json raw_materials.json report.md meta.json5.2 批量任务的关键设计当你要同时处理几十个调研主题就需要面对几个单条任务时不会碰到的问题。并发控制。推荐先并发 1 到 2稳定后再慢慢加。直接开最大并发很容易被搜索接口限流或者把本地模型显存打满。失败重试。单个子任务失败时不要让整个任务崩溃。记录错误重试一次或两次还失败就跳过并写入日志。断点续跑。如果 task 已经完成搜索只是报告生成失败下一次运行可以跳过搜索直接重试 Writer。超时控制。搜索、抓取、模型调用都必须有超时时间。否则一个网页卡住整条任务队列跟着卡。判断批量系统是否稳定不看“能跑多少个”看“失败率、卡住率、错误日志可读性”。5.3 Agent 开发里前后端各干什么把 Deep-Research 做成一个产品一定会涉及前后端分工。这里先把职责理清后端负责编排、任务队列、状态存储、模型调用、工具调用。核心是保证任务可靠执行。前端负责任务创建、进度展示、中间过程查看、报告展示。如果是网页或小程序不建议把模型接口直接暴露给前端。前端应该只调后端 API。典型接口就三个POST /api/tasks 创建调研任务 GET /api/tasks/{id} 查询任务状态和中间结果 GET /api/tasks/{id}/report 获取最终报告后端语言用 Python、Java、Node 都可以。关键是任务执行要独立于 HTTP 请求用后台任务队列运行不要把长时间调研操作塞进同步接口。5.4 成本评估不能只看 DemoDeep-Research 和普通聊天不同一次调研可能调用几十次模型跑几十次搜索。成本估算公式很简单token 成本 每次调用的输入输出 token 总和 x 单价工具成本 搜索 API 次数 x 单价人力成本 排查一次失败任务所需时间建议每次任务在 meta.json 里记录总 token、模型调用次数、搜索次数、耗时。批量跑了 100 个任务之后用这些数据分析成本瓶颈在哪里。你会发现有时候不是模型贵而是搜索抓取太多次。6. 常见问题和排查链路6.1 任务卡住不动先确认卡在哪一步。最简单的方法是看日志如果日志停在“调度 Planner”说明模型调用还没返回停在搜索步骤可能网络或搜索接口超时停在抓取步骤经常是目标网站结构变化。排查顺序杀掉当前进程重新跑单条任务。用脚本单独调用一次搜索接口。用脚本单独抓取指定 URL。查看模型服务端日志确认是否收到请求。检查输出目录里最近一次成功写入的中间文件。大多数卡住问题不是模型问题而是某个外部依赖没有响应。6.2 报告又空又泛报告写得“正确但没用”通常是两种原因。一是 Planner 拆出的关键词太宽泛比如把“OCR 工具现状”拆成三个同义关键词搜到的内容大量重复。二是 Researcher 没有把有效信息写入上下文Writer 只能靠猜测撑篇幅。我建议先看 raw_materials.json。如果里面只有标题、没有正文说明抓取失败。如果有正文但都是营销稿说明搜索词需要加限定词比如“对比、评测、官方文档、GitHub”。案例调研“OCR 工具选型”时把子任务拆成“开源 OCR 工具的对比”、“主流 OCR 项目的 GitHub 信息”、“OCR 在不同场景的准确率实测”会比只搜“OCR 工具”有效得多。6.3 引用错误或来源对不上报告里出现虚假引用是最影响可信度的故障。常见原因有三个Writer 在生成时没有严格约束只能使用提供的资料。Researcher 返回了过多片段Writer 使用了没有来源编号的信息。搜索摘要和正文标题不一致导致引用张冠李戴。解决方法是把引用当成硬约束。系统提示词里写清楚“只能使用提供的材料每条结论必须带对应来源编号。没有来源的信息不要写。”千万不要指望模型自觉最好在生成后写一个简单校验脚本检查每个[数字]是否在 references 中。6.4 通用排查顺序把整个 Deep-Research 开发过程中遇到的问题按这个顺序检查能省掉大量无效调试看现象是报错、卡住、无输出、还是输出质量差。看输入问题表述是否清楚子任务是否重复搜索词是否有效。看环境依赖版本、网络、权限、磁盘空间、系统编码。看参数temperature、max_tokens、超时时间、并发数、重试次数。看链路中间文件是否完整哪个 Agent 环节开始出现问题。这套顺序我反复用。很多时候最后发现不是模型能力不行而是输入材料没有清理干净或者某个依赖库版本不兼容。最后说点实际建议多智能体开发很容易陷入“加角色、加工具、加 Agent”的循环里。我经历过几次之后现在的做法是先用单 Agent 跑通输入输出再加一个 Researcher 接入真实搜索等这一层稳定了再补 Planner 做任务拆解最后才考虑 Reviewer 和协商模式。Deep-Research 这类应用真正落地时最值得盯住的不是功能列表而是输入格式是否干净、资源占用是否可控、工具调用是否稳定、失败任务能否重试。这些问题解决之后报告质量再差也有优化空间。反过来流程不稳定模型说得再好也没法上线。