AI Agent火起来之后圈子里聊的最多的就是“提示词”。前两天有个朋友找我吐槽说他按普通Prompt的思路写了个Agent的系统提示结果模型每次都在该调工具的时候开始编答案该停止的时候又死循环。其实这问题十有八九出在“Harness Engineering”上。Harness不是某款框架的专属概念它描述的是连接模型大脑和外部工具、记忆、执行循环的那整套控制结构。而提示词就是这套结构里最核心的说明书。这篇内容想聊聊怎么设计一套高效的AI Agent Harness Engineering提示词我从实际项目踩坑出发把从结构设计到上线维护的经验一次梳理清楚。适合正在做Agent落地、被多轮工具调用折磨的开发者也适合准备进入这个方向、想少走弯路的新手。1. Harness 和普通 Prompt 的差别1.1 什么是 Agent Harness先给Harness一个直观定义。这个词直译是“马具”用在AI Agent里指的是把大模型、工具调用、记忆模块、执行循环和外部环境装配在一起的整套“控制骨架”。你可以把大模型想象成一台发动机Harness就是变速箱、方向盘、仪表盘和安全带的综合体。没有Harness模型只是一台能聊天但不会干活的发动机有了Harness它才能围绕用户目标自主决策、调用工具、判断结果、在合适时机停下。很多人以为搭Agent就是调一个系统提示词其实系统提示词只是Harness的“表层”。真正完整的Harness还包括工具Schema、消息队列、上下文窗口管理、重试策略、结果解析器以及外部状态管理。这些零件都需要和提示词设计配合才能让模型稳定输出。1.2 为什么提示词是 Harness 的灵魂因为上面的零件最终都要通过自然语言指令传达给模型。工具描述写得模棱两可模型就会在工具选择上开始猜没有定义行动循环模型就会把工具结果当成用户消息来回复没有终止条件模型就会反复调用同一个工具直到超出预算。提示词承担的是一个“把所有零件拧成一致行为”的角色。举个例子同一个工具列表“查天气、设提醒、发邮件”系统提示写法不同行为差异巨大。你写“请帮用户完成请求”模型大概率会自己脑补一个邮件发送成功你写“只有收到用户明确指令后才能调发送邮件工具工具返回失败时立即停止并报告”行为就立刻收敛。这就是提示词在Harness里的控制力。1.3 评判高效性的三个维度判断一套Harness提示词好不好不能只看单次能不能完成任务。我一般用三个指标成功率在固定测试集上完整正确完成任务的概率。这是最基础的指标。成本效率平均每个任务消耗的Token数和工具调用次数。多轮Agent经常在无关细节上浪费调用提示词里的约束能直接压缩成本。可维护性当工具列表增加或任务规则变化修改提示词需要动多少地方。好的提示词应该有清晰的段落边界而不是把规则散落得到处都是。这三个维度会贯穿后面的设计和排查思路。我建议一开始调提示词时就针对每个维度各定一个最低基线比如“成功率不低于80%”“平均调用不超过5次”“新增工具只需改动工具描述小节”。没有基线后面迭代时很容易凭感觉越改越乱。2. 动笔之前先把四个基础模块定下来2.1 任务边界和角色定义要具体到能执行很多提示词失败不是因为模型笨而是任务边界没定清楚。你告诉它“你是数据分析助手”它不知道什么事归自己管、什么事该拒绝。更好的写法是“你是CSV报表处理助手。你只处理传入工作目录中的CSV文件不访问网络不写代码不做图表。”明确边界后模型面对越界请求时会倾向于拒绝或请求确认而不是硬着头皮瞎做。边界定义一般包括四件事允许的目标、可用资源、明确禁止的行为、交付形式。每一条都要用可校验的句子。比如“禁止删除文件”比“请谨慎操作”有用得多。我自己在实际项目中验证过把角色限定得越窄模型越不容易跳出框架反而是那些“万能助手”式的定义经常在任务中途跑偏把用户请求理解成聊天话题。2.2 工具清单和输入输出契约先于提示词确定Harness里的工具不是随口取个名字就行。每个工具需要定义清楚功能一句话、适用场景、参数列表名称/类型/必填/默认值、返回值结构、会抛出的错误。这部分通常以代码Schema形式存在但提示词里的工具描述要和Schema保持一致。如果工具实际只支持CSV描述里就不能写“支持多种格式”。我在项目中就踩过模型根据描述去读Excel、然后工具直接报错的坑。工具描述建议单独写成一个小节和任务规则分开。这样模型在需要查阅时能快速定位后续增删工具也方便。契约的颗粒度要适中太细会把提示词撑得很长太粗模型又可能编参数。我的经验是参数必填项必须写清返回结果给一个示例错误码给常见的两到三个就够了。2.3 记忆策略决定上下文里放什么Harness必须处理多轮对话。短期记忆是当前对话历史长期记忆可能是向量库或外部数据库。设计提示词前先想清楚一个问题模型完成一个任务最多需要几轮哪些信息可以从历史消息中丢弃常见的做法是系统提示只放恒定规则每轮的用户消息和工具结果尽量精简每隔几轮把已完成的子任务压成摘要。如果你在提示词里塞了一大堆用不到的对话背景模型不仅要浪费Token还容易被无关信息带偏。我给一个Agent做维护时发现它经常把用户两个月前的聊天记录当成当前指令后来把历史摘要改成“只保留当前会话目标”后行为立刻稳定了。2.4 安全边界和失败兜底不能靠模型自觉Agent一旦接入工具就具备了真实世界的影响能力。删除文件、发邮件、执行脚本都属于高风险操作。Harness提示词必须显式声明高风险工具调用前需要用户确认工具返回错误时把原始错误抛给用户不自行猜测修复遇到无法判断的请求明确说“需要更多信息”并停止。我见过一个Agent在处理文件时因为拿到的路径不存在硬是自己在回复里编了一份“处理成功”的结果。后来在提示词里加上“不得编造工具返回结果”和“当工具返回ERROR时立即终止当前计划”两条规则这个问题才收敛。类似的兜底规则看起来多余但在真实生产环境里往往是最后一道防线。3. 提示词结构实操从零拼一套 Agent Harness3.1 系统提示先把工作流程写成一个可执行脚本系统提示是Harness的控制中枢。建议用“角色目标工作流程规则结束条件”的固定框架而不是让模型自由理解。下面是一个通用模板可以直接改来用你是[角色]目标[一句话任务目标]。 工作流程必须按以下顺序执行 1. 解析用户请求拆解为可执行子步骤。 2. 判断当前步骤是否需要调用工具。若需要从工具清单中选择最合适的工具。 3. 调用工具后检查返回值。如果成功继续下一步如果失败进入失败处理流程。 4. 所有子步骤完成后按[指定输出格式]生成最终答复。 强制规则 - 只有需要外部数据时才调用工具禁止为了“显得专业”而调用工具。 - 工具返回ERROR时立即停止当前循环并将错误信息整理后反馈给用户。 - 禁止编造任何工具返回结果。 结束条件 - 用户目标已完成。 - 连续3次工具调用返回相同错误。 - 累计调用达到[次数上限]未完成也终止。这个模板的核心思路是把“工作流程”变成显式指令。模型会优先遵循带编号的步骤比“请合理分析”可靠得多。注意每一条强制规则都要用行为动词而不是形容词。比如“立即停止”就比“谨慎处理”更容易被执行。3.2 工具描述让模型知道什么时候用哪个工具工具描述不能只写“用于读取文件”。我一般按下面格式写每个工具控制在几行到一小段内工具名read_csv 功能读取指定CSV文件并返回表格数据。 适用场景用户需要查看或处理某个CSV文件时。 参数 - path文件路径必填。 - max_rows默认1000可选超过最大行数时自动截断。 返回结构化行数据文件不存在时返回ERROR_FILE_NOT_FOUND。 注意事项只支持UTF-8编码不支持Excel文件。遇到Excel请求请提示用户另存为CSV。把“适用场景”和“注意事项”写清楚能显著降低工具错选率。特别是“不支持什么”比“支持什么”更能防止模型脑补。如果你有多个工具名称相近建议在描述开头就写明它们之间的区别。比如“read_csv用于读取list_files用于查看目录两者不要混淆”一句话就能挡住大量错误调用。3.3 行动循环和输出格式是 Harness 的骨架Agent多轮工具调用一般用“思考-行动-观察”循环。提示词里必须规定模型每轮要输出什么否则你没法稳定解析。一个实用约定是每次拿到观察结果后先输出一行THOUGHT说明当前判断再输出一行NEXT内容为“工具名|参数JSON”或“DONE|最终答复”。 例 THOUGHT: 用户要处理的是a.csv需要先确认文件存在。 NEXT: list_files|{dir: /data/input}这种格式的好处是解析简单出错时可以快速定位到底是思考环节错了还是工具参数错了。有些框架支持结构化输出可以让模型输出JSON但文本标记法更通用调试时也直观。我推荐在初期先用手写文本标记等框架成熟后再切换到强制的JSON输出。3.4 边界条件和终止条件一次性写全提示词最怕“差不多”。我建议把所有边界条件集中放在一个“边界与终止”小节包括不允许的行为清单例如“不访问原始网络”“不在没有人工确认时删除文件”。终止条件清单例如“完成目标”“相同错误连续出现N次”“用户取消”“达到最大调用次数”。遇到模糊请求时的处理例如“先列出一个问题清单向用户确认后再行动”。这些条件看起来像“低概率事件”但恰恰是它们决定了一个Agent能不能从演示阶段走到生产环境。没有终止条件死循环几乎是必然的没有越权限制一个测试Demo可能在用户手里变成危险工具。所以我每次搭Harness几乎一半的提示篇幅都花在边界和终止条件上这不是浪费。4. 多轮交互里的上下文管理技巧4.1 用摘要替换冗长历史但保留关键状态多轮Agent跑起来后上下文里会堆满历史消息。直接截断会丢掉用户最初的意图不截断又会成本飙升。我常用的办法是设计一个“状态摘要”。每完成3到5轮就用一个轻量模型或固定模板把历史压缩成三行目标、已完成步骤、未完成事项及最新工具结果。把摘要注入到下一轮消息的头部并在摘要后面明确写“原始对话历史已归档下面请基于当前状态继续”。这样模型不会迷失又不需要把完整历史放在上下文中。注意目标信息必须原样保留在摘要里不能因为压缩而改写。我曾试过让摘要模型自由发挥结果它把用户的原始指令改成了自己的理解Agent就顺着错误目标往下跑了。4.2 动态注入当前状态让提示词“活”起来系统提示里的规则是静态的但Agent运行时的状态是动态的。高效Harness会每轮把当前工作目录、剩余调用预算、最近一次工具返回结果、当前执行阶段等信息拼接到消息里。比如[系统状态] 工作目录/data/input 累计调用次数3/10 最近一次工具调用read_csv /data/input/sales.csv 结果成功共120行包含字段 product, sales, date 当前阶段数据清洗 下一目标去掉 product 字段为空的记录模型看到这些信息后能准确判断下一步而不是靠上下文里翻找。这个动态片段建议放在工具结果之前模型读到的优先级相对更高。维护状态片段时要注意所有数据必须来自上一轮的真实结果不能由模型自己生成。否则状态一旦失真后续决策就全乱了。4.3 隔离工具输出避免“工噪”污染推理工具返回的数据经常又长又乱。如果直接丢给模型它可能把文件内容当成用户指令或者开始复述数据。我习惯用带标签的分隔符把工具输出包起来先做后处理。比如tool_result toolread_csv [{product: A, sales: 10}, ...] /tool_result同时做三层清洗截断超长内容、去掉无意义字段、把错误信息归类。如果工具返回的是一大段JSON尽量只保留当前步骤需要的字段。这样既省Token又降低了模型被噪声带偏的概率。很多项目只关注提示词怎么写忽略了工具输出的清洗结果模型总在“语无伦次”其实就是被脏数据带偏了。5. 一个文件处理 Agent 的 Harness 提示复盘5.1 场景拆解与工具选择虚拟一个典型场景用户上传一批CSV报表Agent负责合并数据、计算汇总、生成一份Markdown报告。我给它配了四个工具list_files、read_csv、merge_data、compute_stats还有一个write_report用于落地报告文件。设计之初我就确定了两个约束Agent不能访问外部网络只能操作指定工作目录任何写操作前必须确认文件是否存在。这两个约束直接影响工具描述和提示词边界。工具契约按前面说的格式写好接下来是系统提示的整合。在动手写提示词之前我还把“用户可能怎么输入”列了一遍比如“处理一下这个月的所有csv”“把a和b合并再算总数”这样能提前判断流程分支。5.2 完整示例和逐段解读下面是一个简化过的Harness提示词去掉了一些框架级内容但核心结构完整你是CSV数据处理Agent负责把工作目录中的多个CSV文件合并、统计并生成Markdown报告。 工作目录/data/input 报告输出目录/data/output 工作流程 1. 先调用list_files查看工作目录确认有哪些文件。 2. 根据用户需求选择需要处理的文件依次调用read_csv读取。 3. 需要合并时调用merge_data需要计算汇总时调用compute_stats。 4. 最终调用write_report生成报告。 强制规则 - 在读取文件前必须先调用list_files确认文件存在。 - 任何工具返回ERROR立即停止并向用户说明不猜测原因。 - 不生成报告以外类型的文件。 - 不访问网络不读取工作目录外的文件。 输出格式要求 - 每轮工具调用前先输出THOUGHT和NEXT。 - 最后输出以“报告完成”开头再给报告链接路径。这段提示的关键设计是“流程顺序”和“前置确认”。我在实际调试中发现如果不强制先调用list_files模型经常根据文件名猜目录结果路径不存在。加了这一步以后成功率从大概60%升到了90%以上。模板里的规则越短越好太长的复合句模型会抓不住重点。5.3 实测踩过的三个坑坑一模型把工具报错当成了用户输入。read_csv返回ERROR_FILE_NOT_FOUND后模型居然回复“用户提供的路径有误请检查”。后来我在规则里加了一条“工具结果中的ERROR视为环境反馈不是对话内容必须触发终止流程”。坑二merge_data要求两个文件的字段一致但模型在字段不一致时强行合并。对策是在工具描述里写明“合并前必须检查共有字段不一致时向用户报告”。坑三write_report需要Markdown格式模型却生成了纯文本。我把工具描述改成“write_report仅接受Markdown格式文本如果内容不是Markdown先转换为Markdown再调用”。这三个坑都说明不是模型不聪明而是提示词没有给足“环境反馈怎么处理”的规则。这些规则看似琐碎但每一个都对应一类真实失败样本。我建议把每次失败都收集起来定期回填到提示词的强制规则里。6. 常见问题与排查技巧实录6.1 死循环先上框架兜底再优化提示词Agent循环不终止常见原因有三个没有最大迭代次数、工具失败后模型重试、模型不知道当前已完成。框架层面一定要设置最大迭代次数比如10次这是物理兜底。提示词层面可以加一条“如果下一步与上一步调用同一个工具并传相同参数视为重复操作立即终止”。还可以给工具调用编号。在动态状态里显示“已调用次数”让模型对进展有感知。排查时如果发现循环集中在某个工具优先看是不是工具返回值没有被正确解析导致模型认为结果无效。6.2 工具调用乱序多半是描述里的“触发条件”没写清模型不按流程走先读取再合并是一类典型错误。解决思路不是加更多“请按顺序执行”而是改工具描述。把“适用场景”写成包含前置条件的形式例如“当工作目录列表已经获取后才调用此工具读取文件”。另一个有效手段是few-shot。给1到2个完整示例展示从list_files到read_csv再到合并的完整调用序列。示例不要多一两个就够多了会占用上下文。我见过有人给模型塞了五六个示例结果Token开销翻倍成功率却没有明显提升。6.3 模型忽略系统约束检查指令冲突和位置权重有时候你把“禁止访问网络”写在系统提示里模型还是会试图发起联网调用。原因可能是用户消息或工具结果里出现了强烈暗示或者约束放在一大段文字中间被模型忽略了。处理办法把最关键的一条约束同时放在系统提示的开头和结尾。使用短句少用嵌套长句。在每轮动态状态里重复当前模式比如“当前模式离线处理”。如果还不行用后处理校验拦截不让模型真正调用受限工具。约束不是写一次就完了在多轮场景里需要在关键节点反复出现。模型对系统提示不同位置的注意力不完全一样把硬约束前置或后置都是经过验证的有效手段。6.4 上下文太长成本爆炸的优化顺序上下文膨胀几乎是所有Agent早晚会遇到的问题。我的优化顺序是先压缩工具输出再压缩历史最后才是考虑换更大窗口模型。历史压缩可以用状态摘要替代早期消息。工具输出采用字段级抽取而不是直接拼接完整JSON。如果使用了对话管理框架还可以把每个工具结果单独存到外部存储只在需要时按ID取回。提示词里告诉模型“要查看某个工具的历史结果时通过retrieve_tool_output工具按ID获取”这样上下文可以始终保持精简。归根结底Token预算要花在“当前这一步”上而不是把整条任务日志都背在身上。7. 测试、迭代与上线维护把提示词当成代码管7.1 用回归测试集代替拍脑袋调参提示词改动了一次往往对旧场景生效却让新场景翻车。所以我坚持维护一份回归测试集包含三类用例正常路径、边界用例、异常用例。正常路径覆盖典型任务边界用例覆盖文件不存在、字段不一致、超大表格异常用例覆盖用户乱输入、连续错误、越权请求。每次改提示词都跑一遍测试集并记录通过率。我通常会维护一个简单的表格比如场景名、输入、期望行为、实际行为、通过与否。不用每次都自动化得很复杂初期手工跑也能发现大量问题。关键是“每次改动都跑”而不是等到项目上线前临时补测。7.2 版本管理、灰度上线和回放提示词本质上是一段可执行配置应该放进Git仓库。命名建议用“harness_提示词名_vN”并且把每次改动对应的工具变更记录在说明里。上线前用历史日志跑一遍离线回放对比新旧版本的成败。灰度时先给20%流量用新版本跑一天看指标没有明显恶化再全量放开。很多人觉得“提示词还要发版很夸张”但一旦Agent接入生产一行改动可能影响几百个任务。做好回滚很重要至少保留上一版提示词出问题能迅速切回。我还会在版本说明里标注“这次改动的动机”这样三个月后回头看不会一脸茫然。7.3 可观测性让每个决策都留痕排查Agent问题最怕黑盒。Harness提示词里要求模型输出结构化思考过程已经成为我的默认设置。每轮记录用户请求、模型思考、工具调用参数、工具返回结果、最终答复。日志要能回放出完整链路。实践中有个小技巧给每轮工具调用生成唯一ID并在NEXT字段里带上。日志和工具调用记录就能对上定位问题时能准确知道模型用的是哪次返回结果。别小看这些细节没有留痕排查死循环和误操作会非常痛苦。8. 几个让提示词更耐用的额外建议8.1 少堆技巧多写边界网上有很多“提示词魔法”但Harness提示词的稳定性来自边界和状态管理而不是华丽话术。我见过有人写了二十条规则模型反而每条都执行不到位。更好的做法是规则别超过十条每条都用可验证的行为描述。比如“工具失败时报告原因”就比“请确保操作正确”更能被执行。8.2 把大任务拆成多个小Harness如果Agent承担的职责太多一个提示词硬撑会越来越难维护。我更倾向于把任务拆成多个小Harness每个Harness的提示词只负责一个子任务通过路由器分发。比如把“文件读取”和“报告生成”分开各自的约束清晰测试和维护成本都低很多。这些是我在实际项目里反复验证过的原则。Harness Engineering说到底是用工程方法控制模型行为提示词只是其中一环但也是最重要的一环。把边界、状态、循环、可观测性想清楚你的Agent会从“偶尔灵光”变成“稳定可用”。最后再分享一个小技巧每次上线新Harness之前拿十个历史失败样本做验收能全部通过再放量你会发现生产事故少一大半。