Agent Harnesses：现代 AI Agent 开发的新标准
Agent Harnesses 是一种把角色、上下文、skills 和 references 组织起来的结构，让通用 AI agent 能在具体任务中更稳定、可复用、可维护地工作。
本文为中文改写与评论，原文作者 Daniel Warfield，发布于 Intuitively and Exhaustively Explained / Medium；用户提供的原文链接：Agent Harnesses — Intuitively and Exhaustively Explained。由于 Medium 页面为会员内容，本文参考作者同步发布的公开 Substack 版本：Agent Harnesses — Intuitively and Exhaustively Explained。本文保留原文的核心结构和论点，并面向中文读者重新组织为一篇便于理解的技术解读。
Agent harness 的核心不是再发明一个“agent”概念，而是给通用 agent 连接角色、上下文、技能和参考材料，让它能在具体问题里稳定、可复用、可维护地工作。
这篇文章讨论的是“Agent Harnesses”：作者提出的一个面向现代 AI agent 开发的标准。它试图解决一个越来越常见的问题：我们已经有了会调用工具、会读文件、会执行任务的通用 agent，但当这些 agent 被放进真实业务、真实代码库或真实组织流程里时，往往缺少稳定的角色边界、上下文入口和可复用的操作方式。
作者的观点可以先压缩成一句话：harness 是围绕 agent 的一层结构，它把 agent 需要的角色说明、技能、参考资料和环境知识组织起来，让通用 agent 能够以更可预测的方式处理复杂任务。
为了说明这个概念，原文先回顾了 LLM、ReAct-style agent、chain of thought、tool use 和 skills，然后再解释 harness 标准本身。下面按照这个脉络展开。
先从 LLM 说起
在这篇文章里，LLM 可以先被理解成一个函数：输入文本，输出文本。无论今天的模型看起来多聪明，它最基础的能力仍然是“根据输入产生响应”。最近几年出现的许多 AI 应用，包括聊天助手、代码 agent、搜索 agent、自动化 worker，本质上都是建立在这个能力之上。
这也是为什么单独一个 LLM 还不等于一个可用的生产系统。它能回答，但它不知道自己在什么环境里；它能生成计划，但它不能天然知道可以调用哪些工具；它可以读上下文，但上下文从哪里来、什么时候加载、加载多少，都需要系统设计。
什么是 ReAct-style Agent
“agent”这个词很宽。学术上有很多不同类型的 agent，但在今天的 AI 工具语境里，普通用户谈到 agent 时，通常指的是一种聊天式系统：用户给出任务，系统会思考、调用工具、观察结果，然后继续推进，最后给出答案。
作者把这种常见形态称为 ReAct-style agent。ReAct 的意思是 reasoning and acting：模型先围绕任务进行推理，然后选择一个动作调用外部工具，再观察工具返回的结果，继续决定下一步。这个循环让 LLM 从“只会生成文本”变成“能通过工具影响环境”。
在本文中，只要提到 agent，基本都可以理解为这种 ReAct 或类似 ReAct 的 agent。它们可能会搜索网页、读本地文件、调用 API、写代码、运行测试，或者和数据库交互。
Chain of Thought 与工具调用
理解 ReAct agent，还需要理解两个底层模式：chain of thought 和 tool use。
Chain of thought 的直觉很简单：让模型在给出答案之前先组织推理过程。早期做法通常是在 prompt 中给一个示例，告诉模型“你应该先这样想，再给答案”。后来，很多模型在训练中就被鼓励先进行内部推理；而 reasoning model 则进一步把长时间推理变成一个显式能力。
Tool use 则是另一条关键线索。最朴素的方式是告诉 LLM：如果你输出某种特定格式，我就会执行一段代码，并把结果返回给你。这样模型就可以决定什么时候搜索、什么时候读文件、什么时候查数据库、什么时候运行某个函数。
当 reasoning、action、observation 组合在一起，agent 就能在一个环境中迭代行动。但问题也随之出现：如果任务很复杂，仅仅给 agent 一堆工具和一个长 prompt 还不够。它需要知道自己的角色、边界、项目结构、可用技能、参考资料和当前任务所属的上下文。
Skills 解决了什么
随着 agent、工具调用和提示工程的发展，行业里逐渐出现了一种很实用的模式：skills。Skill 可以把一组说明、脚本、参考资料和资源放进同一个目录，让 agent 在需要时加载它。
my-skill/
├── SKILL.md # 必需：metadata + instructions
├── scripts/ # 可选：可执行脚本
├── references/ # 可选：参考文档
├── assets/ # 可选：模板和资源
└── ... # 其他文件或目录
skill 的强大之处恰恰在于它很简单。很多 skill 其实就是一堆 markdown 文件，加上一些可选脚本。但它给 agent 提供了一个可复用、可移植的知识包：数据库如何操作、网站如何修改、品牌文案应该怎么写、某个代码库的约定是什么，都可以被封装成 skill。
不过，当一个任务需要多个 skill 协同工作时，新的问题又出现了。比如一个“产品开发助理”可能既需要代码 skill，也需要设计规范、项目背景、客户反馈、发布流程和测试策略。单个 skill 不一定能表达这种更高层级的角色和环境。
Harness 的基本想法
作者认为，harness 可以被理解为 skills 的扩展。Skills 让开发者把一类能力打包；harness 则把多个 skills 和更高层级的参考资料打包起来，让 agent 理解它的角色、环境和工作范围。
换句话说，skill 更像“你会做什么”，harness 更像“你在什么角色里、面对什么环境、可以组合哪些能力来做事”。
这点很关键，因为它避免把 harness 混同为“让 LLM 能做事的代码”。如果 harness 只是“LLM 外面的一层代码”，那它和 agent 的定义会严重重叠。作者更倾向的定义是：harness 是 agent 连接到具体问题空间时需要的信息、技能和参考结构。
Agent Harnesses 标准
在原文中，一个 harness 主要包含三部分：一个描述 harness 的 markdown 文件，一组让 agent 能够操作环境的 skills，以及一组让 agent 理解环境的 references。
my-harness/
├── HARNESS.md # 必需：metadata + instructions
├── skills/ # 可选：一组 skills
└── references/ # 可选：一组参考文档
HARNESS.md 是整个 harness 的入口。它不是用来塞满所有上下文的，而是让 agent 先快速理解：这个 harness 是什么、它大致解决什么问题、哪些 skills 和 references 可能与当前任务相关。
这遵循了“progressive disclosure”的思想：不要一开始就把所有信息塞进上下文窗口，而是让 agent 先读最小入口，再根据任务逐步发现、加载和使用相关材料。
- Discovery：启动时只加载
HARNESS.md。当用户给出任务后，agent 根据 harness 的描述判断可能需要哪些 skills 或 references。 - Activation：发现相关材料后，再加载对应 skill 或 reference 的完整文档。
- Execution：agent 根据 harness 提供的信息执行任务，必要时调用 skill 中的脚本或工具。
如何定义 HARNESS.md
和 skills 类似，HARNESS.md 使用 frontmatter。最基础的信息包括 name 和 description：
---
name: <name of the harness>
description: <description of what the harness is for>
---
<body>
这里的 body 应该是一个简洁的说明文档，帮助 agent 理解这个 harness 的核心用途，以及在什么情况下应该去找哪些 skills 或 references。它不是越长越好；它的价值在于成为高效导航入口。
Skills 目录
skills/ 目录里放的是符合 Agent Skills 标准的一组 skill。每个 skill 仍然可以包含 SKILL.md、脚本、参考资料和资源。
my-harness/
├── HARNESS.md
├── skills/
| ├── my-skill-1/
| | ├── SKILL.md
| | ├── scripts/
| | ├── references/
| | ├── assets/
| | └── ...
| └── my-skill-2/
| ├── SKILL.md
| ├── scripts/
| ├── references/
| ├── assets/
| └── ...
└── references/
这种结构允许一个 agent 在同一个 harness 下调用多个能力。比如一个营销 harness 可以有写博客、生成图片、扫描社交媒体等 skills；一个工程 harness 可以有读代码、跑测试、创建 PR、更新 issue 等 skills。
References 目录
references/ 目录则用于放更高层级的信息。Skill 内部也可以有 references，但 skill 里的 references 通常解释“这个具体能力怎么用”；harness 级别的 references 更适合放跨多个 skill 都需要知道的环境信息。
举例来说，如果你在搭建一个市场营销 agent，skill 可能分别负责“创建博客文章”“生成图片”“扫描社交媒体”。那么 harness 级别的 references 可以放品牌语气、视觉规范、目标客户、产品定位、禁用词、合规约束等通用信息。
my-marketing-harness/
├── HARNESS.md
├── skills/
| ├── create-blog-post/
| | ├── SKILL.md
| | └── ...
| ├── generate-images/
| | ├── SKILL.md
| | └── ...
| └── scan-social/
| ├── SKILL.md
| └── ...
└── references/
├── style-guide.md
└── brand-priorities.md
作者建议 references 尽量使用 markdown，并在每个文件顶部加一个高层级 description，让 agent 能快速判断某个 reference 是否值得加载。
---
description: a style guide for the marketing website, which covers the creation
of all visual assets and standard typography rules
---
<body>
大型 Harness 如何组织
当 harness 包含很多 skills 和 references 时，维护和上下文效率都会变成问题。如果几十个 skill 和几十个参考文档平铺在一个目录里，agent 可能很难知道该先读什么，人类维护者也很难长期管理。
为了解决这个问题，标准允许在 skills/ 和 references/ 下面继续创建子目录。每个子目录可以用 SKILLS.md 或 REFERENCES.md 描述这一层的内容。
my-harness/
├── HARNESS.md
├── skills/
│ ├── software-development/
│ │ ├── SKILLS.md
│ │ ├── skill1/
│ │ │ └── SKILL.md
│ │ └── skill2/
│ │ └── SKILL.md
│ ├── market-analysis/
│ │ ├── SKILLS.md
│ │ └── skill3/
│ │ └── SKILL.md
│ └── social-media/
│ ├── SKILLS.md
│ └── skill4/
│ └── SKILL.md
└── references/
├── brand-assets/
│ ├── REFERENCES.md
│ └── reference1.md
└── software-infrastructure/
├── REFERENCES.md
└── reference2.md
这仍然是在贯彻 progressive disclosure：先让 agent 看最高层结构，再决定是否进入某个子目录，再根据子目录说明加载具体文件。相比“一次性把所有上下文塞进去”，这种方式更便宜、更安全，也更不容易让模型被无关信息带偏。
这个结构还可以继续嵌套。例如数据源相关 reference 下面，可以分 relational 和 warehouse 两类，每一层都用 REFERENCES.md 做导航。
...
└── references/
└── data-sources/
├── REFERENCES.md
├── relational/
│ ├── REFERENCES.md
│ └── schema-overview.md
└── warehouse/
├── REFERENCES.md
└── dataset-catalog.md
为什么这件事重要
Agent harnesses 不是为了目录结构而目录结构。它真正要解决的是 agent 在真实系统中“如何稳定获得必要信息”的问题。
很多失败的 agent 系统，不是因为模型不够强，而是因为上下文管理混乱：该知道的没加载，不该知道的加载太多；该用的工具没暴露，不该用的工具权限太大；同一个任务每次都要重新解释背景，导致行为不稳定。Harness 把这些东西变成一个可版本化、可审查、可复用的结构。
对开发团队来说，这还有一个额外好处：知识不再只存在于某个工程师脑子里，也不只存在于一次对话上下文里。它可以沉淀成 HARNESS.md、skills、references 和目录约定。agent 每次工作时都能沿着同样的入口逐步加载。
进一步阅读
原文最后指向了 Agent Harnesses 的官方文档、GitHub 仓库和示例。它们展示了这个标准如何被定义、验证和应用。
给中文读者的总结
如果用一句话理解 agent harness：它是“让通用 agent 进入具体工作场景”的结构化入口。
Skill 解决的是能力打包；harness 解决的是能力组合、角色约束和环境导航。一个好 harness 不应该把所有资料一次性塞给模型，而应该让 agent 能通过清晰的入口逐步发现必要材料。它像一个给 agent 用的项目地图：先告诉你有什么，再告诉你什么时候该深入哪里。
这个思路和我们最近看到的 loop engineering、Claude Code skills、Codex skills、MCP connectors 都在同一个方向上：AI agent 的关键不只是“模型更强”，而是周围的工程结构更清楚。越是想把 agent 放到长期、复杂、真实的工作里，越需要 harness 这样的组织方式。
