Notes

Appearance

DeepAgents 框架概览与设计理念 ​

imagedeep_agents 是一个专为构建生产级、多智能体（Multi-Agent）与有状态 AI 工作流打造的 Python 核心 SDK。它完全对标 TypeScript 生态的 deepagents 框架，为 Python 开发者提供了开箱即用的高并发任务委派、虚拟沙箱、SOP 技能注入、长期记忆持久化、结构化任务跟踪与防溢出上下文裁剪能力。

核心设计哲学 ​

传统的 Agent 框架（如简单 Prompt + ReAct）在面对复杂多步骤任务时，常面临以下四大痛点：

  1. Token 溢出与历史崩溃：对话工具调用过多导致 Context Exceeded。
  2. 缺乏状态可追踪性：外部程序无法获取 Agent 当前处理到第几步。
  3. 权限与越权风控：Agent 自由读写本地任意磁盘文件带来安全隐患。
  4. 串行阻塞低效：主 Agent 一个一个委派子 Agent，效率极低。

deep_agents 框架通过**“底层图引擎 + 插件化中间件 + 高并发调度器”**的三层解耦架构彻底解决了上述问题。

整体架构视图 ​

text
+-----------------------------------------------------------------------+
|                    DeepAgents 应用层 (如 Deep Research)                 |
+-----------------------------------------------------------------------+
                                  |
                                  v
+-----------------------------------------------------------------------+
|                       DeepAgents Core 引擎                            |
|  - create_agent (ReAct 思考图 + 自动防溢出 + 两阶段格式化)              |
|  - create_subagent_tools (单步委派 + asyncio.gather 高并发并行调度)    |
+-----------------------------------------------------------------------+
                                  |
        +-------------------------+-------------------------+
        |                                                   |
        v                                                   v
+------------------------------------+    +------------------------------------+
|       Middlewares 中间件插件库       |    |          Tools 基础工具库          |
|  - fs: 虚拟沙箱与 RBAC 权限控制    |    |  - python_repl: REPL 代码沙箱      |
|  - skills: SOP 技能动态注入器       |    |  - web_search: 博查搜索引擎       |
|  - memory: AGENTS.md 长期记忆持久化 |    +------------------------------------+
|  - todo: 结构化 Task 拆解与追踪器   |
|  - context: 智能上下文滑动窗裁切    |
|  - logger: 全链路 Trace 结构化日志  |
+------------------------------------+

六大核心特性亮点 ​

  1. ⚡ 高并发 Map-Reduce 调度 内置 delegate_tasks_parallel 调度器，底层基于 Python 原生 asyncio.gather，支持主 Agent 在单次思考中并行拉起多个调研员子 Agent，效率提升 60%+。

  2. 🛡️ 虚拟沙箱与 RBAC 权限策略 绝对隔离真实物理文件系统。支持针对不同的 Agent 配置 read / write / deny 细粒度权限白名单，防止越权写入或穿越。

  3. 📚 SOP 技能库动态加载 自动解析 .agents/skills/ 目录下的 Markdown 技能指南，生成标准 XML 元数据并注入 System Prompt。主 Agent 仅在需要时按需调用工具读取 SOP 指南。

  4. 🧠 AGENTS.md 长期记忆 自动在会话启动时恢复 /AGENTS.md 记忆文件，并指导 Agent 在收到用户“请记住...”指令时，使用沙箱工具增量更新记忆。

  5. 📋 结构化 Task 进度暴露 彻底告别纯文本 Prompt 的虚假步骤。提供闭包 API get_todos()，随时向 UI 前端暴露标准的 [{content, status}] 任务进度状态。

  6. ✂️ 智能上下文滑窗裁切 在 ReAct 思考循环中自动识别并保护顶部系统 Prompt、技能书与记忆，仅滑动裁切过长历史对话，彻底告别 Token 溢出报错。