Agent框架功能
我们将deepagents视为一个“Agent框架”。它与其他Agent框架具有相同的核心工具调用循环，但具有内置的工具和功能。
本页列出了构成Agent框架的组件。
文件系统访问
该框架提供了六种用于文件系统操作的工具，使文件成为Agent环境中一流的公民：
| 工具 | 描述 |
|---|---|
ls | 列出目录中的文件及其元数据（大小、修改时间） |
read_file | 读取带行号的文件内容，支持大文件的偏移/限制 |
write_file | 创建新文件 |
edit_file | 在文件中执行精确的字符串替换（具有全局替换模式） |
glob | 查找与模式匹配的文件（例如，**/*.py） |
grep | 使用多种输出模式搜索文件内容（仅文件、带上下文的内容或计数） |
大型工具结果逐出
当工具结果超过令牌阈值时，该框架会自动将其转储到文件系统，从而防止上下文窗口饱和。
工作原理：
- 监控工具调用结果的大小（默认阈值：20,000 个令牌）
- 超过时，将结果写入文件
- 将工具结果替换为对该文件的简洁引用
- Agent稍后可以在需要时读取该文件
可插拔存储后端
该框架将文件系统操作抽象在一个协议之后，允许针对不同的用例采用不同的存储策略。
可用后端：
StateBackend - 短暂的内存存储
- 文件存在于Agent的状态中（与对话一起检查点）
- 在一个线程内持久存在，但不能跨线程
- 对于临时工作文件很有用
FilesystemBackend - 真实的文件系统访问
- 从实际磁盘读取/写入
- 支持虚拟模式（沙盒化到根目录）
- 与系统工具集成（用于 grep 的 ripgrep）
- 安全功能：路径验证、大小限制、符号链接预防
StoreBackend - 持久的跨对话存储
- 使用 LangGraph 的 BaseStore 实现持久性
- 按 assistant_id 命名空间
- 文件在对话之间持久存在
- 对于长期记忆或知识库很有用
CompositeBackend - 将不同的路径路由到不同的后端
- 示例：
/→ StateBackend，/memories/→ StoreBackend - 用于路由的最长前缀匹配
- 支持混合存储策略
- 示例：
任务委托（子Agent）
该框架允许主Agent为隔离的多步骤任务创建短暂的“子Agent”。
为什么它很有用：
- 上下文隔离 - 子Agent的工作不会弄乱主Agent的上下文
- 并行执行 - 多个子Agent可以同时运行
- 专业化 - 子Agent可以有不同的工具/配置
- 令牌效率 - 大型子任务上下文被压缩成单个结果
工作原理：
- 主Agent有一个
task工具 - 调用时，创建一个具有自己上下文的全新Agent实例
- 子Agent自主执行直到完成
- 向主Agent返回单个最终报告
- 子Agent是无状态的（不能发回多个消息）
默认子Agent：
- “通用”子Agent自动可用
- 默认情况下具有文件系统工具
- 可以使用其他工具/中间件进行自定义
自定义子Agent：
- 定义具有特定工具的专用子Agent
- 示例：代码审查员、网络研究员、测试运行员
- 通过
subagents参数进行配置
对话历史摘要
当令牌使用量过大时，该框架会自动压缩旧的对话历史。
配置：
- 在 170,000 个令牌时触发
- 保持最近的 6 条消息不变
- 较早的消息由模型进行摘要
为什么它很有用：
- 支持非常长的对话而不会达到上下文限制
- 在压缩古老历史的同时保留最近的上下文
- 对Agent透明（显示为特殊的系统消息）
悬空工具调用修复
当工具调用在收到结果之前被中断或取消时，该框架会修复消息历史。
问题：
- Agent请求工具调用：“请运行 X”
- 工具调用被中断（用户取消、错误等）
- Agent在 AIMessage 中看到 tool_call 但没有相应的 ToolMessage
- 这会创建一个无效的消息序列
解决方案：
- 检测没有结果的带有 tool_calls 的 AIMessages
- 创建合成的 ToolMessage 响应，指示调用已被取消
- 在Agent执行之前修复消息历史
为什么它很有用：
- 防止Agent因不完整的消息链而混淆
- 优雅地处理中断和错误
- 保持对话连贯性
待办事项列表跟踪
该框架提供了一个write_todos工具，Agent可以使用它来维护一个结构化的任务列表。
功能：
- 跟踪具有状态（待处理、进行中、已完成）的多个任务
- 持久化在Agent状态中
- 帮助Agent组织复杂的多步骤工作
- 对于长时间运行的任务和规划很有用
人在回路
该框架在指定的工具调用处暂停Agent执行，以允许人工批准/修改。
配置：
- 将工具名称映射到中断配置
- 示例：
{"edit_file": True}- 在每次编辑前暂停 - 可以提供批准消息或修改工具输入
为什么它很有用：
- 破坏性操作的安全门
- 在昂贵的 API 调用之前进行用户验证
- 交互式调试和指导
提示缓存 (Anthropic)
该框架启用了 Anthropic 的提示缓存功能，以减少冗余的令牌处理。
工作原理：
- 缓存跨轮次重复的提示部分
- 显着减少长系统提示的延迟和成本
- 对于非 Anthropic 模型自动跳过
为什么它很有用：
- 系统提示（尤其是带有文件系统文档的）可能超过 5k 个令牌
- 这些在没有缓存的情况下每轮都会重复
- 缓存可提供约 10 倍的速度提升和成本降低