企业官网建设流程全解析

1. 别被"Harness"这个词唬住，它其实就是Agent的骨架

第一次听到"Harness"这个词，很多人脑子里浮现的是线束、马具、测试框架这些不相干的东西。但在AI Agent的语境里，Harness指的不是某个具体工具，而是让大模型真正能"下地干活"的那套运行时骨架。你可以把它理解成一辆车的底盘加传动系统——发动机（LLM）再猛，没有底盘和传动，动力也传不到轮子上。

我见过太多人搭Agent的路径是这样的：调通一个API，写个while循环，把用户输入丢给模型，模型返回个JSON，解析一下执行，然后再丢回去。跑个demo没问题，一旦要处理真实任务——比如连续调用十几个工具、中途需要人工确认、某个步骤失败了要重试、上下文超长了要压缩——整个东西就开始散架。问题不在于模型不够聪明，而在于缺少一套结构化的运行时来管理"干活"这件事本身。

Harness要解决的核心问题就一个：把"模型的一次输出"变成"一个能持续完成任务的系统"。它管的是模型之外的所有事情——循环怎么转、工具怎么调、状态存哪里、失败了怎么办、上下文怎么管、多个Agent怎么协作、外部系统怎么接进来。这七件事，恰好对应了七个子系统。

这篇文章适合两类人看：一类是已经用LangChain、Spring AI或者自己手搓过Agent、但总觉得"能跑但不敢上生产"的开发者；另一类是正准备从0到1搭Agent、想先搞清楚架构再动手的人。我会把这七个子系统逐个拆开，讲清楚每个子系统到底管什么、为什么必须有它、实际实现时容易踩什么坑。不堆概念，讲的是我实际搭过几套Agent之后沉淀下来的东西。

2. Agent Loop：整个Harness的心跳，也是最容易写歪的地方

2.1 为什么"一个while循环"远远不够

几乎所有Agent教程都会给你看这段伪代码：

while not done: response = llm.chat(messages) if response.has_tool_call: result = execute_tool(response.tool_call) messages.append(result) else: done = True

这段代码能跑，但它把Agent Loop想得太简单了。真实的Loop要处理的问题包括：模型连续输出同一个工具调用怎么办（死循环）、工具执行超时怎么办、模型返回的格式解析不了怎么办、用户中途想插话怎么办、任务跑了20轮还没结束要不要强制收敛。这些都不是"循环"本身能解决的，而是Loop子系统必须内建的策略。

我的经验是，一个能上生产的Agent Loop至少要包含四个控制维度：轮次上限、超时控制、异常熔断、人工介入点。轮次上限防止无限循环，一般设15到25轮比较合理，具体看任务复杂度；超时控制分两层，单次LLM调用超时和整个任务超时；异常熔断是指连续N次工具调用失败就停下来，而不是傻傻重试；人工介入点是在关键操作前暂停，等确认后再继续。

2.2 Loop的两种主流形态：ReAct和Plan-Execute

实际落地时，Loop有两种典型形态。ReAct形态是"想一步做一步"，模型每轮都重新决策下一步干什么，灵活但容易跑偏，适合探索性任务。Plan-Execute形态是先让模型出一个完整计划，然后按计划逐步执行，执行中允许调整，稳定但不够灵活，适合流程明确的任务。

我个人的选择标准是：如果任务步骤可以提前枚举（比如"查数据→分析→生成报告"），用Plan-Execute；如果任务需要根据中间结果动态决定下一步（比如"帮我排查这个bug"），用ReAct。很多成熟系统其实是混合的——外层用Plan-Execute定框架，内层每个步骤用ReAct处理细节。

提示：不要一上来就追求复杂的Loop。我见过有人给一个简单的问答Agent套了五层循环控制，结果调试成本高得离谱。Loop的复杂度应该匹配任务的复杂度，简单任务用简单Loop。

2.3 实测中Loop最容易出的三个问题

第一个是工具调用参数幻觉。模型会编造不存在的参数名，或者把参数类型搞错（该传数组传了字符串）。解决办法是在工具定义里把参数schema写死，执行前做一次校验，校验失败就把错误信息回传给模型让它重试。

第二个是上下文爆炸。ReAct形态下每轮都往messages里追加内容，跑十几轮之后上下文就爆了。必须在Loop里内建上下文管理策略，这个后面第5节会细讲。

第三个是状态丢失。Loop跑到一半服务重启，整个任务状态没了。这就要求Loop的状态必须可持久化，不能只存在内存里。我一般会把每轮的状态快照存到数据库或Redis，重启后能从最后一个检查点恢复。

3. LLM Integration：不是"调个API"那么简单

3.1 多模型路由是刚需，不是可选项

很多人以为LLM Integration就是封装一个chat函数。实际做起来，第一个要面对的问题就是多模型路由。不同任务对模型的要求不一样：简单分类用便宜的小模型，复杂推理用强模型，需要长上下文的任务用支持大窗口的模型。如果Harness只绑死一个模型，成本和效果都没法优化。

我的做法是在Integration层做一个路由表，根据任务类型、输入长度、预算约束三个维度选模型。比如输入超过50K token就路由到长上下文模型，任务标记为"简单"就走小模型。路由逻辑要可配置，不能写死在代码里，因为模型的价格和能力变化太快了。

3.2 流式输出和工具调用的兼容坑

流式输出（streaming）和工具调用（tool calling）这两个特性放在一起时，坑特别多。有些模型在流式模式下工具调用的参数是分片返回的，你需要自己拼接；有些模型流式模式下干脆不支持工具调用。Integration层必须处理这些差异，对上层的Loop暴露统一的接口。

我踩过的一个坑是：某模型在流式模式下，工具调用的JSON参数会在多个chunk里分片到达，如果直接解析每个chunk会报错。正确做法是累积所有chunk，等收到结束标志再整体解析。这个逻辑必须封装在Integration层，不能让Loop去操心。

3.3 重试、降级和成本追踪

LLM调用失败是常态，不是异常。网络抖动、限流、模型过载都会导致失败。Integration层必须内建重试机制，但要区分错误类型：限流错误要退避重试，参数错误重试没用，服务错误可以换模型降级。

成本追踪也常被忽略。每个任务消耗了多少token、花了多少钱，这些数据对生产系统至关重要。我一般会在Integration层记录每次调用的输入输出token数和对应成本，按任务ID聚合。没有这层数据，你根本不知道钱花在哪了。

4. Tool System：Agent的手和脚，设计好坏直接决定能力上限

4.1 工具描述写得好不好，决定模型会不会用

工具系统的核心不是"怎么执行工具"，而是"怎么让模型知道该用哪个工具"。这完全取决于工具的描述质量。我见过太多人把工具描述写成"查询用户信息"，然后抱怨模型不会用。正确的描述应该包含：这个工具做什么、什么时候用、参数含义、返回值格式、使用示例。

举个例子，一个查询订单的工具，描述应该写成："根据订单号查询订单详情。当用户询问订单状态、物流信息、退款进度时使用此工具。参数order_id为字符串格式的订单编号，通常以'ORD'开头。返回包含订单状态、金额、创建时间的JSON对象。"这样模型才知道什么时候该调它。

4.2 工具粒度：太粗和太细都是灾难

工具粒度是个需要反复权衡的问题。粒度太粗，比如一个"处理用户请求"的工具包打天下，模型没法精细控制；粒度太细，比如把"查询订单"拆成"连接数据库""执行SQL""格式化结果"三个工具，模型要调三次才能完成一件事，容易出错。

我的经验法则是：一个工具对应一个完整的业务动作。查询订单是一个动作，发送邮件是一个动作，创建日程是一个动作。工具内部可以很复杂，但对模型暴露的应该是一个语义完整的操作。这样模型决策简单，出错概率低。

4.3 工具执行的安全边界

工具执行必须有安全边界。我一般会做三层防护：参数校验（类型、范围、格式）、权限检查（这个Agent有没有权限调这个工具）、操作确认（危险操作如删除、支付需要人工确认）。第三层特别重要，我见过Agent误删生产数据的案例，就是因为没有确认环节。

注意：工具执行结果不要直接原样返回给模型。数据库查询可能返回几万行数据，直接塞进上下文会爆。要在工具层做结果截断和摘要，只返回模型需要的信息。

5. Memory & Context：Agent的记性，决定了它能干多复杂的活

5.1 短期记忆、长期记忆和工作记忆

Agent的记忆分三层。短期记忆是当前对话的上下文，就是messages数组；长期记忆是跨会话持久化的信息，比如用户偏好、历史任务；工作记忆是当前任务执行过程中的中间状态，比如已经查到的数据、已经完成的步骤。

这三层的管理策略完全不同。短期记忆要处理超长压缩，长期记忆要处理检索和更新，工作记忆要处理状态快照和恢复。很多Agent只做了短期记忆，所以一关会话就"失忆"，跨会话的任务根本做不了。

5.2 上下文压缩的几种实用策略

上下文压缩是绕不开的。我的策略是分优先级处理：系统提示词和工具定义永远保留（这是Agent的行为准则），最近N轮对话完整保留（保证连贯性），更早的对话做摘要压缩（用模型把历史对话总结成要点），工具返回的大结果做截断或存外部（需要时再检索）。

摘要压缩有个技巧：不要让模型自由发挥地总结，而是给它一个结构化模板，比如"已完成的步骤、关键发现、待办事项、重要约束"。这样压缩后的信息密度高，不会丢失关键细节。

5.3 长期记忆的检索时机

长期记忆不是越多越好，检索时机很关键。我的做法是在任务开始时检索一次相关记忆注入上下文，任务执行中如果模型显式请求记忆再检索。不要每轮都检索，那样既慢又容易引入无关信息干扰模型。

记忆的存储我一般用向量数据库加结构化字段的混合方案。向量检索负责语义相似，结构化字段负责精确过滤（比如只检索某个用户的记忆）。纯向量检索在Agent场景下经常不够用，因为很多检索条件是精确的。

6. Planning & Orchestration：让Agent从"走一步看一步"到"胸有成竹"

6.1 任务分解的粒度控制

Planning子系统的核心是任务分解。分解太粗，每个子任务还是太复杂，模型执行不了；分解太细，子任务数量爆炸，调度开销大。我的经验是分解到"每个子任务可以用一到三个工具调用完成"这个粒度比较合适。

分解时还要考虑依赖关系。有些子任务可以并行，有些必须串行。Orchestration层要能识别这些依赖，能并行的并行执行，提升效率。比如"查三个城市的天气"这三个子任务就是独立的，可以并行。

6.2 动态重规划：计划赶不上变化时怎么办

再好的计划执行中也会遇到意外。工具返回了预期外的结果、某个步骤失败了、用户改了需求，这些都需要重规划。重规划不是推倒重来，而是保留已完成的部分，只调整未完成的部分。

实现上，我会给每个子任务标记状态（待执行、执行中、已完成、失败、跳过），重规划时只处理未完成和失败的子任务。已完成的结果作为新计划的输入。这样既节省成本，又保证已做的工作不浪费。

6.3 多Agent协作的编排模式

复杂任务往往需要多个Agent协作。常见的编排模式有三种：主管模式（一个主管Agent分配任务给执行Agent）、流水线模式（Agent按顺序处理，前一个的输出是后一个的输入）、辩论模式（多个Agent对同一问题给出方案，再综合）。

我实际用得最多的是主管模式。主管Agent负责分解和调度，执行Agent负责具体干活。关键是要给主管Agent一个清晰的"团队能力清单"，让它知道每个执行Agent擅长什么，才能合理分配。

7. State & Persistence：Agent的"存档"能力，决定它能不能干长活

7.1 状态该存什么、不该存什么

状态持久化不是把所有东西都存下来。我一般只存三类：任务元信息（任务ID、创建时间、当前状态）、执行进度（已完成步骤、当前步骤、待执行步骤）、关键中间结果（后续步骤需要的数据）。模型的原始输出、临时的推理过程这些不用存，存了也是浪费空间。

状态设计要遵循一个原则：能从状态恢复出完整的执行上下文。也就是说，服务重启后，拿着状态数据就能接着往下跑，不需要重新问用户或者重新调模型。

7.2 检查点机制的设计

检查点是状态持久化的关键。我的做法是在每个子任务完成后打一个检查点，记录当前完整状态。任务失败或中断后，从最近的检查点恢复，而不是从头开始。

检查点的频率要权衡。太频繁，存储和性能开销大；太稀疏，恢复时丢失的工作多。我一般按子任务粒度打检查点，因为子任务本身就是自然的执行单元。

7.3 并发场景下的状态一致性

当多个Agent或同一个Agent的多个实例并发操作时，状态一致性是个大问题。我遇到过两个实例同时更新同一个任务状态，导致状态错乱的情况。解决办法是用乐观锁或悲观锁，更新状态时检查版本号，版本不匹配就重试。

对于高并发场景，状态存储要选支持原子操作的。Redis的原子操作、数据库的行锁都可以用。关键是不能让两个执行流同时修改同一份状态。

8. External Interface：Agent和真实世界的接口层

8.1 输入输出的标准化

External Interface管的是Agent和外部系统的所有交互。输入侧要处理各种格式：文本、文件、结构化数据、甚至语音。输出侧要适配不同的消费方：直接返回给用户、写入数据库、触发下游系统。

我的做法是在Interface层做一层标准化，把各种输入统一转成Agent能理解的格式，把Agent的输出统一转成目标系统需要的格式。这样Agent核心不用关心外部格式的差异。

8.2 事件驱动和回调机制

很多Agent任务不是同步的，用户提交任务后要等几分钟甚至几小时。这就需要事件驱动机制：任务完成后通过回调、消息队列或者Webhook通知调用方。Interface层要支持这些异步通知方式。

回调机制要处理失败重试。通知发不出去怎么办？我的做法是回调也进队列，失败自动重试，超过重试次数就记录到死信队列人工处理。

8.3 限流、鉴权和审计

Interface层是Agent对外的门面，必须做限流、鉴权和审计。限流防止单个用户把系统打爆，鉴权确保只有授权用户能调Agent，审计记录所有操作便于追溯。

审计日志我一般记录：谁在什么时候调了什么Agent、输入是什么、输出是什么、消耗了多少资源。这些数据对排查问题和成本核算都很有用。

9. 把这七个子系统串起来：一个最小可用的Harness长什么样

9.1 从零搭建的推荐顺序

如果你要从零搭一个Harness，我建议的顺序是：先做LLM Integration和Tool System（这两个是基础，没有它们Agent啥也干不了），再做Agent Loop（把前两个串起来），然后是State & Persistence（让Loop能持久化），接着是Memory & Context（处理上下文问题），最后是Planning和External Interface（这两个是进阶能力）。

不要一上来就七个全做。我见过有人花两周搭了个七层架构，结果连一个简单的查询任务都跑不通。先用最小闭环跑通，再逐步加子系统。

9.2 各子系统之间的依赖关系

这七个子系统不是平级的，有明确的依赖关系。LLM Integration和Tool System是底座，Agent Loop依赖它们；State & Persistence服务于Loop；Memory & Context被Loop和Planning共用；Planning依赖Loop和Tool System；External Interface在最外层，依赖所有其他子系统。

理解依赖关系很重要，因为它决定了你的开发顺序和调试顺序。底层出问题，上层全崩。所以调试时要从底层往上查。

9.3 什么情况下可以简化

不是所有场景都需要完整的七个子系统。简单的问答Agent可能只需要LLM Integration加一个简化的Loop；单次任务型Agent可能不需要长期记忆；内部工具型Agent可能不需要复杂的External Interface。

我的建议是：先明确你的Agent要解决什么问题，再决定需要哪些子系统。不要为了架构完整而过度设计。我见过最离谱的是一个只做文本分类的Agent套了完整的Planning和Memory系统，纯属浪费。

10. 搭Harness这几年，我踩过的那些坑

10.1 过度设计是最大的坑

刚接触Agent时，我总想把架构做得尽善尽美，结果每个子系统都做了一半，没有一个能用。后来才明白，Harness的价值在于让Agent能干活，不在于架构多漂亮。能跑通一个真实任务的简单Harness，比跑不通任何任务的复杂Harness有价值得多。

10.2 日志和可观测性不能省

Agent的行为很难预测，出问题时如果没有详细的日志，根本不知道哪一步错了。我现在的做法是每个子系统的关键操作都打日志：Loop的每轮决策、工具的每次调用、状态的每次变更、模型的每次请求响应。日志要结构化，方便检索和分析。

可观测性还包括指标监控：任务成功率、平均执行轮次、工具调用失败率、token消耗。这些指标能帮你发现系统的瓶颈和异常。

10.3 测试Agent比测试普通程序难得多

Agent的输出是不确定的，同样的输入可能得到不同的输出。传统的单元测试不太适用。我的做法是：对确定性部分做单元测试（工具执行、状态管理、参数校验），对不确定性部分做评估集测试（准备一批任务，看成功率）。

评估集要覆盖典型场景和边界场景。每次改动Harness后跑一遍评估集，看成功率有没有下降。这是保证Agent质量不倒退的有效手段。

10.4 模型升级是把双刃剑

模型升级通常会带来能力提升，但也可能破坏现有的提示词和工具调用逻辑。我遇到过模型升级后，原本能正确调用的工具突然调不对了，因为新模型对工具描述的理解变了。

所以模型升级前一定要跑评估集，确认没有回归再上线。同时提示词和工具描述要写得足够鲁棒，不要依赖某个模型的特定行为。

10.5 成本控制要贯穿始终

Agent的成本很容易失控。一个复杂任务跑几十轮，每轮都调大模型，成本很快就上去了。我的做法是：简单任务用小模型、缓存重复的模型调用、限制单任务的最大轮次和最大token消耗、定期分析成本构成找优化点。

成本控制不是事后优化，而是设计时就要考虑的。Harness的每个子系统都要有成本意识，比如Memory系统要避免注入过多无关信息，Planning系统要避免不必要的重规划。

搭Harness这件事，说到底是在解决"如何让不确定的模型输出变成确定的系统行为"这个核心矛盾。七个子系统是七种应对策略，每个都在处理这个矛盾的一个侧面。理解了这个本质，你就不会纠结于"到底该用哪个框架"，因为框架只是这些子系统的具体实现，真正重要的是理解每个子系统要解决的问题。我自己的体会是，把七个子系统的职责想清楚了，用任何框架甚至自己手搓都能搭出能用的Harness；想不清楚，用再好的框架也是一团乱麻。