5千字长文：一篇看懂_Agent_Harness_的结构！-平芜编程栈

今天来聊聊，我在 X 上看到的一篇把 Harness 到底是啥讲的巨透彻的文章

这篇文章我提取的最核心的一句话是：Agent = Model + Harness。

模型负责智能，Harness 负责把这份智能变成能持续工作的系统。真正决定 agent 上限的，不只是底座模型，而是模型外面的那整套文件系统、工具、记忆、状态、验证和上下文治理。

全文9000 字看完 20 分钟，开整！

Anthropic、OpenAI、Perplexity 和 LangChain 这些公司，实际上都在搭同一种东西：一套能把无状态 LLM 变成可工作的 agent 的基础设施。这里面包括编排循环、工具、记忆、上下文管理，以及其他所有让模型真正变得“可用”的东西。

你可能已经做过一个 chatbot，也可能已经用几个工具接了个 ReAct loop。做 Demo 的时候一切都挺顺。可一旦你开始尝试做生产级系统，问题马上就出来了：模型忘掉三步前做过什么、tool call 悄无声息地失败、上下文窗口逐渐被垃圾信息塞满。

问题往往不在模型本身，而在模型外面的整套系统。

LangChain 曾经证明过这一点：他们只改了包在 LLM 外面的基础设施，模型和权重完全不变，TerminalBench 2.0 的成绩却从榜单前 30 名之外，一口气跳到第 5 名。另一项研究甚至让 LLM 自己去优化这层基础设施，最终达到了 76.4% 的通过率，超过了人工设计的系统。

现在，这套基础设施终于有了一个统一名字：agent harness。

什么是 Agent Harness？

这个词是在 2026 年初逐渐被正式化的，但它代表的东西其实早就存在了。所谓 harness，就是包在 LLM 外面的整套软件基础设施：编排循环、工具、记忆、上下文管理、状态持久化、错误处理和安全护栏。

Anthropic 在 Claude Code 文档里说得很直白：SDK 就是“驱动 Claude Code 的 agent harness”。OpenAI 的 Codex 团队也用了同样的说法，直接把“agent”和“harness”这两个词放在一起讨论，用来指代那层让 LLM 真正有用起来的非模型基础设施。

我很喜欢 LangChain 的 Vivek Trivedy 给出的那句公式：

如果你不是模型，那你就是 harness。

很多人容易搞混“agent”和“harness”。真正的 agent，是用户看到的那个有目标、会用工具、会自我纠错的行为体；而 harness，是制造出这种行为的那套机器结构。换句话说，当一个人说“我做了一个 agent”，他真正做出来的，往往是一套 harness，然后把模型接了进去。

Beren Millidge 在 2023 年的文章《Scaffolded LLMs as Natural Language Computers》中把这个比喻说得很精确：一个裸 LLM 就像只有 CPU、没有内存、没有磁盘、没有 I/O 的计算机。上下文窗口相当于内存，快但小；外部数据库相当于磁盘，容量大但慢；工具接口像设备驱动；而 harness 更像操作系统。

他说过一句很经典的话：我们其实是把冯·诺依曼架构重新发明了一遍。

三层工程

围绕模型，其实有三层递进的工程：

Prompt engineering：决定你怎么给模型下指令。
Context engineering：决定模型在什么时刻能看到什么信息。
Harness engineering：不仅包含前两者，还包括整个应用层基础设施，比如工具编排、状态持久化、错误恢复、验证回路、安全约束和完整生命周期管理。

所以 harness 不是“给 prompt 套个壳”，它是让 agent 行为真正成立的整个系统。

生产级 Harness 的 12 个组件

综合 Anthropic、OpenAI、LangChain 以及更广泛的实践者经验，认为一个生产级 agent harness 至少包含下面 12 个部分。

1. 编排循环（The Orchestration Loop）

这是整个系统的心跳。它实现的是 Thought-Action-Observation，也就是常说的 TAO / ReAct 循环：

组 prompt → 调模型 → 解析输出 → 执行工具 → 把结果再喂回去 → 继续循环，直到任务结束。

从代码层面看，它往往只是一个 while loop。真正复杂的地方不在循环本身，而在于这个循环管理了什么。Anthropic 就把自己的运行时叫做“dumb loop”：循环本身不聪明，所有智能都在模型里，harness 只负责回合管理。

2. 工具（Tools）

工具就是 agent 的手。它们通常会以 schema 的形式注入到上下文里，让模型知道有哪些工具、每个工具叫什么、接受哪些参数。

工具层真正负责的事包括：

工具注册
schema 校验
参数提取
沙箱内执行
结果捕获
再把结果格式化成模型能继续读懂的 observation

Claude Code 把工具分成文件操作、搜索、执行、网页访问、代码智能和 subagent 六类；OpenAI 的 Agents SDK 支持 function tools、hosted tools 和 MCP tools。

3. 记忆（Memory）

记忆不是单一概念，而是多层次的。

短期记忆：单次会话里的历史消息
长期记忆：跨会话持久存在的内容

Anthropic 用CLAUDE.md、自动生成的MEMORY.md等文件承载长期记忆；LangGraph 用带命名空间的 JSON Store；OpenAI 支持用 SQLite 或 Redis 承载 Session。

Claude Code 做得更细，它把记忆拆成三级：

轻量索引：每条大约 150 个字符，启动时总是加载
详细主题文件：按需读取
原始记录：只有搜索时才访问

一个很重要的原则是：agent 把自己的记忆当成提示，而不是绝对事实。它应该用记忆快速定位方向，但行动前还是要再去核对实际状态。

4. 上下文管理（Context Management）

很多 agent 并不是在显性报错时失败，而是在这里悄悄变差。

核心问题是 context rot：上下文一旦变长，模型推理质量会下降。即便是超长窗口模型，也会随着上下文膨胀而在指令遵循和中段信息利用上明显退化。

常见的生产策略包括：

Compaction：接近窗口上限时，把旧对话压缩总结
Observation masking：旧工具输出不再完整暴露，但保留必要痕迹
Just-in-time retrieval：不整份加载，只按需读取高信号片段
Sub-agent delegation：把大任务拆给子 agent，让它们各自探索后只返回压缩总结

Anthropic 的上下文工程指南里说得很准：目标不是给模型最多 token，而是给它最小但最有效的一组高信号 token。

5. Prompt Construction

这一步负责真正组装模型每一轮看到的内容。通常会包含：

system prompt
工具定义
记忆文件
会话历史
当前用户消息

OpenAI Codex 用的是严格优先级栈：

服务器控制的 system message
工具定义
developer instructions
user instructions
conversation history

这里的关键，不只是“把东西拼起来”，而是决定什么内容放在哪里、优先级怎么排。

6. 输出解析（Output Parsing）

现在更成熟的 harness 会优先依赖原生 tool calling，而不是自由文本解析。也就是说，模型不再随便输出一段像工具调用的文本，而是直接返回结构化的 tool_calls 对象。

Harness 在这里要判断：

有 tool call 吗？有就执行并继续循环
没有 tool call 吗？那就是最终回答

如果要输出结构化结果，OpenAI 和 LangChain 都支持通过 Pydantic schema 约束模型输出。

7. 状态管理（State Management）

LangGraph 把状态建模成一个在 graph 节点间流动的 typed dictionary；OpenAI 则给出四种不同策略：应用内存、SDK session、服务器侧 Conversations API、以及更轻量的 previous_response_id 链接。

Claude Code 的思路更工程化：git commit 是 checkpoint，progress file 是结构化 scratchpad。

也就是说，状态不一定非得是数据库，也可以是文件系统和 Git 自然形成的工作痕迹。

8. 错误处理（Error Handling）

只要任务是多步的，错误就会累积。一个 10 步流程，即便每一步有 99% 成功率，最终端到端成功率也只有大约 90.4%。

LangGraph 把错误分成四类：

瞬时错误：重试
模型可恢复错误：把错误作为 ToolMessage 返回，让模型调整
需要用户处理的错误：中断并请求用户输入
非预期错误：直接上浮，方便调试

Anthropic 的策略是：尽量在 tool handler 里把错误包装成错误结果，继续让主循环跑下去。Stripe 的生产 harness 甚至把重试次数限制在两次以内，避免无限折腾。

9. 安全护栏（Guardrails and Safety）

OpenAI 的 SDK 把护栏做成三层：

输入护栏
输出护栏
工具护栏

一旦触发 tripwire，就立即中止 agent。

Anthropic 则更强调权限与推理的分离：模型决定想做什么，工具系统决定允许它做什么。Claude Code 大约对 40 种工具能力分别设权限，并分成三层检查：项目加载时建立信任、每次 tool call 前检查权限、高风险操作时要求用户确认。

10. 验证回路（Verification Loops）

这是玩具 demo 和生产系统之间最关键的差异之一。

Anthropic 推荐三种验证方式：

规则型反馈：测试、lint、type check
视觉反馈：比如 Playwright 截图来验证 UI
LLM as judge：单独起一个评审 agent

Boris Cherny 甚至说过：只要给模型一个验证自己结果的办法，质量可以提升 2 到 3 倍。

11. 子 Agent 编排（Subagent Orchestration）

Claude Code 支持三种模式：

Fork：完整复制父上下文
Teammate：单独终端窗格，通过文件通信
Worktree：单独 git worktree，拥有独立分支

OpenAI 的 Agents SDK 支持 agents-as-tools 和 handoffs；LangGraph 则可以把 subagent 建成嵌套状态图。

子 agent 的本质不是“把事情搞复杂”，而是在上下文、工具和任务域明显开始冲突时，把任务隔离出去。

12. 循环如何真正跑起来

把完整流程拆成七步：

Prompt Assembly：system prompt + tools + memory + history + 当前消息
LLM Inference：模型生成文本、tool call 或 handoff
Output Classification：判断是最终回答、工具调用还是 handoff
Tool Execution：校验参数、检查权限、在沙箱中执行、获取结果
Result Packaging：把结果重新格式化成模型可读消息
Context Update：把结果追加进历史，必要时 compaction
Loop：回到第一步，继续跑

终止条件通常包括：

模型输出了无 tool call 的最终回答
超过最大轮数
token 预算用尽
护栏触发
用户中断
安全拒绝

对于跨多个上下文窗口的长任务，Anthropic 还提出了一个两阶段 Ralph Loop 模式：先由 Initializer Agent 建好环境、初始化文件和进度记录；之后每一轮都由 Coding Agent 读取 git log 和 progress file，对齐现场后继续推进。文件系统正是跨窗口连续性的关键。

真实框架是怎么实现这套模式的

Anthropic

Anthropic 的 Claude Agent SDK 对外暴露的是一个query()入口，背后就是完整的 agentic loop。Claude Code 则更像 Gather-Act-Verify：

先收集上下文
再行动
然后验证结果
不对再继续循环

OpenAI

OpenAI 的 Agents SDK 通过 Runner 类实现 harness，并支持 async、sync、streamed 三种模式。Codex 又在此之上做了三层结构：

Codex Core
App Server
各种客户端界面（CLI、VS Code、Web）

因为三种入口共享同一套 harness，所以“Codex 在 Codex 自家界面里更顺”，并不只是模型问题，而是 harness 协同带来的体验差异。

LangGraph / LangChain

LangGraph 把 harness 建模成一张显式状态图。最基本的版本也许只有两个节点：llm_call和tool_node，然后通过条件边决定是否继续走工具分支。

LangChain 后来的 Deep Agents 也明确使用了 agent harness 这个说法：工具、planning、file system、subagent、persistent memory，全都算 harness 的一部分。

CrewAI

CrewAI 更强调多 agent 协作，把 Agent、Task 和 Crew 分开建模；它的 Flows 层承担确定性路由和验证骨架，而 Crews 层负责更自治的协作。

AutoGen / Microsoft Agent Framework

AutoGen 走的是 conversation-driven orchestration，后来逐步演化成 Microsoft Agent Framework。它支持顺序、并发、group chat、handoff、manager-led coordination 等不同编排模式。

脚手架隐喻，为什么很重要

“Scaffolding（脚手架）”这个比喻不是修辞，而是非常准确。

建筑脚手架本身不负责盖楼，但没有脚手架，工人就根本够不到更高的楼层。Harness 对 agent 的作用也是一样：它不直接做“智能”这件事，但它让模型可以到达原本根本到不了的工作层级。

更关键的是：脚手架不是永久保留的。

随着模型能力变强，部分 harness 复杂度应该下降。Manus 在六个月里重写了五次系统，每次都在删复杂度：复杂的工具定义逐渐退化成通用 shell 执行，“管理 agent” 被简化成结构化 handoff。

这就是一个很重要的共进化原则：

模型能力越强，harness 里一部分原本必须硬编码的 scaffold，就越可能被删掉。

但删，不等于不要；而是说，优秀 harness 的一个特征，是它未来可以被部分移除。

定义每个 Harness 的 7 个关键决策

最后总结了每个 harness 设计者都必须面对的七个选择。

1. 单 agent 还是多 agent

Anthropic 和 OpenAI 的共同建议都很保守：先把单 agent 做到极限，再考虑多 agent。

多 agent 一定会引入额外开销：

更多 LLM 调用
handoff 上下文损失
额外路由成本

只有当工具太多、任务域明显分裂时，才值得拆。

2. ReAct 还是 Plan-and-Execute

ReAct 是边想边做，灵活，但每一步都要重新决策；Plan-and-Execute 则先整体规划，再执行。不同任务下速度与稳定性的权衡不同。文中引用的 LLMCompiler 结果显示，后者相对顺序 ReAct 可以快 3.6 倍。

3. 上下文管理怎么做

常见生产策略包括：

定时清理
会话总结
observation masking
结构化记笔记
subagent delegation

ACON 的研究甚至表明，只要优先保留高价值推理痕迹，而不是完整工具输出，就能在保留 95% 以上准确率的同时，把 token 消耗降低 26% 到 54%。

4. 验证回路怎么设计

计算型验证（测试、lint）有确定真值；推断型验证（LLM as judge）能补语义层问题，但会增加延迟。Thoughtworks 团队用一个很好的说法来区分：

guides：事前引导
sensors：事后观测

5. 权限和安全是宽还是严

这是速度和风险之间的权衡。越宽松越快，但风险越大；越严格越安全，但越慢。怎么取，取决于部署环境。

6. 工具暴露到什么程度

工具不是越多越好。Vercel 曾经直接砍掉 80% 工具，结果表现反而更好。Claude Code 则靠 lazy loading 做到大约 95% 的上下文削减。

原则很简单：

当前步骤只暴露最小必要工具集。

7. Harness 到底要多厚

这其实是最底层的架构赌注：更多逻辑放在 harness，还是更多留给模型自己解决？

Anthropic 更偏薄 harness，赌模型会越来越强；图式框架和更显式控制的系统，则偏厚 harness，把逻辑提前编码好。

认为，随着模型迭代，Anthropic 甚至会不断删掉 Claude Code 里原本写死的 planning 步骤，因为新模型已经能把这些能力内化。

Harness 才是产品的一部分

即便两个产品用的是一模一样的模型，只要 harness 不同，表现就可能完全不同。TerminalBench 的证据已经很清楚：只改 harness，就足以把一个系统在榜单上往前推二十多名。

所以 harness 绝不是什么“已经商品化、无足轻重的一层”。真正难的工程，恰恰就在这里：

怎么把上下文当稀缺资源来管理
怎么设计验证回路，让错误别一路滚大
怎么做记忆系统，让连续性成立但不靠幻觉
怎么判断哪些 scaffold 该写死，哪些该留给模型

未来 harness 可能会变薄，但它不会消失。再强的模型，也仍然需要一套系统来：

管理上下文窗口
执行工具调用
持久化状态
验证工作结果

所以，下次你的 agent 失败时，别只怪模型。先看看 harness。

2026年AI行业最大的机会，毫无疑问就在应用层！

字节跳动已有7个团队全速布局Agent

大模型岗位暴增69%，年薪破百万！

腾讯、京东、百度开放招聘技术岗，80%与AI相关……

如今，超过60%的企业都在推进AI产品落地，而真正能交付项目的大模型应用开发工程师**，**却极度稀缺！

落地AI应用绝对不是写几个prompt，调几个API就能搞定的，企业真正需要的，是能搞定这三项核心能力的人：

✅RAG：融入外部信息，修正模型输出，给模型装靠谱大脑

✅Agent智能体：让AI自主干活，通过工具调用（Tools）环境交互，多步推理完成复杂任务。比如做智能客服等等……

✅微调：针对特定任务优化，让模型适配业务

目前，脉脉上有超过1000家企业发布大模型相关岗位，人工智能岗平均月薪7.8w！实习生日薪高达4000！远超其他行业收入水平！

技术的稀缺性，才是你「值钱」的关键！

具备AI能力的程序员，比传统开发高出不止一截！有的人早就转行AI方向，拿到百万年薪！👇🏻👇🏻

AI浪潮，正在重构程序员的核心竞争力！现在入场，仍是最佳时机！

我把大模型的学习全流程已经整理📚好了！抓住AI时代风口，轻松解锁职业新可能，希望大家都能把握机遇，实现薪资/职业跃迁～

这份完整版的大模型 AI 学习资料已经上传CSDN，朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【`保证100%免费`】

⭐️从大模型微调到AI Agent智能体搭建

剖析AI技术的应用场景，用实战经验落地AI技术。从GPT到最火的开源模型，让你从容面对AI技术革新！

大模型微调

掌握主流大模型（如DeepSeek、Qwen等）的微调技术，针对特定场景优化模型性能。
学习如何利用领域数据（如制造、医药、金融等）进行模型定制，提升任务准确性和效率。

RAG应用开发

深入理解检索增强生成（Retrieval-Augmented Generation, RAG）技术，构建高效的知识检索与生成系统。
应用于垂类场景（如法律文档分析、医疗诊断辅助、金融报告生成等），实现精准信息提取与内容生成。

AI Agent智能体搭建

学习如何设计和开发AI Agent，实现多任务协同、自主决策和复杂问题解决。
构建垂类场景下的智能助手（如制造业中的设备故障诊断Agent、金融领域的投资分析Agent等）。

如果你也有以下诉求：

快速链接产品/业务团队，参与前沿项目

构建技术壁垒，从竞争者中脱颖而出

避开35岁裁员危险期，顺利拿下高薪岗

迭代技术水平，延长未来20年的新职业发展！

……

那这节课你一定要来听！

因为，留给普通程序员的时间真的不多了！

立即扫码，即可免费预约

「AI技术原理 + 实战应用 + 职业发展」

「大模型应用开发实战公开课」

👇👇

👍🏻还有靠谱的内推机会+直聘权益！！

完课后赠送：大模型应用案例集、AI商业落地白皮书