Skip to main content
代理框架是多种不同能力的组合，使得构建长期运行的代理变得更加容易： 除了这些能力，深度代理还使用技能和记忆来提供额外的上下文和指令。

​
规划能力

框架提供了一个 write_todos 工具，代理可以用它来维护结构化的任务列表。 特性：
  • 跟踪多个任务及其状态（'pending'、'in_progress'、'completed'）
  • 持久化存储在代理状态中
  • 帮助代理组织复杂的多步骤工作
  • 适用于长期运行的任务和规划

​
虚拟文件系统访问

框架提供了一个可配置的虚拟文件系统，可以由不同的可插拔后端支持。 后端支持以下文件系统操作：
工具描述
ls列出目录中的文件及其元数据（大小、修改时间）
read_file读取文件内容并显示行号，支持对大文件进行偏移/限制读取。也支持读取图像（.png、.jpg、.jpeg、.gif、.webp），将其作为多模态内容块返回。
write_file创建新文件
edit_file在文件中执行精确的字符串替换（支持全局替换模式）
glob查找匹配模式的文件（例如 **/*.py）
grep搜索文件内容，支持多种输出模式（仅文件、带上下文的内容或计数）
execute在环境中运行 shell 命令（仅在沙盒后端中可用）
虚拟文件系统被框架的其他多个能力所使用，例如技能、记忆、代码执行和上下文管理。 在构建深度代理的自定义工具和中间件时，你也可以使用文件系统。 更多信息，请参阅后端。

​
任务委派（子代理）

框架允许主代理为隔离的多步骤任务创建临时的“子代理”。 为何有用：
  • 上下文隔离 - 子代理的工作不会干扰主代理的上下文
  • 并行执行 - 多个子代理可以并发运行
  • 专业化 - 子代理可以拥有不同的工具/配置
  • 令牌效率 - 大型子任务上下文被压缩为单个结果
工作原理：
  • 主代理拥有一个 task 工具
  • 调用时，它会创建一个具有独立上下文的新代理实例
  • 子代理自主执行直至完成
  • 向主代理返回一份最终报告
  • 子代理是无状态的（无法发送多条消息）
默认子代理：
  • 自动可用的“通用”子代理
  • 默认拥有文件系统工具
  • 可以通过额外的工具/中间件进行自定义
自定义子代理：
  • 定义具有特定工具的专业化子代理
  • 示例：代码审查员、网络研究员、测试运行器
  • 通过 subagents 参数配置

​
上下文管理

框架管理上下文，使得深度代理能够在令牌限制内处理长期运行的任务，同时保留所需的信息。 工作原理：
  • 输入上下文 — 系统提示、记忆、技能和工具提示塑造了代理启动时的认知
  • 压缩 — 内置的卸载和摘要功能在任务进行时保持上下文在窗口限制内
  • 隔离 — 子代理隔离繁重工作并仅返回结果（参见任务委派）
  • 长期记忆 — 通过虚拟文件系统实现跨线程的持久存储
为何有用：
  • 支持超出单个上下文窗口的多步骤任务
  • 保持最相关信息在范围内，无需手动修剪
  • 通过自动摘要和卸载减少令牌使用量
配置详情，请参阅上下文工程。

​
代码执行

当你使用沙盒后端时，框架会暴露一个 execute 工具，允许代理在隔离环境中运行 shell 命令。这使得代理能够安装依赖、运行脚本并执行代码作为其任务的一部分。 工作原理：
  • 沙盒后端实现了 SandboxBackendProtocol — 当检测到时，框架会将 execute 工具添加到代理的可用工具中
  • 没有沙盒后端时，代理仅拥有文件系统工具（read_file、write_file 等）且无法运行命令
  • execute 工具返回合并的 stdout/stderr、退出码，并截断大输出（保存到文件供代理增量读取）
为何有用：
  • 安全性 — 代码在隔离环境中运行，保护你的主机系统免受代理操作的影响
  • 干净环境 — 使用特定的依赖或操作系统配置，无需本地设置
  • 可重现性 — 跨团队的一致执行环境
关于设置、提供商和文件传输 API，请参阅沙盒。

​
人在回路

框架可以在指定的工具调用处暂停代理执行，以允许人工批准或修改。此功能通过 interrupt_on 参数选择启用。 配置：
  • 将 interrupt_on 传递给 create_deep_agent，并提供一个工具名到中断配置的映射
  • 示例：interrupt_on={"edit_file": True} 会在每次编辑前暂停
  • 提示时，你可以提供批准消息或修改工具输入
为何有用：
  • 为破坏性操作设置安全门
  • 在昂贵的 API 调用前进行用户验证
  • 交互式调试和指导

​
技能

框架支持技能，为你的深度代理提供专业化的工作流程和领域知识。 工作原理：
  • 技能遵循 Agent Skills 标准
  • 每个技能是一个包含 SKILL.md 文件的目录，其中包含指令和元数据
  • 技能可以包含额外的脚本、参考文档、模板和其他资源
  • 技能使用渐进式披露 — 仅当代理确定它们对当前任务有用时才加载
  • 代理在启动时读取每个 SKILL.md 文件的前置元数据，然后在需要时查看完整的技能内容
为何有用：
  • 仅在需要时加载相关技能，减少令牌使用量
  • 将能力捆绑成具有额外上下文的更大操作
  • 提供专业化知识，而不会使系统提示变得杂乱
  • 支持模块化、可重用的代理能力
更多信息，请参阅技能。

​
记忆

框架支持持久性记忆文件，为你的深度代理在跨对话中提供额外的上下文。 这些文件通常包含通用的编码风格、偏好、惯例和指南，帮助代理理解如何与你的代码库协作并遵循你的偏好。 工作原理：
  • 使用 AGENTS.md 文件 提供持久上下文
  • 记忆文件总是被加载（与使用渐进式披露的技能不同）
  • 创建代理时，将一个或多个文件路径传递给 memory 参数
  • 文件存储在代理的后端（StateBackend、StoreBackend 或 FilesystemBackend）
  • 代理可以根据你的交互、反馈和识别出的模式更新记忆
为何有用：
  • 提供持久上下文，无需每次对话重新指定
  • 适用于存储用户偏好、项目指南或领域知识
  • 始终对代理可用，确保行为一致
配置详情和示例，请参阅记忆。
Edit this page on GitHub or file an issue.
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.