一、为什么今天要聊 Harness？

最近学习 Agent 时，我逐渐发现一个问题：

很多文章都在讲：

Agent = LLM + Tools + Memory + Planning

这个公式当然没错。

但是如果真的做项目，就会发现还有一层东西没有被说清楚：

谁来控制 Agent 的执行循环？
谁来决定工具怎么暴露？
谁来维护上下文？
谁来限制模型不能乱操作？
谁来记录每一步执行轨迹？
谁来处理失败、重试、超时、回滚？

这些东西既不是模型本身，也不是某一个工具，更不是简单的 Prompt。

它们组合起来，就是今天要讲的核心：

Agent Harness

这个词最近在 Agent 领域开始被频繁提到。OpenAI 在 2026 年 4 月介绍 Agents SDK 新能力时，也专门提到了更强的 agent loop harness，用来支持 Agent 在受控沙箱环境中检查文件、运行命令、编辑代码和完成长任务。

所以，Harness 不是一个很虚的概念，它正在变成 Agent 工程化里的重要关键词。

---

二、Harness 是什么？

先给一个简单理解：

Harness = 套在 Agent 外面的运行控制层

如果说 LLM 是“大脑”，Tools 是“手脚”，Memory 是“记忆”，Planning 是“思考方式”，那么 Harness 就像是：

身体骨架 + 神经系统 + 安全边界 + 执行环境

它负责让 Agent 不只是“想”，而是真的能够按照规则去执行任务。

一个 Agent Harness 通常包含这些能力：

1. Agent 执行循环
2. 工具注册与调用
3. 上下文管理
4. 状态维护
5. 权限控制
6. 执行环境
7. 失败重试
8. 结果校验
9. Trace 追踪
10. 安全隔离

换句话说：

Harness 不是 Agent 本身，而是让 Agent 能稳定运行的一整套外部机制。

---

三、为什么模型本身不等于 Agent？

很多人会把大模型和 Agent 混在一起。

但严格来说：

LLM 本身不是 Agent。

LLM 本质上是：

输入一段文本，预测下一段文本。

它不会主动访问文件，不会真的执行命令，也不会自己保存状态。

比如你问模型：

帮我检查这个 Java 项目的 bug，并修改代码。

模型本身只能生成一段回答。

但如果有 Harness，它就可以变成：

读取项目文件
  ↓
分析代码结构
  ↓
运行测试命令
  ↓
定位报错
  ↓
修改文件
  ↓
再次运行测试
  ↓
输出修复总结

这里真正把模型输出变成行动的，不只是模型，而是模型外面的 Harness。

所以可以这样理解：

LLM 负责“判断下一步做什么”
Harness 负责“让这一步真的发生”

---

四、一个最小 Agent Harness 长什么样？

一个最简单的 Agent Harness，其实可以理解成一个循环。

伪代码大概是这样：

while (!done) {

    // 1. 把上下文、工具信息、用户任务交给模型
    ModelResponse response = chatModel.call(context, tools);

    // 2. 判断模型是要直接回答，还是要调用工具
    if (response.hasToolCall()) {

        // 3. 执行工具
        ToolResult result = toolExecutor.execute(response.getToolCall());

        // 4. 把工具结果写回上下文
        context.addObservation(result);

    } else {

        // 5. 输出最终答案
        return response.getContent();
    }
}

这段代码很简单，但它已经体现了 Harness 的本质：

模型输出意图
Harness 执行动作
环境返回结果
Harness 再喂给模型
模型继续决策

这就是 Agent 最核心的执行闭环。

---

五、Harness 和 Agent Framework 有什么区别？

很多人会把 Harness 和 Agent Framework 混在一起。

它们确实相关，但不是一个东西。

1. Agent Framework 是框架

比如：

Spring AI
Spring AI Alibaba
LangChain
LangGraph
OpenAI Agents SDK
AutoGen
CrewAI

这些是开发框架。

它们提供：

工具调用封装
模型接入
Memory 能力
Agent 抽象
Workflow 编排
Trace 能力

也就是说，Framework 是你用来开发 Agent 的工具箱。

---

2. Harness 是运行控制层

Harness 更偏向于：

你怎么组织 Agent 的执行过程
你怎么暴露工具
你怎么管理上下文
你怎么处理失败
你怎么限制权限
你怎么验证结果

同一个 Framework，可以写出不同的 Harness。

比如同样使用 Spring AI，你可以做一个很简单的 Harness：

用户输入 → 模型回答

也可以做一个复杂的 Harness：

用户输入
  ↓
意图识别
  ↓
Planner 制定计划
  ↓
Executor 调用工具
  ↓
Verifier 校验结果
  ↓
Replanner 修正流程
  ↓
Trace 记录全过程
  ↓
最终返回

所以：

Framework 是工具箱
Harness 是你搭出来的执行系统

---

六、Harness 和 Runtime 有什么区别？

Runtime 更偏底层，指 Agent 运行所在的环境。

比如：

本地机器
Docker 容器
远程沙箱
云端执行环境
Kubernetes Pod
浏览器环境

Harness 会使用 Runtime，但 Harness 不等于 Runtime。

可以这样区分：

Runtime：Agent 在哪里运行
Harness：Agent 怎么运行

举个例子：

Runtime 是 Docker 容器
Harness 是控制 Agent 在容器里如何读文件、执行命令、限制权限、记录轨迹的那层逻辑

OpenAI 在介绍 Agents SDK 新能力时，也强调了 harness 和 compute 的分离，用于安全性、持久性和扩展性。

这说明一个趋势：

未来 Agent 系统不会只是模型 API 调用，而会越来越重视运行环境和控制层设计。

---

七、Harness 和 Workflow / DAG 有什么区别？

Workflow / DAG 是流程编排。

它关注的是：

步骤 A 执行完，再执行步骤 B
步骤 B 成功后执行 C
失败后执行 D

比如 RAG 入库流程：

上传文件
  ↓
解析文件
  ↓
文本切片
  ↓
生成向量
  ↓
写入 Milvus

这就是典型 Workflow。

而 Harness 关注的不只是流程，还包括：

模型如何接收上下文
工具如何暴露给模型
模型如何选择动作
动作如何执行
失败如何处理
结果如何验证
过程如何追踪
权限如何控制

所以 Workflow 更像是 Harness 里面的一部分。

可以这样理解：

Workflow 管步骤
Harness 管整个 Agent 的运行方式

---

八、为什么说 Harness 决定 Agent 的上限？

以前我们经常会说：

这个 Agent 强不强，主要看模型强不强。

但现在这个观点需要修正。

在真实任务里，Agent 的表现不只取决于模型，还取决于 Harness。

最近也有研究开始专门评估 Harness 对 Agent 表现的影响。例如 Harness-Bench 这类工作关注的就是：在真实 Agent 工作流中，不同 Harness 配置会怎样影响任务完成率、执行质量、效率和失败行为。该研究也提出，Agent 能力应该在“模型 + Harness 配置”的层面进行报告，而不能只归因于基础模型。

这点非常关键。

因为同一个模型，配上不同 Harness，表现可能完全不同。

比如模型一样，但是：

A 系统给模型 50 个混乱工具，没有 Trace，没有失败重试
B 系统给模型清晰工具、结构化上下文、沙箱环境、失败校验和 Replan

最后效果肯定不一样。

这也是为什么现在 Agent 工程越来越强调：

不是只调模型，而是设计模型周围的系统。

---

九、Agent Harness 里最重要的 7 个模块

如果从工程角度拆解，一个完整的 Agent Harness 可以包含下面几个模块。

---

1. Loop：执行循环

这是 Harness 的核心。

也就是：

模型思考 → 工具执行 → 观察结果 → 继续思考

如果是 ReActAgent，这个循环就更加明显：

Thought
Action
Observation
Thought
Final Answer

在 Java 项目里，这个循环可以由框架提供，也可以由我们自己封装。

简单任务可以用框架默认循环。

复杂任务最好自己设计 Orchestrator。

---

2. Tool Layer：工具层

工具层负责把真实系统能力暴露给 Agent。

比如：

查询日志
查询告警
查询数据库
检索知识库
发送通知
生成报告
调用接口
执行脚本

但是 Harness 不只是“把工具给模型”。

它还要决定：

哪些工具可以用
什么时候可以用
工具参数如何校验
工具执行超时怎么办
工具失败怎么返回
工具结果是否需要压缩

这就是工具层设计的价值。

---

3. Context：上下文层

Agent 每一步决策都依赖上下文。

上下文里可能包含：

用户问题
系统提示词
历史对话
当前计划
工具返回结果
RAG 检索内容
任务状态
约束条件
错误信息

如果上下文设计不好，Agent 就会混乱。

比如：

工具返回一堆无结构日志
历史对话无限追加
RAG 检索结果不相关
任务状态没有明确记录

这些都会导致模型做出错误判断。

所以 Harness 需要管理上下文：

该放什么
不该放什么
什么时候压缩
什么时候摘要
什么时候丢弃
什么时候重新检索

---

4. State：状态层

Context 更偏“给模型看的内容”。

State 更偏“系统内部维护的任务状态”。

例如：

public class AgentRunState {

    private String sessionId;

    private String userTask;

    private List<String> planSteps;

    private List<String> finishedSteps;

    private Map<String, Object> observations;

    private int retryCount;

    private boolean needReplan;

    private String finalResult;
}

State 的作用是让 Agent 执行过程变得可控。

没有 State 的 Agent，很容易变成：

模型想到哪走到哪

有了 State，系统就可以知道：

执行到哪一步了
哪些步骤失败了
是否超过重试次数
是否需要重新规划
最终结果是否已经生成

---

5. Guardrail：安全边界

Agent 一旦能调用工具，就必须有边界。

尤其是能执行命令、访问数据库、修改文件时，更不能完全相信模型。

Guardrail 可以包括：

工具白名单
参数校验
权限判断
命令黑名单
敏感信息过滤
危险操作二次确认
输出内容审查
最大执行步数限制

比如一个代码 Agent，如果模型想执行：

rm -rf /

Harness 必须拦住。

如果模型想查询数据库：

DROP TABLE user;

Harness 也必须拦住。

所以 Guardrail 的本质是：

允许 Agent 做事，但不能让它乱做事。

---

6. Trace：执行轨迹

Trace 是 Agent 工程化里非常重要的一环。

OpenAI Agents SDK 文档中提到，Tracing 可以记录 Agent 运行过程中的 LLM 生成、工具调用、handoff、guardrails 以及自定义事件，方便开发和生产环境中的调试、可视化和监控。

为什么 Trace 重要？

因为 Agent 不是普通函数。

普通函数出错，我们可以看日志、看堆栈。

Agent 出错时，我们要看的是：

模型看到的上下文是什么？
它为什么选择这个工具？
工具参数是什么？
工具返回了什么？
模型有没有误解工具结果？
哪一步开始偏离目标？

如果没有 Trace，你只会看到最终回答错了。

但你不知道它为什么错。

所以一个成熟的 Harness，一定要有 Trace。

---

7. Verifier：结果校验

Agent 不能只生成答案，还要检查答案是否可靠。

Verifier 可以是规则，也可以是模型，也可以是测试脚本。

比如代码修复场景：

Agent 修改代码
  ↓
运行单元测试
  ↓
测试通过才算完成

运维分析场景：

Agent 生成故障原因
  ↓
检查是否引用了真实告警和日志证据
  ↓
没有证据则标记为“推测”

RAG 问答场景：

Agent 生成答案
  ↓
检查答案是否基于检索文档
  ↓
没有来源则拒绝编造

Verifier 的作用是：

把“模型觉得完成了”变成“系统确认完成了”。

---

十、用 Java 后端思维理解 Harness

作为 Java 开发者，其实可以把 Harness 理解成一种新的后端架构层。

传统后端大概是：

Controller
  ↓
Service
  ↓
Repository
  ↓
Database

Agent 系统里可以变成：

Controller
  ↓
Agent Harness
  ↓
Agent / LLM
  ↓
Tool Layer
  ↓
External Systems

更完整一点：

Controller
  ↓
Orchestrator
  ↓
Agent Loop
  ↓
Context Manager
  ↓
Tool Executor
  ↓
Guardrail
  ↓
Trace Logger
  ↓
Verifier
  ↓
Result Formatter

所以 Harness 并不是脱离后端工程的新东西。

它本质上还是工程控制层。

只不过以前我们控制的是确定性业务流程，现在我们控制的是：

一个不完全确定的大模型执行过程

---

十一、结合 Spring AI / Spring AI Alibaba 怎么理解 Harness？

在 Spring AI / Spring AI Alibaba 项目里，很多能力其实都可以看作 Harness 的一部分。

比如：

ChatClient：负责和模型交互
ToolCallback：负责工具封装
Advisor：负责上下文增强
ChatMemory：负责对话记忆
RAG：负责知识检索
SSE：负责流式输出
Orchestrator：负责流程编排

它们单独看只是一个个组件。

但组合起来，其实就是一个 Agent Harness。

比如一个智能运维 Agent 的 Harness 可以这样设计：

用户输入告警分析请求
  ↓
意图识别
  ↓
构建 AgentRunState
  ↓
Planner 生成排障计划
  ↓
Executor 调用告警工具、日志工具、监控工具
  ↓
Trace 记录每一步
  ↓
Verifier 检查是否有证据支撑
  ↓
Replanner 判断是否需要补充查询
  ↓
ReportAgent 生成报告
  ↓
SSE 返回用户

这个过程里，模型只是其中一部分。

真正让它稳定运转的，是 Harness。

---

十二、一个简化版 Java Harness 设计

下面给一个简化的结构，方便理解。

public class AgentHarness {

    private final ChatModel chatModel;
    private final ToolExecutor toolExecutor;
    private final ContextManager contextManager;
    private final TraceService traceService;
    private final GuardrailService guardrailService;
    private final Verifier verifier;

    public AgentResult run(String userTask) {

        AgentRunState state = new AgentRunState(userTask);

        while (!state.isFinished()) {

            PromptContext context = contextManager.buildContext(state);

            traceService.recordContext(context);

            ModelDecision decision = chatModel.call(context);

            traceService.recordDecision(decision);

            if (decision.isToolCall()) {

                guardrailService.checkToolCall(decision.getToolCall());

                ToolResult result = toolExecutor.execute(decision.getToolCall());

                traceService.recordToolResult(result);

                state.addObservation(result);

            } else {

                AgentResult result = decision.toFinalResult();

                boolean passed = verifier.verify(result, state);

                if (passed) {
                    state.finish(result);
                } else {
                    state.markNeedReplan();
                }
            }
        }

        return state.getFinalResult();
    }
}

这段代码的重点不是语法，而是结构。

一个 Harness 至少要控制这些事：

1. 构建上下文
2. 调用模型
3. 解析模型决策
4. 校验工具调用
5. 执行工具
6. 记录过程
7. 更新状态
8. 校验结果
9. 判断是否结束

这才是 Agent 工程化的核心。

---

十三、Harness 设计不好，会出现什么问题？

1. Agent 看起来很聪明，但经常乱跑

原因可能是：

没有明确任务状态
没有最大执行步数
没有工具调用边界
没有结果校验

表现就是：

一直调用工具
重复查询相同信息
任务还没完成就提前回答
没有证据也强行总结

---

2. Agent 调错工具

原因可能是：

工具描述太模糊
工具数量太多
工具职责不清晰
工具参数设计混乱

解决方式不是一味换模型，而是优化 Harness 的工具层。

---

3. Agent 回答没有依据

原因可能是：

RAG 检索结果没有进入上下文
工具返回结果太长被截断
上下文拼接顺序不合理
最终回答没有验证

这其实不是单纯模型问题，而是 Context 和 Verifier 的问题。

---

4. Agent 出错后无法排查

原因是：

没有 Trace

如果没有记录：

模型输入
模型输出
工具调用
工具参数
工具结果
状态变化

那 Agent 出错后基本只能靠猜。

这在 Demo 阶段还能接受，但在项目里肯定不行。

---

十四、Harness 和多 Agent 编排的关系

多 Agent 编排其实也是 Harness 的一部分。

比如：

Supervisor Agent
Planner Agent
Executor Agent
Replanner Agent
Report Agent

这些 Agent 谁先执行、谁后执行、谁有权限调用工具、谁负责最终输出，都需要 Harness 控制。

否则多个 Agent 就会变成：

一群模型各说各话

Harness 要解决的是：

谁负责调度？
状态放在哪里？
Agent 之间怎么传递结果？
失败后谁来处理？
最终答案由谁生成？

所以多 Agent 真正难的不是“创建多个 Agent 类”。

真正难的是：

设计一个能够控制多个 Agent 协作的 Harness。

---

十五、Harness 对 RAG 也很重要

很多人以为 RAG 就是：

检索文档 + 拼进 Prompt + 生成答案

但如果从 Harness 角度看，RAG 还要考虑：

什么时候检索？
检索哪些库？
TopK 取多少？
是否需要 Query Rewrite？
是否需要 Rerank？
检索结果是否足够相关？
低相关时是否拒答？
答案是否引用了检索内容？

所以 RAG 不只是一个检索模块，而是 Agent Harness 中的知识注入机制。

一个成熟的 RAG Harness 应该是：

用户问题
  ↓
判断是否需要检索
  ↓
Query 改写
  ↓
多路召回
  ↓
Rerank
  ↓
上下文压缩
  ↓
答案生成
  ↓
引用校验

这样才能减少幻觉。

---

十六、Harness 的核心思想：不要只优化模型，要优化环境

以前我们看到 Agent 出错，第一反应可能是：

模型不够强

但 Harness 思维会让我们换一个角度：

是不是工具描述不清楚？
是不是上下文给错了？
是不是环境反馈不明确？
是不是没有限制动作空间？
是不是没有结果验证？
是不是失败后没有重试策略？

这就是 Harness 最重要的价值。

它让我们从“调模型”转向“调系统”。

也就是说：

Agent 能力 = 模型能力 + Harness 设计能力

模型决定上限的一部分。

Harness 决定这个上限能不能稳定发挥出来。

---

十七、我对 Harness 的理解总结

学到这里，我觉得 Harness 可以用一句话概括：

Harness 是让 LLM 从“会说话”变成“能可靠做事”的工程控制层。

没有 Harness 的 Agent，更像是：

一个会思考但没有身体、没有边界、没有记忆、没有执行环境的大脑。

有了 Harness，Agent 才真正具备：

可执行
可观察
可控制
可恢复
可验证
可扩展

对于 Java 开发者来说，学习 Harness 非常重要。

因为 Agent 项目最终不是拼 Prompt，而是拼工程能力。

你需要知道：

模型什么时候调用
工具怎么封装
上下文怎么组织
状态怎么维护
失败怎么处理
日志怎么追踪
结果怎么校验
权限怎么限制

这些才是 Agent 真正落地的关键。

---

十八、写在最后

如果说过去我们学习 Agent，更关注：

Function Calling
ToolCallback
ReAct
RAG
Memory
Multi-Agent

那么接下来更应该关注：

Harness

因为 Harness 把这些能力串成了一个真正可以运行的系统。

它不是一个单独的框架，也不是某个特定 API。

它更像是一种 Agent 工程化思想：

不要只相信模型，要设计好模型周围的执行环境。

未来真正有价值的 Agent 项目，不会只是：

我接了一个大模型 API

而是：

我设计了一套稳定、可控、可观测、可验证的 Agent Harness。

这也是 AI Agent 从 Demo 走向真实项目必须跨过去的一步。

---

今日文章小结

今天主要学习了 Agent Harness。

核心理解是：

Harness 不是模型，也不是工具，而是 Agent 外面的运行控制层。

它负责：

执行循环
工具调用
上下文管理
状态维护
权限控制
Trace 追踪
失败恢复
结果校验

如果没有 Harness，Agent 很容易变成一个不可控的黑盒。

如果 Harness 设计得好，即使模型能力没有变化，Agent 的稳定性、可靠性和工程可用性也会明显提升。