你一定见过这种场景：
本地演示，行云流水，掌声四起。一上生产，任务成功率断崖式下跌。老板问你怎么回事，你第一反应是——模型不行，得换个更强的。
这个判断，大概率是错的。
LangChain 做过一个实验，专门戳破这个认知。他们一行模型权重没改，只优化了包裹模型的那层架构，智能体在 TerminalBench 2.0 评测里直接从 30 名开外飙到第 5 名。另一个研究团队走得更远，让模型自己去优化这层架构，任务通过率冲到了 76.4%，把所有人工设计的系统都比了下去。
问题从来不在模型。问题在模型外面的那套东西——Agent Harness。
Harness 是什么
LangChain 联合创始人 Vivek Trivedy 说过一句被反复引用的话：如果你不是模型，你就是 Harness。
这话看起来像废话，但它说清楚了一件事：你日常说的"搭建一个智能体"，本质上不是在创造一个会思考的 AI，而是在搭一套 Harness，再把它对接给模型。
用计算机架构来类比最直观。裸的大语言模型就像一颗没有内存、没有硬盘、没有驱动的 CPU，只有核心计算能力，什么实际任务都干不了。上下文窗口是临时内存，快但有限；向量数据库是硬盘，大但慢；工具集成是驱动程序，让模型能操控外部世界。而 Harness，就是让这一切协同工作的操作系统。
2023 年，研究者 Beren Millidge 写过一篇文章说：我们用 Agent Harness 重新发明了冯·诺依曼架构。这不是夸张，是对这件事本质的准确描述。
综合 Anthropic、OpenAI、LangChain 和全球工程社区的实践，一个真正能扛住生产环境的 Agent Harness，需要十二个模块。少一个，稳定性就打折扣。
一、编排循环：智能体的心跳
编排循环是整套系统的动力核心，我们常说的 ReAct 循环、思考-行动-观察（TAO）循环，都是它的具体实现形式。
它的运行逻辑很清晰：先把系统指令、工具信息、记忆内容、对话历史整合成完整提示词发给模型，模型输出后判断是否需要调用工具，调用后把结果返回，再发给模型，重复这个流程，直到任务完成或触发终止条件。
从代码结构上看，它往往就是一个 while 循环，简单得出乎意料。所有的复杂度全藏在循环管理的细节里，不在循环本身。
Anthropic 把自家的编排循环叫做"笨循环"（dumb loop）——所有的智能决策、逻辑思考都由模型完成，Harness 的运行时只负责按流程转场、调度任务，不参与核心推理。这个分工的好处是模型专注输出，Harness 专注执行，系统复杂度大幅降低。
所有智能体的行为，都始于编排循环，也终于编排循环。
二、工具层：智能体的手
如果说编排循环是心跳，工具就是智能体的手——与现实世界交互的唯一途径。
工具不是随便写几个函数扔进去。它是以标准化 Schema 形式定义的能力集合，包含工具名称、功能描述、参数类型、返回格式，通过注入上下文让模型清楚自己具备哪些操作能力。
工具层的职责也远不止"调用"两个字。它还要完成工具注册、Schema 校验、参数提取、沙箱执行、结果捕获，最后把执行结果格式化成模型能读懂的观察信息，再回传给编排循环。没有这层，模型推理能力再强，也只能停留在文字输出，落地不了任何实际操作。
各家的工具设计思路有明显差异。Claude Code 提供六大类核心工具：文件操作、搜索、命令执行、网页访问、代码智能、子智能体孵化。OpenAI Agents SDK 支持三类：函数调用工具、官方托管工具（包括联网搜索、代码解释器、文件检索），以及 MCP 服务器工具。工具层的设计边界，直接决定了智能体的能力边界。
三、记忆：别让它像金鱼一样
记忆模块让智能体能跨越时间尺度保持任务连续性。没有它，智能体每次启动都是白板，什么都不记得。
Harness 的记忆体系不是单一存储，而是在多个时间维度同时运作，分短期和长期两层。短期记忆就是当前会话的对话历史，记录所有交互，保证模型在多轮对话里不脱节。长期记忆实现跨会话持久化，即便服务重启、智能体崩溃，之前的任务进度和决策记录依然在。
各框架的长期记忆实现各有特色：Anthropic 通过 claude.md 项目文件和自动生成的 MEMORY.md 持久化；LangGraph 按命名空间组织 JSON 存储；OpenAI 支持基于 SQLite 或 Redis 的会话存储。
Claude Code 的三级记忆层级被视为行业标杆。第一级是轻量索引，单条约 150 个字符，常驻内存，快速响应；第二级是详细主题文件，按需加载，平衡容量与速度；第三级是原始交互记录，只通过搜索访问，保证数据完整性。
这里有一个关键的设计原则：智能体不能完全依赖记忆，而是把它当作一种提示，行动前要与实际状态核对验证，避免因记忆出错导致任务失败。
四、上下文管理：生产环境最容易默默翻车的地方
这是所有 AI 工程师必须正面应对的难题，也是生产环境里最常见的"沉默杀手"。
核心问题叫上下文腐烂（Context Rot）。斯坦福大学的《Lost in the Middle》研究和 Chroma 团队的实验结论一致：当关键信息落在上下文窗口的中间位置时，模型性能会暴跌 30% 以上。即便现在主流模型支持百万级 Token 的上下文，随着内容不断膨胀，指令遵循能力和推理准确率仍然会持续下滑。
当前，生产环境里已经形成了四种成熟应对策略：
压缩（Compaction）：上下文接近上限时，对对话历史做摘要处理，保留核心决策和未解决的问题，丢弃冗余的工具输出。
观察屏蔽（Observation Masking）：隐藏旧的工具输出细节，但保留工具调用记录。这样既能减少 Token 消耗，又不丢失关键逻辑链条。
即时检索（Just-in-time Retrieval）：维护轻量级索引，动态加载所需数据。Claude Code 的做法是用 grep、glob、head、tail 命令精准提取内容，而不是把整个文件塞进上下文。
子智能体委派：把复杂的探索任务拆给子智能体，最终只返回 1000 到 2000 个 Token 的精简摘要，大幅降低主智能体的上下文压力。
Anthropic 在上下文工程指南里定义了这个模块的终极目标：找到最小的高信噪比 Token 集合 ——用最少的关键信息，最大化完成任务效果。
五、提示词组装：连接一切的最后一环
提示词组装决定了模型在每一轮推理中看到的世界，是连接上下文、记忆、工具、用户需求的汇聚点。
它不是把各种信息拼在一起那么简单，而是一个分层堆叠的结构化过程，优先级需要非常明确。标准的组装顺序是：先通过系统提示词定义智能体的身份和核心规则，再通过工具定义告知可用的能力，然后导入记忆文件提供历史经验，接着是对话历史记录当前进度，最后才是用户的最新消息。
OpenAI 的 Codex 采用了严格的优先级栈设计：服务器控制的系统消息优先级最高，随后依次是工具定义、开发者指令、用户指令，对话历史放在最后。这种顺序确保核心规则不会被后续内容覆盖，智能体行为不偏离预期。
提示词组装的质量，直接影响模型的输出准确率，是 Harness 工程里最考验细节把控的环节。
六、结构化输出：模型与系统的通用语言
这个模块解决了一个老问题：传统自由文本输出，解析困难，容易出错。
现代生产级 Harness 完全依赖原生工具调用，模型不再输出模糊的自然语言指令，而是直接返回标准化的 tool_calls 结构化对象，包含工具名称和参数值等明确信息。Harness 的判断逻辑随之变得极为简单：解析模型输出，如果有 tool_calls 就执行工具并继续循环，没有就把模型输出当做最终答案，终止循环。
OpenAI 和 LangChain 都支持通过 Pydantic 框架做 Schema 约束，确保输出格式符合预期，降低解析失败率。
有一个叫 RetryWithErrorOutputParser 的遗留方案，遇到解析失败会把原始提示词、失败输出和错误信息一起发回给模型，让它自己修正。这种方式效率较低，只适合做补充方案，不应该作为主路径。
七、状态与检查点：长任务的救命稻草
一个大型代码库的重构任务，可能要跑几个小时甚至几天。跑到一半系统崩溃，如果没有状态保存，所有进度归零。这是状态与检查点模块要解决的问题。
各框架的实现方式差别明显。LangGraph 把状态建模为类型化字典，通过归约器合并状态更新，检查点在超级步骤边界触发，支持崩溃后无缝恢复，甚至能实现"时光倒流"式的调试，把系统状态回退到任意历史节点。OpenAI 提供四种互斥的状态策略：应用内存、SDK 会话、服务器端对话 API，以及轻量级的 previous_response_id 链式调用，适配不同部署场景。
Claude Code 的方案最有特色：用 Git 提交作为检查点，用进度文件作为结构化草稿本。借助 Git 天然的版本控制能力，任务进度的精准回溯和管理变得极为自然。
八、错误处理：被忽视的数学问题
很多开发者没想过这道算术题：一个 10 步的任务流程，即便每一步成功率高达 99%，端到端的总成功率也只有大约 90.4%。错误会像滚雪球一样不断放大，任务越长，问题越严重。
LangGraph 的错误分类被视为行业典范，把所有错误分成四类：
瞬时错误，比如网络波动、API 限流，用带退避策略的重试机制处理。
模型可恢复错误，比如参数错误、逻辑失误，把错误包装成工具消息返回给模型，让模型自主调整。
用户可修复的错误，比如权限不足或配置错误，中断流程等待人工介入。
意外错误，比如系统崩溃或底层异常，直接抛出，便于调试，不要试图自动恢复。
Anthropic 的策略更侧重流程稳定性：在工具处理器内部捕获所有失败，把错误结果返回给模型，确保主编排循环不中断。Stripe 的生产实践则更保守，把重试次数严格限制在两次以内，避免无限重试耗尽资源。
九、护栏：智能体的安全红线
护栏防止智能体做出越权、有害、违规操作，是企业级应用的核心保障，不是可选项。
OpenAI SDK 实现了三层防护：输入护栏在智能体接收用户请求时运行，过滤恶意和违规输入；输出护栏在最终输出前运行，确保内容合规安全；工具护栏在每次工具调用时运行，管控权限，拦截高风险操作。一旦触发绊线机制，智能体立即终止当前操作。
Anthropic 的护栏设计在架构层面做了更彻底的分离：权限执行与模型推理完全解耦。模型只负责思考想做什么，工具系统负责判断能做什么，两者互不干扰。Claude Code 独立管控大约 40 种离散的工具能力，分三个阶段把关：项目加载时建立信任体系，每次调用工具前检查权限，高风险操作必须获得用户的明确确认。
十、验证与反馈：玩具和生产之间的分水岭
没有验证机制的智能体，输出结果永远不可信。这是玩具级 demo 和生产级智能体之间最核心的区别。
Claude Code 的创始人 Boris Cherny 说过，给智能体加入验证自身工作的机制，能让输出质量提升 2 到 3 倍。
Anthropic 推荐三种验证方式配合使用：
基于规则的反馈：通过测试用例、Linter 代码检查、类型检查器等确定性工具验证结果，有没有问题一目了然。
视觉反馈：借助 Playwright 等工具截图，检查 UI 任务或可视化操作的完成效果，适合界面相关的任务场景。
让模型当裁判：用独立的子智能体评估主智能体的输出，从语义、逻辑、效果等多个维度给出反馈。
验证循环不是额外开销，是保证智能体产出价值的必要投入。
十一、子 Agent 编排：从个体到集群
当任务涉及多个专业领域、工具数量过多、流程过于复杂时，单个智能体的性能会显著下降。子 Agent 编排让单个智能体升级为协作集群。
Claude Code 提供三种执行模式：Fork 模式创建父上下文的精确副本；Teammate 模式通过独立终端面板通信；Worktree 模式为每个 Agent 分配独立的 Git 工作树，并行开展工作互不干扰。
OpenAI 的 SDK 支持两种模式：Agents-as-tools 让专家 Agent 处理细分任务，Handoffs 模式实现任务的全面交接。LangGraph 则将子 Agent 实现为嵌套状态图，通过图结构管理任务流转。
十二、初始化与环境搭建：所有事情的起点
最后这个模块是其他十一个模块协同工作的起点，定义了智能体从启动到终止的完整生命周期。
一次标准的执行周期分七步走：
- 提示词组装：整合系统提示、工具 Schema、记忆文件、对话历史、用户消息，构建完整输入。
- 模型推理：将组装好的提示词发送给模型，生成输出。
- 输出分类：判断是需要工具调用、任务交接，还是直接输出答案。
- 工具执行：校验参数，检查权限，沙箱运行。只读操作并发，写操作串行。
- 结果打包：把执行结果和错误信息格式化为模型可读消息。
- 上下文更新：追加结果到对话历史，判断是否触发压缩。
- 回到第一步，重复，直到满足终止条件。
终止条件是多层次的：模型输出里没有工具调用、达到最大轮次、Token 预算耗尽、护栏触发、用户中断、安全拒绝……任何一个触发，循环终止。
简单的问答任务，一两轮就结束；复杂的大型重构任务，可能需要几十轮循环、串联几十次工具调用，全靠这个模块保证流程有序推进。
十二个模块，没有哪个是装饰品。
编排循环是心跳，工具是手，记忆是大脑，上下文管理是注意力，提示词组装是每轮思考的起点，结构化输出是表达，状态检查点是记性，错误处理是反应神经，护栏是底线，验证反馈是自省，子 Agent 编排是协作，初始化是生命周期的容器。
下次你的智能体在生产上掉链子，先别去模型市场转一圈。低头看看 Harness，缺的大概就是这里面的某一块。
两个用同款模型跑的智能体，Harness 设计不同，性能可能天差地别。2026 年 AI 的竞争，早就不只是谁的参数多了。
