Agent Harness 是包围模型、使模型能够作为 Agent 运行的一整套支撑系统。它接收任务和环境信息，组织模型上下文，执行工具调用，把观察结果返回模型，并负责权限、验证、状态和错误恢复。
Harness 原意是挽具或安全带。在 Agent 语境中，这个比喻强调：模型提供推理与生成能力，Harness 则把这种能力连接到真实环境，同时限制它能够采取的动作及其影响范围。
可以用一个便于理解的公式表示：
Agent = Model + Harness
这不是严格的行业标准定义，而是一种工程视角。不同资料也会使用 Agent Runtime、Scaffold 或 Orchestrator 等相近名称，但它们关注的范围可能不同。
子词条概述
当前子词条包括 DeepSeek Harness，用于说明一种插件化通用 Agent Harness 的具体实现及其适用边界。主词条保留 Harness 的通用职责、组成、风险和设计原则。
Harness 负责什么
一个完整的 Agent Harness 通常包含以下部分：
上下文组装
把系统指令、用户任务、对话历史、工具定义、外部知识、当前状态和中间结果组织成模型当前需要的上下文。Harness 还需要在信息过多时进行筛选、压缩或持久化。
工具与环境接口
向模型提供结构化工具，并把工具调用连接到文件系统、数据库、浏览器、业务服务或其他环境。工具接口需要有清晰的名称、参数、结果和错误信息。
Agent 循环
Harness 驱动模型与环境反复交互：
- 组装当前上下文；
- 调用模型；
- 解析模型给出的回答或工具调用；
- 检查工具调用是否允许执行；
- 执行工具并获取观察结果；
- 把结果加入状态，再次调用模型；
- 在满足完成条件、达到限制或需要人工处理时结束。
权限与约束
决定 Agent 能读取、修改或调用哪些资源，并对高风险操作进行拒绝、隔离或人工审批。约束既可以作用于工具参数和执行环境，也可以作用于完整的任务流程。
结果验证
检查工具是否真正执行成功，以及最终结果是否满足任务目标。验证信号可以来自测试、Schema、业务状态、规则检查器或人工审核，而不能只依赖模型声称“已经完成”。
错误恢复
识别超时、无效参数、工具故障、重复循环和上下文丢失等问题，并决定重试、改变策略、回退到检查点、降级处理或移交给人。
状态、日志与可观测性
记录当前进度、工具调用、环境变化、审批和验证结果，使长任务能够恢复，也使开发者能够调试、评测和审计 Agent 的行为。
Model、Framework、Harness 与 Sandbox
| 概念 | 主要职责 |
|---|---|
| Model | 根据上下文生成文本、推理过程或工具调用 |
| Agent Framework | 帮助开发者构建 Agent 的代码库、SDK 或开发框架 |
| Agent Harness | 某个 Agent 实际运行时使用的上下文、工具、循环、约束和恢复机制 |
| Sandbox | 隔离文件、进程、网络和资源的受限执行环境 |
框架可以用来实现 Harness，但框架本身不等于一个已经配置好的 Harness。Sandbox 通常只是 Harness 的一个安全组件，不能替代权限判断、验证和任务状态管理。
不是只有 Coding Agent 才有 Harness
所有能够读取环境、采取行动并持续推进任务的 Agent 都需要某种 Harness，只是不同领域提供的工具和验证方式不同。
| Agent 类型 | Harness 中的典型能力 |
|---|---|
| Coding Agent | 搜索与编辑代码、执行命令、运行测试、Git、沙盒和变更审查 |
| 研究 Agent | 网络搜索、资料读取、引用管理、研究计划和事实核查 |
| 客服 Agent | 查询订单、调用业务接口、身份验证、退款审批和操作审计 |
| Wiki 整理 Agent | 搜索词条、读取来源、编辑草稿、目录检查和人工审核 |
| Computer Use Agent | 截图、点击、键盘输入、界面状态识别和敏感操作确认 |
Coding Agent 的 Harness 特别容易观察，因为软件工程已经拥有测试、类型检查、Linter、构建系统和版本控制等自动反馈机制。其他领域同样需要 Harness，但往往需要额外设计业务验证器或人工确认环节。
Harness 工程
Harness 工程是设计、实现、评测和持续改进 Agent Harness 的工程实践。它关注的不只是“模型能否调用工具”，还包括整个系统能否安全、稳定并可证明地完成任务。
典型问题包括：
- 模型当前应该看到哪些信息；
- 工具怎样设计才不容易误用；
- 哪些动作需要审批或必须禁止；
- 什么证据可以证明任务完成；
- Agent 陷入重复、超时或失败时如何恢复；
- 长任务怎样跨会话保存和交接状态；
- 如何从失败轨迹和评测结果中改进系统。
提示工程主要优化模型收到的指令，上下文工程管理模型当前能够看到的信息；Harness 工程进一步覆盖工具接口、运行循环、约束、验证、状态和恢复机制。
代表性 Harness 实现
DeepSeek Harness
DeepSeek Harness 是 DeepSeek AI 开源的通用 Agent Harness。它采用“所有能力均为插件”的组合式架构，把 Session、系统提示、工具、Agent 循环、模型适配、状态持久化、权限、SDK 和用户界面等职责拆分为可组合组件。
它不是 DeepSeek 模型本身，也不只是一款固定的 Coding Agent 产品。开发者可以选择模型和插件，把它组成编码、研究或其他领域的 Agent 运行时。创建本词条时，官方仍将项目标记为 Developer Preview，并明确提示可能出现不兼容变化。
Coding Agent 领域的另一种代表性设计是 Pi。Pi 强调轻量核心和高度可扩展，其编码场景的具体机制参见 Coding Agent Harness。
常见失败
- 工具很多，但缺少明确的完成条件；
- 只检查工具是否返回成功，没有检查外部状态是否真正改变；
- 把不可信网页、文件或工具输出当作高优先级指令；
- 无限制重试相同动作，导致成本增加或陷入循环；
- 上下文压缩后丢失任务要求或已经完成的工作；
- 权限过宽，使一次误判能够造成不可逆影响；
- 日志只记录最终答案，无法还原执行和审批过程。
设计原则
- 从完成任务所需的最小工具和权限开始；
- 优先使用结构化、及时且接近真实环境的反馈；
- 将危险动作限制在可隔离、可审批和可回退的边界内；
- 把“完成”定义为经过验证的环境状态，而不是模型的一句话；
- 保存足够的状态和轨迹，使失败可以分析、任务可以恢复；
- 根据真实失败案例改进 Harness，而不只继续增加提示词。