1. 从"模型很聪明但活干不明白"说起
如果你最近半年在折腾 AI Agent，大概率经历过这种落差：模型在对话里表现得像个专家，一旦让它去完成一个多步骤的真实任务——比如读一份本地文档、查一次数据库、改一个文件、再跑一遍测试——它就开始掉链子。要么忘了自己刚才做了什么，要么把工具调用的参数拼错，要么在第 5 步之后彻底跑偏，把前面 4 步的成果全推翻。
很多人第一反应是"模型不行，换个更强的"。但换了几轮模型之后你会发现，问题依旧。真正的原因往往不在模型本身，而在于模型外面那层"脚手架"没搭好。这层脚手架，业内现在有个越来越统一的叫法——Harness。
Harness 这个词直译是"马具、挽具"，你可以把它理解成套在模型这匹"马"身上的那套缰绳、鞍具和车架。模型负责提供智力和推理，Harness 负责把这份智力约束在正确的轨道上，让它能稳定地、可重复地、可观测地完成一件具体的事。没有 Harness，模型就是一个只会聊天的天才；有了 Harness，它才变成一个能真正干活的 Agent。
那 Harness 到底由哪些东西组成？我把它拆成了 7 个子系统。这个拆法不是教科书上的标准答案，而是我在实际搭建和调试多个 Agent 项目之后，总结出来的一套"能对上号"的结构。你会发现，几乎所有跑得稳的 Agent 框架，都能在这 7 个子系统里找到对应物；而几乎所有跑不稳的 Agent，问题也都能定位到这 7 个里的某一个或某几个。
这篇文章适合三类人：一是刚开始接触 AI Agent、想知道"除了调模型还要做什么"的新手；二是已经搭过 Demo、但发现一上真实任务就崩的开发者；三是想评估某个 Agent 框架到底靠不靠谱的技术选型者。我会把每个子系统讲清楚它解决什么问题、核心机制是什么、实际搭建时容易踩什么坑，尽量让你看完就能对照自己的项目做体检。
2. 子系统一：Agent Loop——整个 Harness 的心跳
2.1 为什么需要一个"循环"而不是一次调用
最朴素的 Agent 实现是这样的：把用户的问题拼成 prompt，发给模型，拿到回复，结束。这在单轮问答里没问题，但一旦任务需要多步，就彻底不够用了。因为模型没法在一次输出里既"思考"又"行动"又"观察结果"——它输出一个工具调用请求之后，必须有人去真正执行这个工具，把结果喂回去，模型才能基于结果决定下一步。
这个"模型输出 → 执行工具 → 结果回填 → 模型再输出"的过程，就是Agent Loop。它是整个 Harness 的心跳，没有它，其他 6 个子系统都没有存在的意义。
一个最小可用的 Agent Loop 大概长这样：
while not done: response = llm.chat(messages, tools=tool_schemas) if response.has_tool_call: result = execute_tool(response.tool_call) messages.append(tool_result_message(result)) else: done = True final_answer = response.content看起来简单，但魔鬼全在细节里。
2.2 循环终止条件：最容易写出死循环的地方
我见过太多 Agent 卡在死循环里烧 token。模型调用同一个工具、拿到同样的结果、再调用一次，无限重复。原因通常是终止条件设计得太粗糙——只判断"模型有没有输出最终答案"，而没考虑"模型是不是在原地打转"。
实际项目里，我一般会同时设置三重终止条件：
- 正常终止：模型输出了不含工具调用的最终回复。
- 步数上限：硬性限制最大循环次数，比如 25 步。超过就强制中断，把当前状态返回给用户。
- 重复检测：连续 N 次（通常 3 次）出现完全相同的工具调用和参数，判定为卡死，主动注入一条提示让模型换思路，或者直接中断。
提示：步数上限不要设得太小。我一开始设成 10，结果稍微复杂点的任务（比如"读三个文件然后汇总"）根本跑不完。后来调到 25 到 30 之间，配合重复检测，才比较平衡。
2.3 上下文管理：循环越长，历史越臃肿
Agent Loop 每转一圈，messages 数组就长一截。转到第 20 圈的时候，光历史记录可能就几万 token 了。这时候有两个问题：一是成本飙升，二是模型在超长上下文里反而容易"迷失"，抓不住重点。
我的做法是分层管理上下文。近期消息保留完整原文，中期消息做摘要压缩（把"调用了 read_file，参数是 xxx，返回了 yyy"压缩成"读取了文件 xxx"），远期消息只保留关键结论。具体压缩策略要看任务类型，但核心原则是：模型当前决策最需要的信息，必须完整保留；已经消化过的过程性信息，可以压缩。
这里有个反直觉的经验：不是所有工具返回结果都值得完整回填。比如一个返回 5000 行日志的工具，如果你原样塞回上下文，模型很可能被淹没。更好的做法是在工具层就做截断或摘要，只把最相关的部分回填给模型。这个"结果预处理"的活儿，属于工具子系统，但它直接影响 Loop 的健康度。
3. 子系统二：LLM Integration——别把模型当成一个黑盒函数
3.1 模型接入不只是"填个 API Key"
很多人以为 LLM Integration 就是配个 API Key、选个模型名，完事。但真正做过生产级 Agent 的人都知道，这一层要处理的事情多得多：多模型路由、流式输出、重试与降级、token 计数、结构化输出约束、以及不同模型对工具调用格式的差异。
举个最实际的例子：不同模型对"工具调用"的支持方式完全不同。有的模型有原生的 function calling 能力，返回结构化的 tool_calls 字段；有的模型只能靠 prompt 约定，让它输出特定格式的 JSON，然后你自己解析。如果你的 Harness 只适配了一种，换个模型就得大改。
我的建议是在这一层做一个统一的模型抽象层，把不同模型的差异屏蔽掉，对上层 Agent Loop 暴露统一的接口：
class LLMAdapter: def chat(self, messages, tools=None, stream=False): # 内部处理不同模型的格式差异 # 统一返回 {content, tool_calls, usage} ...3.2 结构化输出：让模型的输出可被程序消费
Agent 要干活，模型的输出就必须是程序能解析的。但模型天生喜欢"自由发挥"，你让它输出 JSON，它可能给你包一层 markdown 代码块，可能加一句"好的，这是结果："，可能字段名大小写不一致。
处理这个问题有三条路，我按可靠性从高到低排：
- 用模型原生的结构化输出能力（如果支持），比如强制 JSON schema。
- 用解析器做容错，正则提取 JSON、修复常见格式问题。
- 失败后重试，把解析错误信息回填给模型，让它重新输出。
实测下来，最稳的是"原生能力 + 容错解析 + 有限重试"三件套。单靠任何一个都不够。我踩过的坑是：只做了 JSON 解析，没做重试，结果模型偶尔输出带注释的 JSON（JSON 标准不支持注释），直接解析失败，整个 Loop 崩掉。
3.3 重试、降级与成本控制
模型 API 不是 100% 可用的。超时、限流、偶发的服务错误都会发生。Harness 必须处理这些。我的做法是：
- 指数退避重试：失败后等 1s、2s、4s 再试，最多 3 次。
- 模型降级：主模型连续失败，自动切到备用模型（可以是更便宜或更稳定的）。
- token 预算：给每个任务设一个 token 上限，接近上限时主动收尾，而不是等它烧爆。
注意：降级模型的能力可能差很多，切换后要相应调整 prompt 或降低任务复杂度预期，否则降级后反而更容易出错。
4. 子系统三：Tool System——Agent 的"手和脚"
4.1 工具不是越多越好
新手最容易犯的错，是恨不得把能想到的工具全塞给模型。结果模型面对 50 个工具，选择困难，经常调错。我做过一个对比实验：同一个任务，给模型 8 个精心设计的工具，成功率和给 30 个工具相比，前者明显更高。
工具设计的核心原则是正交且语义清晰。每个工具解决一类明确的问题，工具之间不要有功能重叠。比如你有了read_file，就不要再搞一个read_text_file，模型会困惑该用哪个。
4.2 工具描述就是给模型的"使用说明书"
工具的名字、描述、参数 schema，本质上都是 prompt 的一部分。写得含糊，模型就用得含糊。我见过一个工具描述写"处理数据"，模型完全不知道什么时候该调它。改成"读取指定 CSV 文件的前 N 行，用于快速预览数据结构"，调用准确率立刻上来了。
参数描述同样重要。每个参数要说明：它是什么、格式是什么、有没有默认值、边界在哪。比如max_lines参数，要写清楚"最多返回多少行，默认 100，最大 1000"，而不是只写个"行数"。
4.3 工具执行的安全边界
工具是 Agent 真正"动手"的地方，也是最危险的地方。一个能执行 shell 命令的工具，如果没做限制，模型可能删掉你的文件。所以工具层必须做权限和边界控制：
- 文件操作限制在指定目录内，禁止路径穿越。
- 命令执行做白名单，或者至少在沙箱里跑。
- 网络请求限制域名和频率。
- 所有写操作考虑加确认机制或 dry-run 模式。
这些不是"以后再说"的事，而是从第一个工具开始就要设计的。我吃过亏：早期图省事，文件工具直接用了绝对路径，结果模型在一次任务里把配置目录给改了，排查了半天。
4.4 工具结果的预处理
前面提过，工具返回结果不能原样回填。这一层要做的事包括：截断超长输出、提取关键字段、把二进制或复杂结构转成模型能读的文本、错误信息标准化。
一个实用技巧：让工具返回结构化的{success, data, error}格式，而不是裸的字符串。这样 Agent Loop 能统一判断工具是否成功，失败时也能把标准化的错误信息回填给模型，让它决定是重试还是换方案。
5. 子系统四：Memory & State——让 Agent 记得住、接得上
5.1 短期记忆和长期记忆是两回事
Agent 的"记忆"经常被混为一谈，其实至少要分两层：
- 短期记忆（工作记忆）：当前任务内的上下文，就是 Agent Loop 里那个 messages 数组。任务结束就清空。
- 长期记忆：跨任务、跨会话保留的信息。比如用户的偏好、之前任务的结论、领域知识。
短期记忆的管理前面讲上下文时提过了。长期记忆才是真正考验设计的地方。最简单的长期记忆就是一个向量数据库，把重要信息存进去，需要时检索。但实际用起来，检索的时机和内容筛选很讲究——检索太多会污染上下文，检索太少又记不住关键信息。
5.2 状态机：复杂任务不能只靠"自由发挥"
对于步骤明确的任务（比如"先查数据、再分析、再生成报告"），纯靠模型自由决策容易漏步骤。这时候引入一个轻量的状态机，把任务拆成明确的阶段，每个阶段有进入条件和退出条件，会稳很多。
状态机不需要很重。哪怕只是维护一个current_phase变量，在 prompt 里告诉模型"你现在处于数据收集阶段，只能调用查询类工具"，效果就很明显。这本质上是用工程手段给模型的自由度加了个"护栏"。
5.3 检查点与恢复
长任务跑到一半失败了怎么办？如果没有任何检查点机制，只能从头再来，浪费时间和 token。我的做法是在关键节点保存状态快照：当前阶段、已完成步骤、中间结果。失败后可以从最近的检查点恢复，而不是从零开始。
这个机制在调试阶段尤其有用。你可以从任意检查点重放，快速定位是哪一步开始出问题的。
6. 子系统五：Orchestration——多 Agent 协作的调度中枢
6.1 什么时候需要多个 Agent
单个 Agent 能搞定的事，就别上多 Agent。多 Agent 带来的复杂度是成倍增长的：通信开销、状态同步、冲突解决、调试难度。我见过不少项目，明明一个 Agent 加几个工具就能解决，非要拆成五个 Agent 互相调用，结果稳定性一塌糊涂。
真正需要多 Agent 的场景通常是：任务可以清晰拆分成不同专业领域（比如一个负责检索、一个负责写作、一个负责审核），或者需要并行处理多个独立子任务。
6.2 常见的编排模式
实际项目里，编排模式主要有这么几种：
| 模式 | 适用场景 | 复杂度 | 我的评价 |
|---|---|---|---|
| 顺序流水线 | 步骤固定的任务 | 低 | 最稳，优先考虑 |
| 主管-工人 | 任务可动态分派 | 中 | 灵活但主管容易成为瓶颈 |
| 并行竞标 | 需要多方案择优 | 中 | 成本高，适合关键决策 |
| 自由协作 | 开放式复杂任务 | 高 | 最难调，慎用 |
对大多数项目，我建议从顺序流水线开始，不够用了再升级。别一上来就搞自由协作，那是给自己找麻烦。
6.3 通信与状态共享
多 Agent 之间怎么传递信息？最简单的是通过共享的上下文对象，但要注意并发读写的问题。更规范的做法是定义明确的消息格式，Agent 之间只通过消息通信，不直接共享内存。
状态共享的坑在于：多个 Agent 同时修改同一份状态，容易产生不一致。我的经验是尽量让状态"单向流动"——上游 Agent 产出结果，下游 Agent 消费，避免双向修改。
7. 子系统六：Observability——看不见的 Agent 最可怕
7.1 为什么可观测性是刚需
Agent 出问题时，最怕的是"不知道为什么"。模型调了什么工具、传了什么参数、拿到什么结果、为什么做这个决策——如果这些都没有记录，排查就是盲人摸象。
可观测性不是"锦上添花"，而是"雪中送炭"。我在项目里强制要求：每一次 LLM 调用、每一次工具执行、每一次状态变更，都要有结构化日志。日志里至少包含：时间戳、步骤编号、输入、输出、耗时、token 消耗。
7.2 追踪一次完整的 Agent 执行
理想情况下，你能把一次 Agent 执行还原成一条清晰的时间线：
Step 1: LLM 调用 (1.2s, 850 tokens) -> 决定调用 search_docs Step 2: 工具执行 search_docs (0.3s) -> 返回 3 条结果 Step 3: LLM 调用 (2.1s, 1200 tokens) -> 决定调用 read_file Step 4: 工具执行 read_file (0.1s) -> 返回文件内容 Step 5: LLM 调用 (1.8s, 900 tokens) -> 输出最终答案有了这条时间线，哪一步慢、哪一步 token 消耗异常、哪一步决策可疑，一目了然。
7.3 关键指标与告警
除了单次追踪，还要有聚合指标：任务成功率、平均步数、平均 token 消耗、工具调用失败率、平均耗时。这些指标能帮你发现系统性的问题。比如工具失败率突然上升，可能是某个外部服务挂了；平均步数变多，可能是模型变笨了或者 prompt 需要调整。
提示：别等出问题才加日志。从第一天就把可观测性做进去，后面省下的排查时间远超前期投入。
8. 子系统七：Guardrails——给 Agent 装上刹车和护栏
8.1 输入输出双向校验
Guardrails 是最后一道防线，负责在输入和输出两端做校验。输入端：过滤恶意 prompt、检测越权请求、限制任务范围。输出端：检查结果是否符合格式要求、是否包含敏感内容、是否真的完成了任务。
这一层经常被忽略，直到出事。我见过 Agent 被诱导去执行了不该执行的操作，也见过 Agent 输出了一堆看起来像模像样但完全错误的结果。双向校验能拦住大部分这类问题。
8.2 行为约束与预算控制
除了内容校验，还要约束 Agent 的行为边界：单次任务最多调多少次工具、最多花多少 token、最多跑多长时间。这些预算控制是防止 Agent "失控"的关键。
预算控制要和 Agent Loop 的终止条件配合。Loop 负责"正常情况下的收尾"，Guardrails 负责"异常情况下的强制刹车"。两者缺一不可。
8.3 人工介入的时机
不是所有决策都该让 Agent 自己做。涉及不可逆操作（删除、支付、发送）时，应该设置人工确认节点。这个"人在回路"的设计，是很多生产级 Agent 的标配。
我的做法是给工具打上"风险等级"标签，高风险工具在执行前必须经过确认。确认可以是同步的（暂停等用户点确认），也可以是异步的（先记录，事后审核）。具体选哪种，看业务对实时性的要求。
9. 把这 7 个子系统串起来：一次真实任务的完整走查
光讲子系统容易割裂，我们用一个具体任务把它们串一遍。假设任务是："读取项目里的日志文件，找出所有报错，汇总成一份报告。"
第一步，Guardrails 介入：校验这个请求是否在允许范围内（读文件、生成报告，没问题），设定预算（最多 20 步、5 万 token）。
第二步，Agent Loop 启动：把任务和可用工具列表（read_file、list_dir、write_file）交给 LLM Integration 层。
第三步，LLM 决策：模型决定先调用 list_dir 看看有哪些文件。Tool System 执行，返回文件列表。结果经过预处理（截断、格式化）后回填。
第四步，Memory 记录：当前阶段是"文件探索"，已发现日志文件路径，这些状态被记录下来。
第五步，继续 Loop：模型调用 read_file 读取日志，Tool System 返回内容（可能很大，做截断）。模型分析内容，找出报错行。
第六步，Orchestration（如果用了多 Agent）：如果报告生成交给另一个专门的 Agent，这里就是交接点。
第七步，Observability 记录全程：每一步的耗时、token、决策都被记录，形成完整时间线。
第八步，Guardrails 收尾校验：检查生成的报告是否符合格式、是否真的包含了报错信息、有没有越权操作。
第九步，Loop 终止：模型输出最终报告，任务完成。
你看，一个看起来简单的任务，背后是 7 个子系统在协同。任何一个环节薄弱，任务都可能失败或质量下降。
10. 搭建 Harness 时我踩过的几个真实坑
坑一：过早追求"通用"。一开始我想做一个能处理所有任务的通用 Harness，结果每个子系统都做得很泛，哪个任务都跑不好。后来改成针对具体场景做特化，反而稳了。通用性是演化出来的，不是设计出来的。
坑二：忽视工具结果的体量。有个工具返回了几万字的文本，直接塞进上下文，模型直接"失忆"，后面的决策全乱。后来强制所有工具结果做截断和摘要，问题解决。
坑三：日志记了但没人看。早期日志格式混乱，出问题时根本没法快速定位。后来统一了结构化日志格式，还写了个简单的可视化脚本，排查效率提升明显。
坑四：终止条件太单一。只判断"模型有没有输出最终答案"，结果遇到模型反复调用同一工具时死循环。加上步数上限和重复检测后才稳。
坑五：把 Guardrails 当摆设。觉得"模型应该不会乱来"，结果一次测试中模型真的执行了超出预期的操作。从那以后，所有高风险工具都加了确认机制。
11. 关于 Harness 和 Agent 的关系，再说几句
经常有人问：Harness 和 Agent 到底啥区别？我的理解是：Agent 是一个完整的概念，指的是"能自主完成任务的智能体"；Harness 是支撑这个智能体运转的工程基础设施。Agent 是"人"，Harness 是"人的神经系统、骨骼和工具"。
所以当你觉得"我的 Agent 不好用"时，先别急着换模型，先体检这 7 个子系统：Loop 稳不稳？模型接入有没有容错？工具设计清不清晰？记忆管理合不合理？编排是不是过度设计？可观测性够不够？护栏有没有？
大部分问题，都能在这 7 个里找到答案。模型的能力当然重要，但决定一个 Agent 能不能真正干活的，往往是模型外面这层看不见的 Harness。把 Harness 搭扎实了，哪怕用中等能力的模型，也能跑出稳定的结果；Harness 搭得烂，再强的模型也救不了。
这套 7 子系统的拆法，是我自己在多个项目里反复验证、不断修正后形成的。它不一定是最权威的，但至少能对上号、能落地、能帮你快速定位问题。如果你正在搭自己的 Agent，不妨拿这 7 条对照着过一遍，看看哪块最薄弱，先补哪块。
