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 校验参数提取沙箱内执行结果捕获再把结果格式化成模型能继续读懂的 observationClaude Code 把工具分成文件操作、搜索、执行、网页访问、代码智能和 subagent 六类OpenAI 的 Agents SDK 支持 function tools、hosted tools 和 MCP tools。3. 记忆Memory记忆不是单一概念而是多层次的。短期记忆单次会话里的历史消息长期记忆跨会话持久存在的内容Anthropic 用CLAUDE.md、自动生成的MEMORY.md等文件承载长期记忆LangGraph 用带命名空间的 JSON StoreOpenAI 支持用 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 instructionsuser instructionsconversation history这里的关键不只是“把东西拼起来”而是决定什么内容放在哪里、优先级怎么排。6. 输出解析Output Parsing现在更成熟的 harness 会优先依赖原生 tool calling而不是自由文本解析。也就是说模型不再随便输出一段像工具调用的文本而是直接返回结构化的 tool_calls 对象。Harness 在这里要判断有 tool call 吗有就执行并继续循环没有 tool call 吗那就是最终回答如果要输出结构化结果OpenAI 和 LangChain 都支持通过 Pydantic schema 约束模型输出。7. 状态管理State ManagementLangGraph 把状态建模成一个在 graph 节点间流动的 typed dictionaryOpenAI 则给出四种不同策略应用内存、SDK session、服务器侧 Conversations API、以及更轻量的 previous_response_id 链接。Claude Code 的思路更工程化git commit 是 checkpointprogress file 是结构化 scratchpad。也就是说状态不一定非得是数据库也可以是文件系统和 Git 自然形成的工作痕迹。8. 错误处理Error Handling只要任务是多步的错误就会累积。一个 10 步流程即便每一步有 99% 成功率最终端到端成功率也只有大约 90.4%。LangGraph 把错误分成四类瞬时错误重试模型可恢复错误把错误作为 ToolMessage 返回让模型调整需要用户处理的错误中断并请求用户输入非预期错误直接上浮方便调试Anthropic 的策略是尽量在 tool handler 里把错误包装成错误结果继续让主循环跑下去。Stripe 的生产 harness 甚至把重试次数限制在两次以内避免无限折腾。9. 安全护栏Guardrails and SafetyOpenAI 的 SDK 把护栏做成三层输入护栏输出护栏工具护栏一旦触发 tripwire就立即中止 agent。Anthropic 则更强调权限与推理的分离模型决定想做什么工具系统决定允许它做什么。Claude Code 大约对 40 种工具能力分别设权限并分成三层检查项目加载时建立信任、每次 tool call 前检查权限、高风险操作时要求用户确认。10. 验证回路Verification Loops这是玩具 demo 和生产系统之间最关键的差异之一。Anthropic 推荐三种验证方式规则型反馈测试、lint、type check视觉反馈比如 Playwright 截图来验证 UILLM as judge单独起一个评审 agentBoris Cherny 甚至说过只要给模型一个验证自己结果的办法质量可以提升 2 到 3 倍。11. 子 Agent 编排Subagent OrchestrationClaude Code 支持三种模式Fork完整复制父上下文Teammate单独终端窗格通过文件通信Worktree单独 git worktree拥有独立分支OpenAI 的 Agents SDK 支持 agents-as-tools 和 handoffsLangGraph 则可以把 subagent 建成嵌套状态图。子 agent 的本质不是“把事情搞复杂”而是在上下文、工具和任务域明显开始冲突时把任务隔离出去。12. 循环如何真正跑起来把完整流程拆成七步Prompt Assemblysystem prompt tools memory history 当前消息LLM Inference模型生成文本、tool call 或 handoffOutput Classification判断是最终回答、工具调用还是 handoffTool Execution校验参数、检查权限、在沙箱中执行、获取结果Result Packaging把结果重新格式化成模型可读消息Context Update把结果追加进历史必要时 compactionLoop回到第一步继续跑终止条件通常包括模型输出了无 tool call 的最终回答超过最大轮数token 预算用尽护栏触发用户中断安全拒绝对于跨多个上下文窗口的长任务Anthropic 还提出了一个两阶段 Ralph Loop 模式先由 Initializer Agent 建好环境、初始化文件和进度记录之后每一轮都由 Coding Agent 读取 git log 和 progress file对齐现场后继续推进。文件系统正是跨窗口连续性的关键。真实框架是怎么实现这套模式的AnthropicAnthropic 的 Claude Agent SDK 对外暴露的是一个query()入口背后就是完整的 agentic loop。Claude Code 则更像 Gather-Act-Verify先收集上下文再行动然后验证结果不对再继续循环OpenAIOpenAI 的 Agents SDK 通过 Runner 类实现 harness并支持 async、sync、streamed 三种模式。Codex 又在此之上做了三层结构Codex CoreApp Server各种客户端界面CLI、VS Code、Web因为三种入口共享同一套 harness所以“Codex 在 Codex 自家界面里更顺”并不只是模型问题而是 harness 协同带来的体验差异。LangGraph / LangChainLangGraph 把 harness 建模成一张显式状态图。最基本的版本也许只有两个节点llm_call和tool_node然后通过条件边决定是否继续走工具分支。LangChain 后来的 Deep Agents 也明确使用了 agent harness 这个说法工具、planning、file system、subagent、persistent memory全都算 harness 的一部分。CrewAICrewAI 更强调多 agent 协作把 Agent、Task 和 Crew 分开建模它的 Flows 层承担确定性路由和验证骨架而 Crews 层负责更自治的协作。AutoGen / Microsoft Agent FrameworkAutoGen 走的是 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 还是多 agentAnthropic 和 OpenAI 的共同建议都很保守先把单 agent 做到极限再考虑多 agent。多 agent 一定会引入额外开销更多 LLM 调用handoff 上下文损失额外路由成本只有当工具太多、任务域明显分裂时才值得拆。2. ReAct 还是 Plan-and-ExecuteReAct 是边想边做灵活但每一步都要重新决策Plan-and-Execute 则先整体规划再执行。不同任务下速度与稳定性的权衡不同。文中引用的 LLMCompiler 结果显示后者相对顺序 ReAct 可以快 3.6 倍。3. 上下文管理怎么做常见生产策略包括定时清理会话总结observation masking结构化记笔记subagent delegationACON 的研究甚至表明只要优先保留高价值推理痕迹而不是完整工具输出就能在保留 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%免费】