1. 从“能跑”到“跑得稳”AI Agent 的工程化拐点做 AI Agent 的人大概都有过这种体验Demo 阶段惊艳四座一旦放到真实业务里跑上三天各种稀奇古怪的失败就开始冒出来——工具调用参数拼错、多轮对话后意图漂移、外部 API 超时导致整个任务链断裂、模型偶尔“幻觉”出一个不存在的函数名。这些问题单看都是小毛病凑在一起就是“不可用”。我过去一年陆续搭过几个不同形态的 Agent从最简单的“提示词函数调用”到带规划、带记忆、带多 Agent 协作的复杂系统踩的坑足够写一本错题集。后来我慢慢意识到一件事Agent 的竞争力不在于模型多强而在于外面那层“马具”做得多扎实。这个“马具”就是 Harness。Harness 这个词直译是“马具、挽具”放在 AI Agent 语境里它指的是包裹在模型外面的一整套工程结构——负责约束模型的输入输出、管理工具调用、处理错误重试、维护状态与上下文、控制执行流程。模型是那匹力气大但脾气不定的马Harness 就是让它能拉车、能走直线、能听指挥的那套装备。没有 Harness 的 Agent本质上就是一个“能聊天的 API 封装”有了 Harness它才变成一个可以交付的系统。这篇文章我想聊的就是 Harness 工程的核心机制。不吹概念不讲空话就讲我在实际项目里怎么设计这层结构、每个模块解决什么问题、哪些地方最容易翻车。适合已经动手写过 Agent、但被稳定性问题折磨过的朋友如果你还在“提示词工程”阶段也能提前看到工程化会遇到的真实挑战。核心关键词就几个AI Agent、Harness、工程机制、实践、稳定性。2. Harness 到底管什么核心机制拆解2.1 为什么模型本身靠不住必须外挂一层先把一个认知摆正大模型是一个概率性的文本生成器不是一个可靠的函数。你给它同样的输入它可能给你不同的输出你让它调用工具它可能把参数写成自然语言你让它按 JSON 格式返回它可能给你包一层 Markdown 代码块再加一句“好的以下是结果”。这不是模型“笨”而是它的工作方式决定的。它做的是“根据上下文预测下一个 token”而不是“执行一段确定性逻辑”。所以任何指望模型稳定输出结构化结果的想法最后都会在真实流量下被打脸。Harness 的第一个职责就是把概率性的输出收敛成确定性的行为。具体做法包括用严格的 schema 约束输出格式、对模型返回做解析和校验、解析失败时触发重试或降级、把工具调用的参数做类型检查。这一层做得好上层业务代码才能像调用普通服务一样调用 Agent。我见过太多项目把校验逻辑写在业务层结果每个调用点都要重复一遍 try-catch最后代码里全是防御性判断。正确的做法是把这些收敛到 Harness 里业务层只关心“我要什么结果”不关心“模型可能怎么乱来”。2.2 工具调用Agent 的手脚也是最容易断的地方Agent 和普通聊天机器人最大的区别就是它能调用外部工具——查数据库、发请求、读写文件、操作业务系统。工具调用是 Agent 的“手脚”但也是故障率最高的环节。一个完整的工具调用链路通常长这样模型决定调用哪个工具 → 生成参数 → Harness 解析参数 → 校验参数 → 执行工具 → 拿到结果 → 把结果塞回上下文 → 模型继续推理。这条链上任何一环出问题整个任务就卡住。我在实践里总结出几个关键机制参数校验前置。不要等工具执行报错才发现参数不对。Harness 应该在调用前就用 JSON Schema 校验参数类型、必填项、取值范围。比如一个“查询订单”的工具要求 order_id 是字符串且长度固定那就在 Harness 层拦住所有不合规的调用直接返回错误信息给模型让它重试而不是让数据库去报一个看不懂的错。超时与重试策略。外部工具可能慢、可能挂。Harness 必须给每个工具配置独立的超时时间和重试次数。我的经验是读操作可以重试 2-3 次写操作要谨慎最好配合幂等键。重试不是无脑重发要区分“可重试错误”网络超时、限流和“不可重试错误”参数错误、权限不足。结果截断与摘要。工具返回的数据可能非常大比如一个查询返回几千行。直接塞进上下文会撑爆 token 限制还会稀释模型的注意力。Harness 需要在返回结果前做截断或摘要只保留关键字段。这一步做得好不好直接决定多轮任务能不能跑下去。2.3 上下文管理Agent 的记忆不是越多越好很多人以为给 Agent 越多上下文越好实际上恰恰相反。上下文越长模型越容易“迷失”关键信息被淹没在噪声里推理质量反而下降。而且 token 是要花钱的长上下文意味着成本飙升。Harness 在上下文管理上要做几件事分层记忆。把上下文分成几个层次系统提示词固定不变的角色和规则、任务状态当前进行到哪一步、近期对话最近几轮交互、长期记忆从历史中检索出来的相关信息。不同层次用不同的策略管理系统提示词永远保留近期对话滚动窗口长期记忆按需检索。主动压缩。当上下文接近阈值时Harness 要触发压缩——把早期的对话总结成摘要把不再需要的工具返回结果丢弃只保留结论。压缩的时机和策略很关键压太早会丢信息压太晚就爆了。状态外置。不要把关键状态只存在上下文里。任务进度、已完成的步骤、中间结果都应该存在 Harness 维护的状态对象里需要时再注入上下文。这样即使上下文被压缩状态也不会丢。2.4 错误处理与自愈让 Agent 自己爬起来Agent 跑长任务时出错是常态。网络抖动、工具超时、模型输出格式错误、外部系统返回异常——这些都会发生。关键不是避免错误而是出错后能不能自己恢复。Harness 的错误处理机制我一般分三层第一层是即时重试针对瞬时故障比如网络超时直接重试往往就好了。第二层是反馈修正把错误信息作为新的输入喂回给模型让它调整策略。比如工具调用参数错了就把校验错误告诉模型让它重新生成参数。这一层是 Agent 自愈能力的核心。第三层是降级与兜底当重试和修正都失败时走预设的降级路径——返回部分结果、切换到备用工具、或者明确告知用户任务失败并给出已完成的部分。这里有个经验错误信息要写得让模型能看懂。不要返回“Error 500”而要返回“调用查询订单工具失败原因是 order_id 格式不正确应该是 16 位数字字符串你提供的是 12 位”。模型拿到这种信息修正成功率会高很多。3. 从零搭一个 Harness实操流程与关键配置3.1 整体架构先画清楚数据怎么流动手写代码之前先把架构想清楚。我习惯把 Harness 分成几个独立的模块每个模块职责单一通过明确的接口通信输入适配层接收用户输入做初步清洗和意图识别决定走哪条处理路径。上下文管理器负责组装、压缩、检索上下文维护对话状态。模型调用层封装对模型的调用处理重试、超时、流式输出。工具注册与执行层管理工具定义、参数校验、执行、结果处理。输出解析层解析模型返回提取结构化结果校验格式。状态与持久化层保存任务状态、执行日志、中间结果。错误处理与调度层统一处理各类错误决定重试、修正还是降级。这几个模块不一定要拆成独立服务但在代码结构上要清晰分离。我见过把所有这些逻辑塞在一个大函数里的项目改一处崩三处根本没法维护。数据流大致是用户输入 → 输入适配 → 上下文组装 → 模型调用 → 输出解析 → 判断是工具调用还是最终回复 → 工具调用则走工具执行 → 结果回填上下文 → 再次模型调用 → 循环直到产出最终结果或触发终止条件。3.2 工具定义用 Schema 把话说死工具定义是 Harness 的地基。定义得清楚模型调用就准定义得模糊后面全是坑。我用的是 JSON Schema 来描述每个工具包含名称、描述、参数结构。这里有几个实操要点描述要写“什么时候用”不只是“是什么”。比如一个“搜索知识库”的工具描述不要只写“搜索知识库”而要写“当用户询问产品功能、政策条款、历史文档内容时使用此工具输入自然语言查询语句”。模型靠描述来判断该不该调用描述写得越贴近使用场景误调用越少。参数类型要严格。能用枚举就用枚举能用整数就别用字符串。参数越具体模型越不容易乱填。必填项和可选项分开。必填项缺失直接报错可选项缺失走默认值。下面是一个工具定义的示例结构{ name: query_order, description: 当用户需要查询订单状态、物流信息、退款进度时调用此工具。输入订单号返回订单详情。, parameters: { type: object, properties: { order_id: { type: string, description: 订单号16位数字字符串, pattern: ^[0-9]{16}$ }, fields: { type: array, items: {type: string, enum: [status, logistics, refund]}, description: 需要返回的字段不填则返回全部 } }, required: [order_id] } }这个 schema 里order_id 用正则约束了格式fields 用枚举限制了取值。Harness 在调用前校验这些约束不合规的直接打回让模型重生成。3.3 上下文组装把对的信息在对的时候放进去上下文组装是 Harness 里最需要“手感”的部分。同样一组信息排列顺序不同模型的表现可能差很多。我的组装顺序一般是系统提示词 → 任务目标 → 当前状态 → 工具定义 → 近期对话 → 当前用户输入。系统提示词放最前面因为模型对开头和结尾的内容注意力最集中。任务目标和当前状态紧随其后让模型时刻知道“我在干什么、干到哪了”。工具定义放在中间偏后近期对话和当前输入放最后。系统提示词里我会明确写几件事角色定位、行为边界、输出格式要求、错误处理原则。比如“你是一个订单处理助手只能调用已注册的工具不要编造工具名称。如果工具调用失败根据错误信息调整参数后重试最多重试两次。”这里有个细节工具定义不要每轮都全量塞进去。如果工具有几十个全量塞会占用大量 token。我的做法是按任务类型动态加载相关工具或者用检索的方式选出最可能用到的几个。这个优化在工具多的场景下效果很明显。3.4 执行循环控制好节奏和终止条件Agent 的执行是一个循环模型推理 → 判断动作 → 执行 → 回填 → 再推理。这个循环必须有明确的终止条件否则可能无限转下去。我设置的终止条件包括模型输出了最终答案没有工具调用意图、达到最大循环次数一般设 10-15 次、累计 token 超限、执行时间超时、连续多次错误无法恢复。循环里还要注意节奏控制。每轮循环之间可以加一个短暂的检查点判断当前状态是否正常、是否需要人工介入。对于高风险操作比如写数据库、发消息可以在执行前插入确认步骤。3.5 日志与可观测性出问题时能查Agent 出问题是必然的关键是出问题后能不能快速定位。Harness 必须记录完整的执行日志每轮模型的输入输出、工具调用的参数和结果、错误信息、耗时、token 消耗。我一般会把日志结构化存储方便查询和统计。关键字段包括会话 ID、轮次、时间戳、模型输入摘要、模型输出、工具名称、工具参数、工具结果、错误类型、耗时。有了这些排查问题时可以还原整个执行过程。可观测性还包括监控指标成功率、平均轮次、平均耗时、工具调用失败率、token 消耗趋势。这些指标能帮你发现系统性问题比如某个工具失败率突然升高可能是外部系统出了问题。4. 踩坑实录那些让我熬夜的典型问题4.1 模型“自作聪明”编造工具名这是最常见的问题之一。模型在推理时如果找不到合适的工具有时会“编”一个看起来合理的工具名然后生成一堆参数。Harness 如果不做校验直接去执行就会报“工具不存在”。我的解法是在 Harness 层做严格的白名单校验模型返回的工具名必须在注册表里不在的直接拒绝并把可用工具列表返回给模型让它重新选择。同时在系统提示词里明确写“只能使用已注册的工具不要编造”。4.2 参数类型漂移模型有时会把数字写成字符串把数组写成逗号分隔的字符串把布尔值写成“true”字符串。这些在人类看来无所谓但程序解析会出错。Harness 的参数校验层要做类型强制转换和校验。能转的转转不了的报错。比如字符串“123”可以转成整数 123但“abc”转整数就报错。转换规则要明确并且把转换结果记录在日志里方便排查。4.3 上下文爆炸长任务跑到后面上下文越来越长最后超出模型限制。这个问题在早期不明显任务一长就暴露。我的解法是三层防护一是工具结果返回前做截断只保留关键字段二是设置上下文阈值超过就触发压缩把早期对话总结成摘要三是状态外置关键信息存在状态对象里不依赖上下文传递。压缩策略我用的是“保留最近 N 轮完整对话 早期对话摘要 当前任务状态”。摘要用模型生成提示词是“把以下对话总结成不超过 200 字的要点保留关键决策和结果”。4.4 工具调用死循环模型可能反复调用同一个工具每次参数略有不同但都失败然后一直重试。如果不加控制会烧掉大量 token。Harness 要检测重复调用同一个工具、相似参数、连续多次失败就触发熔断停止重试返回错误给用户或走降级路径。我一般设置“同一工具连续失败 3 次就熔断”。4.5 模型输出格式不稳定要求模型返回 JSON它有时返回纯 JSON有时包在 Markdown 代码块里有时前面加一句“好的以下是结果”。解析层如果只按一种格式处理就会失败。我的解法是解析层做容错先尝试直接解析失败则提取代码块内容再解析再失败则用正则提取 JSON 片段。同时把解析失败的情况记录下来如果某个提示词导致的解析失败率很高就回去优化提示词。下面这张表是我整理的常见问题速查问题现象可能原因排查方向解决手段工具名不存在模型编造检查工具注册表白名单校验提示词约束参数类型错误模型输出格式漂移检查参数校验日志类型转换严格校验上下文超限长任务累积检查 token 消耗截断压缩状态外置死循环重试工具持续失败检查工具调用日志熔断机制失败上限输出解析失败格式不稳定检查原始输出多级解析容错任务中途卡住状态丢失检查状态对象状态外置检查点5. 让 Harness 更稳的几个进阶思路5.1 幂等设计重复执行不出错Agent 重试是常态但重试不能产生副作用。比如“发消息”这个操作重试两次就发了两条用户会疯。Harness 要支持幂等每个操作带一个幂等键外部系统根据幂等键去重。对于不支持幂等的外部系统Harness 要在本地记录已执行的操作重试前先检查。5.2 人机协同该让人介入时就介入不是所有决策都适合让 Agent 自己做。高风险操作、模糊意图、多次失败后的场景应该触发人工确认。Harness 可以设计一个“确认点”机制执行到关键步骤时暂停把当前状态和待执行操作展示给用户等用户确认后再继续。这个机制在金融、医疗等场景尤其重要。5.3 灰度与回滚新版本先小范围跑Harness 的提示词、工具定义、执行策略都可能调整。每次调整都是一次风险。我的做法是灰度发布新版本先对一小部分流量生效观察成功率、耗时、错误率等指标没问题再全量。同时保留回滚能力配置化的部分提示词、工具定义、阈值参数支持热更新和快速回滚不用重新部署。5.4 成本控制token 是要花钱的Agent 跑起来 token 消耗很快尤其是长任务和多轮循环。Harness 要有成本控制机制设置单次任务的 token 上限、监控 token 消耗趋势、对高消耗任务做告警。优化手段包括精简系统提示词、动态加载工具定义、工具结果截断、上下文压缩、选择更经济的模型处理简单任务。这些手段组合起来成本能降不少。6. 一些个人体会Harness 工程这件事说到底是在跟“不确定性”打交道。模型是不确定的外部系统是不确定的网络是不确定的。Harness 的价值就是把这些不确定性收敛到一个可控的范围内让整个系统表现得像一个可靠的工程系统。我最大的体会是不要试图让模型变得完美而要让系统在模型不完美时依然能工作。模型会犯错这没关系关键是犯错后能发现、能恢复、能兜底。把精力花在 Harness 的健壮性上比反复调提示词追求“一次成功”要划算得多。另一个体会是可观测性怎么强调都不过分。Agent 出问题时如果没有完整的日志排查就是盲人摸象。我现在的习惯是Harness 的每个关键节点都打日志宁可多打不可漏打。日志结构化存储方便查询和统计。最后分享一个小技巧给 Harness 写单元测试。工具调用的参数校验、输出解析、错误处理、上下文压缩这些逻辑都可以脱离模型单独测试。用 mock 数据模拟各种边界情况能提前发现很多问题。我现在的项目里Harness 层的测试覆盖率比业务层还高因为这部分逻辑最需要稳定。这个方向后续还可以往几个方向扩展多 Agent 协作时的 Harness 设计、跨会话的长期记忆管理、Agent 行为的审计与合规。每个方向都有不少值得深挖的东西等我在实际项目里跑出更多经验再找机会聊。 
长河君 · 2026/10/26 23:32:11 · 阅读 1.2k AI Agent 工程化拐点：Harness 核心机制与实践踩坑
1. 从“能跑”到“跑得稳”AI Agent 的工程化拐点做 AI Agent 的人大概都有过这种体验Demo 阶段惊艳四座一旦放到真实业务里跑上三天各种稀奇古怪的失败就开始冒出来——工具调用参数拼错、多轮对话后意图漂移、外部 API 超时导致整个任务链断裂、模型偶尔“幻觉”出一个不存在的函数名。这些问题单看都是小毛病凑在一起就是“不可用”。我过去一年陆续搭过几个不同形态的 Agent从最简单的“提示词函数调用”到带规划、带记忆、带多 Agent 协作的复杂系统踩的坑足够写一本错题集。后来我慢慢意识到一件事Agent 的竞争力不在于模型多强而在于外面那层“马具”做得多扎实。这个“马具”就是 Harness。Harness 这个词直译是“马具、挽具”放在 AI Agent 语境里它指的是包裹在模型外面的一整套工程结构——负责约束模型的输入输出、管理工具调用、处理错误重试、维护状态与上下文、控制执行流程。模型是那匹力气大但脾气不定的马Harness 就是让它能拉车、能走直线、能听指挥的那套装备。没有 Harness 的 Agent本质上就是一个“能聊天的 API 封装”有了 Harness它才变成一个可以交付的系统。这篇文章我想聊的就是 Harness 工程的核心机制。不吹概念不讲空话就讲我在实际项目里怎么设计这层结构、每个模块解决什么问题、哪些地方最容易翻车。适合已经动手写过 Agent、但被稳定性问题折磨过的朋友如果你还在“提示词工程”阶段也能提前看到工程化会遇到的真实挑战。核心关键词就几个AI Agent、Harness、工程机制、实践、稳定性。2. Harness 到底管什么核心机制拆解2.1 为什么模型本身靠不住必须外挂一层先把一个认知摆正大模型是一个概率性的文本生成器不是一个可靠的函数。你给它同样的输入它可能给你不同的输出你让它调用工具它可能把参数写成自然语言你让它按 JSON 格式返回它可能给你包一层 Markdown 代码块再加一句“好的以下是结果”。这不是模型“笨”而是它的工作方式决定的。它做的是“根据上下文预测下一个 token”而不是“执行一段确定性逻辑”。所以任何指望模型稳定输出结构化结果的想法最后都会在真实流量下被打脸。Harness 的第一个职责就是把概率性的输出收敛成确定性的行为。具体做法包括用严格的 schema 约束输出格式、对模型返回做解析和校验、解析失败时触发重试或降级、把工具调用的参数做类型检查。这一层做得好上层业务代码才能像调用普通服务一样调用 Agent。我见过太多项目把校验逻辑写在业务层结果每个调用点都要重复一遍 try-catch最后代码里全是防御性判断。正确的做法是把这些收敛到 Harness 里业务层只关心“我要什么结果”不关心“模型可能怎么乱来”。2.2 工具调用Agent 的手脚也是最容易断的地方Agent 和普通聊天机器人最大的区别就是它能调用外部工具——查数据库、发请求、读写文件、操作业务系统。工具调用是 Agent 的“手脚”但也是故障率最高的环节。一个完整的工具调用链路通常长这样模型决定调用哪个工具 → 生成参数 → Harness 解析参数 → 校验参数 → 执行工具 → 拿到结果 → 把结果塞回上下文 → 模型继续推理。这条链上任何一环出问题整个任务就卡住。我在实践里总结出几个关键机制参数校验前置。不要等工具执行报错才发现参数不对。Harness 应该在调用前就用 JSON Schema 校验参数类型、必填项、取值范围。比如一个“查询订单”的工具要求 order_id 是字符串且长度固定那就在 Harness 层拦住所有不合规的调用直接返回错误信息给模型让它重试而不是让数据库去报一个看不懂的错。超时与重试策略。外部工具可能慢、可能挂。Harness 必须给每个工具配置独立的超时时间和重试次数。我的经验是读操作可以重试 2-3 次写操作要谨慎最好配合幂等键。重试不是无脑重发要区分“可重试错误”网络超时、限流和“不可重试错误”参数错误、权限不足。结果截断与摘要。工具返回的数据可能非常大比如一个查询返回几千行。直接塞进上下文会撑爆 token 限制还会稀释模型的注意力。Harness 需要在返回结果前做截断或摘要只保留关键字段。这一步做得好不好直接决定多轮任务能不能跑下去。2.3 上下文管理Agent 的记忆不是越多越好很多人以为给 Agent 越多上下文越好实际上恰恰相反。上下文越长模型越容易“迷失”关键信息被淹没在噪声里推理质量反而下降。而且 token 是要花钱的长上下文意味着成本飙升。Harness 在上下文管理上要做几件事分层记忆。把上下文分成几个层次系统提示词固定不变的角色和规则、任务状态当前进行到哪一步、近期对话最近几轮交互、长期记忆从历史中检索出来的相关信息。不同层次用不同的策略管理系统提示词永远保留近期对话滚动窗口长期记忆按需检索。主动压缩。当上下文接近阈值时Harness 要触发压缩——把早期的对话总结成摘要把不再需要的工具返回结果丢弃只保留结论。压缩的时机和策略很关键压太早会丢信息压太晚就爆了。状态外置。不要把关键状态只存在上下文里。任务进度、已完成的步骤、中间结果都应该存在 Harness 维护的状态对象里需要时再注入上下文。这样即使上下文被压缩状态也不会丢。2.4 错误处理与自愈让 Agent 自己爬起来Agent 跑长任务时出错是常态。网络抖动、工具超时、模型输出格式错误、外部系统返回异常——这些都会发生。关键不是避免错误而是出错后能不能自己恢复。Harness 的错误处理机制我一般分三层第一层是即时重试针对瞬时故障比如网络超时直接重试往往就好了。第二层是反馈修正把错误信息作为新的输入喂回给模型让它调整策略。比如工具调用参数错了就把校验错误告诉模型让它重新生成参数。这一层是 Agent 自愈能力的核心。第三层是降级与兜底当重试和修正都失败时走预设的降级路径——返回部分结果、切换到备用工具、或者明确告知用户任务失败并给出已完成的部分。这里有个经验错误信息要写得让模型能看懂。不要返回“Error 500”而要返回“调用查询订单工具失败原因是 order_id 格式不正确应该是 16 位数字字符串你提供的是 12 位”。模型拿到这种信息修正成功率会高很多。3. 从零搭一个 Harness实操流程与关键配置3.1 整体架构先画清楚数据怎么流动手写代码之前先把架构想清楚。我习惯把 Harness 分成几个独立的模块每个模块职责单一通过明确的接口通信输入适配层接收用户输入做初步清洗和意图识别决定走哪条处理路径。上下文管理器负责组装、压缩、检索上下文维护对话状态。模型调用层封装对模型的调用处理重试、超时、流式输出。工具注册与执行层管理工具定义、参数校验、执行、结果处理。输出解析层解析模型返回提取结构化结果校验格式。状态与持久化层保存任务状态、执行日志、中间结果。错误处理与调度层统一处理各类错误决定重试、修正还是降级。这几个模块不一定要拆成独立服务但在代码结构上要清晰分离。我见过把所有这些逻辑塞在一个大函数里的项目改一处崩三处根本没法维护。数据流大致是用户输入 → 输入适配 → 上下文组装 → 模型调用 → 输出解析 → 判断是工具调用还是最终回复 → 工具调用则走工具执行 → 结果回填上下文 → 再次模型调用 → 循环直到产出最终结果或触发终止条件。3.2 工具定义用 Schema 把话说死工具定义是 Harness 的地基。定义得清楚模型调用就准定义得模糊后面全是坑。我用的是 JSON Schema 来描述每个工具包含名称、描述、参数结构。这里有几个实操要点描述要写“什么时候用”不只是“是什么”。比如一个“搜索知识库”的工具描述不要只写“搜索知识库”而要写“当用户询问产品功能、政策条款、历史文档内容时使用此工具输入自然语言查询语句”。模型靠描述来判断该不该调用描述写得越贴近使用场景误调用越少。参数类型要严格。能用枚举就用枚举能用整数就别用字符串。参数越具体模型越不容易乱填。必填项和可选项分开。必填项缺失直接报错可选项缺失走默认值。下面是一个工具定义的示例结构{ name: query_order, description: 当用户需要查询订单状态、物流信息、退款进度时调用此工具。输入订单号返回订单详情。, parameters: { type: object, properties: { order_id: { type: string, description: 订单号16位数字字符串, pattern: ^[0-9]{16}$ }, fields: { type: array, items: {type: string, enum: [status, logistics, refund]}, description: 需要返回的字段不填则返回全部 } }, required: [order_id] } }这个 schema 里order_id 用正则约束了格式fields 用枚举限制了取值。Harness 在调用前校验这些约束不合规的直接打回让模型重生成。3.3 上下文组装把对的信息在对的时候放进去上下文组装是 Harness 里最需要“手感”的部分。同样一组信息排列顺序不同模型的表现可能差很多。我的组装顺序一般是系统提示词 → 任务目标 → 当前状态 → 工具定义 → 近期对话 → 当前用户输入。系统提示词放最前面因为模型对开头和结尾的内容注意力最集中。任务目标和当前状态紧随其后让模型时刻知道“我在干什么、干到哪了”。工具定义放在中间偏后近期对话和当前输入放最后。系统提示词里我会明确写几件事角色定位、行为边界、输出格式要求、错误处理原则。比如“你是一个订单处理助手只能调用已注册的工具不要编造工具名称。如果工具调用失败根据错误信息调整参数后重试最多重试两次。”这里有个细节工具定义不要每轮都全量塞进去。如果工具有几十个全量塞会占用大量 token。我的做法是按任务类型动态加载相关工具或者用检索的方式选出最可能用到的几个。这个优化在工具多的场景下效果很明显。3.4 执行循环控制好节奏和终止条件Agent 的执行是一个循环模型推理 → 判断动作 → 执行 → 回填 → 再推理。这个循环必须有明确的终止条件否则可能无限转下去。我设置的终止条件包括模型输出了最终答案没有工具调用意图、达到最大循环次数一般设 10-15 次、累计 token 超限、执行时间超时、连续多次错误无法恢复。循环里还要注意节奏控制。每轮循环之间可以加一个短暂的检查点判断当前状态是否正常、是否需要人工介入。对于高风险操作比如写数据库、发消息可以在执行前插入确认步骤。3.5 日志与可观测性出问题时能查Agent 出问题是必然的关键是出问题后能不能快速定位。Harness 必须记录完整的执行日志每轮模型的输入输出、工具调用的参数和结果、错误信息、耗时、token 消耗。我一般会把日志结构化存储方便查询和统计。关键字段包括会话 ID、轮次、时间戳、模型输入摘要、模型输出、工具名称、工具参数、工具结果、错误类型、耗时。有了这些排查问题时可以还原整个执行过程。可观测性还包括监控指标成功率、平均轮次、平均耗时、工具调用失败率、token 消耗趋势。这些指标能帮你发现系统性问题比如某个工具失败率突然升高可能是外部系统出了问题。4. 踩坑实录那些让我熬夜的典型问题4.1 模型“自作聪明”编造工具名这是最常见的问题之一。模型在推理时如果找不到合适的工具有时会“编”一个看起来合理的工具名然后生成一堆参数。Harness 如果不做校验直接去执行就会报“工具不存在”。我的解法是在 Harness 层做严格的白名单校验模型返回的工具名必须在注册表里不在的直接拒绝并把可用工具列表返回给模型让它重新选择。同时在系统提示词里明确写“只能使用已注册的工具不要编造”。4.2 参数类型漂移模型有时会把数字写成字符串把数组写成逗号分隔的字符串把布尔值写成“true”字符串。这些在人类看来无所谓但程序解析会出错。Harness 的参数校验层要做类型强制转换和校验。能转的转转不了的报错。比如字符串“123”可以转成整数 123但“abc”转整数就报错。转换规则要明确并且把转换结果记录在日志里方便排查。4.3 上下文爆炸长任务跑到后面上下文越来越长最后超出模型限制。这个问题在早期不明显任务一长就暴露。我的解法是三层防护一是工具结果返回前做截断只保留关键字段二是设置上下文阈值超过就触发压缩把早期对话总结成摘要三是状态外置关键信息存在状态对象里不依赖上下文传递。压缩策略我用的是“保留最近 N 轮完整对话 早期对话摘要 当前任务状态”。摘要用模型生成提示词是“把以下对话总结成不超过 200 字的要点保留关键决策和结果”。4.4 工具调用死循环模型可能反复调用同一个工具每次参数略有不同但都失败然后一直重试。如果不加控制会烧掉大量 token。Harness 要检测重复调用同一个工具、相似参数、连续多次失败就触发熔断停止重试返回错误给用户或走降级路径。我一般设置“同一工具连续失败 3 次就熔断”。4.5 模型输出格式不稳定要求模型返回 JSON它有时返回纯 JSON有时包在 Markdown 代码块里有时前面加一句“好的以下是结果”。解析层如果只按一种格式处理就会失败。我的解法是解析层做容错先尝试直接解析失败则提取代码块内容再解析再失败则用正则提取 JSON 片段。同时把解析失败的情况记录下来如果某个提示词导致的解析失败率很高就回去优化提示词。下面这张表是我整理的常见问题速查问题现象可能原因排查方向解决手段工具名不存在模型编造检查工具注册表白名单校验提示词约束参数类型错误模型输出格式漂移检查参数校验日志类型转换严格校验上下文超限长任务累积检查 token 消耗截断压缩状态外置死循环重试工具持续失败检查工具调用日志熔断机制失败上限输出解析失败格式不稳定检查原始输出多级解析容错任务中途卡住状态丢失检查状态对象状态外置检查点5. 让 Harness 更稳的几个进阶思路5.1 幂等设计重复执行不出错Agent 重试是常态但重试不能产生副作用。比如“发消息”这个操作重试两次就发了两条用户会疯。Harness 要支持幂等每个操作带一个幂等键外部系统根据幂等键去重。对于不支持幂等的外部系统Harness 要在本地记录已执行的操作重试前先检查。5.2 人机协同该让人介入时就介入不是所有决策都适合让 Agent 自己做。高风险操作、模糊意图、多次失败后的场景应该触发人工确认。Harness 可以设计一个“确认点”机制执行到关键步骤时暂停把当前状态和待执行操作展示给用户等用户确认后再继续。这个机制在金融、医疗等场景尤其重要。5.3 灰度与回滚新版本先小范围跑Harness 的提示词、工具定义、执行策略都可能调整。每次调整都是一次风险。我的做法是灰度发布新版本先对一小部分流量生效观察成功率、耗时、错误率等指标没问题再全量。同时保留回滚能力配置化的部分提示词、工具定义、阈值参数支持热更新和快速回滚不用重新部署。5.4 成本控制token 是要花钱的Agent 跑起来 token 消耗很快尤其是长任务和多轮循环。Harness 要有成本控制机制设置单次任务的 token 上限、监控 token 消耗趋势、对高消耗任务做告警。优化手段包括精简系统提示词、动态加载工具定义、工具结果截断、上下文压缩、选择更经济的模型处理简单任务。这些手段组合起来成本能降不少。6. 一些个人体会Harness 工程这件事说到底是在跟“不确定性”打交道。模型是不确定的外部系统是不确定的网络是不确定的。Harness 的价值就是把这些不确定性收敛到一个可控的范围内让整个系统表现得像一个可靠的工程系统。我最大的体会是不要试图让模型变得完美而要让系统在模型不完美时依然能工作。模型会犯错这没关系关键是犯错后能发现、能恢复、能兜底。把精力花在 Harness 的健壮性上比反复调提示词追求“一次成功”要划算得多。另一个体会是可观测性怎么强调都不过分。Agent 出问题时如果没有完整的日志排查就是盲人摸象。我现在的习惯是Harness 的每个关键节点都打日志宁可多打不可漏打。日志结构化存储方便查询和统计。最后分享一个小技巧给 Harness 写单元测试。工具调用的参数校验、输出解析、错误处理、上下文压缩这些逻辑都可以脱离模型单独测试。用 mock 数据模拟各种边界情况能提前发现很多问题。我现在的项目里Harness 层的测试覆盖率比业务层还高因为这部分逻辑最需要稳定。这个方向后续还可以往几个方向扩展多 Agent 协作时的 Harness 设计、跨会话的长期记忆管理、Agent 行为的审计与合规。每个方向都有不少值得深挖的东西等我在实际项目里跑出更多经验再找机会聊。