DeepAgents 多智能体架构实战：从设计模式到后端选型
本文以 DeepAgents 框架为基础，通过「智能旅行助手」这一典型场景，总结多智能体架构的核心设计模式，并系统梳理框架提供的多种后端执行环境及其选型策略。
一、为什么需要多智能体？
系统的核心问题来自一个典型的旅行场景：
"我下个月想去云南玩 7 天，两个人，预算 1 万以内。帮我规划行程、订机票酒店，再出一份费用清单。"
这个在日常对话中再普通不过的请求，拆解开来却涉及多个截然不同的专业领域：
- 行程规划：需要分析景点分布、交通路线、时间分配，可能需要执行数据分析脚本来做路线优化
- 机酒预订：需要查询航班、比价、创建订单，涉及支付——必须经过人工确认才能执行
- 当地推荐：需要实时获取天气、餐厅评分、当地活动等动态信息
- 费用报告：需要汇总所有消费数据，生成可视化的费用清单
如果让一个智能体包揽所有工作，系统提示词会膨胀到上万字，工具集混杂着二十几个工具，模型在"什么都要懂"的重压下反而什么都做不精。
多智能体架构的核心思想就是：让专业的智能体做专业的事。
一个"总指挥"负责理解意图和分配任务，每个"专家"只关注自己的领域——就像一家旅行社里，有行程规划师、票务专员、当地向导、应急协调员各司其职。
二、DeepAgents 的多智能体设计模式
2.1 核心架构：主从编排模式
DeepAgents 采用经典的 主从编排（Master-Worker） 模式：
用户请求 → 主 Agent（任务理解 + 路由决策）
├── 子 Agent A（专业领域 A）
├── 子 Agent B（专业领域 B）
└── 子 Agent C（专业领域 C）
主 Agent 扮演"总指挥"角色——它不直接执行具体业务操作，而是：
- 理解用户意图：解析自然语言需求
- 任务拆解：将复杂需求分解为多个子任务
- 智能路由：根据子 Agent 的能力描述，将任务委派给最合适的子 Agent
- 结果汇总：收集子 Agent 的执行结果，组织最终回复
这种模式的关键在于委派模板（Delegation Template）。每个子 Agent 都有一份清晰的"能力说明书"，主 Agent 通过这些说明书来判断谁最适合处理当前任务。
2.2 子 Agent 的定义：声明式配置
在 DeepAgents 中，每个子 Agent 通过一份 YAML 配置文件来定义。这种声明式的方式带来几个好处：
- 零代码新增子 Agent：只需新建一个 YAML 文件
- 配置即文档：配置文件本身就是子 Agent 的完整描述
- 易于维护和迭代：修改提示词或工具列表不需要改代码
一份典型的子 Agent 配置包含以下核心要素：
| 字段 | 说明 |
|---|---|
name |
子 Agent 的唯一标识符 |
description |
供主 Agent 决策的能力描述（关键词匹配的重要依据） |
system_prompt |
子 Agent 的系统提示词，定义其角色和行为规范 |
tools |
可用工具列表（运行时动态解析为实际工具对象） |
skills |
技能路径列表（渐进式加载，按需激活） |
model |
可选，指定使用的模型（不指定则继承主 Agent） |
middleware |
可选，子 Agent 专属的中间件 |
interrupt_on |
可选，人工介入配置（Human-in-the-Loop） |
2.3 智能体集群方案
在智能旅行助手系统中，共设计 5 个专业子 Agent。下面逐一拆解每个 Agent 的定位和设计决策。
🗺️ 行程规划师（trip-planner）
- 职责：目的地分析、行程路线规划、景点推荐、时间分配优化
- 触发词："规划行程"、"推荐景点"、"路线"、"几天"、"行程安排"
- 工具箱：景点数据库查询、地图距离计算、天气查询 + 网络搜索 + 数据分析脚本执行
- 执行环境：沙箱隔离环境（需要运行 Python 数据分析脚本来做路线优化）
- 中间件：摘要中间件（景点信息量大，需要频繁压缩上下文）
设计决策：行程规划需要查询多个数据源、执行 Python 脚本做路线优化，这些操作需要安装额外依赖，必须放在沙箱中执行。
✈️ 机酒预订专家（flight-hotel-booker）
- 职责：航班查询与比价、酒店搜索与推荐、创建预订订单
- 触发词："订机票"、"订酒店"、"预订"、"航班"、"住宿"、"比价"
- 特色：支持 Human-in-the-Loop，涉及支付的订单创建前必须经过人工审批确认
- 工具箱：航班搜索、酒店搜索、订单创建 + 数据补充工具（人工介入补齐旅客信息）
设计决策：预订操作涉及真金白银，必须设置人工确认环节。通过
interrupt_on配置审批拦截——Agent 准备好订单详情后，系统暂停执行，等待用户确认才真正下单。
🏮 当地向导（local-guide）
- 职责：当地美食推荐、文化活动查询、实时天气播报、交通指南
- 触发词："吃什么"、"哪里好玩"、"天气"、"交通"、"当地"、"推荐"
- 执行环境：本地执行（直接调用外部 API，不需要沙箱）
- 中间件：轻量模式（20 次模型调用 / 50 次工具调用），工具调用流程相对固定
设计决策：当地向导的任务是"即问即答"型的——用户问"附近有什么好吃的"，Agent 调用 API 查询、返回结果，完事。不需要复杂的上下文管理，所以中间件配置得很轻。
🆘 旅途应急员（trip-emergency）
- 职责：航班取消处理、紧急医疗协助、保险理赔指引、投诉工单创建
- 触发词："取消"、"投诉"、"紧急"、"出问题"、"理赔"、"延误"
- 特色：智能选择处置路径——简单问题自动处理（如航班改签），复杂问题创建人工工单
- 核心规则：自动处理与创建工单是互斥选择，不能同时执行
设计决策：应急场景需要明确果断。在提示词中硬性规定两条路径互斥——Agent 必须且只能选择一条，避免"又做自动处理又转人工"的模糊响应。
📊 旅行报告官（travel-reporter）
- 职责：生成旅行费用汇总报告、行程回顾、消费分析图表
- 触发词："费用清单"、"花了多少"、"账单"、"报告"、"费用分析"
- 执行环境：本地执行（直接调用原生 Python 报表工具，不依赖沙箱）
设计决策：报表生成不需要沙箱隔离——它只是读取已有的消费数据，用原生 Python 工具汇总输出。放在本地执行可以省去沙箱通信开销，生成速度更快。
2.4 运行时加载：从配置到可执行智能体
子 Agent 的加载分为两个阶段：
阶段一：配置加载
扫描配置目录下所有 YAML 文件，解析并校验必填字段。这一步得到的是"原始配置"——工具字段还是字符串名称列表。
阶段二：工具解析
将字符串工具名与实际的工具对象进行匹配。匹配规则采用子串匹配策略：
- 精确匹配：
"flight_search"→ 匹配名为flight_search的工具 - 前缀匹配：
"hotel_"→ 匹配所有以hotel_开头的工具
这种设计的好处是：当 MCP 服务器新增了工具（例如新增 hotel_review 酒店评价工具），只要名称符合已有的 hotel_ 前缀匹配模式，机酒预订专家就自动获得了新工具的能力，不需要修改任何配置。
三、中间件系统：智能体的"操作系统"
中间件系统是 DeepAgents 架构中最精妙的部分之一。它像"操作系统"一样，为智能体提供了自动化的基础能力，让智能体可以专注于业务逻辑。
3.1 核心中间件一览
| 中间件 | 作用 | 适用场景 |
|---|---|---|
| 摘要中间件 | 上下文达到窗口 85% 时自动压缩，防止溢出 | 行程规划、旅行报告等长对话场景 |
| 模型调用限制 | 防止无限循环，设定最大模型调用次数 | 所有子 Agent |
| 工具调用限制 | 防止工具调用爆炸，设定最大调用次数 | 所有子 Agent |
| 上下文注入 | 在每轮对话前注入用户偏好、出行人数、预算等信息 | 主 Agent |
| 记忆更新 | 对话过程中自动提取并持久化用户偏好（如偏好靠窗座位、喜欢海景房） | 主 Agent |
| 技能同步 | 将用户自定义技能（如私人导游联系方式列表）同步到执行环境 | 主 Agent |
3.2 差异化中间件策略
"一刀切"的中间件配置会导致两个问题：分析类 Agent 上下文频繁溢出，操作类 Agent 却被不必要的摘要计算拖慢响应。因此需要差异化策略：
| 子 Agent | 摘要中间件 | 模型调用上限 | 工具调用上限 | 策略原因 |
|---|---|---|---|---|
| 行程规划师 | ✅ | 50 | 200 | 景点信息量大，需要反复查询对比 |
| 机酒预订专家 | ❌ | 20 | 50 | 流程固定：查询→确认→下单 |
| 当地向导 | ❌ | 20 | 50 | 即问即答，流程简短直接 |
| 旅途应急员 | ❌ | 20 | 50 | 应急处理讲究快速决策 |
| 旅行报告官 | ✅ | 50 | 200 | 需要汇总大量消费数据 |
核心规律：分析类任务配宽松限制 + 摘要中间件；操作类任务配严格限制、不配摘要。既保证灵活性，又避免资源浪费。
四、后端执行环境：选对舞台很重要
后端抽象层是选择 DeepAgents 的重要原因之一。不同的任务对执行环境有不同的要求——有的需要沙箱隔离保证安全，有的需要直接访问本地资源提升性能。
4.1 五种后端类型与选型方案
📦 LocalShellBackend（本地 Shell 后端）
最基础的执行后端。 直接在宿主机本地文件系统上执行命令和文件操作。
- 适用场景：开发测试、快速原型验证、不需要隔离的简单任务
- 优势：零配置、启动快、无额外依赖
- 劣势：无隔离，代码直接在本机执行
用法：作为快速模式（Fast Mode） 的默认后端——跳过沙箱连接，直接本地执行，用于自动化测试和开发联调。
🏖️ OpenSandbox（沙箱后端）
隔离的执行环境。 代码在远程沙箱容器中执行，与宿主机完全隔离。
- 适用场景：执行不可信代码、需要依赖安装的复杂分析任务、多租户场景
- 优势：安全隔离、环境独立、不污染宿主机
- 劣势：需要额外部署沙箱服务、有网络连接开销
用法：行程规划师的后端。路线优化需要安装 scipy、networkx 等包来运行图论算法，沙箱环境确保这些操作不会影响主系统。
🔄 ResilientBackend（弹性后端）
这是最有价值的后端设计之一。 它继承自 LocalShellBackend，但可以在沙箱可用时自动"升级"到沙箱执行。
核心行为：
- 启动时不阻塞——沙箱在后台线程中异步连接
- 沙箱连接完成前：使用本地后端兜底
- 沙箱连接完成后：自动切换到沙箱执行
- 沙箱执行失败时：自动降级回本地执行
请求到达 → 沙箱可用？
├── 是 → 沙箱执行 → 成功？→ 返回结果
│ └── 失败 → 降级到本地执行
└── 否 → 本地执行
用法：行程规划师使用弹性后端——沙箱可用时在容器里跑数据分析，沙箱不可用时退化为本地简单规划，保证用户始终能得到响应。
🗂️ FilesystemBackend（文件系统后端）
专注于文件操作的后端。 提供读写、列表、搜索等文件系统能力。
用法：用于持久化存储路由：
/memories/→ 本地文件系统（用户旅行偏好：靠窗座位、素食、海景房等）/persisted-skills/→ 本地文件系统（用户自定义技能：私人导游联系方式等）/download/→ 本地文件系统（费用报告下载目录）
🧩 CompositeBackend（组合后端）
路由分发的"元后端"。 它不直接执行操作，而是根据文件路径将请求路由到不同的后端。
这是整个后端体系中最关键的一层。通过 CompositeBackend 实现混合存储策略：
| 路径 | 路由目标 | 设计原因 |
|---|---|---|
/AGENTS.md |
沙箱 | 智能体指引文件，需要与执行环境一致 |
/docs/ |
沙箱 | 委派模板等文档 |
/memories/ |
本地文件系统 | 用户旅行偏好需要持久化，不受沙箱生命周期影响 |
/persisted-skills/ |
本地文件系统 | 用户技能需要跨会话持久化 |
/download/ |
本地文件系统 | 报告文件需要用户可直接下载 |
| 其他路径 | 沙箱 | 临时文件、脚本执行等 |
这种设计的巧妙之处在于：对智能体来说，它看到的是一个统一的文件系统；但在底层，不同路径的数据被存储在了最合适的位置。
4.2 后端选型决策树
以下是选型参考指南：
你的场景是什么？
│
├── 开发/测试 ──────────→ LocalShellBackend
│ 快速、零配置
│
├── 执行不可信代码 ─────→ OpenSandbox
│ 安全隔离、环境独立
│
├── 需要高可用 ─────────→ ResilientBackend
│ 沙箱优先、自动降级
│
├── 混合存储需求 ───────→ CompositeBackend
│ 路径路由、统一管理
│
└── 纯文件操作 ─────────→ FilesystemBackend
轻量、专注
五、LLM 后端：多模型协作
DeepAgents 的多智能体架构不仅体现在"多个 Agent"上，还体现在"多个模型"的灵活配置上。
5.1 模型分层方案
推荐采用三级模型分层策略：
| 层级 | 模型选择 | 用途 | 选择理由 |
|---|---|---|---|
| 主力模型 | GPT-4o | 主 Agent 推理、复杂行程规划 | 推理能力强，工具调用稳定 |
| 轻量模型 | GPT-4o-mini | 摘要生成、上下文压缩、记忆更新 | 成本仅为主力模型的 1/15，摘要质量足够 |
| 备用模型 | 通义千问 Qwen-Max | 主力模型故障时的降级方案 | 中文能力强，国内访问稳定 |
这种策略的核心思想是成本与性能的平衡：
- 复杂的推理和决策用大模型，确保行程规划的质量
- 摘要、压缩等"体力活"用小模型，降低整体调用成本
- 备用模型确保单点故障不会导致整个系统瘫痪
5.2 支持的模型提供商
得益于 LangChain 生态的统一抽象，DeepAgents 可以灵活对接多种模型提供商：
| 提供商 | 代表模型 | 特点 |
|---|---|---|
| OpenAI | GPT-4o / GPT-4o-mini | 生态成熟，工具调用稳定，全球可用 |
| Anthropic | Claude 3.5 Sonnet / Haiku | 长上下文支持好，安全性高 |
| DeepSeek | DeepSeek-V3 / DeepSeek-R1 | 高性价比，中文能力强，支持思维链控制 |
| Gemini 2.0 Pro / Flash | 多模态能力强 | |
| 阿里云 | 通义千问 Qwen-Max / Plus | 国内合规，中文理解好，延迟低 |
| 智谱 AI | GLM-4 / GLM-5 | 国内部署，结构化输出支持好 |
| MiniMax | ABAB 系列 | 长文本生成能力强 |
| Kimi（月之暗面） | Kimi 系列 | 超长上下文支持，适合长文档分析 |
所有模型都通过统一的 ChatOpenAI 接口（OpenAI 兼容协议）接入，只需配置不同的 base_url 和 api_key 即可切换。换模型提供商只需修改配置文件中的三行参数，不需要改动任何业务代码。
六、系统架构全景
将所有组件组合在一起，整个系统的架构如下：
┌──────────────────────────────────────────────────────────┐
│ 用户界面（Web / App） │
└──────────────────────────┬───────────────────────────────┘
│ HTTP / SSE
┌──────────────────────────▼───────────────────────────────┐
│ API 网关（FastAPI） │
└──────────────────────────┬───────────────────────────────┘
│
┌──────────────────────────▼───────────────────────────────┐
│ DeepAgents 框架层 │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 主 Agent（任务理解 → 智能路由 → 结果汇总） │ │
│ │ ├── 行程规划师 ←→ [弹性后端: 沙箱/本地] │ │
│ │ ├── 机酒预订专家 ←→ [弹性后端 + HITL 审批] │ │
│ │ ├── 当地向导 ←→ [本地后端] │ │
│ │ ├── 旅途应急员 ←→ [本地后端] │ │
│ │ └── 旅行报告官 ←→ [本地后端] │ │
│ └─────────────────────────────────────────────────┘ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 中间件系统 │ │ 记忆系统 │ │ 技能系统 │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└──────────┬───────────────┬───────────────┬───────────────┘
│ │ │
┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
│ MCP 工具层 │ │ LLM 模型层 │ │ 存储层 │
│ (业务工具集) │ │ (多模型协作) │ │ (混合存储) │
└─────────────┘ └─────────────┘ └─────────────┘
一次典型的请求流转：
- 用户说："帮我规划 7 天云南行程，两个人，预算 1 万"
- 主 Agent 识别意图 → 委派给 行程规划师
- 行程规划师 在沙箱中运行路线优化脚本 → 输出行程方案
- 用户说："帮我订去昆明的机票"
- 主 Agent 路由 → 委派给 机酒预订专家
- 机酒预订专家 查询航班 → 触发 HITL 审批 → 用户确认 → 创建订单
- 用户说："到了之后有什么好吃的？"
- 主 Agent 路由 → 委派给 当地向导
- 当地向导 调用本地 API 推荐餐厅 → 返回结果
- 旅行结束后，用户说："帮我出一份费用清单"
- 主 Agent 路由 → 委派给 旅行报告官
- 旅行报告官 汇总所有消费数据 → 生成可视化报告 → 返回下载链接
七、实战经验与最佳实践
以下是方案设计中需要注意的关键点。
7.1 子 Agent 划分的"度"
不要太粗，也不要太细。
- 太粗（一个子 Agent 包揽太多）→ 失去分工的意义，提示词臃肿
- 太细（每个操作一个子 Agent）→ 主 Agent 路由负担重，Agent 间通信开销大
经验法则：按"专业领域"划分，而不是按"操作步骤"划分。 一个好的子 Agent 应该能用一句话清晰描述其职责，并且它的职责与其他子 Agent 没有明显重叠。
比如"行程规划师"和"当地向导"的边界：规划师负责宏观的多日行程编排（Day1 去哪、Day2 去哪），向导负责微观的即时推荐（这家餐厅值不值得去）。两者互补而不重叠。
7.2 描述字段是路由的灵魂
主 Agent 选择子 Agent 的唯一依据就是 description 字段。一个好的描述应该包含三要素：
- 触发关键词（用户可能使用的词汇）
- 能力边界（做什么，不做什么）
- 典型场景（帮助主 Agent 理解何时该找它）
反面教材："我可以帮你处理旅行相关的事情。"——太空泛，主 Agent 无法精确路由。
正面示例："行程规划专家。负责目的地分析、路线规划、景点推荐和时间分配。当用户需求涉及'规划行程'、'推荐景点'、'路线安排'、'几天怎么玩'时，应委派给此 Agent。不处理机票酒店预订（找 flight-hotel-booker）和即时推荐（找 local-guide）。"
7.3 中间件是成本控制的核心杠杆
在长对话场景中，上下文窗口溢出是一个常见问题。摘要中间件可以在对话达到窗口 85% 时自动生成摘要，将完整历史保存到文件系统，而在上下文中只保留摘要。
配合模型分层策略（大模型做决策，小模型做摘要），可以有效控制 Token 成本。
7.4 弹性降级不是可选项，是必选项
在生产环境中，任何外部依赖都可能失败。ResilientBackend 的设计哲学是：优雅地降级，而不是粗暴地报错。
- 沙箱不可用？→ 本地执行
- MongoDB 不可用？→ 内存存储
- MCP 工具加载失败？→ 空工具列表兜底
每一层都有自己的降级方案，确保系统在任何情况下都能给出响应。
7.5 HITL 要放在对的环节
Human-in-the-Loop 不是越多越好。核心原则：只在不可逆操作前设置人工确认。
- ✅ 订单支付前确认——不可逆，涉及金钱
- ✅ 取消预订前确认——不可逆，影响行程
- ❌ 查询航班时确认——无风险，增加不必要的等待
八、总结
DeepAgents 的多智能体方案在以下几个层面提供了完整的解决思路：
| 维度 | 方案 | 解决的问题 |
|---|---|---|
| 智能体定义 | YAML 声明式配置 | 新增子 Agent 从改代码变成改配置 |
| 运行时编排 | 主从模式 + 动态工具解析 | 主 Agent 自动路由，工具新增无需改配置 |
| 执行环境 | 5 种后端 + 弹性降级 | 安全隔离与高可用并存 |
| 成本控制 | 模型分层 + 差异化中间件 | 按需分配计算资源 |
| 安全保障 | 沙箱隔离 + HITL 审批 | 代码安全执行，关键操作人工确认 |
| 用户体验 | 统一文件系统视图 + 优雅降级 | 用户感知不到后端的复杂性 |
DeepAgents 的设计哲学可以概括为：把复杂性留给框架，把简单性留给开发者。 你只需要用 YAML 描述"这个 Agent 是谁、能做什么"，框架会自动处理工具匹配、上下文管理、后端路由、降级容控这些基础设施层面的事情。
如果你正在构建需要处理多种业务场景的 AI 助手，这份方案的核心建议：
- 让每个 Agent 只做一件事——专业分工是多智能体架构的根基
- 选对后端——执行环境决定了 Agent 能做什么、不能做什么
- 为降级做准备——优雅降级不是锦上添花，而是生产环境的必要设计
本文基于 DeepAgents 框架总结多智能体架构的设计模式与后端选型方案。
作者：Work Hard Work Smart
出处：http://www.cnblogs.com/linlf03/
欢迎任何形式的转载，未经作者同意，请保留此段声明！
浙公网安备 33010602011771号