# Agent Harness 是什么，以及它为什么值得你认真对待

- **HTML:** <https://blog.asuk.app/zh/p/what-is-agent-harness>
- **Language:** `zh`
- **Author:** Asuka
- **Published:** `2026-04-04T06:38:00.000Z`
- **Updated:** `2026-10-13T10:42:20.000Z`
- **Tags:** agent, AI, developer-tools, api

> 解释什么是 agent harness，以及为什么真正决定 AI Agent 可用性的往往不是模型本身，而是它背后的执行环境、工具接口、权限边界、反馈机制与可观测性。

## Content

过去一年里，大家都在谈 AI Agent。很多演示看起来很惊艳：模型会写代码、会点按钮、会查文档、会提 PR，像一个能够自主行动的数字同事。

但当你真的把 Agent 放进生产环境、工程环境、或者长期工作流里，很快就会发现一个关键问题：**模型本身并不等于可用的 Agent，真正决定 Agent 能否稳定工作的，是它运行时所依赖的那套外壳与约束系统。**

这套外壳，通常可以统称为 **Agent Harness**。


## 一句话理解

如果把大模型看成“大脑”，那么 Agent Harness 更像是它的：

- 手和脚
- 工具箱
- 工作台
- 安全护栏
- 反馈面板
- 记忆与状态容器
- 审计与观测系统

也就是说，Harness 不是模型参数的一部分，而是模型与真实世界之间的接口层。它决定模型：

- 能看到什么
- 能调用什么
- 能修改什么
- 能不能获得即时反馈
- 出错时如何恢复
- 权限边界在哪里
- 是否需要人类确认
- 每一步是否可追踪、可回放、可审计

没有 Harness，模型只能“说”；有了 Harness，模型才开始真正“做”。


## 为什么 Harness 比很多人想象中更重要

很多人第一次接触 Agent 时，直觉会把注意力放在模型能力上，比如：

- 这个模型会不会写代码
- 推理能力够不够强
- 上下文窗口够不够大
- 会不会调用工具
- 生成结果是否自然

这些当然重要，但在实际落地时，Harness 往往更早成为瓶颈。

原因很简单：**模型再聪明，也必须通过某种执行环境才能接触你的系统。**

举个最现实的例子。

假设你希望 Agent 帮你管理博客文章。模型并不天然知道：

- 你的文章存在哪里
- 什么字段是必填的
- 怎样发布一篇草稿
- 哪些操作需要鉴权
- 哪些操作会产生不可逆影响
- 出错后应该重试、回滚，还是终止
- 多个用户或多个 Agent 同时修改时如何避免覆盖

这些都不是单纯的“模型知识”问题，而是“接入协议、执行环境与操作边界”问题。Harness 负责把这些边界明确下来。


## 一个典型 Harness 通常包含什么

不同产品的实现形式不同，但一个成熟的 Agent Harness 往往会包含以下几层。


### 1. 工具暴露

最基础的能力是让模型可以调用外部工具。

例如：

- 读文件
- 写文件
- 执行命令
- 发 HTTP 请求
- 查询数据库
- 操作浏览器
- 创建草稿、发起审批、提交工单

如果没有这一层，模型就只能停留在建议和解释。


### 2. 输入输出格式

工具不是只要“能调”就够了，还要让模型容易理解。

好的 Harness 会为工具提供：

- 清晰的参数结构
- 可预期的返回值
- 稳定的错误格式
- 足够短但有信息密度的反馈
- 明确的成功、失败、部分成功状态
- 适合模型阅读的字段命名和文档说明

这也是为什么很多 CLI、MCP Server、Agent SDK 和内部工具平台都很重视“工具描述”和“结构化输出”。对模型来说，格式就是可用性。


### 3. 执行反馈

Agent 不是一次性生成，而是一个不断观察结果、修正动作的循环。

所以 Harness 需要告诉模型：

- 命令执行成功还是失败
- 接口返回了什么
- 文件是否真的改动了
- 测试是否通过
- 当前系统状态有没有变化
- 这一步是否触发了权限限制或安全策略

没有反馈，模型就无法闭环。


### 4. 权限与安全约束

越能行动的 Agent，越需要边界。

Harness 通常会负责：

- 限制可调用工具
- 限制文件访问范围
- 限制网络访问范围
- 限制高风险命令
- 区分只读、可写、可发布、可删除等权限
- 要求敏感动作二次确认
- 记录谁在什么时候通过什么 Agent 做了什么操作

也就是说，Harness 不只是给能力，也是在设护栏。


### 5. 状态、记忆与并发控制

真正能做长期任务的 Agent，不能只依赖单轮上下文。

Harness 需要处理：

- 当前任务状态
- 历史操作记录
- 文件或资源版本号
- 乐观锁与冲突检测
- 重试策略
- 幂等键
- 回滚或恢复路径

比如文章管理场景里，更新文章前最好读取当前版本，并在提交更新时携带 `expectedVersion`。这样即使另一个人或另一个 Agent 同时修改了文章，也不会被悄悄覆盖。


### 6. 工作流编排

更进一步的 Harness 还会组织多步任务，比如：

1. 先读代码
2. 再找调用链
3. 然后修改文件
4. 运行测试
5. 汇总结果
6. 等待人类确认
7. 再执行发布或提交

这时 Harness 已经不只是“工具容器”，而是在塑造一种可重复执行的工作方式。


### 7. 可观测性与评估

生产级 Agent 还需要知道自己为什么成功、为什么失败。

因此 Harness 最好能提供：

- trace
- tool call 日志
- token 与成本统计
- 错误分类
- 延迟统计
- 人类接管记录
- 任务成功率评估
- 回放与复盘能力

没有这些，Agent 很容易停留在“演示能跑，但出了问题没人知道为什么”的阶段。


## 为什么 CLI 形态的 Harness 往往体验很好

很多工程师会发现，像 Claude Code、OpenCode 这类 agentic CLI 用起来特别顺手。

原因并不神秘，CLI 天然具备几种非常适合 Agent 的特征。


### 文档内置

命令、参数、输出格式，往往就在同一个环境里。模型不用频繁跳转上下文。


### 即时反馈

命令一跑，stdout 和 stderr 立刻回来。模型能迅速判断下一步。


### 文本友好

终端天生就是结构化文本环境，对模型特别友好。相比复杂图形界面，文本更容易被压缩、归纳和追踪。


### 组合能力强

CLI 很容易串联多个命令，形成工作流。一个 Agent 可以先 `git status`，再跑测试，再改文件，再提交。

这也是为什么很多人明明不喜欢“重”的集成方案，最后还是觉得 CLI 风格更可靠：因为它的反馈链路非常短。


## 但 CLI 不是唯一答案

CLI 的优势明显，但也有代价：

- 接入成本偏高
- 运行环境更重
- 不一定适合公网调用
- 对非本机场景不够轻量
- 权限、审计、租户隔离需要额外设计

所以在很多业务系统里，更现实的路线是：**保留 CLI 那套“自描述 + 即时反馈 + 结构化输出”的优点，但把落地点换成 agent-friendly 的 API 或协议层。**

这正是越来越多团队在做的事情。


## MCP、Agent SDK 与 REST 的位置

到 2026 年，MCP 已经成为连接 LLM 应用与外部工具、数据源的一种重要标准化方向。它的价值在于把工具、资源、提示词和上下文边界用统一协议表达出来，让不同 Host 和不同工具服务之间更容易组合。

同时，OpenAI Agents SDK、各种 agent framework、内部 workflow engine 也在把工具调用、handoff、guardrail、session、tracing、人类确认等能力产品化。

但这不意味着所有系统都必须一上来就做完整 MCP Server，或者直接绑定某个 Agent SDK。

一个更现实的判断是：

- 如果你要服务多个 Agent Host，或者希望工具能被 Claude、ChatGPT、IDE、内部平台等多种环境复用，MCP 很值得考虑。
- 如果你在构建一个完整 Agent 应用，需要托管 agent loop、状态、handoff、guardrail、trace，Agent SDK 会更省力。
- 如果你的核心资产本来就是业务 API，或者你只是想先让某个系统“对 Agent 友好”，REST + OpenAPI 仍然是非常务实的起点。

也就是说，MCP、SDK、REST 并不是互斥路线。它们更像是不同层级的 Harness 形态：一个偏协议互操作，一个偏运行时编排，一个偏业务系统接入面。


## 一种轻量的思路：Agent-Friendly REST

如果你不想一开始就上完整 MCP，也不想维护很重的专有桥接层，那么一个很实用的方向是：

- 用 REST 作为执行面
- 用 OpenAPI 作为机器可读契约
- 用 RFC 9457 Problem Details 统一错误格式
- 用紧凑 JSON 保持 agent 可读性
- 用 docs 页面给人类快速理解
- 用版本号、幂等键、dry-run 降低误操作风险

这样做的核心思想是：

> 不强迫 Agent 适应人类随手设计的接口，而是把接口本身设计成适合 Agent 阅读、调用和恢复。

比如一个好的 agent-friendly 文章管理 API，通常会有这些特征：

- 列表接口不默认返回全文，避免上下文膨胀
- 单篇详情返回 markdown 正文
- 错误统一为 `application/problem+json`
- 响应里带 `links` 或 `actions`
- 机器说明放在 `openapi.json`
- 人类说明放在 `/docs/api`
- 写操作要求传入当前版本号，避免并发覆盖
- 发布、删除、发送等高风险动作要求确认
- 重要操作有 audit log

这本质上就是把 CLI 中“帮助信息内置、执行结果明确、格式稳定”的经验迁移到了 HTTP 世界。


## Harness 设计得好，Agent 才会显得聪明

有时候我们会误以为某个 Agent 很强，是因为模型更高级。

但实践里经常相反：

- 一个普通模型，放进设计良好的 Harness，表现会非常稳定
- 一个很强模型，接入糟糕的工具系统，也会频繁犯错

因为大多数失败都不是单纯的“推理失败”，而是：

- 工具描述含糊
- 返回值太乱
- 错误不可恢复
- 权限边界不清楚
- 没有发现入口
- 反馈链路太长
- 状态不可追踪
- 高风险操作缺少确认
- 没有评估和回放能力

你可以把 Harness 理解成“为模型降低操作熵”的工程。熵越低，模型越容易做对。


## 对个人开发者来说，应该怎么开始

如果你也想把自己的系统变得更适合 Agent 使用，不需要一步到位做成平台。一个很务实的起点是：

1. 先挑一个高频任务，比如文章管理、工单处理、内容发布
2. 抽出稳定的领域操作，而不是暴露数据库细节
3. 给这些操作设计简洁的 REST 接口
4. 提供 OpenAPI 契约和统一错误格式
5. 用 Bearer Token 或 OAuth 做最小鉴权
6. 让响应尽量紧凑、稳定、可推理
7. 给写操作加上版本号、幂等键和 dry-run
8. 给高风险操作加上人类确认
9. 记录 tool call、错误、耗时和关键状态变化

走到这一步，你就已经拥有一个轻量但实用的 Harness 雏形了。

之后如果需要，再往上叠：

- MCP
- OAuth/OIDC
- 更细的权限模型
- 审计日志
- 并发控制
- dry-run / validate-only
- sandbox
- evaluation
- tracing
- human-in-the-loop

重点不是一开始做多重，而是先让 Agent 真能稳定完成一件事。


## 结语

Agent Harness 听起来像一个很“基础设施”的词，但它实际决定了 AI Agent 能不能从演示走向生产。

模型提供的是智能潜力，Harness 提供的是行动方式。

如果说大模型让我们第一次看见“机器可能会工作”，那么 Harness 解决的就是下一步：**怎样让它在真实系统里，以一种可控、可恢复、可持续、可观测的方式工作。**

而这，往往比模型排行榜上的名次更重要。


## 参考

- [Model Context Protocol Specification](https://modelcontextprotocol.io/specification/2025-06-18)
- [OpenAI Agents SDK](https://openai.github.io/openai-agents-python/)
- [OpenAPI Specification](https://spec.openapis.org/oas/latest.html)
- [RFC 9457: Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc9457.html)