第一章 从概念入门到实战落地

一、什么是 Agent Harness ？​

​

😊

Anthropic 的 Claude Code 工具文档对此做出了通俗定义：软件开发工具包就是驱动Claude Code 运行的Agent Harness。科德克斯研发团队也采用相同定义逻辑，明确将 Agent 与 Harness 划等号，特指让大语言模型具备实用价值的非模型类底层架构。​

​

​

​

很多人容易混淆二者概念，核心区别如下：​

​

•

Agent 是模型涌现出的行为能力，是以目标为导向、可调用工具、具备自我纠错能力、供用户直接交互的智能实体；​

•

Agent Harness 则是支撑上述智能行为运转的底层核心架构。​

​

当人们表述“我开发了一个智能体”时，其本质是搭建了一套Agent Harness，并将其对接适配大语言模型。​

二、Agent Harness 工程的三个层级​

​

🌐

围绕模型存在三个同心层级的工程体系：​

•

Prompt engineering 提示工程：负责设计模型接收的指令。​

•

Context engineering 上下文工程：管控模型所能获取的内容与获取时机。​

•

Harness engineering 调度工程：涵盖前两者，同时包含完整的应用基础设施：工具编排、状态持久化、错误恢复、校验循环、安全管控以及生命周期管理。​

​

​

​

三、Harness 的十二大组成部分​

综合参考Anthropic, OpenAI, LangChain以及广大行业从业者的实践经验，一套生产级智能体调度体系包含十二个独立模块。下面我们逐一进行介绍。​

1. 调度循环​

​

😊

这是智能体的核心运转中枢。该循环实现思考-行动-观察（TAO） 流程，也被称作推理与行动循环（ReAct循环）。循环运行逻辑为：组装提示词、调用大语言模型、解析输出内容、执行各类工具调用、回传运行结果、重复以上步骤直至任务完成。​

​

​

从技术底层来看，它本质上就是一个循环语句。整套架构的复杂点不在于循环本身，而在于循环所统筹管理的各类模块。人工智能公司Anthropic将其运行时机制定义为「简易循环」，所有智能决策能力都由大模型承载，调度框架仅负责流程回合的管理。​

​

​

2. 工具能力​

​

😊

工具是智能体的执行抓手。工具以规范模式定义，包含名称、功能描述、参数类型等信息，并注入大语言模型的上下文语境中，让模型知晓可调用的能力范围。工具层主要负责工具注册、格式规范校验、参数提取、沙箱安全执行、结果捕获，以及将执行结果整理为模型可识别的观测信息。​

​

​

•

Claude Code 提供六大类工具：文件操作、信息检索、程序执行、网络访问、代码智能分析、子智能体创建。OpenAI智能体开发套件支持函数工具（通过函数装饰器调用）、托管工具（网页搜索、代码解释器、文件检索）以及MCP服务器工具。​

​

​

3. 记忆体系​

​

😊

记忆体系分为多个时间维度。短期记忆指单次会话内的对话历史；长期记忆可跨会话持久留存：Anthropic 依托项目配置文件CLAUDE.md与自动生成的MEMORY.md文件实现长期记忆；LangGraph采用命名空间分类的JSON存储结构；OpenAI 支持基于SQLite或Redis数据库的会话记忆。​

​

​

Claude Code 采用三层记忆架构：轻量索引库（单条内容约150字符，常驻加载）、按需加载的专题详情文件、仅可通过检索访问的原始对话记录。其核心设计原则为：Agent 仅将自身记忆作为参考线索，执行操作前必须结合实际运行状态进行核验。​

​

​

4. 上下文管理​

​

😊

上下文管理是多数智能体隐性失效的关键诱因。核心痛点为上下文衰减：当关键内容处于上下文窗口中间位置时，模型性能会下降30%以上（该结论源自Chroma研究院，也与斯坦福大学《迷失在文本中段》的研究成果相互印证）。即便拥有百万级超长上下文窗口，随着文本体量增加，模型的指令遵循能力也会持续弱化。​

​

​

工业级落地优化方案：​

•

内容压缩：上下文临近上限时，自动精简对话历史（克劳德代码会保留架构设计决策与未解决问题，剔除冗余工具输出内容）​

•

观测内容屏蔽：捷迈软件（JetBrains）的智能体Junie隐藏老旧工具执行结果，保留工具调用记录​

•

即时按需加载：留存轻量化标识信息，动态加载所需数据（克劳德代码采用文本检索、路径匹配、首尾内容读取等指令，避免加载完整大文件）​

•

子智能体分工处理：各子智能体完成深度探索后，仅返回1000至2000令牌的精简总结内容​

​

Anthropic的上下文优化指南明确核心目标：筛选最小范围、高有效信息的文本内容，最大化任务目标的达成概率。​

​

5. 提示词构建​

​

😊

​

​

OpenAI代码模型Codex采用严格的优先级排序：服务端管控的系统提示（最高优先级）、工具定义、开发者指令、用户指令（关联多级配置文件，单文件上限32千字节），最后为对话历史内容。​

​

​

6. 输出解析​

​

😊

现代智能体调度框架依托原生工具调用能力，模型直接输出结构化的工具调用对象，无需对自由文本进行二次解析。框架判定逻辑：若存在工具调用指令，则执行对应工具并进入循环；若无工具调用指令，当前内容即为最终回复结果。​

​

​

在结构化输出场景下，OpenAI与LangChain均支持通过数据校验模型（Pydantic）实现格式约束输出。针对特殊边界场景，传统解析容错方案（错误重试解析器）仍可使用，该方案会将原始提示词、异常回复内容、解析错误信息回传给模型，完成二次修正。​

​

​

7. 状态管理​

​

😊

LangGraph以带类型字典数据定义运行状态，数据在图谱节点间流转，通过合并处理器完成状态更新。系统在关键步骤节点生成检查点，支持中断恢复与时序回溯调试。OpenAI提供四种互斥的状态管理方案：应用本地内存、开发套件会话、服务端对话接口、轻量化历史标识链式调用。克劳德代码则采用差异化方案：以代码提交记录作为检查点，以进度文件作为结构化临时记录载体。​

​

​

8. 异常处理​

​

​

​

LangGraph将异常划分为四类：​

•

临时故障（阶梯式重试）​

•

模型可修复故障（将错误信息封装为工具反馈，供模型自主调整）​

•

用户可修复故障（中断流程，等待人工介入）​

•

未知异常（抛出错误，用于问题排查）。​

​

Anthropic在工具处理器内捕获运行故障，并以错误结果形式回传，保障主循环持续运行。支付平台Stripe的线上调度框架，将工具重试次数严格限制为两次。​

​

9. 防护机制与安全管控​

​

😊

OpenAI开发套件设置三级安全防护：输入防护（智能体启动阶段生效）、输出防护（最终回复生成阶段生效）、工具防护（每一次工具调用时生效），同时配备触发即暂停的熔断机制。​

​

​

Anthropic 在架构层面实现权限管控与模型决策解耦：​

​

​

10. 核验循环​

​

😊

核验循环是简易演示版智能体与工业级商用智能体的核心区别。Anthropic推荐三类核验方案：基于规则的反馈校验（自动化测试、代码检测、类型校验）、可视化反馈校验（网页自动化工具截取界面截图，适配UI交互任务）、大模型裁判校验（独立子智能体对输出结果进行审核评估）。​

​

​

Cluade Code 创始人Boris Cherny指出：为模型增加自主核验能力，可将任务输出质量提升2至3倍。​

​

11. 子智能体调度​

​

😊

Claude Code 支持三种运行模式：分支模式（完整复刻父级上下文）、协作模式（独立终端面板，基于文件消息池通信）、工作区模式（独立代码工作区，单智能体绑定隔离分支）。​

OpenAI开发套件支持工具化智能体（专业子智能体承接限定子任务）与权限移交模式（专业智能体接管全部流程）。LangGraph则以嵌套状态图谱的形式实现子智能体调度。​

​

​

四、循环运转：完整流程分步解析​

了解核心组件后，接下来完整拆解单次任务周期内，各模块协同运转的全过程。​

​

​

​

​

•

步骤1（提示词组装）：调度层构建完整输入内容，包含系统提示词、工具模式、记忆文件、对话历史以及当前用户消息。关键上下文会放置在提示词的开头与结尾位置（对应“中间信息易丢失”的研究结论）。​

•

步骤2（大语言模型推理）：组装完成的提示词发送至模型应用程序接口。模型生成输出令牌，形式可为文本、工具调用请求，或两者兼具。​

•

步骤3（输出分类）：若模型仅输出文本且无工具调用需求，流程终止；若发起工具调用，则继续执行后续操作；若请求代理移交，则更新当前代理并重新启动流程。​

•

步骤4（工具执行）：针对每一次工具调用，调度层会校验参数、核查权限、在沙箱环境中执行操作，并捕获运行结果。只读类操作可并发执行，数据修改类操作需串行执行。​

•

步骤5（结果封装）：将工具运行结果格式化为大语言模型可识别的消息格式。捕获各类异常错误并以错误结果形式返回，以便模型进行自我修正。​

•

步骤6（上下文更新）：把工具执行结果追加至对话历史。当接近上下文窗口上限时，调度层会触发内容压缩机制。​

•

步骤7（循环执行）：回到步骤1，重复全流程，直至满足终止条件。​

​

😊

终止条件分为多层级：模型输出不含工具调用的最终回复、超出最大交互轮次限制、令牌额度耗尽、触发安全防护机制、用户主动中断、或是模型返回安全拒绝响应。简单问题通常只需1至2轮交互即可完成，复杂的代码重构任务则可能在多轮交互中串联数十次工具调用。​

​

针对跨多个上下文窗口的长期运行任务，安索帕（Anthropic）研发了双阶段的“拉尔夫循环”运行模式：初始化代理负责搭建运行环境，包括初始化脚本、进度文件、功能清单、初始代码提交记录；后续每一轮会话中，代码代理会读取代码日志与进度文件以明确工作方向，筛选优先级最高的未完成功能模块进行开发、提交代码并输出工作总结。文件系统可保障不同上下文窗口之间的任务连续性。​

​

五、主流实际框架的该模式落地实现方式​

​

​

​

​

Anthropic 旗下的 Claude 智能体 SDK，通过单一的 query() 函数对外开放运行调度层，该函数会构建智能体循环，并以异步迭代器的形式流式返回消息。其运行时只是一套简易循环逻辑，所有智能推理能力完全由大模型承载。Claude Code 采用「收集—执行—核验」闭环机制：收集上下文（检索文件、读取代码）、执行操作（编辑文件、运行命令）、核验结果（执行测试、校验输出），随后循环往复。​

​

OpenAI 智能体 SDK 依托 Runner 类实现调度管控能力，提供异步、同步、流式三种运行模式。该 SDK 秉持代码优先设计理念：业务流程逻辑直接使用原生 Python 编写，而非图形领域专用描述语言。Codex 调度框架在此基础上升级为三层架构：Codex 核心层（智能体代码+运行时）、应用服务层（双向 JSON-RPC 接口）、多端客户端（命令行、VS Code、网页应用）。全终端共用同一套底层调度体系，这也是Codex 专属端内模型体验，远优于通用对话窗口的核心原因。​

​

LangGraph 将智能体调度层抽象为显性状态图架构。核心由两大节点构成：大模型调用节点、工具调用节点，二者通过条件分支连通：若存在工具调用指令，则路由至工具节点；若无，则直接终止流程。LangGraph 迭代进化自 LangChain 的 AgentExecutor，后者在 0.2 版本被正式废弃，原因是扩展性差、且不支持多智能体协作。LangChain 深度智能体已明确使用智能体调度框架这一概念：内置工具集、任务规划能力（待办清单工具）、上下文文件管理、子智能体派生、持久化记忆存储，全部整合在统一调度体系内。​

​

CrewAI 采用角色化多智能体架构设计：智能体 Agent：围绕大模型构建专属调度层，由角色定位、目标任务、背景设定、可用工具共同定义；任务 Task：最小执行工作单元；协作团队 Crew：多个智能体的组合集群。​

​

CrewAI 的流程层额外增加了「确定性主干+智能分支」设计，统一管控路由分发与结果校验，而智能体团队则负责自主协同作业。​

​

AutoGen（现已迭代升级为微软智能体框架）开创了对话驱动编排范式。其三段式架构（核心层、对话交互层、扩展层）支持五种主流协作编排模式：串行执行、并发分发（发散/汇总）、群聊协作、任务交接、管理式协同（由管理智能体维护动态任务台账，统一调度各专业智能体）。​

​

六、脚手架隐喻​

脚手架并非修饰性比喻，而是严谨的技术类比。​

•

建筑施工里的脚手架，是临时性基础设施，用来辅助施工人员完成原本无法触及的建造工作。​

•

脚手架本身不参与施工建造，但缺少它，施工人员就无法完成高层作业、复杂工程的搭建。​

​

​

​

​

😊

核心观点：建筑完工之日，便是脚手架拆除之时。随着大模型能力持续迭代升级，智能体调度框架的复杂度理应逐步降低。Manus 项目曾在半年内历经五次重构，每一次重写都在不断精简冗余设计、削减架构复杂度。繁杂零散的工具定义，被统一通用的命令行执行能力替代；原本厚重的「管理型智能体」，简化为轻量化的结构化任务交接机制。这引申出协同进化原则：当下的大模型后训练阶段，会将专属调度框架直接纳入训练闭环中。Claude Code 专属模型，早已适配其配套的调度运行体系并形成习得依赖。正因这种强绑定关系，一旦改动工具底层实现，反而会直接削弱模型实际表现。调度框架设计的未来兼容性检验标准：倘若模型性能随算力与能力升级自然提升，且无需同步叠加框架复杂度，那么这套智能体调度架构，才称得上稳健、具备长期价值。 ​

​

​

​

​

​

七、定义智能体调度框架的七大核心决策​

每位 Harness 设计人员都面临七大选择：​

​

​

​

​

单智能体 vs 多智能体Anthropic 与 OpenAI 观点一致：优先做强单智能体。多智能体架构会增加额外开销（路由调度需要额外大模型调用、任务交接易丢失上下文）。仅在工具数量过载、存在大量重叠工具，或是业务场景可以明确拆分时，才考虑拆分为多智能体。​

ReAct 架构 vs 规划执行架构ReAct 每一步都交替进行推理与工具行动，灵活度高，但单步成本更高。规划执行模式则将「任务规划」与「落地执行」解耦。LLMCompiler 实测性能远超串行 ReAct，运行效率提升数倍。​

上下文窗口管理策略业界主流五种落地方案：定时清理会话、对话摘要压缩、观测信息掩码过滤、结构化笔记留存、子智能体代为处理。ACON 研究证明：优先保留推理链路、精简原始工具返回内容，可大幅削减 Token 消耗，同时保证超高任务准确率。​

校验闭环设计计算机校验（单元测试、代码检查工具）：结果确定、可作为客观事实依据。推理级校验（大模型充当裁判）：能识别语义类问题，但会增加响应延迟。马丁・福勒所在 Thoughtworks 团队将其归纳为：前置引导（行动前预判与约束）vs 后置感知（执行后观测与复盘）。​

权限与安全架构宽松模式：执行效率高、自动放行大部分操作，但风险更高；严格模式：安全性强、每项操作需审批确认，但流程更慢。具体选型取决于业务部署场景与风险等级。​

工具范围管控策略工具并非越多越好，冗余工具反而会拉低模型决策效果。Vercel 为 v0 删减八成工具后，整体表现显著优化；Claude Code 通过懒加载工具实现超高比例上下文精简。核心原则：只暴露当前任务必需的最小工具集。​

调度层轻重设计核心权衡：业务逻辑放在调度框架，还是交由大模型自身处理。Anthropic 主打轻量调度层，依靠模型能力持续迭代；图结构框架则偏向显性流程控制、强人工干预。随着模型能力增强，Claude Code 会持续删减调度层中的规划逻辑，让模型原生内化复杂规划能力。​

​

八、Harness 才是产品的核心​

两款完全使用同款大模型的产品，仅凭调度层设计差异，就能产生天差地别的实际表现。TerminalBench 基准测试足以佐证：仅更换调度架构，智能体综合排名就能拉开二十名以上差距。​

​

​

😊

Harness 绝非成熟通用的基础组件，而是高难度工程的核心所在：把上下文当作稀缺资源精细化管理、设计校验闭环以阻断故障连锁反应、搭建连贯且无幻觉的记忆系统、理性权衡「脚手架层级」与「模型原生能力」的架构取舍。​

​

​

行业趋势很明确：模型越强，调度层就会越轻量化。但调度层永远不会彻底消失。即便是顶尖大模型，也依然需要依赖外层能力：上下文管理、工具调用执行、状态持久化、执行结果校验。​

往后智能体出现故障时，不必一味归咎模型本身，更应该审视：你的调度框架，是否合格。​

​