type
Post
status
Published
date
Mar 28, 2026
slug
deepagents-002
summary
DeepAgents 框架核心（2）
tags
Agent
category
DeepAgents
icon
password
😀
 

一、DeepAgents 框架核心（2）

1.6 兼容Langgraph和Langchain

LangChain 生态下的其他 Agent（比如 AgentExecutor、ReActAgent、StructuredChatAgent 等）可以挂载为 DeepAgents 的子代理，但不能直接挂 —— 需要先把这些 Agent 封装成「符合 LangGraph StateGraph 规范的图」（核心是状态里包含 messages 键），再用 CompiledSubAgent 封装。
简单说：DeepAgents 认的是「LangGraph 格式的图」，不是直接认 LangChain Agent；但所有 LangChain Agent 都能转成 LangGraph 图，所以最终都能挂。
兼容Langgraph编译图
  1. DeepAgents 子代理的 “准入门槛”
      2. DeepAgents 调度子代理的核心要求只有一个：子代理的执行逻辑必须是**「带有 messages 键的状态图」**（不管这个图是直接用 StateGraph 写的，还是从其他 Agent 转来的）。这个 messages 键就是你之前看 result 结构时的核心字段 ——DeepAgents 靠它传递对话、工具调用、执行结果，没有这个键就无法和主代理通信。
  1. 演示LangGraph格式图挂载
兼容Langchain单智能体

1.7 流程人机交互 (HITL)

https://docs.langchain.com/oss/python/deepagents/human-in-the-loop
有些工具作可能比较敏感，需要人工批准才能执行。深度代理通过 LangGraph 的中断功能支持人机参与的工作流程。您可以使用 interrupt_on 参数配置哪些工具需要批准。
notion image

1.7.1 交互步骤说明

步骤1：设置tool是否进行人工互动
根据不同工具的风险等级配置
步骤2：配置检查点
人工互动需要一个检查点，在中断和恢复之间保持代理状态：
步骤3：设置相同的thead_id
恢复时，必须使用相同的配置和相同的 thread_id
步骤4：行动决策配置
决策列表必须符合以下 action_requests 顺序：
字段
含义
action_requests
需要审批的操作列表（如删库 delete_database、删文件 delete_file），包含操作名、参数、风险描述! {'action_requests': [{'name': 'delete_table', 'args': {'tablename': 'users'}, 'description': "描述"}
review_configs
允许的审批操作（approve 同意 /reject 拒绝 /edit 编辑参数）
id
中断会话唯一标识（确保恢复时匹配同一个会话）

1.7.2 中断交互

当代理调用多个需要批准的工具时，所有中断都会被批量处理成一个中断。必须按顺序为每个动作提供决策

1.7.3 编辑参数

结合之前的删库 / 删文件场景，编写完整的「edit 审批处理」代码，包含参数编辑、多操作编辑、执行验证等核心逻辑，注释清晰可直接运行：

1.8 后端存储 (Backends)

https://docs.langchain.com/oss/python/deepagents/backends
DeepAgents 的 Backend 系统是为 Agent 构建的 “虚拟文件系统”，核心作用是定义 Agent 生成文件的最终存储位置，也是实现跨线程数据共享、落地长期记忆能力的核心载体。
notion image
核心机制：
  1. 被动触发逻辑：Backend 仅在 Agent 主动调用文件操作工具（如 write_file、edit_file、read_file）时才会被激活。需注意的是，Agent 的思考过程、对话上下文等临时状态仅存储在内存（State）中，不会自动写入 Backend，只有显式执行文件操作的内容才会进入该系统。
  1. 路径映射规则：Agent 操作的所有文件均基于 “虚拟路径”（如 /report.txt、/store/memory.txt），Backend 会按照预设规则将这些虚拟路径映射到实际物理存储介质 —— 比如本地硬盘、Redis 数据库、内存等，实现 “虚拟路径” 到 “物理存储” 的无感转换。
存储行为对照表：
行为
Backend 是否存储
存储位置
Agent 说："你好"
否
仅在当前对话内存 (State)
Agent 思考过程
否
仅在当前对话内存 (State)
Agent 调用 write_file("a.txt", "内容")
是
Backend (硬盘/数据库)

1.8.1 后端类型概览

DeepAgents 提供了四种标准的后端实现，适用于不同的开发和生产场景：
后端类型
存储介质
适用场景
类比
StateBackend (默认)
内存 (State)
临时文件、中间运算结果。会话结束即销毁。
浏览器的“无痕模式”
FilesystemBackend
本地硬盘
本地开发、调试、需要直接查看生成文件的场景。
电脑的本地磁盘
StoreBackend
数据库 (KV Store)
生产环境、跨 Agent 共享数据、持久化记忆 (Redis/Postgres)。
云盘 (iCloud/OneDrive)
CompositeBackend
混合存储
生产环境最佳实践。区分“临时文件”和“重要记忆”。
系统盘 (C盘) + 数据盘 (D盘)

1.8.2 本地文件存储 (FilesystemBackend)

场景描述： 在本地开发或调试时，我们希望 Agent 生成的文件直接出现在项目文件夹中，方便开发者查看和验证。FilesystemBackend 将 Agent 的虚拟路径直接映射到宿主机的物理文件系统。
功能特点：
  • 直观可见：生成的文件可以直接在 IDE 或文件管理器中打开。
  • 安全隔离：推荐开启 virtual_mode=True，将 Agent 限制在指定的工作目录（root_dir）内，防止越权访问系统敏感文件。
代码示例：

1.8.3 数据库/内存存储 (StoreBackend)

场景描述： 在生产环境或分布式系统中，文件不适合存储在本地磁盘。StoreBackend 利用 LangGraph 的 Store 机制，将文件内容作为 Key-Value 数据存储在数据库（如 Redis、Postgres）或内存中。这对于实现跨线程记忆共享至关重要。
功能特点：
  • 持久化：配合 RedisStore 可实现数据持久保存。
  • 共享性：不同线程（Thread）甚至不同 Agent 可以通过访问同一个 Store 来共享数据。
  • 适配器模式：StoreBackend 充当适配器，将文件操作转换为 KV 存储操作。
代码示例：

1.8.4 混合存储策略 (CompositeBackend)

场景描述： 这是最灵活且推荐的生产环境配置。CompositeBackend 允许你根据文件路径的前缀，将文件路由到不同的后端。例如，将临时文件存本地，将重要记忆存数据库。
配置逻辑：
  • 默认路由 (Default)：处理普通路径，通常映射到 FilesystemBackend（本地）或 StateBackend（临时）。
  • 特定路由 (Routes)：处理特定前缀路径（如 /store/），映射到 StoreBackend（数据库）。
代码示例：

1.9 Middleware 核心概念

Middleware 是 DeepAgents 的「流程拦截器」，可以在 Agent 执行的关键生命周期节点（如工具调用前 / 后、思考完成后、回复生成前）插入自定义逻辑，实现：
  • 操作日志记录
  • 权限校验 / 参数过滤
  • 工具调用结果修改
  • 异常捕获 / 兜底处理
  • 自定义监控 / 告警
案例实现一个中间件，进行日志输出：
  1. 工具调用前日志：记录调用的工具名和参数；
  1. 工具调用后日志：记录工具执行结果和耗时。
@wrap_tool_call实现

1.10 Agent Skills (技能扩展)

DeepAgents 提供的 Skills（技能） 机制，是为智能体（Agent）注入领域知识与专业能力的核心方式。Skills 本质是可复用、可插拔的 “能力包”，核心由指令文档（SKILL.md）及配套资源构成，能让 Agent 在运行过程中，根据任务场景的实际需求动态加载、调用对应的技能知识，无需修改 Agent 核心逻辑即可快速扩展专业能力。
https://skillsmp.com/zh
核心概念：
  • SKILL.md：技能的核心描述文件，是 Agent 学习和使用该技能的 “说明书”。文件整体分为两部分 —— 头部的元数据（Frontmatter）（以 YAML 格式定义 定义name 和 description）和正文的具体指令（以 Markdown 格式编写），Agent 会通过解析该文件掌握技能的使用方法、适用场景及操作流程。
  • 渐进式披露：Skills 机制的核心优化策略，用于解决大模型上下文窗口有限的问题。Agent 启动时仅读取所有技能的元数据（轻量信息，占用极少上下文），仅记录 “技能名称、适用场景、触发关键词” 等基础信息；只有当用户任务匹配某一技能的触发条件时，Agent 才会加载该技能的详细指令内容，有效避免无关信息占用上下文，提升任务执行效率。
notion image
标准技能目录结构：
一个完整的 DeepAgents 技能包遵循标准化的文件目录结构，不同文件各司其职，确保技能可复用、易维护，典型结构如下：
各文件 / 目录的具体功能：
  1. SKILL.md（必选）
      2. 技能的核心载体，是 Agent 唯一需要解析的文件，典型结构如下：
  1. requirements.txt（可选）
      2. 声明技能运行所需的第三方依赖包及版本，例如：
      作用：部署技能时可一键安装依赖，避免因环境缺失导致技能执行失败。
  1. resources/（可选）
      2. 存放技能配套的静态资源，按用途细分：
      • template/：存放各类模板文件，如 “数据清洗报告模板.md”“财务报表模板.xlsx”，Agent 可调用模板快速生成标准化输出；
      • examples/：存放技能使用示例，如 “原始数据示例.csv”“清洗后数据示例.csv”，帮助 Agent 理解技能的预期输入 / 输出；
      • config/：存放配置文件（如 JSON/YAML 格式），如 “数据清洗规则.json”，定义固定规则（如日期格式、字段映射），避免硬编码在 SKILL.md 中。
  1. scripts/（可选）
      2. 存放技能配套的辅助脚本，封装复杂逻辑或工具调用细节，例如：
      • helper.py：编写 fill_missing_value() 函数封装缺失值填充逻辑，SKILL.md 中只需调用该函数，无需写完整代码；
      • 脚本可被 Agent 调用的工具函数引用，简化 SKILL.md 中的指令复杂度，提升技能执行效率。
补充说明
  • 技能包的核心是 SKILL.md，其余文件均为辅助，可根据技能复杂度选择是否添加；
  • 所有文件需遵循 “轻量化” 原则，尤其是 SKILL.md 的详细指令部分，避免内容过长导致上下文超限；
  • 技能包支持动态加载 / 卸载，可通过 DeepAgents 的 API 将技能注册到 Agent，也可在运行时移除无需使用的技能。
SKILL.md 标准格式示例： 文件路径：base/skills/code-reviewer/SKILL.md
代码示例：加载外部 Skills 文件
关键点：
  1. 物理存储：将 SKILL.md 存放在实际的文件目录中 (base/skills/code-reviewer/)
  1. FilesystemBackend：使用 FilesystemBackend 将本地目录挂载到 Agent 的虚拟文件系统中。
  1. Skills 路径映射：skills=["skills"] 指向的是虚拟路径，Agent 会通过 Backend 自动映射到物理路径。

📎 参考文章

  • 一些引用
  • 引用文章
 
💡
欢迎您在底部评论区留言，一起交流~
上一篇
第一节　大脑：重新认识你自己
下一篇
Harness Engineering - 搭建Mini Harness
Loading...
Invalid Date