Agent Harness 十二大模块完全解析：为什么生产级智能体的胜负手不在模型，而在“脚手架”

两个一模一样的模型，只因为外围基础设施的设计不同，最终表现可能天差地别。这套被称为Agent Harness的系统，正是 2026 年 AI 工程竞争真正的主战场。

一、从一个普遍的“翻车现场”说起

几乎每一个做过智能体（Agent）的人都遇到过同一个尴尬场景：在本地演示时，智能体行云流水、对答如流，任务一次成功；可一旦把它部署到真实的生产环境，立刻原形毕露——任务成功率断崖式下跌，原本流畅的多步推理变得磕磕绊绊，甚至中途彻底卡死。

面对这种落差，绝大多数开发者的第一反应几乎是一致的：模型不行，得换个更强的。于是不断追逐参数更大、榜单更高的新模型，期待“一换解千愁”。

但真相往往令人意外：问题从来不在模型本身，而在模型周围那套基础设施。

LangChain 团队用一个极具说服力的实验狠狠敲醒了整个行业：他们完全没有改动模型权重，也没有触碰任何底层算法，仅仅优化了包裹大语言模型的那层架构，就让智能体在 TerminalBench 2.0 评测中从 30 名开外一路飙升到第 5 名。另一支研究团队更进一步，让大模型自主优化这层架构，任务通过率直接冲到 76.4%，超越了所有人工精心设计的系统。

同一个模型，仅仅因为外围设计不同，性能就能拉开如此巨大的差距。这层决定成败的基础设施，就是本文的主角——Agent Harness（智能体运行框架，亦可直译为“智能体挽具/脚手架”）。

二、Agent Harness 到底是什么

2026 年初，「Agent Harness」这个术语才被全球 AI 社区正式定义并广泛传播。但它所代表的理念，其实早已渗透在每一个真正落地的生产级 AI 应用里，只是过去缺少一个统一的名字。

用一句话概括：Agent Harness 就是包裹大语言模型的一整套操作系统级软件基础设施。它的作用，是把一个只会输出文本、无状态、容易出错的“裸”大语言模型，改造成一个有目标、会用工具、能纠错、可长期稳定运行的可靠智能体。

LangChain 的 Vivek Trivedy 有一句被行业反复引用的话，精准道破了本质：

如果你不是在做模型，那你就是在做 Harness。

这句话戳中了一个常被忽视的事实：我们日常所说的“搭建一个智能体”，本质上从来不是去创造一个会思考的 AI，而是搭建一套 Harness，再把它对接给现成的模型。模型负责“思考”，Harness 负责让思考变成可靠的行动。

用计算机架构来类比

要理解 Harness，最贴切的方式是把它放进计算机体系结构里类比。这也是 AI 领域公认最直观的解释：

一颗再强的 CPU，如果没有内存、硬盘、外设驱动和操作系统，也只是一块无法做任何实事的硅片。裸模型同理：再强的推理能力，缺了 Harness，也只能停留在“输出一段文本”。

研究者 Beren Millidge 在 2023 年那篇《AI 的脚手架》中说得更直白：我们正在通过 Agent Harness，重新发明冯·诺依曼架构。这并非简单的技术封装，而是计算系统走向实用过程中一种近乎必然的抽象——任何 AI 智能体想要真正落地，都绕不开这层底层逻辑。

三、先理清三个容易混淆的工程层级

在拆解 Harness 之前，必须先厘清三个常被混为一谈的工程层级，否则很容易把 Harness 理解窄了。

1. 提示工程（Prompt Engineering）：专注于打磨发给模型的那段指令本身，让模型更精准地理解需求。这是最早被大众熟知的一层。
2. 上下文工程（Context Engineering）：核心在于管理模型在不同阶段“能看到哪些信息”，控制信息的取舍与时机，避免信息过载或关键信息缺失。
3. Harness 工程（Harness Engineering）：它涵盖前两者，并进一步囊括工具编排、状态持久化、错误恢复、验证循环、安全管控、生命周期管理等一整套应用级基础设施。

换句话说，提示工程和上下文工程都是 Harness 工程的子集。很多人误以为 Harness 不过是“给提示词套个壳”，这是彻底的误解。Harness 不是包装，而是一套让自主智能体能够自主思考、自主行动、自主修复的完整系统——它正是“玩具级 Demo”与“生产级智能体”之间的本质分水岭。

综合 Anthropic、OpenAI、LangChain 以及全球 AI 工程社区的最佳实践，可以归纳出一个清晰的结论：一个真正能落地的生产级 Agent Harness，由十二个相互独立又环环相扣的核心模块组成。少了任何一个，都难以支撑智能体的稳定运行。下面逐一拆解。

四、十二大核心模块逐一拆解

模块一：编排循环（Orchestration Loop）——智能体的心跳

编排循环是整个智能体的心跳，是所有行为的核心引擎。我们常听到的ReAct 循环，以及思考-行动-观察（Thought–Action–Observation，TAO）循环，本质上都是编排循环的具体实现。

它的运行逻辑非常清晰：

1. 组装完整提示词：把系统指令、工具信息、记忆内容、对话历史整合后发送给模型；
2. 等待模型输出，解析内容，判断是否需要调用工具；
3. 若需要，执行工具调用并把结果回传给模型；
4. 重复上述流程，直到任务完成或触发终止条件。

从代码结构看，编排循环往往只是一个朴素的while循环：

whilenotdone:prompt=assemble_prompt(system,tools,memory,history,user_msg)response=model.generate(prompt)ifresponse.has_tool_call:result=execute_tool(response.tool_call)# 执行工具history.append(result)# 观察结果回灌else:done=True# 无工具调用，输出最终答案

看似毫无技术含量，但真正的复杂度全部藏在“循环管理”的细节里，而非循环骨架本身。

Anthropic 对自家编排循环的定位很有意思——他们称之为**“笨循环（dumb loop）”**：所有的智能决策、逻辑推理都交给模型完成，Harness 运行时只负责按流程转场、调度任务，绝不插手核心推理。这种设计的妙处在于分工极其清晰：模型专注于“智能”，Harness 专注于“稳定”，从而大幅降低系统整体的复杂度。

无论是简单问答，还是复杂的代码重构、数据分析，所有智能体行为都始于编排循环，也终于编排循环。它是整个 Harness 架构的动力核心。

模块二：工具（Tools）——智能体的手

如果编排循环是心跳，那工具就是智能体的“手”，是它与现实世界交互的唯一途径。

工具绝不是随意的函数调用，而是以标准化 Schema形式定义的能力集合，至少包含：工具名称、功能描述、参数类型、返回格式。这套 Schema 会被注入模型上下文，让模型清楚地知道自己具备哪些操作能力。

工具层的职责远不止“调用”这么简单，它要完成一条完整的链路：

工具注册 → Schema 校验 → 参数提取 → 沙箱执行 → 结果捕获 → 格式化为模型可读的观察信息 → 回传编排循环

没有完善的工具层，模型推理能力再强，也只能停在文本输出，落不了地。

头部厂商早已构建起成熟的工具体系：

• Anthropic Claude Code提供六大类核心工具，覆盖文件操作、搜索、命令执行、网页访问、代码智能、子智能体孵化；
• OpenAI Agents SDK支持三类工具：函数调用工具、官方托管工具（联网搜索、代码解释器、文件检索等）、以及 MCP 服务器工具。

一个朴素但深刻的结论：工具层的设计，直接决定了智能体的能力边界。

模块三：记忆（Memory）——跨越时间的连续性

记忆让智能体不再像“只有七秒记忆的鱼”，得以跨越时间尺度、保持任务连续性。

Harness 的记忆体系不是单一存储，而是在多个时间维度上同时运作：

• 短期记忆：单次会话内的对话历史，记录当前任务的全部交互，确保多轮对话不脱节；
• 长期记忆：跨会话持久化，即便智能体重启、服务中断，也能保留此前的任务进度与决策记录。

不同框架的长期记忆实现各有特色：

• Anthropic：通过CLAUDE.md项目文件与自动生成的MEMORY.md实现持久化；
• LangGraph：采用按命名空间组织的 JSON 存储；
• OpenAI：支持基于 SQLite 或 Redis 的会话存储，兼顾性能与稳定。

其中 Claude Code 的三级记忆层级堪称行业标杆：

这里有一条极易被忽视却至关重要的设计原则：智能体绝不完全依赖记忆，而是把记忆当作一种“提示”。在行动前，它会与实际状态核对验证，从而避免因记忆陈旧或错误而导致任务失败。

模块四：上下文管理（Context Management）——最容易默默翻车的重灾区

这是生产级智能体最容易“悄无声息翻车”的地方，也是每位 AI 工程师都必须攻克的难题。核心痛点只有一个：上下文腐烂（Context Rot）。

斯坦福大学的《Lost in the Middle》研究与 Chroma 团队的实验相互印证了同一个结论：当关键信息落在上下文窗口的中间位置时，模型性能会暴跌 30% 以上。即便如今主流模型已支持百万级 Token 上下文，随着内容不断膨胀，模型的指令遵循能力与推理准确率仍会持续下滑。

生产环境为此沉淀出一套成熟的应对策略：

1. 压缩（Compaction）：当上下文接近上限时，对对话历史做摘要，保留核心决策与未解决的问题，丢弃冗余的工具输出；
2. 观察屏蔽（Observation Masking）：隐藏旧的工具输出细节，但保留工具调用记录，既省 Token 又不丢关键逻辑；
3. 即时检索（Just-in-time Retrieval）：维护轻量级索引，动态加载所需数据。例如 Claude Code 用grep、glob、head、tail精准提取片段，而非加载整个文件；
4. 子智能体委派（Sub-agent Delegation）：把复杂探索任务拆给子智能体，最终只回传 1000–2000 Token 的精简摘要，大幅减轻主智能体的上下文压力。

Anthropic 在其上下文工程指南中给出了这一步的终极目标：找到最小的、高信噪比的 Token 集合——用最少的关键信息，最大化达成预期效果。这就是上下文管理的核心准则。

模块五：提示词组装（Prompt Assembly）——定义模型“看到的世界”

提示词组装定义了模型在每一轮推理中所看到的世界，是连接上下文、记忆、工具与用户需求的最后一环。

它绝不是简单拼接，而是一个分层堆叠、优先级明确的结构化过程。标准组装顺序通常是：

1. 系统提示词：定义智能体的身份与核心规则；
2. 工具定义：告知当前可用的能力；
3. 记忆文件：总结历史经验；
4. 对话历史：获取当前任务进度；
5. 用户消息：得到最新需求。

OpenAI 的 Codex 则采用了一套严格的优先级栈：服务器控制的系统消息优先级最高，随后依次是工具定义、开发者指令、用户指令，最后才是对话历史。这种自上而下的优先级设计，确保核心规则不会被后续冗余信息覆盖，让智能体行为始终不偏离预期。

实践中，提示词组装的质量直接影响模型输出的准确率，是 Harness 工程里最考验工程师“细节把控力”的环节。

模块六：工具调用与结构化输出（Tool Calling & Structured Output）——人机之间的通用语言

这是模型与 Harness 之间的“通用语言”，解决了传统自由文本输出难以解析、容易出错的老问题。

现代生产级 Harness 完全依赖原生工具调用：模型不再输出模糊的自然语言指令，而是直接返回标准化的tool_calls结构化对象，里面明确包含工具名称、参数值等信息。如此一来，Harness 的判断逻辑就变得极其简单：

ifresponse.tool_calls:run(response.tool_calls)# 有工具调用：执行并继续循环else:returnresponse.content# 无工具调用：直接作为最终答案

对于结构化输出，OpenAI 与 LangChain 都支持通过Pydantic进行 Schema 约束，确保输出格式符合预期、降低解析失败率。

frompydanticimportBaseModelclassTicket(BaseModel):category:strpriority:intowner:str# 模型输出会被强制约束为该结构，解析失败率大幅下降

一些遗留方案在边缘场景仍有价值，比如RetryWithErrorOutputParser：它会把原始提示词、失败输出和解析错误一并回传给模型，让模型自行修正。但这种方式效率较低，只建议作为兜底补充。

模块七：状态与检查点（State & Checkpointing）——断点续跑的底气

状态与检查点是智能体实现断点续跑、可回溯、可调试的核心，专门解决长周期任务中断后无法恢复的痛点。

大型项目的代码重构、多步骤数据分析等长流程任务，可能持续数小时甚至数天。一旦中途崩溃而又没有状态保存，所有进度瞬间归零。各框架的方案差异明显：

• LangGraph：把状态建模为类型化字典，通过归约器（reducer）合并状态更新，检查点在“超级步骤”边界触发，支持中断后无缝恢复，甚至能实现“时光倒流”式调试；
• OpenAI：提供四种互斥策略——应用内存、SDK 会话、服务器端对话 API，以及轻量级的previous_response_id链式调用，适配不同部署场景；
• Claude Code：设计极具特色——用Git 提交作为检查点，用进度文件作为结构化草稿本，借助 Git 的版本控制能力实现任务进度的精准回溯。

模块八：错误处理（Error Handling）——对抗“雪球效应”的安全网

很多人忽视了一个残酷的数学事实：一个 10 步的任务流程，即便每步成功率高达 99%，端到端总成功率也只有约90.4%（0.99¹⁰）。错误会像滚雪球一样层层放大，最终拖垮整个任务。

因此，生产级 Harness 必须建立完善的错误分类与处理机制。LangGraph 的四类划分堪称典范：

Anthropic 的策略更侧重流程稳定性：在工具处理器内部捕获所有失败，把错误结果返回给模型，确保主编排循环永不中断。Stripe 的生产级 Harness 则更为保守，将重试次数严格限制在两次以内，避免无限重试引发资源耗尽。

模块九：护栏（Guardrails）——不可逾越的安全红线

护栏是智能体的安全红线，用于防止越权、有害或违规操作，是企业级应用的核心保障。

OpenAI SDK 实现了三层防护：

• 输入护栏：在接收用户请求时运行，过滤恶意与违规输入；
• 输出护栏：在最终输出前运行，确保内容合规安全；
• 工具护栏：每次调用工具时运行，管控调用权限、拦截高风险操作。

一旦触发护栏的“绊线（tripwire）”机制，智能体会立即终止当前操作，实现紧急制动。

Anthropic 的护栏设计更为彻底——在架构层面就把权限执行与模型推理完全解耦：模型只负责思考“想做什么”，工具系统负责判断“能做什么”，两者互不干扰。Claude Code 可独立管控约 40 种离散工具能力，并分三阶段严格把关：项目加载时建立信任体系、每次调用工具前检查权限、高风险操作必须获得用户明确确认。

模块十：验证与反馈（Verification & Feedback）——玩具与生产的分水岭

这是玩具级与生产级智能体的真正分水岭：没有验证的智能体，其输出永远不可信。

Anthropic 推荐三种通用验证方式：

1. 基于规则的反馈：用测试用例、Linter、类型检查器等确定性工具验证结果的正确性；
2. 视觉反馈：借助 Playwright 等工具截图，检查 UI 任务或可视化操作的完成效果；
3. 让模型当裁判（LLM-as-a-Judge）：用独立的子智能体，从语义、逻辑、效果等维度评估主智能体的输出。

Claude Code 的创始人 Boris Cherny 明确指出：给智能体加入“验证自身工作”的机制，能让输出质量提升2 到 3 倍。验证循环从来不是额外开销，而是保证智能体真正产出价值的必要投入。

模块十一：子智能体编排（Subagent Orchestration）——从单兵到集群

子智能体编排，可以把单个智能体升级为“智能体集群”，从而应对复杂、大规模、跨领域的任务。当任务涉及多个专业领域、工具数量过多、流程过于冗长时，单个智能体性能会显著下降，此时子智能体编排往往是最优解。

主流框架都有成熟方案：

• Claude Code：支持三种执行模式——Fork（创建父上下文的精确副本）、Teammate（通过独立终端面板通信）、Worktree（为每个 Agent 分配独立的 Git 工作树）；
• OpenAI SDK：支持两种模式——Agents-as-tools（专家 Agent 处理细分任务）与 Handoffs（任务全面交接）；
• LangGraph：将子 Agent 实现为嵌套状态图，通过图结构管理任务流转。

模块十二：初始化与环境搭建（Initialization & Environment Setup）——让一切有序启动

这是所有模块协同工作的起点，定义了智能体从启动到运行的完整生命周期。通过一个标准执行周期，可以看清各模块是如何联动的：

1. 提示词组装：整合系统提示、工具 Schema、记忆文件、对话历史、用户消息，构建完整输入；
2. 模型推理：把组装好的提示词发给模型，生成文本或工具调用；
3. 输出分类：判断是需要工具调用、任务交接，还是直接输出答案；
4. 工具执行：校验参数、检查权限、沙箱运行——只读操作并发、写操作串行；
5. 结果打包：把工具结果与错误信息格式化为模型可读消息；
6. 上下文更新：将结果追加到对话历史，必要时触发上下文压缩；
7. 循环执行：回到第一步，直到满足终止条件。

终止条件是多层级的，包括：模型输出无工具调用、达到最大轮次、Token 预算耗尽、护栏触发、用户中断、安全拒绝等等。简单任务 1–2 轮即可完成，复杂的重构任务可能需要几十轮循环、串联几十次工具调用——而这一切的有序推进，全靠初始化与环境搭建在背后兜底。

五、五大主流框架：同一套模块，不同的设计哲学

拆完十二大模块，再来看全球主流框架是如何落地 Agent Harness 的。它们的核心模式高度趋同，但设计哲学截然不同。

Anthropic Claude Agent SDK——“薄 Harness”哲学的极致

核心是信任模型、简化框架。通过query()函数创建智能体循环，运行时是极简的“笨循环”，遵循 Gather–Act–Verify（收集→执行→验证）流程；状态管理用 Git 提交；多智能体支持 Fork、Teammate、Worktree 三种模式。优势是轻量、高效、与模型深度耦合。

OpenAI Agents SDK——代码优先，开发者友好

采用代码优先理念，通过Runner类实现 Harness，支持异步、同步、流式三种运行模式；工作流用原生 Python 编写，无需学习专用的图 DSL；状态管理提供四种策略；多智能体支持 Agents-as-tools 与 Handoffs。侧重快速落地，适合快速开发生产级应用。

LangGraph——图结构，显式可控

从 LangChain 进化而来，采用图结构设计，把 Harness 建模为显式状态图，通过llm_call与tool_node两个节点加条件边来控制流程，支持嵌套状态图。侧重显式流程控制与可调试性，适合复杂、多分支的长流程任务。

CrewAI——基于角色的多智能体协作

主打基于角色的多智能体架构，将智能体、任务、团队三者解耦，通过 Flows 层实现路由与验证。侧重多智能体协作与角色分工，适合团队式、多角色的复杂任务场景。

AutoGen（现微软智能体框架）——对话驱动编排

开创了“对话驱动编排”的先河，支持顺序、并发、群组聊天、交接、Magentic 五种编排模式，核心是把“对话”当作协作协议。适合开放式、多智能体交互的场景。

下面这张表，便于横向对比：

没有绝对的优劣，只有场景的适配——这是选型时最该牢记的一句话。

六、脚手架隐喻：Harness 与模型的“共同进化”

理解了模块与框架，还需要理解一条决定未来走向的规律。

建筑工地上的脚手架是临时基础设施：它帮助工人完成施工，大楼一旦建成便会被拆除。Agent Harness 也是如此——它是让模型落地为智能体的临时支撑。一个反直觉但极其重要的判断是：模型能力越强，Harness 的复杂度反而应该越低。

行业实践已经验证了这一点。Manus 项目在半年内重构了五次，每一次都在做减法：把复杂的工具定义简化为通用的 Shell 执行，把臃肿的管理智能体简化为结构化交接——结果性能不降反升。

这背后正是共同进化（Co-evolution）原则：现代大模型在后训练阶段会把特定 Harness 纳入训练循环，使模型与框架深度耦合。模型内化的能力越多，Harness 需要的封装就越少。

由此可以推导出一条优秀 Harness 的设计准则——它必须通过**“面向未来的测试”**：当模型升级后，智能体性能应当自然提升，而无需增加 Harness 的复杂度。未来趋势已然清晰：更薄的 Harness、更强的模型、更模块化的架构。

七、七大架构抉择：每位 AI 工程师的核心考题

搭建 Agent Harness，绕不开七个关键的架构抉择。它们没有标准答案，却决定着系统的成败。

抉择一：单智能体 vs 多智能体。行业共识是先榨干单智能体的性能。多智能体存在额外开销，只有当工具重叠超过 10 个、或任务域明显分离时，才考虑拆分。

抉择二：ReAct 循环 vs 计划-执行循环。ReAct 灵活，但每一步成本高；计划-执行把规划与执行分离，LLMCompiler 的数据显示其比顺序 ReAct 快 3.6 倍。任务越确定、步骤越可预测，越适合计划-执行。

抉择三：上下文管理策略。五种方法可选——基于时间清理、对话摘要、观察掩码、结构化笔记、子智能体委派。核心原则是：保留推理痕迹，减少 Token 消耗。

抉择四：验证循环设计。计算式验证（测试、Linter）提供确定性，推理式验证（让模型当裁判）解决语义问题。两者结合，效果最佳。

抉择五：权限与安全。宽松模式高效但有风险，严格模式安全但低效，需要根据部署场景在二者间权衡。

抉择六：工具范围。一条反直觉的规律：工具越多，性能往往越差。Vercel 砍掉 80% 的工具后，性能反而提升。原则是只暴露“当前步骤所需的最小工具集”。

抉择七：Harness 的厚度。薄 Harness 依赖对模型的信任，厚 Harness 依赖编码来控制逻辑。模型越强，越应偏向薄 Harness。

八、结语：先别急着责怪模型

回到最初的问题——为什么有的智能体演示时无比流畅，一到生产环境就频频翻车？

答案从来不是“模型不行”，而是Harness 的架构不够完善。两个一模一样的模型，仅因 Harness 设计不同，表现就可能天差地别。

2026 年的 AI 竞争，早已不再是单纯比拼模型参数的内卷，而是 Harness 工程的较量：

• 如何把上下文当作稀缺资源来精细管理；
• 如何设计能拦截错误、对抗雪球效应的验证循环；
• 如何构建不产生幻觉的记忆系统；
• 如何在脚手架的厚度与模型的能力之间找到平衡。

这些，才是 AI 工程化真正难啃的硬骨头。

所以，下一次当你的智能体掉链子时，先别急着责怪模型——低头看看它的 Harness，问题大概率就藏在那里。