智能体框架能力

我们将 deepagents 视为一种“智能体框架（agent harness）”。它与其他智能体框架一样采用核心的工具调用循环，但内置了丰富的工具与能力。 本页列出了构成该框架的各个组件。

​

文件系统访问

框架提供六个文件系统工具，使文件成为智能体环境中的一等公民：

​

大型工具结果的驱逐

当工具结果超过设定的 token 阈值时，框架会自动将其写入文件系统，避免上下文窗口被挤满。 工作方式：

• 监控工具返回结果的大小（默认阈值：20,000 tokens）
• 超过阈值时，将结果写入文件
• 在对话中以简明引用替换原有结果
• 智能体可在需要时再读取对应文件

​

可插拔的存储后端

框架将文件系统操作封装在协议之上，可根据场景选择不同存储策略。 可用后端：

1. StateBackend - 内存短暂存储
   • 文件存放在智能体状态中（随对话检查点保存）
   • 在同一线程内持久，但跨线程不保留
   • 适用于临时工作文件
2. FilesystemBackend - 访问真实文件系统
   • 直接读写磁盘
   • 支持虚拟模式（限制在指定根目录内）
   • 集成系统工具（如 ripgrep 用于 grep）
   • 安全特性：路径校验、大小限制、防止危险的符号链接
3. StoreBackend - 跨会话持久存储
   • 使用 LangGraph 的 BaseStore 提供持久化
   • 按 assistant_id 区隔命名空间
   • 文件可跨会话保留
   • 适用于长期记忆或知识库
4. CompositeBackend - 将不同路径路由到不同后端
   • 示例：/ → StateBackend，/memories/ → StoreBackend
   • 基于最长前缀匹配进行路由
   • 实现混合存储策略

​

任务委派（子智能体）

框架允许主智能体创建短生命周期的“子智能体”来处理隔离的多步骤任务。 优势：

• 上下文隔离：子智能体的处理不会污染主智能体的上下文
• 并行执行：可同时运行多个子智能体
• 专长分工：子智能体可拥有不同的工具/配置
• Token 效率：大型子任务的上下文被压缩为单一结果

工作方式：

• 主智能体具备 task 工具
• 调用后创建一个拥有独立上下文的智能体实例
• 子智能体自主执行直至完成
• 返回单一最终报告给主智能体
• 子智能体无状态（不能多次返回消息）

默认子智能体：

• 始终可用的 “general-purpose” 子智能体
• 默认可使用文件系统工具
• 可扩展附加工具/中间件

自定义子智能体：

• 根据具体需求定义带有专用工具的子智能体
• 示例：代码审查、网络调研、测试执行
• 通过 subagents 参数进行配置

​

对话历史摘要

当 token 消耗过高时，框架会自动压缩历史对话。 配置：

• 触发阈值：170,000 tokens
• 保留最近 6 条消息原样
• 更早的消息由模型生成摘要

优势：

• 支持超长对话而不超过上下文限制
• 保留最新上下文，同时压缩久远历史
• 对智能体透明（表现为特殊系统消息）

​

悬空工具调用修复

当工具调用在返回结果前被中断或取消时，框架会修复消息历史。 问题描述：

• 智能体请求工具调用：“Please run X”
• 工具调用被中断（用户取消、报错等）
• 智能体看到 AIMessage 中带有 tool_call，但没有对应的 ToolMessage
• 造成消息序列缺失

解决方案：

• 检测到没有结果的 tool_call 时
• 生成一个表明调用已取消的合成 ToolMessage
• 在智能体继续执行前修复消息历史

优势：

• 避免智能体因不完整的消息链而困惑
• 优雅处理中断与错误
• 保持对话一致性

​

待办清单追踪

框架提供 write_todos 工具，帮助智能体维护结构化任务列表。 功能：

• 追踪多项任务及其状态（pending、in_progress、completed）
• 存储在智能体状态中
• 帮助智能体管理复杂的多步骤工作
• 适用于长时间运行的任务与规划

​

人在回路

框架可在指定工具调用处暂停执行，等待人工审批或修改。 配置：

• 将工具名称映射到中断配置
• 示例：{"edit_file": True} 表示每次编辑前暂停
• 支持提供审批意见或修改工具输入

优势：

• 为破坏性操作提供安全门
• 在执行高成本 API 调用前进行确认
• 支持交互式调试与指导

​

提示缓存（Anthropic）

框架支持 Anthropic 的提示缓存功能，减少重复的 token 处理。 工作方式：

• 缓存对话中重复出现的提示片段
• 显著降低长系统提示的延迟与成本
• 自动忽略非 Anthropic 模型

优势：

• 系统提示（尤其是包含文件系统说明时）可能超过 5k tokens
• 若无缓存，每轮对话都会重复发送
• 启用缓存后可获得约 10 倍的提速与成本下降

---