核心能力

https://docs.langchain.com/oss/python/deepagents/harness

核心能力

Deep Agents 框架提供了四类内置功能，使构建长期运行、可靠的代理变得更加容易：

• 执行环境工具、虚拟文件系统、可选沙箱和 REPL（解释器）
• 上下文管理技能、记忆、摘要、上下文卸载和提示缓存
• 代表团子代理生成和任务规划
• 转向人机交互审批和中断

除了这四个组件之外，线束配置文件还允许您将每个模型的配置打包成可重用的捆绑包。

执行环境

执行环境是智能体执行操作的地方。它由四层组成：

• ​**工具**：代理可以调用​​的自定义函数、API 和数据库
• ​**虚拟文件系统**：由可插拔后端支持的文件工具
• ​**文件系统权限**：对代理可以读取或写入哪些路径的声明式访问控制
• ​**代码执行**：沙盒 shell 执行和进程内 JavaScript 解释器

工具

​create_deep_agent​通过参数传递任何 Python 可调用对象、LangChain 工具或工具字典tools=。这些是您的代理可以执行的特定领域操作——网络搜索、数据库查询、API 调用或您定义的任何函数。

from deepagents import create_deep_agent

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    tools=[search, fetch_page, run_query],
)

有关定义和使用工具的更多信息，请参阅“工具”部分。

虚拟文件系统访问

该框架提供了一个可配置的虚拟文件系统，可由不同的可插拔后端提供支持。这些后端支持以下文件系统操作：

支持的多模态文件类型

要对模型隐藏上面列出的文件系统工具，请注册一个工具配置文件​excluded_tools：

from deepagents import HarnessProfile, register_harness_profile

register_harness_profile(
    "anthropic:claude-sonnet-4-6",
    HarnessProfile(
        excluded_tools=frozenset(
            {"ls", "read_file", "write_file", "edit_file", "glob", "grep"}
        ),
    ),
)

故意拒绝通过这种方式移除FilesystemMiddleware​自身——请使用此方法仅隐藏模型可见的工具界面，并保留中间件。要移除该工具，请参阅“不使用子代理运行”。excluded_middleware`excluded_tools`task

虚拟文件系统被其他多种功能所利用，例如技能、内存、代码执行和上下文管理。您也可以在为 Deep Agents 构建自定义工具和中间件时使用该文件系统。

有关更多信息，请参阅后端。

文件系统权限

该框架支持声明式权限规则，用于控制代理可以读取或写入哪些文件和目录。权限适用于上述内置文件系统工具，并按声明顺序进行评估，遵循“先匹配获胜”的语义。工作原理：

• ​permissions=创建代理时，传递一个规则列表。
• 每条规则都指定了operations​（"read"​，"write"​），paths​（全局模式），以及mode​（"allow"​或"deny"）
• 第一个匹配的规则生效。如果没有匹配的规则，则允许该操作。

它的优势在于：

• 限制代理只能访问特定目录（例如，/workspace/）
• 保护敏感文件（例如.env，凭据）
• 赋予子代理比父代理更窄的访问权限

权限限制不适用于沙盒后端，沙盒后端支持通过该execute​工具执行任意命令。如需自定义验证逻辑，请使用后端策略钩子。有关完整的规则结构、示例和子代理继承，请参阅“权限”。

代码执行

Deep Agents支持两种代码执行方式：

• 沙箱后端提供了一个execute用于在隔离环境中执行 shell 命令的工具。
• 解释器添加了一个eval工具，该工具可以在限定作用域的 QuickJS 运行时环境中运行 JavaScript。

当代理需要安装依赖项、运行测试、调用命令行界面 (CLI) 或操作操作系统文件系统时，请使用沙箱后端。沙箱后端实现了相关功能SandboxBackendProtocolV2​；检测到后，该工具会被添加execute​到代理的可用工具列表中。当代理需要一个轻量级的可编程层来进行循环、批处理、确定性数据转换或程序化工具调用时，可以使用解释器。解释器不提供 shell 访问、软件包安装或文件系统和网络访问。有关沙箱设置、提供程序和文件传输 API 的信息，请参阅“沙箱”部分。有关 QuickJS 运行时和程序化工具调用的信息，请参阅“解释器”部分。

上下文管理

上下文管理组件控制代理知道什么、在令牌限制内可以运行多长时间以及在会话之间保留哪些信息。它有四层：

• ​**技能**——按需从技能文件中逐步加载的领域知识
• **内存**​AGENTS.md——启动时从文件中加载的持久性指令和首选项
• ​**摘要和上下文卸载**——自动压缩对话历史记录和大型工具结果
• ​**提示缓存**——静态提示部分可以缓存，以加快推理速度并降低所支持模型的成本

技能

该工具支持为您的深度代理提供专业工作流程和领域知识的技能。工作原理：

• 技能遵循特工技能标准
• 每个技能都是一个目录，其中包含一个SKILL.md带有说明和元数据的文件。
• 技能可能包括额外的脚本、参考文档、模板和其他资源。
• 技能采用渐进式披露——只有当智能体确定技能对当前任务有用时，才会加载这些技能。
• 代理程序在启动时读取每个SKILL.md文件的前置信息，然后在需要时查看完整的技能内容。

它的优势在于：

• 通过仅在需要时加载相关技能来减少令牌使用量
• 将各项功能捆绑成更大的行动，并添加更多背景信息。
• 提供专业知识，且不会使系统提示信息混乱。
• 支持模块化、可重用的代理功能

更多信息请参见“技能”部分。

记忆

该框架支持持久内存文件，可在对话过程中为您的深度代理提供额外的上下文信息。这些文件通常包含通用的编码风格、偏好设置、约定和指南，帮助代理理解如何与您的代码库交互并遵循您的偏好。工作原理：

• 使用AGENTS.md​文件来提供持久上下文
• 内存文件始终会被加载（与技能不同，技能采用渐进式披露）。
• ​memory创建代理时，请将一个或多个文件路径传递给参数。
• 文件存储在代理的后端（StateBackend、StoreBackend 或 FilesystemBackend）中。
• 代理可以根据您的交互、反馈和已识别的模式更新记忆。

它的优势在于：

• 提供持久的上下文，无需在每次对话中重新指定。
• 可用于存储用户偏好、项目指南或领域知识
• 始终与代理人保持联系，确保行为一致

有关配置详情和示例，请参阅内存。

摘要和上下文卸载

该框架管理上下文，以便深度代理能够在令牌限制内处理长时间运行的任务，同时保留它们所需的信息。工作原理：

• ​输入上下文——系统提示、记忆、技能和工具提示共同决定了智能体在启动时所掌握的知识。
• ​压缩——内置的卸载和摘要功能可在任务进行过程中将上下文信息保持在窗口限制内。
• ​隔离​——子代理人隔离繁重工作，只返回结果（参见委托）
• ​长期内存——通过虚拟文件系统在线程间持久存储

它的优势在于：

• 支持跨越单个上下文窗口的多步骤任务
• 无需手动裁剪，即可保留最相关的信息。
• 通过自动汇总和卸载来减少令牌使用量

有关配置详情，请参阅上下文工程。

提示缓存

对于 Anthropic 模型，create_deep_agent​会自动将提示缓存应用于系统提示的静态部分——即每个回合都会重复出现的基本代理指令、内存和技能内容。这避免了在不同调用之间重复处理相同的标记，从而降低了长时间运行代理的延迟和成本。使用 Anthropic 模型时，提示缓存默认启用，无需任何配置。对于其他提供商，请参阅中间件集成，了解可用的特定于提供商的缓存中间件。

代表团

委托组件使代理能够将大型问题分解成更小、可并行化的工作单元。它包含两层：

• **任务规划**​write_todos：用于结构化任务跟踪的内置
• ​**子代理**：处理独立子任务的临时性子代理

任务规划

该工具框架为write_todos​代理提供了一个工具，可以用来维护结构化的任务列表。特征：

• 使用状态（'pending'​，，）跟踪多个任务'in_progress'``'completed'
• 持续存在于代理状态
• 帮助代理人组织复杂的多步骤工作
• 适用于长时间运行的任务和计划

次级代理商

该组件允许主代理创建临时的“子代理”来执行孤立的多步骤任务。它的优势在于：

• ​上下文隔离——子代理的工作不会干扰主代理的上下文。
• ​并行执行——多个子代理可以同时运行
• ​专业化——子代理可以拥有不同的工具和配置
• ​令牌效率——将大型子任务上下文压缩成单个结果

工作原理：

• 主代理人拥有一个task工具
• 调用时，它会创建一个具有自身上下文的全新代理实例。
• 子代理自主执行直至完成
• 向主代理返回一份最终报告。
• 可以使用默认子​general-purpose​代理（默认启用）或添加自定义子代理。
• 子代理是无状态的（不能发送多条消息）。

要在不使用工具的情况下运行代理task​，请参阅“不使用子代理运行”。

请勿尝试SubAgentMiddleware​通过--remove​ 命令移除子代理，excluded_middleware​因为该操作会被故意拒绝。请改用 --shared-subagent​ 命令禁用自动添加的子代理，并通过 --no-synchronized-subagents​ 命令不传递任何同步子代理。​subagents=异步子代理不受影响。

有关更多信息，请参阅“子代理商”。

转向

控制组件使人类能够在运行时控制智能体的行为。

人机交互

该安全平台可以在指定工具调用时暂停代理程序的执行，以便人工审批或修改。此功能可通过参数启用interrupt_on​。配置：

• 传递工具名称到中断配置的interrupt_on​映射create_deep_agent
• 例如：interrupt_on={"edit_file": True}每次编辑前暂停
• 您可以在收到提示时提供审批消息或修改工具输入。

它的优势在于：

• 破坏性作业的安全门
• 在进行昂贵的 API 调用之前，需要进行用户验证。
• 交互式调试和指导

更多信息请参见“人机交互”。

Harness Profile 配置

该工具框架可以在选择特定提供程序或模型时应用声明式配置包 (a HarnessProfile​)。配置文件在模型构建完成后调整运行时行为，无需为每个代理编写设置代码。工作原理：

• 使用提供商名称（"openai"​）或provider:model​密钥（"openai:gpt-5.4"）注册个人资料
• ​create_deep_agent在解析模型时查找并应用配置文件
• 提供商级别和模型级别的配置文件在解析时合并

它的优势在于：

• 将每个提供商或每个型号的默认设置（系统提示调整、工具覆盖、中间件）集中在一个地方。
• ​create_deep_agent切换型号时，请保持通话地点不变。
• 通过入口点以插件形式发布可重用的配置文件

有关完整的字段列表、合并语义和插件打包，请参阅配置文件。

‍