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