第一次听到 Agent Harness 这个名词时，我脑子里冒出来的画面，是一副骑马用的皮革马具。后来真去搭 Agent 工程化的底座，才发现这个命名一点都不随意：Agent 是那匹有脑子的马，Harness 就是套在马身上、让你真正能驾驭它的整套装置。把这条类比想通之后，散落在我项目里的十几个模块忽然串成了一条线——这篇文章就是要把这条线重新捋一遍，从类比出发推导出 12 个组件，给正在纠结“Harness 到底是什么”“Agent 和 Harness 到底啥区别”的你一份可以直接参考的组件地图。

先说清楚这篇内容能解决什么问题。如果你已经能写出一个会调工具、会自己规划步骤的 Agent demo，但一放到真实业务里就发现它不可控、不听话、上下文记不住、工具乱调用、出了问题没法复盘，那你缺的往往不是更强的模型，而是一层 Harness。如果你刚开始接触这个概念，想搞明白它和 Agent 的边界，这篇文章同样适合你。下面我会用一个贯穿全文的类比，把组件一个个拆开讲，不堆概念，全是我自己落地时踩过的坑和验证过的方式。

1. 先用一个类比搞清楚 Harness 到底是什么

1.1 骑马的那个人，和那副马具

骑马这件事，真正的难点从来不是“马有没有力气”。马天生会跑，但你想让它按你的路线走、在该停的地方停、跑完还能复盘刚才哪段路走岔了，光靠马自己是不够的。马具就是为这件事存在的：缰绳负责传递方向指令，马鞍负责让你稳定地骑在背上，肚带负责固定，马镫负责给你一个发力点，甚至马铃铛还能让你在复杂环境里听到马在哪。

Agent 开发也一样。模型本身就具备“思考”和“调用工具”的能力，但把这种能力丢进一个真实的业务流程里，你会发现少了中间那一层“连接件”。没有这一层，模型会忘记前面已经做完的步骤，会拿着错误的参数去调接口，会在一个死循环里反复打转，甚至会编造一个不存在的查询结果。这不是模型不够聪明，而是“马”没有被“装好鞍、系好缰绳”。

1.2 Agent 是脑子，Harness 是骨架和缰绳

很多人把 Agent 和 Harness 混在一起，其实它们的分工非常清晰。Agent 负责的是“推理与生成”：给定当前状态，决定下一步做什么、生成什么回复、选择哪个工具。Harness 负责的是“让这一切稳定发生”：任务从哪来、状态怎么保存、工具怎么注册、模型怎么路由、结果怎么校验、过程怎么记录。

打个比方：Agent 是决策者，Harness 是让决策落地的执行系统。决策者可以很聪明，但如果执行系统是乱的，再聪明也会翻车。我见过不少团队把大量精力放在调 Prompt、换更强模型上，结果瓶颈却在“两个工具之间状态没同步”这种 Harness 层面的问题。这也是我后来坚持先搭 Harness、再调模型的原因。

为什么叫 Harness 而不是 Framework？Framework 强调的是“框架”，给你一套代码结构；Harness 更强调“约束与控制”，有点像汽车里的安全带——它让你在高速路上跑得再快，也不至于失控。理解了这一层，后面的组件推导就顺理成章了。

2. 从驾驭一匹马推导出 4 类问题、12 个组件

要驾驭一匹马稳定地跑完一段路，你需要解决四类问题：第一，方向问题——马往哪走、走哪条路、什么节奏走；第二，记忆问题——马走到哪了、刚才经历了什么、下次怎么做得更好；第三，能力问题——马背上带了哪些工具、遇到不同路况换哪匹马、骑手用什么样的口令；第四，治理与交付问题——跑偏了怎么拉回来、跑完了怎么复盘、换一个赛场这套马具还能不能直接用。

这四类问题，每组推导出 3 个组件，总共正好 12 个。下面逐个推。

2.1 方向问题：谁来决定下一步做什么

如果让马完全自由地跑，它会按照自己的本能走，而不是按你的目标走。Agent 也是一样，如果不加约束，它可能跑题、重复操作、过早收工。所以方向问题需要三个层次的机制：由谁来决定任务的整体拆解、由谁来决定每一步具体动作、由谁来安排执行节奏。这三个层次，对应到工程上就是 Orchestrator（任务编排器）、Planner（规划器）、Scheduler（调度器）。

我曾经写过一个没有编排层的 Agent，它收到“统计上月所有渠道的订单异常”这个任务后，自己拆成了三步，但执行完第一步就把第二步忘了，最后输出结果缺了一半。这不是模型推理能力的问题，是缺少一个“拿着任务清单逐项打钩”的编排层。

2.2 记忆问题：上下文不是简单的“历史消息”

马跑过一段路之后，必须知道自己从哪来、要到哪去、刚才哪块石头绊了一下。Agent 的上下文窗口是有限的，你不能把全部历史都塞进每次请求里。这时候需要三样东西：工作记忆，负责当前对话里哪些信息必须保留；长期记忆，负责把跑完这一趟的经验沉淀下来供以后使用；状态记录，负责标记“当前处于哪一个阶段、完成度是多少”。对应组件就是 Context Manager（上下文管理器）、Memory Store（长期记忆库）、State Machine（状态机）。

这里我踩过一个大坑：最初我用一个全局字典存所有中间结果，看起来方便，实际上并发一高就互相覆盖。后来才明白，上下文管理和状态管理不能混为一谈，前者管“模型能看到什么”，后者管“系统能确认什么”，职责必须分开。

2.3 能力问题：工具、模型、提示词必须统一接进来

马背上的工具箱，不能每件工具都随便丢在背上，得有一个固定的取用规则。Agent 的工具接入也是一样——不同工具参数格式五花八门，需要有一个统一的注册、发现、调用入口，这就是 Tool Registry（工具注册器）。同时，你很可能不会只用一个模型：贵的模型用来做复杂推理，便宜的模型用来做格式整理，主模型挂了要能快速降级，需要一个统一的出口来管理它们，这就是 Model Gateway（模型网关）。最后，骑手给马下口令的方式也不能每次随性发挥，需要一套经过验证的话术模板，这就是 Prompt Manager（提示词管理器）。

很多项目把 Prompt 直接写死在业务代码里，每次调一句都得改代码发版。引入 Prompt Manager 之后，提示词变成了可配置、可版本管理的资产，同样是修改行为，成本从半小时降到了两分钟。

2.4 治理与交付问题：跑得快不如跑得稳

马跑得快不重要，重要的是该停的时候停得下来。Agent 治理层的核心是 Guardrails（安全护栏）：输出内容要校验、工具调用要鉴权、操作范围要受限。跑完之后还得知道刚才到底发生了什么，所以要有 Trace & Evaluate（链路追踪与评估）：每一步的输入输出、模型、耗时、成本全部落盘，并且能自动对比结果好坏。最后，这套马具不能只在自家马厩里能用，换一个环境、换一套部署方式也要能装上去，这就是 Runtime Adapter（运行时适配器）。

我团队里发生过一次事故：Agent 在执行订单退款工具时，因为工具入参校验没做好，把“数量”字段传成了负数。那一次我们才真正重视 Guardrails，它不该只拦“明显违规的内容”，更该拦“结构合法但业务上非法的调用”。这类经验，只有把治理层当作一等组件去做，才不会被发现。

3. 12 个核心组件逐个拆解

在进入细节之前，先给你一张速查表，把这 12 个组件的类比和后文关键词列出来，方便随时对照。

下面按四组展开讲。

3.1 任务编排三件套：Orchestrator、Planner、Scheduler

**Orchestrator（任务编排器）**是最核心的组件，它定义的是“Agent 的主循环”。常见的循环模式包括 ReAct（思考-行动-观察）、Plan-and-Execute（先定计划再逐项执行）、多代理协作中的“经理-员工”模式。Orchestrator 不是简单地调用模型，而是要决定“什么情况下继续循环、什么情况下终止”。我建议把终止条件显式写出来：连续 N 步没有取得进展就该停止，而不是单纯依赖模型自己说“我完成了”。

**Planner（规划器）**负责把大目标拆成可执行的小步骤。它和 Orchestrator 的区别在于：Planner 只负责“产出计划”，不负责“执行计划”；Orchestrator 负责“拿着计划推进”。早期项目可以不做 Planner，直接把任务交给模型自由发挥，但一旦任务复杂度上来，自由发挥的失败率会急剧上升。规划结果我建议输出成结构化数据，比如带依赖关系的任务列表，而不是一大段自然语言，否则后续编排程序根本没法稳定解析。

**Scheduler（调度器）**管的是执行粒度：多个子任务要不要并行、同时最多跑几个、一个任务失败后是重试还是跳过。它是 Harness 里最容易偷懒的组件，很多人用普通 for 循环代替。直到某次所有子任务并发调用同一个上游接口，把对方打挂了，我才意识到调度器不只是“排顺序”，更是“流量闸门”。实现上可以从简单的信号量并发控制开始，后续再引入优先级队列。

3.2 上下文与状态三件套：Context Manager、Memory Store、State Machine

**Context Manager（上下文管理器）**直接决定模型能看到什么。它做三件事：把当前对话相关的关键信息拼装成上下文；在上下文超过窗口上限时做裁剪或摘要；确保不把敏感信息或无关历史塞给模型。这里有个经验：裁剪时不要只是“从最早的消息开始删”，而要先保留下“终止标志”和“关键约束”。我踩过两次坑，都是因为裁剪太狠，把系统指令里“已经完成，不要继续”的信号裁掉了，模型又开始自作主张地执行下一步。

**Memory Store（长期记忆库）**负责跨会话的信息沉淀。它可以存用户偏好、历史任务结果、领域知识。技术上通常是向量数据库加关键词索引的组合。很多人的误区长在这里也可以用来存中间状态。我建议严格区分：Memory Store 存的是“语义化的事实和经验”，State Machine 存的是“当前任务的执行状态”。如果混在一起，语义检索会给状态读写带来很大的不确定性和延迟。

**State Machine（状态机）**是很多人会忽略的隐性组件。Agent 是有状态的：等待用户输入、执行工具调用、生成最终回复、异常终止，每个状态都有明确的进入和退出条件。有了状态机，并发场景下两个任务才不会互相覆盖数据；排查问题时，你才能准确说出“这个任务死在哪一步”。我团队现在是每个任务实例维护一个只写一次的 state 字段，所有状态变更都走同一个接口，这个习惯救了我们很多次。

3.3 工具与模型接入三件套：Tool Registry、Model Gateway、Prompt Manager

**Tool Registry（工具注册器）**是所有工具的统一入口。每个工具在注册时要声明名称、描述、输入参数 JSON Schema、权限等级、超时时间。注册器负责把模型的函数调用结果映射到真实代码。协议统一之后，工具的接入成本会大幅下降。例如“查天气”工具和“查库存”工具，虽然底层系统完全不同，但到 Agent 这边都是“传参数、返回 JSON”，模型只关心这两个工具能给它什么信息，不关心数据结构差异。注意，工具描述写得越准确，模型选对工具的几率越高，这一步值得花时间锤炼。

**Model Gateway（模型网关）**解决的是多模型问题。它统一封装不同模型供应商的 API，向外只暴露一套接口，内部做路由、鉴权、限流、降级和成本统计。为什么需要它？因为今天你用的模型，三个月后大概率会被更强或更便宜的替换。有了网关，替换模型只是一个配置变更，不需要改动业务代码。更关键的是降级策略：主模型超时或限流时，网关能自动切到备用模型，让服务不至于整体挂掉。这个组件在 demo 阶段可以省，上线后必须补。

**Prompt Manager（提示词管理器）**把提示词从代码中抽出来，做成可管理、可测试、可版本化的资产。一个合格的 Prompt Manager 至少包含模板渲染、版本号、按场景组装。举个例子：同一个“总结”能力，在客服场景和数据分析场景下的提示词完全不同，Prompt Manager 能把它们分开管理，并且在 Trace 中记录“当前回复用的是模板的哪个版本”。这样当模型表现突然变差时，你能快速判断是模板改坏了还是模型升级了。

3.4 治理与运行三件套：Guardrails、Trace & Evaluate、Runtime Adapter

**Guardrails（安全护栏）**是 Harness 和“裸调模型”的最大区别。它至少要做三层检查：输出内容层，检测敏感词、越狱指令、幻觉风险；工具调用层，校验参数类型、取值范围、权限是否匹配；业务流程层，判断这个动作在当前状态下是否合理。我在第 2.4 节提过的“数量传负数”事故，就是第三层没做。护栏的实现要分阶段：用户输入进来时做一次，模型输出返回时做一次，工具返回结果后做一次。别只挡最后一环，越早拦截成本越低。

**Trace & Evaluate（追踪与评估器）**是全链路唯一能回答“刚才到底发生了什么”的组件。每次任务运行，都应该记录：任务 ID、模型名称、Prompt 版本、每一步输入输出、工具调用参数与返回、耗时、Token 消耗、护栏拦截记录。评估要做的是把这些数据聚合成可对比的指标，比如任务完成率、工具调用成功率、平均步数。没有这个组件，你就是拿着一个黑盒跑业务，出问题只能靠猜。补充一句：埋点要第一天就做，因为事后补的数据结构永远对不上真实需求。

**Runtime Adapter（运行时适配器）**把 Harness 与具体运行环境解耦。你的 Agent 可能跑在本地进程、云函数、容器集群，也可能被不同的上游服务调用。Adapter 负责把不同触发方式（HTTP 请求、消息队列、定时任务）转换成统一的内部任务格式，再把结果转换成各自需要的返回值。做的时候记住一条：Adapter 只做“翻译”，不要在里面写业务逻辑。我之前就遇到过有人把校验逻辑写进 Adapter，结果换了一个部署环境后，同一套逻辑被复制了三份，维护成本直线上升。

4. 实操视角：怎么把这 12 个组件装进一个真实项目

4.1 最小 Harness 骨架：先跑通，再长肉

我知道你现在的想法肯定是：12 个组件，第一次都要全部实现吗？当然不是。我建议的最小化骨架只保留 5 个东西：一个主循环（对应 Orchestrator 和 Planner 的合体）、一个上下文管理器、一个工具注册器、一个模型网关的简化版（直接用参数指定模型）、一个最简单的护栏。状态机先用字典代替，Trace 先打印日志，Scheduler 用同步 for 循环，这些后续再换成正式组件。

下面这个代码是我常用的最小骨架，核心是 ReAct 循环：

class MinimalHarness: def __init__(self, model, tool_registry, context, guardrails): self.model = model self.tool_registry = tool_registry self.context = context self.guardrails = guardrails def run(self, task): state = {"task": task, "steps": []} for step in range(10): # Orchestrator 控制步数 messages = self.context.build(state) response = self.model.generate(messages) if response.is_final_answer(): state["steps"].append({"type": "answer", "content": response.content}) return response.content tool_call = response.get_tool_call() self.guardrails.check_tool_call(tool_call) # Guardrails 拦截非法调用 result = self.tool_registry.invoke(tool_call) # Tool Registry 统一调用 state["steps"].append({"type": "tool", "call": tool_call, "result": result}) self.context.append(tool_call, result) # Context Manager 更新上下文

这段代码把 12 个组件的边界全部画出来了：for step in range(10)是简化版的编排器；state是简化版的状态机；self.context是上下文管理器；self.tool_registry是工具注册器；self.guardrails是护栏。你完全可以在 LangGraph、AutoGen 这类现成框架上跑通同样结构，具体用哪个不关键，关键是职责边界要一致。

从最小骨架到完整形态，我推荐的填充顺序是：先补状态机，因为并发出问题最致命；再补 Trace 埋点，因为越早积累数据越好；接着补 Prompt Manager，把提示词收拢起来；最后补 Scheduler 和 Runtime Adapter，这两个是性能和部署层面的优化。

4.2 组件之间的“通信”怎么做才不乱

很多人一看到“组件”就套用前端组件的思维，想着父传子、子传父、事件总线。Harness 里完全不是这套逻辑。它更像是后端微服务之间的显式数据流：数据通过调用参数传入，通过返回值传出，需要共享核心状态时走统一的状态管理接口，而不是互相之间随意传引用。

组件通信的三种常见方式，我按优先级排了一下：一是显式参数传递，调用方把需要的对象通过构造函数或方法参数传给目标组件，最容易追踪；二是共享状态对象，所有组件共同读写一个明确定义的任务上下文对象，但必须规定好哪些字段只读、哪些字段只写；三是事件或消息总线，适合跨进程场景，但调试成本会高一些。

依赖方向也很有讲究。我吃过一次循环依赖的亏：Context Manager 为了裁剪上下文，去调 Model Gateway 做摘要，而 Model Gateway 的日志又要依赖 Trace，Trace 又反过来读 Context 里的数据。最后改成了单向依赖：上层组件可以依赖下层组件，下层组件绝不知道上层存在。类似地，Tool Registry 不应该反向调用 Orchestrator，否则你就没法换掉任何一个组件而不牵连全局。

还有一个容易踩的坑是组件内部状态和 Agent 全局状态混用。前端的组件可以有自己的 localStorage、sessionStorage，但 Harness 这边不应该允许每个组件私自保存 Agent 的运行状态。所有状态必须显式放在任务上下文或 State Machine 里。否则排查问题时你会遇到“为什么同一个任务在两个请求中表现完全不同”的幽灵问题。

4.3 常见问题排查与避坑速查表

最后把这几年沉淀下来的排查经验整理成一张表，遇到类似症状可以先对号入座。

5. 最后聊几句个人体会

做 Agent 工程化这几年，我最深的一个感受是：Harness 的价值不是一开始就能看见的，它是在事故中慢慢显现的。你单独看每个组件，好像都可以用“简单的 if-else”代替；但当你面对 10 万次调用、多个模型、几十个工具、随时可能出错的网络和上游系统时，缺少这些组件的代价会被无限放大。

所以我的建议是：不要迷信 12 这个数字，也不要一上来就追求每个组件都做到完美。先把最小骨架跑通，让一个真实业务在它上面稳定运行；然后每遇到一个新问题，就打开对应的那层抽屉，补上对应的组件能力。过程中你会慢慢发现，组件数量其实不重要，重要的永远是那件事——你要能控制住 Agent，而不是让 Agent 带着项目乱跑。

如果你正在为自己的项目设计 Harness，不妨先把这篇文章里的组件清单打印出来，对照你现在已有的代码，逐个问一句“这个职责谁负责”。大部分情况下，你很快就能找到最缺的那一块，然后你的 Agent 会在那个瞬间开始变得不一样。