Harness 能力

Agent harness 是多种不同能力的组合，使构建长时运行的 agent 更加容易：

• 规划能力
• 虚拟文件系统
• 任务委派（子 agent）
• 上下文与 token 管理
• 代码执行
• Human-in-the-loop

除了这些能力之外，deep agent 还使用 Skills 和 Memory 来获取额外的上下文和指令。

​

规划能力

Harness 提供了一个 write_todos 工具，agent 可以使用它来维护结构化的任务列表。 功能特性：

• 使用状态跟踪多个任务（'pending'、'in_progress'、'completed'）
• 持久化到 agent 状态中
• 帮助 agent 组织复杂的多步骤工作
• 适用于长时运行任务和规划场景

​

虚拟文件系统访问

Harness 提供了一个可配置的虚拟文件系统，支持不同的可插拔后端。 这些后端支持以下文件系统操作： 虚拟文件系统被 harness 的多项其他能力使用，例如 skills、memory、代码执行和上下文管理。 在为 deep agent 构建自定义工具和中间件时，也可以使用文件系统。 更多信息，请参见后端。

​

任务委派（子 agent）

Harness 允许主 agent 创建临时的”子 agent”来处理隔离的多步骤任务。 为什么有用：

• 上下文隔离 — 子 agent 的工作不会干扰主 agent 的上下文
• 并行执行 — 多个子 agent 可以并发运行
• 专业化 — 子 agent 可以拥有不同的工具和配置
• Token 效率 — 大型子任务的上下文被压缩成单一结果

工作原理：

• 主 agent 拥有一个 task 工具
• 调用时，会创建一个具有自身上下文的全新 agent 实例
• 子 agent 自主执行直至完成
• 向主 agent 返回单一的最终报告
• 子 agent 是无状态的（无法发送多条消息返回）

默认子 agent：

• 自动提供”通用”子 agent
• 默认具有文件系统工具
• 可使用额外的工具和中间件进行自定义

自定义子 agent：

• 定义具有特定工具的专业化子 agent
• 示例：代码审查员、网络研究员、测试运行器
• 通过 subagents 参数进行配置

​

上下文管理

Deep agent 通过有效的上下文管理来处理长时运行的任务。 Agent 可以访问多种类型的上下文。 某些来源在启动时提供给 agent；其他来源在运行时变为可用，例如用户输入。 本节概述了 deep agent 可以访问和管理的不同类型上下文。

​

输入上下文

输入上下文由启动时提供给 deep agent 的信息来源组成，这些信息会被添加到提示词中。

​

提示词

Deep agent 使用系统提示词来定义 agent 的角色、行为、能力和知识库。 如果提供了自定义系统提示词，它会被添加到内置系统提示词的前面，内置提示词包含了使用内置工具（如规划工具、文件系统工具和子 agent）的详细指导。 添加工具的中间件（例如文件系统中间件）会自动将工具特定的说明附加到系统提示词中，创建解释如何有效使用这些工具的工具提示词。 最终的 deep agent 提示词由以下部分组成：

1. 自定义 system_prompt（如果提供）
2. 基础 agent 提示词
3. 待办列表提示词：关于如何使用待办列表进行规划的说明
4. Memory 提示词：AGENTS.md + memory 使用指南（仅在提供 memory 时）
5. Skills 提示词：Skills 位置 + 带 frontmatter 信息的 skills 列表 + 使用说明（仅在提供 skills 时）
6. 虚拟文件系统提示词（文件系统 + 执行工具文档，如适用）
7. 子 agent 提示词：Task 工具使用说明
8. 用户提供的中间件提示词（如果提供了自定义中间件）
9. Human-in-the-loop 提示词（当设置了 interrupt_on 时）
10. 本地上下文提示词：当前目录、项目信息等（在本地使用 CLI 时）

​

运行时上下文

Deep agent 使用一种称为上下文压缩的模式，通过减少 agent 工作内存中信息的大小，同时保留与任务相关的细节来实现。 以下技术是内置功能，用于确保传递给 LLM 的上下文保持在其上下文窗口限制之内：

• 卸载大型工具输入和结果
• 摘要化

您还可以配置 deep agent 使用长期记忆，以便跨不同线程和对话存储信息。

​

卸载大型工具输入和结果

Deep agent 使用内置文件系统工具来自动卸载内容，并根据需要搜索和检索已卸载的内容。 内容卸载发生在两种情况下：

1. 工具调用输入超过 20,000 个 token（可通过 tool_token_limit_before_evict 配置）：文件写入和编辑操作会在 agent 的对话历史中留下包含完整文件内容的工具调用。 由于此内容已持久化到文件系统中，通常是多余的。 当会话上下文超过模型可用窗口的 85% 时，Deep agent 将截断较旧的工具调用，用磁盘上的文件指针替换它们，从而减小活动上下文的大小。
2. 工具调用结果超过 20,000 个 token（可通过 tool_token_limit_before_evict 配置）：发生这种情况时，deep agent 将响应卸载到配置的后端，并用文件路径引用和前 10 行的预览替换它。Agent 随后可以根据需要重新读取或搜索内容。

​

摘要化

当上下文大小超过模型的上下文窗口限制（例如 max_input_tokens 的 85%），且不再有符合卸载条件的上下文时，deep agent 会对消息历史进行摘要化处理。 此过程包含两个组成部分：

• 上下文内摘要：LLM 生成对话的结构化摘要——包括会话意图、已创建的产物和后续步骤——替换 agent 工作内存中的完整对话历史。
• 文件系统保存：完整的原始对话消息作为规范记录写入文件系统。

这种双重方法确保 agent 保持对其目标和进度的感知（通过摘要），同时保留在需要时恢复特定细节的能力（通过文件系统搜索）。 配置：

• 在模型的模型配置文件中，当 max_input_tokens 的 85% 时触发
• 保留 10% 的 token 作为最近上下文
• 如果模型配置文件不可用，则回退到 170,000 token 触发 / 保留 6 条消息
• 如果任何模型调用引发 ContextOverflowError，Deep agent 立即回退到摘要化并使用摘要和最近保留的消息重试
• 较旧的消息由模型进行摘要化

为什么有用：

• 使超长对话成为可能，不会触及上下文限制
• 保留最近上下文同时压缩较早的历史记录
• 对 agent 透明（表现为特殊系统消息）

​

长期记忆

使用默认文件系统时，deep agent 将其工作内存文件存储在 agent 状态中，该状态仅在单个线程内持久化。 长期记忆使 deep agent 能够跨不同线程和对话持久化信息。 要使用长期记忆，您必须使用 CompositeBackend，它将特定路径（通常是 /memories/）路由到 LangGraph Store，后者提供持久的跨线程持久化。 CompositeBackend 是一种混合存储系统，其中某些文件无限期持久化，而其他文件则限定在单个线程内。 Agent 存储在长期记忆路径中的文件（例如 /memories/preferences.txt）在 agent 重启后仍然存在，并可从任何对话线程访问。 Deep agent 可以使用这些文件存储用户偏好、积累的知识、研究进度，或任何应在单个会话之外持久化的信息。 更多信息，请参见长期记忆。

​

代码执行

当使用沙箱后端时，harness 会暴露一个 execute 工具，让 agent 在隔离环境中运行 shell 命令。这使 agent 能够作为任务的一部分安装依赖、运行脚本和执行代码。 工作原理：

• 沙箱后端实现 SandboxBackendProtocol——检测到时，harness 将 execute 工具添加到 agent 的可用工具中
• 没有沙箱后端时，agent 只有文件系统工具（read_file、write_file 等），无法运行命令
• execute 工具返回合并的 stdout/stderr、退出码，并截断大型输出（将其保存到文件供 agent 增量读取）

为什么有用：

• 安全性 — 代码在隔离环境中运行，保护主机系统不受 agent 操作的影响
• 干净的环境 — 无需本地设置即可使用特定的依赖项或 OS 配置
• 可复现性 — 跨团队一致的执行环境

有关设置、提供商和文件传输 API，请参见沙箱。

​

Human-in-the-loop

Harness 可以在指定的工具调用处暂停 agent 执行，以便人工审批或修改。此功能通过 interrupt_on 参数选择性启用。 配置：

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

为什么有用：

• 为破坏性操作设置安全关卡
• 在进行昂贵的 API 调用前进行用户验证
• 交互式调试和引导

​

Skills

Harness 支持为 deep agent 提供专业化工作流和领域知识的 skills。 工作原理：

• Skills 遵循 Agent Skills 标准
• 每个 skill 是一个包含带有说明和元数据的 SKILL.md 文件的目录
• Skills 可以包含额外的脚本、参考文档、模板和其他资源
• Skills 使用渐进式披露——仅在 agent 判断其对当前任务有用时才加载
• Agent 在启动时读取每个 SKILL.md 文件的 frontmatter，然后在需要时查看完整的 skill 内容

为什么有用：

• 通过仅在需要时加载相关 skills 来减少 token 使用
• 将能力捆绑成具有额外上下文的更大操作
• 提供专业专长而不会使系统提示词杂乱
• 支持模块化、可复用的 agent 能力

更多信息，请参见 Skills。

​

Memory

Harness 支持为 deep agent 跨对话提供额外上下文的持久化 memory 文件。 这些文件通常包含通用的编码风格、偏好、约定和指南，帮助 agent 了解如何与您的代码库协作并遵循您的偏好。 工作原理：

• 使用 AGENTS.md 文件提供持久化上下文
• Memory 文件始终被加载（与使用渐进式披露的 skills 不同）
• 创建 agent 时，向 memory 参数传递一个或多个文件路径
• 文件存储在 agent 的后端（StateBackend、StoreBackend 或 FilesystemBackend）
• Agent 可以根据您的互动、反馈和识别出的模式更新 memory

为什么有用：

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

有关配置详细信息和示例，请参见 Memory。

---