利用 Harness 功能

Agent harness 是几种不同功能的组合，使构建长时间运行的智能体变得更加容易：

• 规划能力 (Planning capabilities)
• 虚拟文件系统 (Virtual filesystem)
• 任务委托 (子智能体) (Task delegation (subagents))
• 上下文和令牌管理 (Context and token management)
• 代码执行 (Code execution)
• 人在回路 (Human-in-the-loop)

除了这些功能之外，deep agents 还使用 技能 (Skills) 和 记忆 (Memory) 来获取额外的上下文和指令。

​

规划能力 (Planning capabilities)

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

• 跟踪多个任务的状态 ('pending', 'in_progress', 'completed')
• 持久化在智能体状态中
• 帮助智能体组织复杂的多步骤工作
• 适用于长时间运行的任务和规划

​

虚拟文件系统访问 (Virtual filesystem access)

Harness 提供了一个可配置的虚拟文件系统，它可以由不同的可插拔后端支持。 后端支持以下文件系统操作： 虚拟文件系统被其他几个 harness 功能使用，例如技能、记忆、代码执行和上下文管理。 在为 deep agents 构建自定义工具和中间件时，你也可以使用文件系统。 更多信息，请参阅 后端。

​

任务委托 (子智能体) (Task delegation (subagents))

Harness 允许主智能体为隔离的多步骤任务创建临时的“子智能体”。 为什么有用：

• 上下文隔离 - 子智能体的工作不会弄乱主智能体的上下文
• 并行执行 - 多个子智能体可以并发运行
• 专业化 - 子智能体可以拥有不同的工具/配置
• 令牌效率 - 大型子任务上下文被压缩为单个结果

工作原理：

• 主智能体有一个 task 工具
• 当调用时，它会创建一个带有自己上下文的新智能体实例
• 子智能体自主执行直到完成
• 返回单个最终报告给主智能体
• 子智能体是无状态的（不能发回多条消息）

默认子智能体：

• “通用”子智能体自动可用
• 默认具有文件系统工具
• 可以使用额外的工具/中间件进行自定义

自定义子智能体：

• 定义带有特定工具的专用子智能体
• 示例：代码审查员、网络研究员、测试运行员
• 通过 subagents 参数配置

​

上下文管理 (Context management)

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

​

输入上下文 (Input context)

输入上下文包括在启动时提供给你的 deep agent 并添加到提示中的信息源。

​

提示 (Prompts)

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

1. 自定义 system_prompt（如果提供）
2. 基础智能体提示
3. 待办事项列表提示：关于如何使用待办事项列表进行规划的说明
4. 记忆提示：AGENTS.md + 记忆使用指南（仅当提供 memory 时）
5. 技能提示：技能位置 + 带有 frontmatter 信息的技能列表 + 用法（仅当提供技能时）
6. 虚拟文件系统提示（文件系统 + execute 工具文档，如果适用）
7. 子智能体提示：Task 工具用法
8. 用户提供的中间件提示（如果提供了自定义中间件）
9. 人在回路提示（当设置了 interrupt_on 时）
10. 本地上下文提示：当前目录、项目信息…（在本地使用 CLI 时）

​

运行时上下文 (Runtime context)

Deep agents 使用一种称为上下文压缩的模式，其工作原理是减小智能体工作记忆中的信息大小，同时保留与任务相关的细节。 以下技术是内置功能，可确保传递给 LLM 的上下文保持在其上下文窗口限制内：

• 卸载大型工具输入和结果
• 摘要 (Summarization)

你还可以配置 deep agents 使用 长期记忆，允许它们跨不同的线程和对话存储信息。

​

卸载大型工具输入和结果

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

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

​

摘要 (Summarization)

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

• 上下文内摘要：LLM 生成对话的结构化摘要——包括会话意图、创建的工件和后续步骤——它取代了智能体工作记忆中的完整对话历史记录。
• 文件系统保存：完整的、原始的对话消息作为规范记录写入文件系统。

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

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

为什么有用：

• 启用非常长的对话而不会触及上下文限制
• 在压缩古代历史的同时保留最近的上下文
• 对智能体透明（显示为特殊的系统消息）

​

长期记忆 (Long-term memory)

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

​

代码执行 (Code execution)

当你使用 沙盒后端 时，harness 会公开一个 execute 工具，让智能体在隔离环境中运行 shell 命令。这使智能体能够安装依赖项、运行脚本并执行代码作为其任务的一部分。 工作原理：

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

为什么有用：

• 安全性 — 代码在隔离中运行，保护你的主机系统免受智能体操作的影响
• 清洁环境 — 使用特定的依赖项或 OS 配置，无需本地设置
• 可重复性 — 团队之间一致的执行环境

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

​

人在回路 (Human-in-the-loop)

Harness 可以在指定的工具调用处暂停智能体执行，以允许人工批准或修改。此功能通过 interrupt_on 参数选择加入。 配置：

• 将 interrupt_on 传递给 create_deep_agent，带有名为中断配置的工具名称映射
• 示例：interrupt_on={"edit_file": True} 在每次编辑前暂停
• 当提示时，你可以提供批准消息或修改工具输入

为什么有用：

• 破坏性操作的安全门
• 昂贵 API 调用前的用户验证
• 交互式调试和指导

​

技能 (Skills)

Harness 支持为你的 deep agent 提供专门工作流和领域知识的技能。 工作原理：

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

为什么有用：

• 通过仅在需要时加载相关技能来减少令牌使用
• 将功能捆绑成带有额外上下文的更大动作
• 提供专业知识而不会弄乱系统提示
• 启用模块化、可重用的智能体功能

更多信息，请参阅 技能。

​

记忆 (Memory)

Harness 支持持久记忆文件，为你的 deep agent 提供跨对话的额外上下文。 这些文件通常包含一般编码风格、偏好、约定和指南，帮助智能体了解如何处理你的代码库并遵循你的偏好。 工作原理：

• 使用 AGENTS.md 文件 提供持久上下文
• 记忆文件始终加载（与使用渐进式披露的技能不同）
• 在创建智能体时将一个或多个文件路径传递给 memory 参数
• 文件存储在智能体的后端（StateBackend, StoreBackend 或 FilesystemBackend）
• 智能体可以根据你的互动、反馈和识别的模式更新记忆

为什么有用：

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

有关配置详细信息和示例，请参阅 记忆。

---