> For the complete documentation index, see [llms.txt](https://yeasy.gitbook.io/harness_engineering_guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://yeasy.gitbook.io/harness_engineering_guide/di-yi-bu-fen-harness-gong-cheng-ji-chu/01_harness_intro/1.2_definition.md).

# 1.2 Harness 的定义与职责边界

本节深入定义 Harness 的核心概念，阐明其在智能体系统中的关键角色，并通过隐喻、对比和具体示例说明其职责范围。

## 1.2.1 核心定义

**Harness** 是在大语言模型与真实执行环境之间构建的一套系统工程框架。它通过标准化的消息协议、分层的权限管理、多维的执行可见性和完善的错误处理机制，使得 LLM 能够在受控约束下安全、可靠地感知环境、执行任务、学习反馈。

这个定义的核心要素有三个：

(1) **中间层角色**：Harness 本质上是一个适配器和控制层，坐在 LLM 和执行环境之间。它不替代 LLM 产生业务推理，也不直接承担工具内部逻辑——而是把 LLM 的意图转化为可验证、可授权、可执行的操作，并将结果正确反馈给 LLM。

(2) **约束和可控性**：Harness 的主要目标不是扩展智能体的能力，而是 **限制智能体的风险**。通过权限管理、操作校验、隔离执行、失败恢复等手段，将智能体的行为控制在安全边界内。

(3) **完整的生命周期管理**：从任务接收、状态追踪、工具调用、结果验证、到最终反馈，Harness 需要在整个智能体执行周期中保持可见性和控制力。

## 1.2.2 驾驭的隐喻

为什么选择“驾驭”(harness)这个名字？

Harness 一词源自马具——骑手用来驾驭烈马的缰绳、鞍具和套具系统。它不是给马匹增加力量，而是：

* **引导方向**：通过缰绳确保马匹的力量用在正确的方向上，而非狂奔失控
* **分散风险**：通过鞍具和套具的多个接点均匀分散冲击力，防止单点失效
* **标准化协作**：让骑手与马匹之间形成可预期的交互协议

同样，AI Harness 的工作原理是：

* **约束智能体的行为**：明确定义智能体能做什么、不能做什么
* **分散执行风险**：通过多个检查点、多层验证，确保没有单个错误能够导致灾难性后果
* **标准化交互**：制定统一的工具调用、权限请求、结果反馈的协议

## 1.2.3 与传统中间件的区别

在分布式系统中，中间件(Middleware)也提供适配、转发、可见性等功能。那么 Harness 与传统中间件有什么本质区别？

**传统中间件的假设**：参与交互的各方（服务 A、服务 B）都是确定的、行为可预测的。中间件的工作是高效地转发消息、处理协议转换、管理连接。

**Harness 的假设**：Agent 的决策可能包含错误、理解偏差，甚至存在潜在的不当意图。Harness 需要对 Agent 的每一个决策都进行验证、授权、隔离执行。

具体来说，传统中间件通常不会：

* 在转发请求前，拦截和验证请求的合法性
* 对某些危险操作进行权限检查或人工审批
* 在执行失败时自动进行智能重试或降级
* 为每个操作维护完整的审计日志

而这些恰好是 Harness 的核心职责。

## 1.2.4 Harness 的职责边界

理解 Harness 的职责边界，对于系统架构设计至关重要。以下是几个关键的职责分界线：

### Harness 做的事

(1) **工具集成**：Harness 负责将各种外部工具和系统集成进来——无论是 API 调用、数据库查询、文件操作还是系统命令。它维护一个统一的工具注册表，确保每个工具都有清晰的接口定义、权限配置和使用说明。

(2) **权限和授权**：Harness 实现从 Free 到 Ask-first 再到 Approve-once 的梯度化权限管理。对于高危操作（如删除数据、转账、修改配置），Harness 可以拦截请求、记录意图、等待人工审批。

(3) **执行跟踪和验证**：每一个工具调用都被记录、追踪、验证。如果工具返回了意外的结果（如网络错误、超时、权限拒绝），Harness 需要识别这些异常并决策是否重试、降级或报告。

(4) **状态管理**：Harness 维护智能体执行过程中的完整上下文状态：当前步骤、已执行的操作、中间结果、依赖关系。这样当智能体被中断或故障后，可以恢复到一致的状态。

(5) **可观测性和审计**：通过日志、分布式追踪、性能指标等多个维度，记录 Agent 的每个行为和决策。这不仅用于故障排查，更是合规性和安全审计的基础。

### Harness 不做的事

(1) **业务推理和任务分解**：Agent 的核心思维过程——如何分解问题、选择使用哪个工具、如何理解反馈——这些主要由 LLM 承担。Harness 不替代模型做业务推理，但会约束、验证、拒绝、重试、路由或升级人工审批；这是执行治理，不是替模型思考。

(2) **工具的实际执行**：当调用一个 API、查询一个数据库、执行一个脚本时，实际的执行是由那个工具或系统负责的。Harness 只是负责正确地构造请求和处理响应。

(3) **模型的优化和训练**：Harness 不涉及模型参数、提示词优化、强化学习训练等。这些都属于模型层的责任。

(4) **业务逻辑**：某个具体业务流程应该如何进行——这是应用层的定义，而不是 Harness 层的职责。Harness 只是提供实现这个流程的技术基础。

## 1.2.5 职责的实际示例

让我们通过一个具体场景来说明这些职责边界。假设 Agent 需要执行“将客户的活期存款转为定期存款”这一金融操作：

```python
# Agent的推理和决策(LLM的职责)
# "用户请求转账,我需要:
#  1) 查询账户余额确认有足够资金
#  2) 调用转账API
#  3) 记录操作日志
# 让我开始第一步..."

# 实际执行(工具的职责)
# transfer_api.execute(source_account, target_account, amount)
# -> 实际向银行后端系统发起转账请求

# Harness的职责
# 1) 权限:在调用transfer_api前,检查该Agent是否有权限执行金融转账操作
#    如果权限等级是Ask-first,则发起审批流程,等待人工确认
# 2) 验证:确认请求的参数格式正确、金额合理(防止1000倍的误输入)
# 3) 隔离:这次调用在一个事务容器内执行,失败时能够安全回滚
# 4) 追踪:记录请求的完整细节、API的响应、任何中间异常
# 5) 反馈:将结果(成功/失败)标准化后反馈给Agent继续推理
```

通过这样的分工，我们实现了三个目标：

* **安全性**：权限层确保不会有非法操作
* **可靠性**：追踪和验证层确保即使出错也能快速定位
* **可用性**：Harness 的重试和降级机制确保系统韧性

## 1.2.6 总结

Harness 不是一个可有可无的“包装层”，而是让 LLM 和实际系统能够安全协作的 **关键基础设施**。它的存在，使得在生产环境中使用 Agent 不再是一个冒险的赌注，而是一个经过工程化验证的方案。

在接下来的章节，我们将深入探讨 Harness 的五大核心子系统，以及如何将这些原则转化为具体的代码和架构。