Agent Harness：构建生产级AI智能体的核心基础设施

你是不是也遇到过这样的情况：花了不少精力搭建的AI聊天机器人，在演示时能精准响应、调用工具完成简单任务，可一旦想做成生产级应用，各种问题就接踵而至——模型转头就忘了前几步做了什么，工具调用悄无声息地失败，上下文窗口里堆满没用的信息，最终整个智能体的表现一落千丈。

如果你把问题归咎于大语言模型（LLM）本身，那可能找错了方向。真正的核心问题，藏在包裹LLM的整套软件基础设施里——这就是如今AI领域越来越受重视的Agent Harness（智能体框架）。从Anthropic、OpenAI到LangChain，头部企业和框架都在深耕这一领域，因为它才是把“无状态的LLM”变成“有能力的智能体”的关键。本文会基于行业实践，拆解Agent Harness的核心逻辑、组件、运行机制，以及搭建时的关键决策，帮你理解为什么“框架才是生产级智能体的灵魂”。

从演示到生产：AI智能体的差距，藏在“框架”里

很多人误以为，AI智能体的能力上限只由LLM的参数、训练数据决定。但实际案例狠狠推翻了这个认知：LangChain曾仅调整了包裹LLM的基础设施（模型和权重完全不变），就让自身在TerminalBench 2.0的排名从30名开外跃升至第5名；另有研究项目让LLM自主优化这套基础设施，最终实现了76.4%的通过率，超过了人工设计的系统。

这足以说明：决定AI智能体生产级表现的，从来不是模型本身，而是围绕模型的整套“支撑系统”——也就是Agent Harness。

什么是Agent Harness？

虽然“Agent Harness”这个术语在2026年初才被正式定义，但它的核心概念早已存在。简单来说，Agent Harness是包裹LLM的完整软件基础设施，涵盖了编排循环、工具体系、记忆系统、上下文管理、状态持久化、错误处理、安全护栏等所有模块。Anthropic在Claude Code的文档里直接点明：其SDK就是“驱动Claude Code的智能体框架”；OpenAI的Codex团队也将“智能体（Agent）”和“框架（Harness）”等同，用来指代让LLM真正发挥作用的非模型类基础设施。

这里要分清一个容易混淆的点：“智能体（Agent）”是一种“涌现行为”——是用户能交互到的、有目标导向、会用工具、能自我修正的实体；而“框架（Harness）”是产生这种行为的“底层机械结构”。当有人说“我搭建了一个智能体”，本质上是搭建了一套框架，并将其对接至LLM。

为了让这个概念更易理解，Beren Millidge在2023年的论文里做了一个精准的类比：

• ▸
  
  原生的LLM就像一颗只有CPU、没有内存（RAM）、没有硬盘、没有输入输出（I/O）的芯片；
• ▸
  
  上下文窗口相当于内存——速度快但容量有限；
• ▸
  
  外部数据库相当于硬盘——容量大但速度慢；
• ▸
  
  工具集成相当于设备驱动程序；
• ▸
  
  而Agent Harness，就是整个操作系统。

这个类比背后的逻辑很简单：我们其实是在重新发明冯·诺依曼架构——因为它是任何计算系统都天然适配的抽象模式，AI智能体也不例外。

围绕LLM的三层工程体系

要理解Agent Harness的定位，需要先看清围绕LLM的三层工程层级（从内到外）：

1. 提示词工程（Prompt Engineering）：打磨模型接收的指令，核心是让模型“懂要做什么”；
2. 上下文工程（Context Engineering）：管理模型在不同阶段能“看到什么、什么时候看”，核心是控制信息的供给；
3. 框架工程（Harness Engineering）：涵盖前两者，再加上整个应用的基础设施——工具编排、状态持久化、错误恢复、验证循环、安全管控、生命周期管理等，核心是让智能体的自主行为成为可能。

需要特别注意：Agent Harness绝不是“提示词的封装器”，而是让智能体实现自主行为的完整系统。

生产级Agent Harness的11个核心组件

综合Anthropic、OpenAI、LangChain等企业和社区的实践，一套能落地的生产级Agent Harness包含11个核心组件。这些组件各司其职，共同支撑起智能体的稳定运行。

1. 编排循环（The Orchestration Loop）：智能体的“心跳”

这是Agent Harness的核心，实现了“思考-行动-观察（TAO）”循环（也叫ReAct循环）。整个流程很清晰：组装提示词 → 调用LLM → 解析输出 → 执行工具调用（如有） → 将结果反馈回上下文 → 重复直到任务完成。

从技术层面看，它本质上就是一个while循环，但复杂度不在循环本身，而在循环要管理的所有内容。Anthropic把自己的运行时描述为“笨循环”——所有的智能决策都由模型完成，框架只负责管理“轮次”，确保循环按规则推进。

2. 工具（Tools）：智能体的“手脚”

工具是智能体和外部世界交互的载体，核心是先定义好工具的schema（名称、描述、参数类型），并注入到LLM的上下文中，让模型知道“自己能用到什么工具”。

工具层的核心工作包括：

• ▸
  
  工具注册：把可用工具纳入框架管理；
• ▸
  
  Schema验证：确保工具的参数、格式符合规范；
• ▸
  
  参数提取：从模型输出中解析工具调用所需的参数；
• ▸
  
  沙箱执行：在隔离环境中运行工具，避免风险；
• ▸
  
  结果捕获与格式化：把工具执行结果转化为模型能理解的“观察结果”。

举个例子，Claude Code提供的工具覆盖6大类：文件操作、搜索、代码执行、网页访问、代码智能分析、子智能体生成；OpenAI的Agents SDK则支持函数工具、托管工具（如WebSearch、CodeInterpreter）和MCP服务器工具。

3. 记忆（Memory）：智能体的“大脑存储”

记忆系统按时间尺度分为两类，支撑智能体的持续交互：

• ▸
  
  短期记忆：单会话内的对话历史，随会话结束失效；
• ▸
  
  长期记忆：跨会话持久化的信息，比如Anthropic用项目文件和自动生成的日志文件、LangGraph用按命名空间组织的JSON存储、OpenAI则支持基于SQLite或Redis的Sessions。

Claude Code还设计了三层记忆体系，兼顾效率和完整性：

1. 轻量级索引（每条约150字符）：始终加载，快速检索；
2. 详细主题文件：按需加载，补充关键信息；
3. 原始对话记录：仅通过搜索访问，避免占用上下文。

这里有个关键设计原则：智能体会把自身记忆当作“提示”，在行动前会验证记忆与实际状态是否一致，避免基于错误记忆决策。

4. 上下文管理（Context Management）：智能体的“信息过滤器”

这是很多智能体在生产环境失效的重灾区——行业里称之为“上下文腐烂（Context Rot）”：当关键内容出现在上下文窗口的中间位置时，模型性能会下降30%以上（Chroma研究、斯坦福“中间丢失”研究均证实），哪怕是百万级token的大窗口，也会随上下文增长出现指令遵循能力下降的问题。

生产环境中常用的上下文管理策略有4类：

• ▸
  
  压缩（Compaction）：接近窗口上限时总结对话历史。比如Claude Code会保留架构决策、未解决的bug，丢弃冗余的工具输出；
• ▸
  
  观察掩码（Observation masking）：隐藏旧的工具输出，但保留工具调用记录（如JetBrains的Junie）；
• ▸
  
  即时检索（Just-in-time retrieval）：维护轻量级标识符，动态加载数据。比如Claude Code用grep、glob、head、tail等命令读取文件片段，而非加载完整文件；
• ▸
  
  子智能体委托（Sub-agent delegation）：让子智能体深入探索任务，但只返回1000-2000token的精简总结。

Anthropic的上下文工程指南明确了核心目标：找到最小规模的高信号token集，最大化模型产出预期结果的概率。

5. 提示词构建（Prompt Construction）：智能体的“指令集组装”

这一步负责组装模型每一轮实际接收的输入，是分层结构：系统提示词 → 工具定义 → 记忆文件 → 对话历史 → 当前用户消息。

不同厂商有不同的优先级规则，比如OpenAI的Codex采用严格的优先级栈：

1. 服务器控制的系统消息（最高优先级）；
2. 工具定义；
3. 开发者指令；
4. 用户指令（分层的配置文件，32KiB限制）；
5. 对话历史。

6. 输出解析（Output Parsing）：智能体的“结果翻译器”

现代框架都依赖“原生工具调用”——模型直接返回结构化的tool_calls对象，而非需要解析的自由文本。框架的核心工作是：

• ▸
  
  检查输出中是否有工具调用请求；
• ▸
  
  有则执行工具并进入下一轮循环；
• ▸
  
  无则判定为最终答案，结束循环。

对于结构化输出，OpenAI和LangChain都支持通过Pydantic模型约束响应格式；针对边缘场景，也保留了传统方案（如RetryWithErrorOutputParser）——把原始提示词、失败的输出、解析错误反馈给模型，让模型自我修正。

7. 状态管理（State Management）：智能体的“进度存档”

状态管理确保智能体的运行状态可追踪、可恢复。不同框架的实现方式不同：

• ▸
  
  LangGraph：将状态建模为类型化字典，通过reducer合并更新，在“超级步骤”边界做检查点，支持中断后恢复和时间旅行调试；
• ▸
  
  OpenAI：提供4种互斥策略——应用内存、SDK会话、服务端Conversations API、轻量级previous_response_id链式调用；
• ▸
  
  Claude Code：把git提交作为检查点，进度文件作为结构化的草稿本。

8. 错误处理（Error Handling）：智能体的“容错机制”

为什么错误处理至关重要？一个10步的流程，哪怕每一步成功率99%，最终端到端成功率也只有约90.4%——错误会快速累积。

LangGraph把错误分为4类，针对性处理：

• ▸
  
  临时错误：退避重试；
• ▸
  
  LLM可恢复错误：将错误作为ToolMessage返回，让模型调整策略；
• ▸
  
  用户可修复错误：中断流程等待人工输入；
• ▸
  
  意外错误：向上抛出供调试。

Anthropic的策略是在工具处理器内捕获失败，并将其作为错误结果返回，确保循环不中断；Stripe的生产级框架则将重试次数限制为2次，避免无限重试。

9. 安全护栏（Guardrails and Safety）：智能体的“行为边界”

OpenAI的SDK实现了三层安全管控：

• ▸
  
  输入护栏：在首个智能体执行前校验输入；
• ▸
  
  输出护栏：在最终输出返回前校验；
• ▸
  
  工具护栏：每次工具调用前校验。

同时设计了“触发线”机制——一旦触发，立即终止智能体运行。

Anthropic则从架构上分离了权限执行和模型推理：模型决定“想做什么”，工具系统决定“能做什么”。Claude Code对约40个独立的工具能力做了分级管控：项目加载时建立信任、每次工具调用前检查权限、高风险操作需用户明确确认。

10. 验证循环（Verification Loops）：智能体的“自查机制”

这是区分玩具级演示和生产级智能体的关键。Anthropic推荐三种验证方式：

• ▸
  
  基于规则的反馈：通过测试、代码检查器、类型检查器验证结果；
• ▸
  
  视觉反馈：通过Playwright等工具截图，验证UI类任务的结果；
• ▸
  
  LLM作为裁判：用独立的子智能体评估输出是否符合要求。

Claude Code的创造者Boris Cherny提到：给模型提供自查的方式，能让输出质量提升2-3倍。

11. 子智能体编排（Subagent Orchestration）：智能体的“团队协作”

复杂任务往往需要多个智能体分工，不同框架的实现方式不同：

• ▸
  
  Claude Code支持三种执行模式：Fork（父上下文的字节级副本）、Teammate（独立终端面板，基于文件的邮箱通信）、Worktree（独立git工作树，每个智能体对应隔离分支）；
• ▸
  
  OpenAI SDK：支持“智能体作为工具”（专家处理限定子任务）和“交接”（专家完全接管任务）；
• ▸
  
  LangGraph：将子智能体建模为嵌套的状态图。

Agent Harness的运行循环：一步一步看懂工作流程

了解了核心组件后，我们可以顺着一个完整的循环，看看这些组件如何协同工作。

步骤1：提示词组装

框架按层级拼接模型的完整输入：系统提示词 + 工具schema + 记忆文件 + 对话历史 + 当前用户消息。关键是把重要内容放在提示词的开头和结尾——这是为了规避“中间丢失”问题，最大化模型对关键信息的捕捉效率。

步骤2：LLM推理

组装好的提示词被发送到模型API，模型生成输出token——可能是纯文本、工具调用请求，或两者兼有。

步骤3：输出分类

框架解析模型输出，做三类判断：

• ▸
  
  只有文本、无工具调用：循环结束，返回文本作为最终结果；
• ▸
  
  有工具调用请求：进入工具执行环节；
• ▸
  
  有智能体交接请求：更新当前运行的智能体，重启循环。

步骤4：工具执行

对每个工具调用请求，框架依次完成：参数验证 → 权限检查 → 沙箱内执行 → 捕获执行结果。这里有个小细节：只读操作可并发执行，修改类操作需串行执行，避免数据冲突。

步骤5：结果打包

把工具执行结果格式化为模型能理解的消息；如果执行出错，也会把错误信息封装成“错误结果”返回，让模型有机会自我修正。

步骤6：上下文更新

将工具执行结果（或错误）追加到对话历史中；如果上下文窗口接近上限，框架会触发上下文压缩策略。

步骤7：循环

回到步骤1，重复整个流程，直到满足终止条件。

终止条件（多层级设计）

循环不会无限运行，触发以下任一条件就会终止：

• ▸
  
  模型返回无工具调用的文本响应；
• ▸
  
  达到最大轮次限制；
• ▸
  
  耗尽token预算；
• ▸
  
  触发安全护栏的“触发线”；
• ▸
  
  用户手动中断；
• ▸
  
  模型返回安全拒绝响应。

不同任务的轮次差异很大：简单问题可能只需要1-2轮，复杂的代码重构任务可能会串联数十次工具调用，经历数十轮循环。

举个实际案例：Claude Code的运行流程是“初始化智能体搭建环境（初始化脚本、进度文件、功能列表、初始git提交）→ 编码智能体读取git日志和进度文件 → 选择最高优先级的未完成功能 → 开发 → 提交代码 → 写入总结”。文件系统在这里充当了跨上下文窗口的“连续性载体”。

主流框架如何落地Agent Harness模式

不同的AI框架对Agent Harness的实现方式各有特色，但核心逻辑都围绕前文的组件和循环展开。

1. Anthropic Claude Agent SDK

Anthropic通过单个query()函数暴露框架能力——这个函数会创建智能体循环，并返回异步迭代器来流式输出消息。其运行时是前文提到的“笨循环”，所有智能决策都交给模型。

Claude Code在此基础上设计了“收集-行动-验证”循环：

• ▸
  
  收集：搜索文件、读取代码，获取上下文；
• ▸
  
  行动：编辑文件、执行命令，推进任务；
• ▸
  
  验证：运行测试、检查输出，确认结果；
• ▸
  
  重复上述步骤直到任务完成。

2. OpenAI Agents SDK

OpenAI通过Runner类实现框架，支持三种运行模式：异步、同步、流式。其核心特点是“代码优先”——工作流逻辑用原生Python编写，而非图形化领域特定语言（DSL）。

OpenAI的Codex框架在此基础上扩展为三层架构：

• ▸
  
  Codex Core：智能体代码 + 运行时；
• ▸
  
  App Server：双向JSON-RPC API；
• ▸
  
  客户端层：CLI、VS Code插件、Web应用。

所有客户端共享同一套框架，这也是为什么“Codex模型在Codex专属界面的表现，远好于通用聊天窗口”。

3. LangGraph

LangGraph将框架建模为“显式状态图”，核心是两个节点（llm_call、tool_node）和一条条件边：

• ▸
  
  输出中有工具调用 → 路由到tool_node；
• ▸
  
  无工具调用 → 路由到END。

LangGraph是从LangChain的AgentExecutor进化而来——AgentExecutor在v0.2被弃用，原因是扩展性差、不支持多智能体；而LangChain的Deep Agents也明确使用“agent harness”术语，内置工具、规划能力、文件系统上下文管理、子智能体生成和持久化记忆。

4. CrewAI

CrewAI主打“基于角色的多智能体架构”，核心组件包括：

• ▸
  
  Agent：包裹LLM的框架，由角色、目标、背景故事、工具定义；
• ▸
  
  Task：最小工作单元；
• ▸
  
  Crew：智能体集合。

其Flows层增加了“确定性骨干+智能点”的设计：框架管理路由和验证，智能体负责自主协作。

5. AutoGen（微软Agent Framework）

AutoGen是“对话驱动编排”的先驱，三层架构（Core、AgentChat、Extensions）支持五种编排模式：

• ▸
  
  顺序式；
• ▸
  
  并发式（扇出/扇入）；
• ▸
  
  群聊式；
• ▸
  
  交接式；
• ▸
  
  磁式（管理器智能体维护动态任务台账，协调专家智能体）。

脚手架隐喻：Agent Harness的现在与未来

用“脚手架”比喻Agent Harness非常贴切，而非单纯的装饰：建筑脚手架是临时基础设施，能让工人到达原本够不到的高度完成施工；脚手架不直接参与建筑，但没有它，工人无法完成高层作业。

这个隐喻还揭示了一个关键趋势：当建筑（模型）完工后，脚手架（框架）会被拆除。随着LLM能力提升，Agent Harness的复杂度应该逐步降低。比如Anthropic的Manus项目在6个月内重构了5次，每次重构都在删减复杂度——复杂的工具定义简化为通用shell执行，“管理智能体”简化为结构化交接。

这背后是“共进化原则”：如今的模型会结合特定框架做后训练，比如Claude Code的模型就适配了其专属框架；如果修改工具实现，可能因这种强耦合导致性能下降。

判断框架设计是否“面向未来”，有一个测试标准：当模型能力提升时，无需增加框架复杂度就能实现性能提升——满足这个条件的设计，才是可持续的。

搭建Agent Harness的7个核心决策

每个框架架构师在设计Agent Harness时，都要面对7个关键选择——这些选择直接决定框架的性能、复杂度和适配性。

1. 单智能体 vs 多智能体

Anthropic和OpenAI的建议一致：先把单智能体的能力做到极致。多智能体系统会增加额外开销——比如路由需要额外LLM调用、交接时丢失上下文；只有当工具过载（超过10个重叠工具）或任务域明显分离时，才适合拆分多智能体。

2. ReAct vs 计划-执行

• ▸
  
  ReAct：每一步都交织推理和行动，灵活性高，但单步成本高；
• ▸
  
  计划-执行：先制定完整计划，再执行，LLMCompiler的实践显示，这种模式比顺序ReAct快3.6倍。

3. 上下文窗口管理策略

生产环境有5种主流策略：基于时间的清理、对话总结、观察掩码、结构化笔记、子智能体委托。ACON研究显示，优先保留推理轨迹而非原始工具输出，能减少26%-54%的token使用，同时保持95%以上的准确率。

4. 验证循环设计

验证分两类：

• ▸
  
  计算验证（测试、代码检查器）：提供确定性真值，但只能验证形式合规；
• ▸
  
  推理验证（LLM-as-judge）：能捕捉语义问题，但增加延迟。

Thoughtworks的Martin Fowler团队将其总结为“指南（行动前引导）” vs “传感器（行动后观察）”。

5. 权限与安全架构

有两种极端选择：

• ▸
  
  宽松型：速度快但风险高，自动批准多数操作；
• ▸
  
  严格型：安全但速度慢，每次操作都需审批。

选择的核心依据是部署场景（如对内使用可宽松，对外服务需严格）。

6. 工具范围策略

工具越多，模型性能反而可能越差。Vercel在v0版本中移除了80%的工具，结果表现更好；Claude Code通过懒加载实现了95%的上下文缩减。核心原则：只暴露当前步骤必需的最小工具集。

7. 框架厚度

即“逻辑放在框架还是模型中”：

• ▸
  
  Anthropic押注“薄框架”：框架只做基础管理，逻辑交给模型，且会随着模型版本升级，删除框架中的规划步骤（因为模型已内置该能力）；
• ▸
  
  图类框架押注“厚框架”：通过显式控制实现精准管理。

FAQ：关于Agent Harness的常见问题

Q1：为什么我的AI智能体在生产环境总出问题？

核心原因不是模型，而是Agent Harness的设计缺陷：比如上下文管理不当导致“信息丢失”、错误处理缺失导致错误累积、验证循环缺失导致结果不可靠、工具范围过大导致模型决策混乱等。先检查框架的组件是否完整，而非更换模型。

Q2：Agent Harness和普通的LLM封装有什么区别？

普通LLM封装通常只做“调用模型+返回结果”的基础工作，甚至只是封装提示词；而Agent Harness是完整系统，涵盖编排循环、记忆、上下文管理、错误处理、安全管控等，能支撑智能体的自主、稳定运行。

Q3：多智能体系统一定比单智能体好吗？

不一定。多智能体增加了上下文丢失、额外LLM调用成本、协作协调的复杂度。Anthropic和OpenAI都建议：先最大化单智能体的能力，仅在工具过载（≥10个重叠工具）或任务域明显分离时，再考虑多智能体。

Q4：上下文窗口越大，Agent Harness的管理压力越小吗？

不是。即使是百万级token的大窗口，也会因上下文增长出现指令遵循能力下降的问题（斯坦福“中间丢失”研究证实）。核心是通过压缩、即时检索等策略，让模型只接触“高信号”信息，而非单纯扩大窗口。

Q5：如何判断我的Agent Harness设计是否“面向未来”？

核心测试标准：当LLM能力提升时，无需增加框架的复杂度，就能实现智能体性能的提升。如果每次模型升级都要重构框架，说明设计存在缺陷。

总结

Agent Harness是生产级AI智能体的核心——它不是模型的“附属品”，而是让无状态的LLM转化为有目标、会行动、能自我修正的智能体的完整基础设施。

从LangChain的排名跃升，到Claude Code、OpenAI Codex的落地实践，都证明了同一个结论：两个使用相同模型的产品，性能差距完全由Agent Harness的设计决定。

如今的Agent Harness还在快速进化，整体趋势是“薄框架+强模型”，但框架本身不会消失——哪怕是最强大的LLM，也需要框架来管理上下文、执行工具调用、持久化状态、验证结果。

下次你的AI智能体表现不佳时，别再责怪模型了——先看看你的Agent Harness，是否搭建得足够完善。