AI Agent Harness工程骨架：七个子系统设计与落地实践-北京尧图网络

1. 别被Harness这个词唬住它其实就是Agent的骨架第一次听到Harness这个词的时候我脑子里浮现的是马具、安全带这类东西。后来在Agent开发圈子里频繁看到它才反应过来——这个比喻其实相当精准。Harness原意是挽具是把马匹和马车连接起来的那套装置。放到AI Agent的语境里Harness就是把大语言模型和真实世界任务连接起来的那套工程骨架。很多人做Agent开发一上来就想着怎么写Prompt、怎么调模型参数结果跑起来发现模型回答得挺漂亮但就是干不了活。问题出在哪就出在缺少Harness这一层。模型本身只是一个大脑它能理解、能推理、能生成文本但它没有手、没有脚、没有记忆、没有工具。Harness就是给这个大脑装上手脚和记忆系统的工程层。我见过太多项目把Agent等同于LLMPrompt然后发现根本没法落地。真正的Agent系统LLM只是其中一个组件剩下的全是Harness在干活。Harness负责的事情包括什么时候调用模型、调用几次、模型输出的内容怎么解析、解析完怎么执行、执行结果怎么反馈给模型、循环什么时候终止、上下文怎么管理、工具怎么注册和调用、错误怎么处理、状态怎么持久化……这些听起来琐碎但每一个环节出问题Agent就跑不起来。所以这篇文章我想把Harness这件事讲透。不是讲某个具体框架的API怎么用而是讲清楚Harness到底由哪些子系统构成每个子系统解决什么问题它们之间怎么协作。理解了这套骨架你再看任何Agent框架——不管是LangChain、LangGraph还是其他什么——都能一眼看穿它的设计思路。这篇文章适合谁看如果你已经写过一些调用LLM的代码但觉得这玩意儿怎么才能真的干活那这篇就是写给你的。如果你正在从零搭建Agent想知道该考虑哪些模块这篇也能帮你理清思路。如果你只是好奇AI Agent到底怎么工作的看完你会有个完整的认知框架。2. Agent Loop整个系统的心跳2.1 为什么需要一个循环而不是一次调用大多数人第一次用LLM API的时候都是这样写的给一个prompt拿一个response结束。这叫单次调用。但Agent要干活单次调用远远不够。举个例子。你让Agent帮我查一下明天北京的天气然后根据天气推荐穿什么衣服。单次调用的话模型可能会说我无法查询实时天气。但如果你给它一个天气查询工具它就能先调用工具拿到天气数据再根据数据推理出穿衣建议。这个过程至少需要两次模型调用第一次模型决定调用天气工具第二次模型根据工具返回的结果生成最终建议。这就是Agent Loop的起点。Agent Loop是一个思考-行动-观察的循环模型思考下一步该做什么执行一个动作比如调用工具观察动作的结果然后基于结果继续思考下一步。这个循环一直持续到模型认为任务完成或者达到某个终止条件。用伪代码表示大概是这样while not done: thought llm.think(context) if thought.is_final_answer: return thought.content action thought.action observation execute(action) context.append(observation)看起来简单但魔鬼在细节里。这个循环什么时候该停模型说我完成了就真的完成了吗如果模型陷入死循环怎么办如果工具调用失败了怎么办这些全是Harness要解决的问题。2.2 循环终止条件的三种设计模式终止条件是Agent Loop里最容易被忽视、但最容易出问题的部分。我踩过的坑包括模型反复调用同一个工具、模型一直说让我再想想但永远不给最终答案、模型输出了无法解析的格式导致循环卡死。常见的终止条件设计有三种模式第一种是模型自主判断终止。模型在输出中明确表示这是最终答案循环结束。这种模式最自然但依赖模型的能力。能力强的模型能准确判断什么时候该停能力弱的模型可能永远不停。我实测下来用这种方式必须配合最大迭代次数作为兜底。第二种是最大迭代次数限制。设定一个上限比如最多循环10次超过就强制终止。这是最可靠的兜底机制但上限设多少需要根据任务复杂度调整。设太小复杂任务做不完设太大简单任务浪费token。我的经验是简单问答类任务设3-5次多步推理任务设10-15次复杂工作流设20-30次。第三种是状态机驱动的终止。预先定义好任务的状态流转图每个状态有明确的完成条件所有状态都完成才终止。这种方式最可控但设计成本最高适合流程固定的场景。实际项目中我通常把三种模式组合使用模型自主判断为主最大迭代次数兜底关键节点用状态检查。这样既灵活又安全。2.3 循环中的上下文膨胀问题Agent Loop跑起来之后你会发现一个很现实的问题上下文越来越长。每一轮循环都会往context里追加模型的思考、工具调用的参数、工具返回的结果。跑个七八轮context可能就上万token了。上下文膨胀带来两个问题一是成本token是要花钱的二是效果太长的上下文会让模型注意力分散关键信息被淹没。我试过几种应对策略。最简单的做法是只保留最近N轮的完整记录更早的轮次只保留摘要。这个策略实现简单但可能丢失早期的重要信息。更精细的做法是维护一个工作记忆和长期记忆的分离结构工作记忆放当前任务相关的信息长期记忆放跨任务的知识需要时再检索。还有一种做法是在每轮循环结束时让模型自己总结一下目前已知什么、还差什么用这个总结替代冗长的历史记录。这个做法效果不错但增加了一次模型调用。注意上下文管理策略没有银弹需要根据任务特点选择。我的建议是先用最简单的滑动窗口摘要方案跑通遇到问题再优化。3. LLM Integration不只是调个API那么简单3.1 模型调用的封装层要解决什么很多人觉得LLM Integration就是写个函数调API能有多复杂我一开始也这么想直到我需要在同一个Agent里切换不同模型、需要处理流式输出、需要做重试和降级、需要统计token消耗……才发现这层封装的水很深。一个合格的LLM Integration层至少要解决这些问题多模型适配不同厂商的API格式不一样参数名不一样返回结构不一样。你需要一个统一的接口让上层代码不用关心底层用的是哪个模型。流式与非流式统一有些场景需要流式输出比如实时展示给用户有些场景需要完整结果比如需要解析结构化输出。封装层要能同时支持两种模式。重试与降级API调用可能失败可能是网络问题可能是限流可能是模型过载。封装层要有重试机制重试失败后能降级到备用模型。Token统计与成本控制每次调用消耗了多少token累计花了多少钱这些数据对生产环境至关重要。超时控制模型响应可能很慢不能让整个Agent卡死在一个调用上。我见过不少项目这些逻辑散落在业务代码各处改一个模型要改十几个文件。正确的做法是把这些都收敛到LLM Integration层上层只调一个统一的generate()方法。3.2 结构化输出让模型输出可解析的内容Agent Loop里模型的输出不是给人看的是给程序解析的。如果模型输出一段自然语言程序怎么知道它是要调用工具还是要给最终答案所以需要让模型输出结构化的内容通常是JSON格式。但让模型稳定输出合法JSON本身就是个挑战。我试过几种方案方案一Prompt约束。在系统提示里明确要求你必须输出JSON格式包含thought、action、action_input三个字段。这个方案最简单但模型经常不听话尤其是能力弱的模型会加一些额外的解释文字。方案二Function Calling。现在主流模型都支持Function Calling你定义好工具的函数签名模型会直接返回结构化的调用请求。这个方案最可靠但依赖模型支持而且不同厂商的实现有差异。方案三输出解析修复。模型输出后用正则或解析器提取JSON部分如果解析失败尝试修复比如补全缺失的括号修复失败再让模型重新输出。这个方案最灵活但增加了复杂度。我的实践经验是优先用Function Calling不支持的话用Prompt约束输出解析兜底。解析失败时不要直接把错误抛给用户而是把解析错误信息反馈给模型让它重新输出。通常第二次就能成功。3.3 模型选择的权衡能力、速度、成本做Agent绕不开一个问题用哪个模型我的经验是不要追求一个模型打天下而是根据任务特点选择。任务类型推荐模型特点理由复杂推理、规划能力强、上下文长需要深度思考对准确性要求高简单工具调用速度快、成本低任务简单不需要太强的推理能力结构化输出支持Function Calling需要稳定的格式输出最终答案生成语言表达好直接影响用户体验实际项目中我经常在同一个Agent里混用多个模型用强模型做规划和复杂推理用轻量模型做简单的工具调用和格式转换。这样能在效果和成本之间取得平衡。还有一个容易被忽视的点模型的稳定性。有些模型在某些时段响应特别慢有些模型偶尔会返回空结果。生产环境里你需要监控这些指标准备好降级方案。4. Tool SystemAgent的手和脚4.1 工具注册与发现机制Agent要干活就得有工具。工具就是Agent能调用的外部能力查数据库、调API、读文件、发邮件、执行代码……没有工具Agent就是个只会聊天的嘴炮。工具系统的第一个问题是工具怎么注册怎么让模型知道有哪些工具可用最简单的做法是在系统提示里列出所有工具的名称和描述。但工具一多提示词就会变得很长而且模型可能记不住。更好的做法是用结构化的方式定义工具然后动态注入到模型的上下文中。一个工具的定义通常包含这几部分{ name: get_weather, description: 查询指定城市的天气信息, parameters: { type: object, properties: { city: {type: string, description: 城市名称}, date: {type: string, description: 日期格式YYYY-MM-DD} }, required: [city] } }这个定义既是给模型看的让它知道有这个工具、怎么用也是给执行层看的知道怎么调用、参数怎么校验。工具多了之后还需要考虑工具的分类和检索。比如有几十个工具的时候不可能全部塞给模型。这时候需要根据当前任务动态选择相关工具。我试过的做法包括按领域分类、用向量检索匹配、让模型先选择工具类别再选择具体工具。4.2 工具执行的沙箱与安全边界工具执行是Agent系统里风险最高的环节。模型可能调用错误的工具、传入错误的参数、甚至被恶意输入诱导执行危险操作。所以工具执行必须有安全边界。我总结的安全措施包括参数校验工具执行前严格校验参数类型、范围、格式。不要相信模型传过来的参数一定合法。权限控制不同工具设置不同的权限级别。读操作可以宽松写操作、删除操作必须严格。沙箱执行代码执行类工具必须在沙箱里跑限制文件系统访问、网络访问、执行时间。人工确认高风险操作比如发邮件、转账、删除数据需要人工确认后才执行。审计日志所有工具调用都记录日志包括调用时间、参数、结果、耗时。提示我见过一个案例Agent被用户输入诱导调用了删除文件的工具把服务器上的重要数据删了。工具执行的安全边界不是可选项是必选项。4.3 工具调用失败的处理策略工具调用失败是常态不是异常。网络超时、API限流、参数错误、服务不可用……各种失败都可能发生。Harness需要有一套完整的失败处理策略。我的处理策略分三层第一层是重试。对于临时性失败网络抖动、限流自动重试。重试要设置次数上限和退避策略比如第一次等1秒第二次等2秒第三次等4秒。第二层是降级。重试失败后尝试备用方案。比如主API不可用切换到备用API精确查询失败改用模糊查询。第三层是反馈。如果重试和降级都失败把失败信息反馈给模型让模型决定下一步怎么做。模型可能会选择换一个工具、换一种方式、或者告诉用户这个操作暂时无法完成。关键点是失败信息要清晰地反馈给模型包括失败原因、已尝试的方案、可能的替代方案。模型拿到这些信息后往往能找到绕过去的方法。5. Memory ContextAgent的记忆系统5.1 短期记忆与长期记忆的分工Agent的记忆系统经常被简化成把历史对话塞进context但这远远不够。一个完整的记忆系统应该区分短期记忆和长期记忆。短期记忆是当前任务的上下文用户说了什么、Agent做了什么、工具返回了什么。这部分记忆生命周期短任务结束就可以丢弃。短期记忆的关键是相关性——只保留与当前任务相关的信息不相关的信息及时清理。长期记忆是跨任务的知识用户的偏好、历史交互的经验、领域知识。这部分记忆需要持久化存储下次任务时能检索出来。长期记忆的关键是可检索性——存进去容易取出来难。你需要设计好的索引和检索机制。我见过不少Agent项目短期记忆和长期记忆混在一起结果就是要么上下文爆炸要么重要信息丢失。正确的做法是分开管理短期记忆用滑动窗口摘要长期记忆用向量数据库结构化存储。5.2 上下文压缩的几种实用手段上下文压缩是Agent工程里最实用的技能之一。同样的任务上下文管理做得好token消耗能降一半效果还能提升。我常用的压缩手段包括摘要压缩。让模型把一段对话总结成几句话。这个手段适合压缩历史对话但要注意摘要可能丢失细节。关键信息提取。不是所有信息都值得保留只提取关键实体、关键决策、关键结果。比如工具返回了一大段JSON你只需要提取其中几个关键字段。分层存储。最近的几轮保留完整记录更早的只保留摘要再早的只保留索引。需要时再逐层展开。去重与合并。多轮对话中经常有重复信息比如用户反复确认同一个问题。这些重复信息可以合并。结构化替代自然语言。把自然语言的历史记录转成结构化的状态表示。比如用户想查天气已经查了北京还要查上海可以表示成{task: weather, completed: [北京], pending: [上海]}。实测下来组合使用这些手段上下文能压缩到原来的30%-50%效果基本不受影响。5.3 记忆检索的触发时机长期记忆存进去之后什么时候取出来用这个问题看似简单实际上很关键。取早了无关信息干扰模型取晚了模型缺少必要信息。我的做法是在两个时机触发检索任务开始时。根据用户输入检索相关的历史记忆。比如用户说帮我订机票检索出用户之前提到的偏好靠窗、常飞航司、预算范围。任务执行中。当模型遇到需要决策的节点时主动检索相关记忆。比如模型在选航班时检索用户的历史选择。检索的触发可以是模型主动发起的模型输出一个我需要检索记忆的动作也可以是Harness自动触发的根据当前状态判断需要哪些记忆。我倾向于两者结合自动检索作为兜底模型主动检索作为补充。6. Planning ReasoningAgent的思考方式6.1 ReAct模式的实际落地细节ReActReasoning Acting是Agent领域最经典的思考模式。它的核心思想是让模型交替进行推理和行动先推理下一步该做什么然后执行行动观察结果再推理下一步。听起来简单但落地时有几个细节需要注意推理和行动的格式要严格定义。模型输出必须明确区分这是推理和这是行动。通常用固定的标记比如Thought:、Action:、Observation:。格式不严格解析就会出错。推理内容要简洁。我见过模型在Thought里写了一大段分析结果token消耗巨大。实际上推理只需要说清楚下一步做什么、为什么就够了。Observation要准确反馈。工具执行的结果要原样反馈给模型不要做过多加工。模型需要看到真实的结果才能做出正确判断。循环要有节奏。不是每一步都要推理简单的工具调用可以直接执行。推理应该用在需要决策的节点。6.2 任务分解的粒度控制复杂任务需要分解成子任务。但分解到什么粒度太粗模型执行不了太细循环次数太多成本和延迟都上去了。我的经验是分解到一个子任务对应一次工具调用或一次推理的粒度。比如帮我规划一个三天的北京旅行可以分解成查景点、查天气、查酒店、排行程。每个子任务都是可执行的。粒度控制还有一个原则子任务之间尽量独立。如果子任务之间有强依赖分解的意义就不大了。比如先查天气再决定去哪个景点这两个任务有依赖应该合并成一个任务。6.3 反思与自我修正机制Agent执行任务时难免出错。出错不可怕可怕的是错了不知道、知道了不改。反思机制就是让Agent能发现自己的错误并修正。反思的触发时机包括工具调用失败、模型输出无法解析、任务执行超时、结果不符合预期。反思的实现方式通常是把错误信息、当前状态、原始目标一起给模型让模型分析哪里出了问题、为什么、怎么修正。模型给出修正方案后重新执行。我实测下来反思机制能显著提升Agent的成功率尤其是多步任务。但要注意反思不能无限循环要有次数上限。有些错误是模型能力问题反思多少次也解决不了这时候应该及时终止并报告。7. State Persistence让Agent能记住、能恢复7.1 状态快照的设计Agent执行任务可能持续很长时间中间可能因为各种原因中断服务重启、超时、人工暂停。如果没有状态持久化中断后就得从头再来。状态快照就是定期把Agent的当前状态保存下来中断后能从快照恢复。状态快照需要保存什么我的经验是保存这几类信息任务状态当前在做什么、做到哪一步了、还剩什么没做。上下文状态当前的对话历史、工具调用记录、中间结果。循环状态当前是第几轮循环、已经调用了哪些工具、累计消耗了多少token。外部状态如果任务涉及外部系统比如已经创建了订单要记录外部系统的状态。快照的存储可以用文件、数据库、对象存储根据规模和性能要求选择。关键是快照要能快速写入和读取不能因为保存快照拖慢主流程。7.2 断点恢复的完整流程断点恢复是状态持久化的目的。恢复流程包括加载快照从存储中读取最近的状态快照。校验状态检查快照是否完整、是否过期、外部状态是否一致。重建上下文把快照中的上下文重新加载到Agent的context里。恢复循环从上次中断的地方继续执行。处理不一致如果外部状态和快照不一致比如快照说订单已创建但实际没有需要做补偿处理。断点恢复最难的部分是处理不一致。因为快照和外部操作之间有时间差可能出现快照记录了操作但操作实际没成功或者操作成功了但快照没记录。这需要设计幂等操作和补偿机制。7.3 多轮对话中的状态管理多轮对话场景下状态管理更复杂。用户可能中途改变主意、补充信息、切换话题。Agent需要能跟踪这些变化。我的做法是维护一个对话状态机每个状态有明确的进入条件、退出条件、可执行的操作。用户输入触发状态转移Agent根据当前状态决定怎么响应。比如订机票场景状态从收集信息到确认信息到执行预订到完成。用户中途说算了不订了状态直接跳到取消。用户说换个日期状态回到收集信息。状态机的好处是行为可预测、可测试。坏处是设计成本高不适合开放式任务。开放式任务更适合用目标约束的方式管理状态而不是固定状态机。8. Observability看不见的Agent最危险8.1 日志、指标、追踪三件套Agent系统跑起来之后最怕的就是黑盒——你不知道它在干什么、为什么这么干、哪里出了问题。可观测性就是让Agent的每一步都可见。可观测性包括三个层面日志Logging记录每个关键事件。包括模型调用输入、输出、耗时、token消耗、工具调用参数、结果、耗时、状态变化、错误信息。日志要结构化方便检索和分析。指标Metrics统计关键指标。包括任务成功率、平均循环次数、平均耗时、token消耗、工具调用成功率、错误率。指标要能实时监控异常时能告警。追踪Tracing追踪一个任务的完整执行链路。从用户输入到最终输出中间经过了哪些步骤、每步耗时多少、哪步是瓶颈。追踪对于排查复杂问题特别有用。我见过不少Agent项目上线后出了问题只能靠猜。有了可观测性三件套排查问题从猜变成看效率提升不是一点半点。8.2 排查Agent异常行为的思路Agent行为异常时怎么排查我总结了一套思路第一步看日志定位异常发生的节点。是模型调用出了问题还是工具调用出了问题还是状态管理出了问题第二步看上下文理解模型为什么这么决策。把异常发生时的完整上下文拿出来看看模型看到了什么、基于什么做的决策。第三步复现问题。用相同的输入和上下文重新跑一遍看是否能复现。能复现的问题才好修。第四步对比正常案例。找一个类似的正常案例对比两者的差异找出异常的原因。第五步验证修复。修复后用相同的场景验证确保问题解决且没有引入新问题。这套思路看起来简单但实际排查时经常因为日志不全、上下文丢失而卡住。所以可观测性要在设计阶段就考虑不能等出了问题再补。8.3 成本与延迟的监控Agent系统的成本和延迟是生产环境必须关注的指标。成本主要是token消耗延迟主要是模型调用和工具调用的耗时。成本监控要细化到每个任务的token消耗、每个模型的token消耗、每个工具调用的成本。这样才能知道钱花在哪了哪里可以优化。延迟监控要细化到模型调用的P50、P95、P99延迟工具调用的延迟整个任务的端到端延迟。延迟高的环节要重点优化。我的经验是成本和延迟的优化80%的收益来自20%的优化点。通过监控找到那20%集中优化效果最明显。比如发现某个工具调用特别慢优化它比优化模型调用收益更大。9. 把这七个子系统串起来一个最小可用的Harness长什么样说了这么多子系统最后我想把它们串起来给你一个最小可用的Harness的轮廓。不是完整代码而是结构上的示意。整个Harness的核心是一个循环class AgentHarness: def __init__(self, llm, tools, memory, state_store): self.llm llm self.tools tools self.memory memory self.state_store state_store def run(self, task): state self.state_store.load_or_create(task) context self.memory.build_context(task, state) while not state.done: # LLM Integration: 调用模型 response self.llm.generate(context, toolsself.tools.schemas()) # Planning: 解析模型的决策 decision self.parse(response) if decision.is_final: state.done True return decision.content # Tool System: 执行工具 result self.tools.execute(decision.action, decision.params) # Memory: 更新上下文 context self.memory.update(context, decision, result) # State: 保存快照 state.step 1 self.state_store.save(state) # Observability: 记录日志和指标 self.log(decision, result) return state.result这个轮廓里七个子系统各司其职Agent Loop控制循环LLM Integration封装模型调用Tool System管理工具Memory管理上下文Planning解析决策State持久化状态Observability记录一切。实际项目中每个子系统都会比这个复杂得多。但核心结构就是这样。理解了这套结构你再看任何Agent框架都能快速理解它的设计。最后分享一个我踩过的坑一开始做Agent的时候我总想一步到位把所有子系统都做得很完善。结果就是开发周期特别长还没上线就过时了。后来我改变了策略先做一个最小可用的版本只包含Agent Loop、LLM Integration、Tool System三个核心子系统跑通一个简单场景。然后再逐步加上Memory、Planning、State、Observability。这样迭代速度快每一步都有可验证的成果。这个策略我称之为骨架先行血肉后补。Harness的骨架就是那三个核心子系统没有它们Agent根本跑不起来。其他子系统是让Agent跑得更好、更稳、更可控。先跑起来再跑得好。

AI Agent Harness工程骨架：七个子系统设计与落地实践

相关推荐

PyTorch DDP 单卡改双卡训练结果对齐实战指南

AI工程化实战：从空服务器到生产级AI服务的七层构建

指数分布、伽马分布与泊松分布：泊松过程视角下的统一解读

更多资讯

MicroPython STM32移植：启动流程、时钟配置与链接脚本深度解析

NWD转STL精度可控重建全流程

STM32嵌入式开发入门与进阶：环境搭建、外设调试与项目实战避坑

北邮计算机复试上机真题解析：输入输出规范与Dev-C++环境避坑指南

小波变换在雷达目标探测中的应用：基于Matlab的瞬态信号检测与去噪实战

Home Assistant网页改配置全攻略：从编辑器选择到安全恢复

今日更新

企业AI转型实战指南：从场景选择到落地避坑的完整路线图

OpenRig：本地大模型服务编排的轻量级运行时框架

夸克网盘1TB免费扩容领取全攻略：新老用户实操流程与避坑指南

本周精选

如何彻底离线使用 Laya-CoreML：Hugging Face 下载、缓存机制与 local_files_only 详解

基于1Panel 部署MySQL MCP 服务：TaoToken 统一 Key 接入与 config.toml 配置实战

崇州园区营销网站建设避坑指南：5大注意事项保备案安全

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？