5千字长文：一篇看懂 Agent Harness 的结构！

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

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

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 用的是严格优先级栈：

1. 服务器控制的 system message
2. 工具定义
3. developer instructions
4. user instructions
5. 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. 循环如何真正跑起来

把完整流程拆成七步：

1. Prompt Assembly：system prompt + tools + memory + history + 当前消息
2. LLM Inference：模型生成文本、tool call 或 handoff
3. Output Classification：判断是最终回答、工具调用还是 handoff
4. Tool Execution：校验参数、检查权限、在沙箱中执行、获取结果
5. Result Packaging：把结果重新格式化成模型可读消息
6. Context Update：把结果追加进历史，必要时 compaction
7. 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。

学AI大模型的正确顺序，千万不要搞错了

🤔2026年AI风口已来！各行各业的AI渗透肉眼可见，超多公司要么转型做AI相关产品，要么高薪挖AI技术人才，机遇直接摆在眼前！

有往AI方向发展，或者本身有后端编程基础的朋友，直接冲AI大模型应用开发转岗超合适！

就算暂时不打算转岗，了解大模型、RAG、Prompt、Agent这些热门概念，能上手做简单项目，也绝对是求职加分王🔋

📝给大家整理了超全最新的AI大模型应用开发学习清单和资料，手把手帮你快速入门！👇👇

学习路线:

✅大模型基础认知—大模型核心原理、发展历程、主流模型（GPT、文心一言等）特点解析
✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑
✅开发基础能力—Python进阶、API接口调用、大模型开发框架（LangChain等）实操
✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用
✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代
✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经

以上6大模块，看似清晰好上手，实则每个部分都有扎实的核心内容需要吃透！

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

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