代理能力框架是多种不同能力的组合，旨在简化构建长期运行的代理 除这些能力外，深度代理还使用技能和记忆来获取额外的上下文和指令。文档索引
在以下地址获取完整的文档索引：https://docs.langchain.org.cn/llms.txt
在进一步探索之前，请使用此文件发现所有可用页面。
规划能力
能力框架提供了一个write_todos 工具，代理可以使用它来维护结构化的任务列表。 特点：- 跟踪多个任务及其状态（
'pending'、'in_progress'、'completed'） - 持久化在代理状态中
- 帮助代理组织复杂的、多步骤的工作
- 对长期运行的任务和规划很有用
虚拟文件系统访问
能力框架提供了一个可配置的虚拟文件系统，它可以由不同的可插拔后端支持。这些后端支持以下文件系统操作：| 工具 | 描述 |
|---|---|
ls | 列出目录中的文件及其元数据（大小、修改时间） |
read_file | 读取文件内容（带行号），支持大文件的偏移/限制。还支持返回非文本文件（图像、视频、音频和文档）的多模态内容块。请参阅下面的支持扩展名。 |
write_file | 创建新文件 |
edit_file | 在文件中执行精确的字符串替换（支持全局替换模式） |
glob | 查找匹配模式的文件（例如，**/*.py） |
grep | 以多种输出模式搜索文件内容（仅文件、带上下文的内容或计数） |
execute | 在环境中运行 shell 命令（仅适用于沙盒后端） |
支持的多模态文件扩展名
支持的多模态文件扩展名
文件系统权限
能力框架支持声明式权限规则，这些规则控制代理可以读取或写入哪些文件和目录。权限适用于上面列出的内置文件系统工具，并按声明顺序评估，采用首次匹配优先的语义。 工作原理：- 在创建代理时，将规则列表传递给
permissions= - 每个规则指定
operations("read","write")、paths(glob 模式) 和mode("allow"或"deny") - 第一个匹配的规则获胜。如果没有规则匹配，则允许该操作。
- 将代理限制到特定目录（例如，
/workspace/） - 保护敏感文件（例如，
.env、凭据） - 赋予子代理比父代理更窄的访问权限
execute 工具支持任意命令执行。对于自定义验证逻辑，请使用后端策略钩子。 有关完整的规则结构、示例和子代理继承，请参阅权限。任务委托（子代理）
能力框架允许主代理创建临时的“子代理”以执行独立的多步骤任务。 为什么它有用：- 上下文隔离 - 子代理的工作不会使主代理的上下文变得混乱
- 并行执行 - 多个子代理可以同时运行
- 专业化 - 子代理可以拥有不同的工具/配置
- 令牌效率 - 大型子任务上下文被压缩成单一结果
- 主代理有一个
task工具 - 被调用时，它会创建一个具有自己上下文的全新代理实例
- 子智能体自主执行直到完成
- 向主代理返回一份最终报告
- 子代理是无状态的（不能发送多条消息回来）
- “通用”子代理自动可用
- 默认具有文件系统工具
- 可以通过额外的工具/中间件进行定制
- 定义具有特定工具的专业子代理
- 示例：代码评审员、网络研究员、测试运行器
- 通过
subagents参数进行配置
不使用子代理运行（无 `task` 工具）
不使用子代理运行（无 `task` 工具）
上下文管理
能力框架管理上下文，因此深度代理可以在令牌限制内处理长期运行的任务，同时保留所需的信息。 工作原理：- 输入上下文 — 系统提示、记忆、技能和工具提示塑造了代理启动时所知的信息
- 压缩 — 内置的卸载和摘要功能在任务进行过程中将上下文保持在窗口限制内
- 隔离 — 子代理隔离繁重的工作并只返回结果（参见任务委托）
- 长期记忆 — 通过虚拟文件系统在线程之间进行持久存储
- 启用超出单个上下文窗口的多步骤任务
- 在不手动修剪的情况下，将最相关的信息保持在范围内
- 通过自动摘要和卸载减少令牌使用
代码执行
当您使用沙盒后端时，能力框架会暴露一个execute 工具，允许代理在隔离环境中运行 shell 命令。这使得代理能够安装依赖项、运行脚本并执行代码作为其任务的一部分。 工作原理：- 沙盒后端实现
SandboxBackendProtocolV2— 检测到后，能力框架会将execute工具添加到代理的可用工具中 - 没有沙盒后端时，代理只有文件系统工具（
read_file、write_file等），无法运行命令 execute工具返回组合的 stdout/stderr、退出码，并截断大输出（将其保存到文件供代理逐步读取）
- 安全性 — 代码在隔离环境中运行，保护您的主机系统免受代理操作的影响
- 清洁环境 — 使用特定的依赖项或操作系统配置，无需本地设置
- 可重现性 — 团队之间一致的执行环境
人工干预
能力框架可以在指定的工具调用处暂停代理执行，以允许人工批准或修改。此功能通过interrupt_on 参数选择启用。 配置：- 将
interrupt_on传递给create_deep_agent，其中包含工具名称到中断配置的映射 - 示例：
interrupt_on={"edit_file": True}会在每次编辑前暂停 - 您可以在提示时提供批准消息或修改工具输入
- 破坏性操作的安全门
- 在昂贵的 API 调用前进行用户验证
- 交互式调试和指导
技能
能力框架支持为您的深度代理提供专业工作流和领域知识的技能。 工作原理：- 技能遵循代理技能标准
- 每个技能都是一个目录，包含一个带有指令和元数据的
SKILL.md文件 - 技能可以包含额外的脚本、参考文档、模板和其他资源
- 技能采用渐进式披露——只有当代理认为它们对当前任务有用时才会被加载
- 代理在启动时读取每个
SKILL.md文件的元数据，然后在需要时查阅完整的技能内容
- 只在需要时加载相关技能，减少令牌使用
- 将能力与额外上下文捆绑成更大的操作
- 提供专业知识，而不会使系统提示混乱
- 实现模块化、可重用的代理能力
内存
能力框架支持持久性记忆文件，这些文件在会话之间为您的深度代理提供额外的上下文。这些文件通常包含通用的编码风格、偏好、约定和指南，帮助代理理解如何与您的代码库协作并遵循您的偏好。 工作原理：- 使用
AGENTS.md文件提供持久性上下文 - 记忆文件总是被加载的（与技能不同，技能采用渐进式披露）
- 在创建代理时，将一个或多个文件路径传递给
memory参数 - 文件存储在代理的后端中（StateBackend、StoreBackend 或 FilesystemBackend）
- 代理可以根据您的交互、反馈和识别出的模式更新记忆
- 提供持久性上下文，无需在每次对话中重新指定
- 对于存储用户偏好、项目指南或领域知识很有用
- 始终可供代理使用，确保行为一致
能力框架配置文件
每当选择给定的提供商或模型时，能力框架都可以应用声明式配置包（HarnessProfile）。配置文件可以在模型构建后调整运行时行为，而无需为每个代理编写设置代码。 工作原理：- 在提供商名称 (
"openai") 或provider:model键 ("openai:gpt-5.4") 下注册配置文件 create_deep_agent在解析模型时查找并应用配置文件- 提供商级别和模型级别配置文件在解析时合并
- 将每个提供商或每个模型的默认设置（系统提示调整、工具覆盖、中间件）打包在一个地方
- 在切换模型时保持
create_deep_agent调用站点不变 - 通过入口点以插件形式发布可重用配置文件
将这些文档连接到 Claude、VSCode 等，以获得实时答案。