企业官网建设流程全解析

1. 拆开“Harness”这个词，先搞清楚它到底指什么

很多人第一次听到“AI Agent 的 Harness”这个说法，脑子里冒出来的可能是测试框架里的 harness，或者是硬件领域里的线束。但在 AI Agent 这个语境下，Harness 指的是一套让 Agent 真正能跑起来、能干活、能稳定交付结果的运行时骨架。你可以把它理解成汽车的底盘和传动系统——发动机（大模型）再强，没有底盘和传动，动力也传不到轮子上。

我刚开始接触 Agent 开发的时候，也走过一段弯路。那时候觉得 Agent 不就是“大模型 + 工具调用”吗？写个循环，让模型决定调哪个工具，调完把结果塞回去，再让模型决定下一步，不就完了？结果真上手做项目才发现，事情远没有这么简单。模型会忘记上下文、工具调用会失败、多轮循环会跑飞、并发一上来整个系统就卡死。这些问题不是靠“换个更强的模型”就能解决的，它们属于 Harness 层要处理的事情。

所以这篇文章我想把 Harness 这个东西彻底拆开讲清楚。核心结论先放在前面：一个能真正干活的 AI Agent Harness，通常由7 个子系统协同构成。这 7 个子系统各司其职，缺一个都会在某个场景下出问题。下面我会逐个拆解每个子系统解决什么问题、怎么实现、有哪些坑，以及它们之间是怎么配合的。

这篇文章适合谁看？如果你正在从 0 到 1 搭建 AI Agent，或者已经搭了一个但发现它“不太靠谱”，又或者你在评估市面上的 Agent 框架到底该选哪个，那这篇内容应该能帮你建立一套完整的认知框架。我不打算只讲概念，每个子系统我都会给出可落地的实现思路和关键参数。

2. 为什么“模型 + 工具调用”远远不够

2.1 一个真实的翻车场景

先讲一个我亲身经历的场景。之前做一个客服工单自动处理的 Agent，需求很明确：读取工单内容，判断类型，调用相应的内部 API 获取信息，然后生成回复或者转人工。逻辑听起来很简单，我用了当时觉得最顺手的方案，一个 while 循环加工具调用，半天就跑通了 demo。

结果上线测试第一天就出问题了。有个工单触发了连续 11 轮工具调用，模型在第 8 轮的时候开始重复调用同一个接口，因为前一次返回的数据格式和它预期的不一样，它以为没调成功。到第 11 轮的时候 token 已经烧了快 3 万，最后超时失败。更麻烦的是，这个失败是静默的——用户那边看到的是“正在处理中”，实际上 Agent 已经卡死了。

这个问题暴露出来的不是模型能力问题，而是 Harness 缺失。具体来说，缺少了循环控制、缺少了工具返回结果的规范化处理、缺少了失败重试策略、缺少了超时熔断机制。这四样东西，分别对应后面要讲的 Agent Loop、工具执行、错误处理和可观测性几个子系统。

2.2 Harness 和 Agent 的关系

这里需要厘清一个概念。Agent 是“做什么”，Harness 是“怎么让它稳定地做”。Agent 的核心是决策逻辑，也就是给定当前状态，下一步该干什么。Harness 的核心是执行环境，也就是让这个决策能够被可靠地执行、被观测、被控制、被恢复。

打个比方，Agent 像是司机，Harness 像是整辆车加上道路系统。司机再厉害，如果方向盘会卡死、刹车会失灵、油表不准、路上没有路标，那也到不了目的地。很多团队在 Agent 开发上投入大量精力调 prompt、换模型，但效果提升有限，原因往往就是 Harness 层太薄了。

2.3 七个子系统的整体视图

在展开细节之前，先给出这 7 个子系统的清单，让大家有个全局印象：

这 7 个不是随便凑数的，它们覆盖了 Agent 从启动到结束的完整生命周期。下面逐个展开。

3. 子系统一：Agent Loop，整个 Harness 的心脏

3.1 Loop 的基本形态

Agent Loop 是整个 Harness 里最核心的部分，它决定了 Agent 以什么节奏运转。最基础的形态就是一个循环：把当前上下文发给模型，模型返回一个动作（可能是调用工具，也可能是给出最终答案），执行这个动作，把结果追加到上下文，然后进入下一轮。

用伪代码表示大概是这样：

while not done: response = llm.invoke(context) action = parse(response) if action.type == "final_answer": done = True return action.content elif action.type == "tool_call": result = execute_tool(action) context.append(result) if step_count > max_steps: raise LoopLimitExceeded()

看起来简单，但魔鬼在细节里。这个循环里至少有五个关键决策点需要仔细设计。

3.2 循环终止条件的设计

第一个决策点是什么时候停。最直观的是模型输出最终答案就停，但实际项目中你需要至少三重保险。

第一重是模型主动终止，也就是它认为任务完成了。第二重是步数上限，防止无限循环。第三重是资源上限，比如累计 token 消耗或者累计耗时超过阈值就强制终止。我一般会把步数上限设在 15 到 25 之间，具体看任务复杂度。简单问答类 5 步足够，复杂的数据处理任务可能需要 20 步以上。

这里有个经验：步数上限不要设得太紧。我见过有团队为了省钱把上限设成 5，结果稍微复杂一点的任务全部失败，反而浪费了前面几步的 token。宁可设宽一点，配合资源上限来兜底。

3.3 循环内的上下文增长控制

第二个决策点是上下文怎么增长。每一轮工具调用的结果都会追加到上下文里，几轮下来上下文就会变得很长。如果不加控制，很快就会撞到模型的上下文窗口上限，而且 token 成本会线性上升。

常见的做法有三种。第一种是滑动窗口，只保留最近 N 轮。第二种是摘要压缩，把早期的轮次用模型总结成一段简短描述。第三种是结构化裁剪，只保留关键字段，丢弃冗余信息。我通常会把第二种和第三种结合使用：工具返回结果先做结构化提取，只保留必要字段；当轮次超过阈值时，对早期轮次做摘要。

3.4 循环的并发与中断

第三个决策点是能不能中断。用户可能中途想取消任务，或者系统需要优雅关闭。这就要求 Loop 的每一轮之间要检查中断信号，并且要保证中断时状态是可保存的。这一点和后面的 State & Persistence 子系统强相关。

第四个决策点是并发。单个 Agent 实例的 Loop 是串行的，但多个 Agent 实例可以并发。这里要注意的是，并发控制不应该放在 Loop 内部，而应该放在更上层的调度层。Loop 本身保持简单和纯粹，这样更容易测试和调试。

提示：Agent Loop 最容易出的问题是“静默卡死”，也就是循环还在跑但实际没有任何进展。建议在每一轮记录一个“进展指标”，比如是否产生了新的工具调用、是否获取到了新信息。如果连续 N 轮没有进展，主动终止并报错。

4. 子系统二：LLM Integration，别把它当成简单的 API 调用

4.1 Prompt 组装不是拼字符串

很多人把 LLM Integration 理解成“调一下模型 API”，这是最大的误解。这个子系统真正要做的事情包括：系统提示词的版本管理、动态上下文的注入、工具描述的格式化、输出格式的约束、多模型的路由和降级。

先说 prompt 组装。Agent 的 prompt 通常由几部分组成：角色设定、任务描述、可用工具列表、当前上下文、输出格式要求。这几部分不是简单拼接就完事，它们之间有优先级和相互影响。比如工具描述太长会挤占上下文空间，输出格式要求太严格会限制模型的推理能力。

我的做法是把 prompt 拆成模板和变量两部分。模板固定不变，变量根据运行时状态动态填充。模板本身做版本管理，每次修改都记录变更原因和效果对比。这样出问题的时候可以快速回滚。

4.2 输出解析的健壮性

输出解析是另一个重灾区。你要求模型输出 JSON，它大部分时候会输出 JSON，但偶尔会加个 markdown 代码块标记，偶尔会在 JSON 前后加解释文字，偶尔会漏个括号。如果解析逻辑写得太脆，这些情况都会导致整个 Loop 崩溃。

我的经验是解析逻辑要分层。第一层尝试严格解析，失败后第二层尝试提取 JSON 片段，再失败第三层尝试用模型自己修复格式，最后还失败才报错。同时要记录解析失败的频率和样本，用来持续优化 prompt。

4.3 多模型路由与降级

实际项目中很少只用一个模型。常见的情况是：简单任务用便宜快的模型，复杂任务用贵但强的模型；主模型不可用时自动降级到备用模型。这要求 LLM Integration 层提供统一的路由接口，上层 Loop 不需要关心具体用的是哪个模型。

路由策略可以基于任务类型、上下文长度、历史成功率等维度。降级策略要设置好触发条件和恢复条件，避免在主模型只是偶尔抖动时就永久切换。

5. 子系统三：Tool Execution，工具调用的可靠性工程

5.1 工具注册与描述生成

工具执行子系统的第一件事是工具注册。每个工具需要定义：名称、描述、参数 schema、执行函数、超时时间、重试策略。其中描述和参数 schema 会直接进入 prompt，所以它们的质量直接影响模型能否正确调用工具。

我见过很多团队工具描述写得很随意，比如“查询用户信息”就完事了。模型看到这种描述根本不知道参数该传什么、返回什么格式。好的工具描述应该包含：这个工具做什么、什么时候用、参数含义和格式、返回结果的结构、可能的错误情况。

5.2 参数校验与修正

模型生成的工具参数经常有问题：类型不对、必填项缺失、格式不符合要求。如果直接把这种参数传给工具函数，轻则报错，重则产生副作用。所以参数校验是必须的。

校验之后还有一步是修正。有些问题可以自动修正，比如字符串 “123” 转成数字 123，日期格式统一化。有些问题需要让模型重新生成，比如必填参数缺失。这里要设置好重试次数，避免陷入“模型反复生成错误参数”的死循环。

5.3 工具执行的隔离与超时

工具执行必须做隔离。一个工具卡死不能拖垮整个 Agent。常见的做法是每个工具调用放在独立的执行单元里，设置硬超时，超时后强制终止并返回错误。

超时时间怎么定？我的经验是分三档：本地计算类工具 5 秒，外部 API 调用 15 秒，涉及文件或数据库操作 30 秒。超过这个时间基本可以认为出了问题，继续等下去没有意义。

5.4 结果处理与副作用控制

工具返回的结果不能直接塞回上下文，需要先做处理。处理包括：截断过长的结果、提取关键字段、脱敏敏感信息、格式化数据结构。这一步做得好，能显著降低上下文膨胀速度和 token 成本。

副作用控制是另一个重点。有些工具是有副作用的，比如发邮件、改数据库、下单。这类工具要特别小心，需要加确认机制，避免模型误调用。我的做法是把工具分成只读和写入两类，写入类工具需要额外的确认步骤。

注意：工具执行失败时，返回给模型的错误信息要具体但不暴露内部细节。比如“参数格式错误，日期应为 YYYY-MM-DD”比“ValueError at line 42”更有用，同时也不会泄露实现细节。

6. 子系统四：Memory & Context，让 Agent 记得住又不撑爆

6.1 短期上下文的管理策略

短期上下文就是当前任务执行过程中的对话历史。它的管理核心是在“记得足够多”和“不撑爆窗口”之间找平衡。前面提到过滑动窗口、摘要压缩、结构化裁剪三种策略，这里展开讲一下具体怎么选。

滑动窗口最简单，但会丢失早期重要信息。摘要压缩能保留信息但会增加一次模型调用。结构化裁剪需要针对具体工具做定制。我的建议是：默认用滑动窗口 + 关键信息固定保留。所谓关键信息固定保留，是指把任务目标、已确认的事实、当前进度这些信息单独维护，不参与滑动。

6.2 长期记忆的存取设计

长期记忆解决的是跨任务的信息复用。比如用户偏好、历史交互记录、领域知识。长期记忆的难点不在存，而在取。存的时候容易，全存下来就行；取的时候要精准，不能把所有记忆都塞进上下文。

常见的做法是用向量检索。把记忆条目做 embedding，查询时用当前上下文做相似度检索，取 top-k 条。这里的关键是 embedding 的质量和检索的阈值设置。阈值太低会引入无关信息，太高会漏掉有用信息。我一般会先用一个较宽的阈值召回，再用模型做一次相关性过滤。

6.3 上下文压缩的实操参数

上下文压缩涉及几个关键参数：触发阈值、压缩比例、保留策略。触发阈值一般设在上下文窗口的 70% 到 80%。压缩比例看情况，通常压缩到原来的 30% 到 50%。保留策略要明确哪些信息绝对不能丢，比如任务目标、用户明确指令、已确认的关键事实。

压缩本身也是一次模型调用，所以要注意压缩的 prompt 设计。压缩 prompt 要明确告诉模型：保留什么、丢弃什么、输出格式是什么。压缩后的结果要校验，确保没有丢失关键信息。

7. 子系统五：State & Persistence，断点恢复的底气

7.1 状态快照的时机与内容

Agent 运行过程中会产生大量状态：当前轮次、上下文内容、已调用的工具及结果、中间变量。这些状态如果不持久化，一旦进程崩溃或者需要重启，整个任务就得从头再来。对于长任务来说这是不可接受的。

状态快照的时机很关键。太频繁会影响性能，太稀疏会丢失进度。我的做法是在几个关键节点做快照：每轮 Loop 结束后、每次工具调用前后、每次上下文压缩后。快照内容要包含恢复所需的最小信息集，不是全量 dump。

7.2 恢复逻辑的设计

恢复逻辑要处理几种情况：正常恢复、部分恢复、恢复失败。正常恢复就是从快照点继续执行。部分恢复是指快照不完整，需要重新执行某些步骤。恢复失败是指快照损坏或版本不兼容，只能从头开始。

这里有个容易忽略的点：恢复后的上下文要和恢复前保持一致。如果恢复时上下文组装逻辑变了，模型看到的内容就不一样，可能导致行为不一致。所以上下文组装逻辑也要版本化。

7.3 存储选型与性能考量

状态存储的选型取决于任务时长和并发量。短任务可以用内存加定期落盘。长任务需要持久化存储，Redis 或数据库都可以。高并发场景要考虑存储的读写性能，避免成为瓶颈。

8. 子系统六：Guardrails & Error Handling，别让 Agent 闯祸

8.1 输入输出的约束

Guardrails 的第一层是输入输出约束。输入侧要防止 prompt 注入、恶意指令、超长输入。输出侧要防止敏感信息泄露、格式错误、有害内容。这些约束有的可以用规则做，有的需要模型判断。

规则类的约束比如长度限制、格式校验、关键词过滤，成本低速度快，应该尽量用规则。模型类的约束比如意图判断、内容安全，成本高但更灵活，用在规则覆盖不到的地方。

8.2 异常分类与处理策略

Agent 运行中的异常可以分成几类：模型异常（超时、限流、返回格式错误）、工具异常（调用失败、返回错误、超时）、逻辑异常（循环超限、状态不一致）、外部异常（网络问题、依赖服务不可用）。

每类异常的处理策略不同。模型异常通常重试或降级。工具异常要看是否可重试，只读工具可以重试，写入工具要谨慎。逻辑异常一般需要终止并报警。外部异常要有熔断机制，避免雪崩。

8.3 降级与兜底方案

再好的系统也会出问题，关键是出问题时有兜底。Agent 的兜底方案包括：返回部分结果、转人工处理、返回预设的默认回复。选择哪种取决于业务场景。客服场景转人工是合理的，数据处理场景返回部分结果可能更有用。

兜底方案要提前设计好，不能等出问题了再想。而且兜底方案本身也要测试，确保真的能用。

提示：Guardrails 最容易犯的错误是“过度限制”。限制太多会导致 Agent 正常任务也做不了。建议先用宽松策略上线，根据实际出问题的情况逐步收紧，而不是一开始就设一堆限制。

9. 子系统七：Observability & Control，看不见就等于失控

9.1 日志与追踪的设计

Agent 的日志和普通应用日志不一样。普通日志记录“发生了什么”，Agent 日志还需要记录“为什么这么决策”。具体来说，每一轮要记录：输入上下文、模型输出、解析结果、工具调用及结果、耗时、token 消耗。

追踪方面，一个任务从开始到结束应该有一个统一的 trace id，所有相关日志都带上这个 id。这样排查问题时可以完整还原整个执行链路。如果用了多个模型或工具，还要记录每个环节的耗时分布，找出瓶颈。

9.2 关键指标监控

需要监控的指标分几类。性能类：每轮耗时、总耗时、token 消耗。质量类：任务成功率、工具调用成功率、解析失败率。成本类：单任务平均成本、模型调用分布。异常类：各类异常的发生频率。

这些指标要设置告警阈值。比如任务成功率低于 90% 告警，单任务 token 消耗超过阈值告警。告警要及时，但也不能太敏感，否则会疲劳。

9.3 人工干预的接口

有些场景需要人工介入：Agent 卡住了、Agent 要做高风险操作、Agent 的结果需要审核。这要求 Harness 提供人工干预接口，包括：暂停/恢复、修改上下文、跳过当前步骤、强制终止。

人工干预接口的设计要考虑权限和审计。谁能干预、干预了什么、什么时候干预的，都要有记录。这既是安全要求，也是后续优化的数据来源。

10. 七个子系统怎么串起来：一个完整的执行流程

10.1 从任务接收到结果返回

把七个子系统串起来看，一个完整的执行流程是这样的：

1. 任务进入，Guardrails 做输入校验
2. State & Persistence 创建任务状态
3. Memory & Context 加载相关记忆和初始上下文
4. Agent Loop 启动，进入循环
5. 每轮循环中，LLM Integration 组装 prompt 并调用模型
6. 解析模型输出，如果是工具调用则进入 Tool Execution
7. Tool Execution 校验参数、执行工具、处理结果
8. 结果追加到上下文，Memory & Context 判断是否需要压缩
9. State & Persistence 在关键节点做快照
10. Observability 记录全过程
11. 循环终止后，Guardrails 做输出校验
12. 返回结果，State & Persistence 清理或归档状态

这个流程里每个环节都可能出问题，所以每个环节都需要有对应的错误处理。

10.2 子系统之间的依赖关系

这七个子系统不是完全独立的，它们之间有依赖关系。Agent Loop 依赖 LLM Integration 和 Tool Execution。Memory & Context 依赖 State & Persistence 做持久化。Guardrails 贯穿所有环节。Observability 也是横切关注点。

理解这些依赖关系有助于排查问题。比如 Loop 卡住可能是 LLM Integration 的问题，也可能是 Tool Execution 的问题。有了清晰的依赖图，就能快速定位。

10.3 不同规模下的取舍

不是所有项目都需要完整的七个子系统。小项目可能只需要 Agent Loop、LLM Integration、Tool Execution 三个核心，其他四个简化处理。但随着项目变大、要求变高，缺失的子系统会逐渐成为瓶颈。

我的建议是：核心三个子系统一开始就要做好，其他四个可以先简化但要有预留。比如 Observability 一开始可以只打日志，但日志格式要设计好，方便后续接入完整的监控系统。

11. 实操中踩过的坑和排查技巧

11.1 常见问题速查表

11.2 几个反直觉的经验

第一个反直觉的经验是：模型不是越强越好。强模型在简单任务上可能过度推理，反而增加不确定性和成本。我做过对比测试，在分类任务上小模型配合好的 prompt，效果和大模型差不多，但成本和延迟都低很多。

第二个反直觉的经验是：重试不一定能解决问题。有些失败是确定性的，比如参数格式错误，重试多少次都一样。这时候应该做的是修正参数而不是重试。只有瞬时性失败才适合重试。

第三个反直觉的经验是：日志不是越多越好。日志太多会淹没关键信息，也会影响性能。关键是日志的结构化，让每条日志都有明确的字段和用途，方便过滤和聚合。

11.3 性能优化的几个切入点

性能优化优先看三个地方。第一是模型调用，这是最大的耗时来源。优化方向包括：用更快的模型、减少不必要的调用、并行化可以并行的调用。第二是工具执行，特别是外部 API 调用。优化方向包括：加缓存、批量调用、异步化。第三是上下文处理，特别是压缩和检索。优化方向包括：减少压缩频率、优化检索算法、缓存检索结果。

12. 关于 Harness 工程化的一些个人体会

做了一段时间 Agent 开发之后，我越来越觉得 Harness 的重要性被低估了。大家讨论 Agent 的时候，焦点往往在模型能力、prompt 技巧、应用场景上，但真正决定 Agent 能不能在生产环境稳定运行的，是 Harness 这一层。

我现在的习惯是，接到一个 Agent 需求，先不急着写 prompt 和调模型，而是先把 Harness 的骨架搭起来。七个子系统里，至少把 Agent Loop、Tool Execution、Observability 这三个先做扎实。然后再在这个骨架上迭代 Agent 的决策逻辑。这样做的结果是，前期看起来慢一点，但后期调试和优化的效率高很多。

还有一个体会是，Harness 的设计要留有余地。不要一开始就把所有策略写死，而是把关键参数做成可配置的。这样上线后可以根据实际数据调整，而不需要改代码重新部署。比如步数上限、超时时间、压缩阈值这些，都应该是配置项。

最后分享一个小技巧：给 Agent 的每一轮循环打一个“决策标签”，比如“信息收集”“方案生成”“结果验证”。这个标签可以由模型自己生成，也可以由规则判断。有了这个标签，后续分析 Agent 行为的时候就清晰很多，能快速看出它在哪个阶段容易出问题。这个做法成本很低，但排查问题时特别有用。