Deep-Research多智能体开发实战：从环境搭建到批量任务排查

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 B，B 给 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 python=3.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_url="http://localhost:11434/v1", # 以你的实际服务地址为准 api_key="local", ) def call_llm(system: str, user: str) -> str: resp = client.chat.completions.create( model="qwen2.5:7b", # 以实际可用模型为准 messages=[ {"role": "system", "content": system}, {"role": "user", "content": user}, ], temperature=0.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 标准化工具层

MCP（Model Context Protocol）这几年在 Agent 开发里出现频率很高。它的作用可以理解成：把工具封装成标准服务，Agent 通过统一协议调用，而不是每个 Agent 各自写死函数。

对于多智能体系统，MCP 的直接收益有三个：

• 工具复用。同一个搜索服务可以被 Researcher、Reviewer 等多个 Agent 共用。
• 接口解耦。工具更新时，Agent 端不需要跟着改。
• 权限可控。工具服务层可以统一控制频率、配额、日志。

语言生态上，Python 和 Node 都有对应 SDK，Java 后端可以关注 LangChain4j 对 MCP 的接入方式。不过要注意，MCP 只是让工具调用更规范，它不能提升模型自身能力。工具服务器写不好，协议再标准也没用。

4.4 报告输出必须带来源

多 Agent 系统最怕的就是“看起来专业、实际不可查”。所以从第一版开始，就要强制输出来源编号。

可以在 Researcher 阶段给每条资料一个 index，Writer 生成报告时明确引用[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.json

5.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 成本评估不能只看 Demo

Deep-Research 和普通聊天不同，一次调研可能调用几十次模型，跑几十次搜索。成本估算公式很简单：

• token 成本 = 每次调用的输入输出 token 总和 x 单价
• 工具成本 = 搜索 API 次数 x 单价
• 人力成本 = 排查一次失败任务所需时间

建议每次任务在 meta.json 里记录总 token、模型调用次数、搜索次数、耗时。批量跑了 100 个任务之后，用这些数据分析成本瓶颈在哪里。你会发现有时候不是模型贵，而是搜索抓取太多次。

6. 常见问题和排查链路

6.1 任务卡住不动

先确认卡在哪一步。最简单的方法是看日志，如果日志停在“调度 Planner”，说明模型调用还没返回；停在搜索步骤，可能网络或搜索接口超时；停在抓取步骤，经常是目标网站结构变化。

排查顺序：

1. 杀掉当前进程，重新跑单条任务。
2. 用脚本单独调用一次搜索接口。
3. 用脚本单独抓取指定 URL。
4. 查看模型服务端日志，确认是否收到请求。
5. 检查输出目录里最近一次成功写入的中间文件。

大多数卡住问题不是模型问题，而是某个外部依赖没有响应。

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 开发过程中遇到的问题，按这个顺序检查，能省掉大量无效调试：

1. 看现象：是报错、卡住、无输出、还是输出质量差。
2. 看输入：问题表述是否清楚，子任务是否重复，搜索词是否有效。
3. 看环境：依赖版本、网络、权限、磁盘空间、系统编码。
4. 看参数：temperature、max_tokens、超时时间、并发数、重试次数。
5. 看链路：中间文件是否完整，哪个 Agent 环节开始出现问题。

这套顺序我反复用。很多时候最后发现不是模型能力不行，而是输入材料没有清理干净，或者某个依赖库版本不兼容。

最后说点实际建议

多智能体开发很容易陷入“加角色、加工具、加 Agent”的循环里。我经历过几次之后，现在的做法是：先用单 Agent 跑通输入输出，再加一个 Researcher 接入真实搜索，等这一层稳定了，再补 Planner 做任务拆解，最后才考虑 Reviewer 和协商模式。

Deep-Research 这类应用真正落地时，最值得盯住的不是功能列表，而是输入格式是否干净、资源占用是否可控、工具调用是否稳定、失败任务能否重试。这些问题解决之后，报告质量再差也有优化空间。反过来，流程不稳定，模型说得再好也没法上线。