AI Agent 稳定干活的关键：Harness 7 大子系统拆解

1. 从"能聊"到"能干活"：AI Agent 缺的从来不是模型

很多人第一次搭 AI Agent 的时候，都会经历一个非常相似的阶段：模型接上了，Prompt 调通了，Demo 跑起来看着挺像那么回事。可一旦让它连续处理三五个真实任务，问题就全冒出来了——上下文越滚越长、工具调用偶尔串台、跑到一半忘了自己刚才在干嘛、报错之后直接卡死不会自愈。这时候你才意识到，模型只是"大脑"，而真正让 Agent 稳定干活的，是外面那一整套支撑结构。

这套结构，业内现在越来越多地用一个词来称呼它：Harness。直译过来是"马具""挽具"，意思很形象——模型是那匹有劲但方向感不稳定的马，Harness 就是套在它身上、把它的力量导向正确方向的那套缰绳、鞍具和连接件。没有 Harness，模型再强也只是在原地打转；有了 Harness，它才能拉着车稳稳地往前走。

我接触过不少做 AI Agent 开发的朋友，大家一开始都把注意力放在"用哪个模型""Prompt 怎么写"上，结果真正卡住项目的，往往是 Harness 这一层没搭好。所以这篇我想把 Harness 这件事彻底讲清楚：它到底由哪些部分组成，每个部分解决什么问题，为什么是这 7 个子系统而不是别的，以及在实际搭建时哪些地方最容易翻车。不管你是刚入门想搞懂 Agent 的底层结构，还是已经在做企业级 Agent 应用想查漏补缺，这篇应该都能给你一些能直接用的东西。

需要先说明一点：Harness 目前还没有一个被所有厂商统一认可的官方标准定义，不同团队、不同框架对它的拆法不完全一样。下面这套 7 子系统的划分，是我结合 Agent Loop、LLM Integration、工具调用、记忆管理这些核心概念，以及实际项目里反复验证后总结出来的一套相对完整、可落地的结构。你可以把它当成一个思考框架，而不是死板的教条。

2. 为什么"模型 + Prompt"撑不起一个能干活的 Agent

2.1 模型本身只负责"下一步该输出什么"

要理解 Harness 为什么必要，得先搞清楚大模型到底做了什么、没做什么。LLM 的本质是一个条件概率生成器：给定一段输入（上下文），它预测下一个 token 最可能是什么，然后一个接一个地生成下去。它做的事情，本质上就是"根据当前看到的所有文字，续写最合理的内容"。

这个能力很强，但它的边界也非常清晰。模型不会主动去查数据库，不会自己记住三天前那次对话，不会在工具报错时换个方式重试，更不会判断"这个任务该拆成几步"。它只是在被调用的时候，基于你喂给它的上下文，吐出下一段文字。所有的"记忆""规划""执行""纠错"，都得靠外面的系统来提供。

打个比方：模型像一个知识渊博但完全没有手脚的顾问，你问他什么他都能答，但他没法自己去翻文件、打电话、填表格。Harness 就是给这位顾问配上的手、脚、记事本和助理团队。

2.2 一个真实任务暴露出的所有缺口

我们拿一个具体任务来看：让 Agent"帮我查一下上周的销售数据，生成一份周报，发到团队群里"。

如果只有模型和 Prompt，会发生什么？

• 它不知道"上周"具体是哪几天——需要有时间感知和上下文注入。
• 它拿不到销售数据——需要工具调用能力去查数据库或 API。
• 它可能一次生成不完周报——需要任务拆解和多轮执行。
• 它发完消息后要记得自己发过了——需要状态记录。
• 如果查询接口报错，它得知道重试还是换方案——需要错误处理和循环控制。
• 整个过程中产生的中间结果不能丢——需要记忆和上下文管理。

你看，一个看起来简单的任务，背后牵扯出至少六七个不同的能力需求。这些需求没有一个能靠模型单独完成，它们全部落在 Harness 这一层。这就是为什么我说，Agent 能不能干活，拼的不是模型，而是 Harness。

2.3 Harness 和 Agent 到底啥关系

这里顺便澄清一个经常被混淆的点：Harness 和 Agent 不是一回事。

Agent 是一个更宏观的概念，指的是"能感知环境、做出决策、采取行动以达成目标的智能体"。它是一个完整的系统。而 Harness 是这个系统里负责驱动和约束模型的那套工程结构。可以说，Agent = 模型 + Harness + 具体业务逻辑。Harness 是 Agent 的"骨架和神经系统"，业务逻辑是"肌肉"，模型是"大脑"。

很多人说"我在搭 Agent"，其实大部分时间花在搭 Harness 上。理解了这一点，你就知道该把精力放在哪了。

3. 拆开看：Harness 的 7 个子系统各自管什么

下面进入正题。我把 Harness 拆成 7 个子系统，它们之间有明确的职责边界，又通过标准接口互相协作。先上一张总览表，让你有个全局印象，然后逐个展开。

3.1 Agent Loop：整个系统的心跳

Agent Loop 是 Harness 最核心的部分，它定义了 Agent"怎么运转"。最经典的循环是ReAct 模式：Reason（推理）→ Act（行动）→ Observe（观察），然后回到 Reason，如此往复，直到任务完成或达到终止条件。

具体来说，一轮循环是这样的：模型先根据当前上下文推理出"我下一步该做什么"，如果需要调用工具就输出一个工具调用请求；Harness 拦截这个请求，真正去执行工具，把结果作为"观察"塞回上下文；然后再次调用模型，让它基于新信息继续推理。这个循环会一直转，直到模型输出一个"最终答案"或者触发了最大轮次限制。

为什么这个循环这么重要？因为它把一次性的文本生成，变成了一个可以多步推进的过程。没有循环，模型只能回答一个问题；有了循环，它就能一步步逼近目标。这就像人做事：看一眼情况，动一下手，看看结果，再决定下一步，而不是闭着眼睛一口气做完。

实际搭建时，循环里最容易出问题的是终止条件。我见过太多 Agent 陷入死循环，反复调用同一个工具，或者一直在"我再想想"里打转。所以循环必须设置硬性上限：最大轮次、最大 token 消耗、最大执行时间，三个都得有。别指望模型自己会停，它不会。

3.2 LLM Integration：别把模型焊死在代码里

LLM Integration 这一层，负责把 Harness 和具体的模型解耦。听起来简单，但它是很多项目后期最头疼的地方。

为什么？因为模型是会换的。今天用这个，明天可能因为成本、速度、能力换另一个；同一个产品里，简单任务用便宜的小模型，复杂任务用强模型，这都很常见。如果你的 Harness 代码里到处写死了某个模型的调用方式、消息格式、参数名，那换一次模型就是一场灾难。

所以这一层的核心设计原则是抽象出统一的模型接口。不管底层是哪家模型，上层看到的都是一套标准的方法：chat(messages, tools, ...)，返回统一的响应结构。模型特有的东西——比如某些模型对 system message 的处理方式不同、某些模型不支持并行工具调用、某些模型的 function calling 格式有差异——全部在这一层做适配和转换。

这里有个实操经验：消息格式的归一化一定要早做。不同模型对多轮对话、工具调用结果、系统提示的格式要求差别很大，如果等到项目中期才发现格式对不上，改起来会牵一发动全身。建议一开始就定义一套内部统一的消息结构，所有模型调用都经过一层转换。

3.3 Tool / Function Calling：Agent 的手脚

工具调用是 Agent 从"会说"变成"会做"的关键。模型本身不能执行任何操作，它只能"表达"自己想调用某个工具、传什么参数，真正执行的是 Harness。

这一层要做的事情包括：工具注册（把可用的工具及其参数 schema 告诉模型）、调用解析（从模型输出里提取出工具名和参数）、实际执行（调用真实的函数、API、数据库）、结果回传（把执行结果格式化后塞回上下文）。

工具设计有几个坑，我踩过不止一次：

• 工具描述要写得像给新人看的文档。模型完全靠描述来判断什么时候用这个工具、参数怎么填。描述含糊，模型就会乱用或不用。参数说明要具体到"格式是什么、取值范围、必填还是选填"。
• 工具数量不是越多越好。工具太多，模型选择困难，容易选错。经验值是单次暴露给模型的工具控制在 10 个以内，多了就分组或做路由。
• 工具要能优雅地失败。工具执行出错时，不要把异常直接抛给模型看一堆堆栈，而要返回结构化的错误信息，比如"查询失败，原因是参数格式错误，请检查日期格式"。这样模型才有机会自我修正。

3.4 Memory & Context：Agent 的记事本

记忆系统分两层：短期记忆和长期记忆。

短期记忆就是当前这次任务执行过程中的上下文，包括对话历史、工具调用记录、中间结果。它决定了 Agent"记不记得自己刚才干了啥"。长期记忆则是跨会话、跨任务保留下来的信息，比如用户偏好、历史结论、知识库。

短期记忆最大的挑战是上下文窗口有限。任务一长，上下文就爆了。这时候就需要做上下文管理：滑动窗口（只保留最近 N 轮）、摘要压缩（把早期内容总结成一段话）、关键信息提取（只保留和当前任务相关的部分）。这几种策略往往要组合使用。

长期记忆则涉及存储和检索。常见做法是把信息向量化存进向量库，需要时按语义相似度检索出来注入上下文。但这里有个容易被忽视的点：不是所有信息都值得记。什么都往长期记忆里塞，检索时噪音会淹没信号。要有明确的写入策略，比如只记"用户明确表达的偏好""任务的关键结论"，而不是每一句闲聊。

3.5 Planning & Task Decomposition：把大目标拆成小步骤

复杂任务没法一步到位，必须拆解。Planning 这一层负责把"帮我做一份季度分析报告"这种大目标，拆成"拉数据→清洗→分析→写结论→排版"这样的子任务序列。

拆解方式主要有两种：静态规划（一开始就把所有步骤列出来）和动态规划（走一步看一步，根据中间结果调整后续步骤）。实际项目里，纯静态太死板，纯动态容易跑偏，通常是先粗后细：先出一个高层计划，每个子任务执行时再动态细化。

这里的关键经验是：计划要可验证、可回退。每个子任务最好有明确的完成标准，这样 Agent 才知道自己这步做完了没有。同时，如果某一步失败，要能回退到上一个稳定状态重新规划，而不是从头再来。

3.6 State & Execution Control：Agent 的仪表盘

状态管理是很多人一开始不重视、后期被坑惨的部分。它要记录的东西包括：当前任务进行到哪一步、已经完成了哪些子任务、有哪些中间产物、当前处于循环的第几轮、有没有触发异常。

为什么重要？因为 Agent 的执行是有状态的、可能中断的。如果执行到一半进程挂了，或者需要人工介入，你得能恢复到中断前的状态继续跑。没有状态管理，一切只能从头再来，这在长任务里是不可接受的。

执行控制还包括异常处理策略：工具调用失败是重试、换工具还是上报？模型输出格式不对是重新生成还是兜底解析？循环超时是强制终止还是降级处理？这些策略要提前定义好，而不是等出问题了临时拍脑袋。

3.7 Observability & Guardrails：既要看得见，也要刹得住

最后一个子系统，我把它拆成两块：可观测性和安全护栏。

可观测性指的是：Agent 每一步在干什么，要能被记录下来、被追踪、被回放。包括每次模型调用的输入输出、每次工具调用的参数和结果、每轮循环的耗时和 token 消耗。没有这些，Agent 出了问题你根本不知道从哪查起。我强烈建议从第一天就把日志和追踪做起来，别等出问题才补。

安全护栏则是给 Agent 划边界：哪些操作允许、哪些禁止、哪些需要人工确认。比如涉及资金转账、删除数据、对外发送消息这类高风险操作，必须有确认机制或权限校验。护栏还包括输入输出的内容过滤、调用频率限制、资源消耗上限等。

提示：护栏不是限制 Agent 的能力，而是让它在可控范围内发挥能力。一个没有护栏的 Agent，能力越强，风险越大。

4. 这 7 个子系统是怎么串起来的

光知道每个子系统管什么还不够，关键是它们怎么协作。我用一个完整的任务流程来串一遍。

假设用户说："帮我分析一下这个月的用户增长情况，找出异常点，生成一份简报。"

第一步，任务进入 Planning 层。它把任务拆成：拉取本月用户数据 → 计算增长指标 → 对比历史找异常 → 生成简报文本。

第二步，Agent Loop 启动。每一轮循环里，LLM Integration 层把当前上下文（任务描述 + 已完成步骤 + 中间结果）发给模型。

第三步，模型决定调用工具。比如它输出"调用数据查询工具，参数是本月日期范围"。Tool 层解析并执行，把数据结果返回。

第四步，结果进入 Memory。数据被存进短期记忆，同时关键指标可能被写入长期记忆供后续参考。

第五步，State 层记录进度。"拉取数据"这个子任务标记为完成，进入下一个子任务。

第六步，循环继续。模型基于新数据计算增长指标，可能再次调用工具做对比分析。

第七步，Observability 全程记录。每一步的输入输出、耗时、token 都被记下来，方便事后排查。

第八步，Guardrails 在关键节点拦截。比如生成简报后要对外发送，护栏会要求确认。

整个过程中，7 个子系统各司其职，又通过统一的数据结构（上下文、状态、消息）互相传递信息。这就是 Harness 的运转方式。

5. 搭建 Harness 时最容易翻车的几个地方

讲了这么多结构，最后落到实操。下面这几个坑，是我和身边做 Agent 的朋友反复踩过的，分享出来帮你省点时间。

第一个坑：把循环逻辑写进 Prompt 里。有人试图用 Prompt 让模型"自己循环"，比如告诉它"如果没完成就继续"。这在简单场景偶尔能work，但极不稳定。循环控制必须由代码来做，模型只负责单步决策。

第二个坑：上下文不做管理，任其膨胀。任务稍微长一点，上下文就爆了，然后模型开始"失忆"或者胡言乱语。一定要有上下文压缩和裁剪机制，而且要早做。

第三个坑：工具报错直接抛异常。工具执行失败是常态，不是异常。要把失败当成一种正常的"观察结果"返回给模型，让它有机会调整。直接抛异常会让整个循环崩掉。

第四个坑：没有状态持久化。Agent 跑到一半挂了，所有进度丢失。长任务一定要把状态存下来，支持断点续跑。

第五个坑：日志记了但没人看。可观测性不是记了就行，要能方便地查询、过滤、回放。建议用结构化的日志格式，把每次调用的关键字段都打上。

第六个坑：护栏形同虚设。要么没有护栏，要么护栏只在最外层做做样子。真正的护栏要深入到每个高风险操作，做到"默认拒绝，明确允许"。

6. 关于 Harness，我个人的几点体会

搭了一段时间 Agent 之后，我最大的感受是：Harness 的复杂度，往往被严重低估。大家一开始都以为难点在模型，做着做着才发现，模型反而是最省心的部分——它就在那里，你调它它就答。真正花时间的是外面这一圈：怎么让循环稳定、怎么让工具可靠、怎么让记忆不丢、怎么让状态可恢复。

另一个体会是，Harness 的设计要"面向失败"。不要假设模型每次都输出正确格式，不要假设工具每次都成功，不要假设任务一次就能跑完。把失败当成常态来设计，系统反而更稳。

还有一点，别一上来就追求大而全。7 个子系统不是让你第一天全搭齐。可以先从 Agent Loop + LLM Integration + Tool 这三个最核心的开始，跑通一个能干活的最小闭环，然后再逐步补上记忆、规划、状态和护栏。边跑边补，比一开始就设计一个完美架构要实际得多。

最后说个具体的：如果你现在正在搭 Agent，建议先问自己一个问题——我的 Agent 在连续处理 10 个真实任务后，还能稳定工作吗？如果答案是不确定，那大概率是 Harness 这一层还有没补上的洞。把这 7 个子系统对照着过一遍，缺哪补哪，通常能解决大部分稳定性问题。