写 Agent 写了快两年我最大的一个感受是真正拖垮项目的往往不是模型能力不够而是提示词先失控了。今天这篇聊提示词模板管理和 Agent 提示词编排是系列第七篇。如果你还在把提示词当成一段存起来、用的时候粘贴的文本或者你的 Agent 已经有超过十个工具调用路径却连一次执行都很难复现这篇文章大概率对你有用。这套东西到底解决什么问题简单说提示词模板管理解决的是同一套规则在不同场景下如何稳定复用Agent 提示词编排解决的是多个模板如何按流程组合、切换、串联。两者配合好Agent 的迭代速度、可观测性和效果稳定性都会明显提升。我会从工程化落地、编排逻辑、实战复盘三个方向展开最后聊聊我在真实项目里踩过的坑。1. 为什么提示词模板管理决定Agent项目生死1.1 提示词模板不是存起来的字符串很多人把模板理解成一段固定文案最多加两个变量。真正把提示词当代码管起来之后你会发现它远比字符串复杂。一个合格的模板应该由四部分组成元信息、变量声明、渲染逻辑、被调用的场景定义。缺少任何一个解决一个问题另一个问题就会出现。我在项目里用 YAML 维护模板大概长这样meta: id: intent_classifier version: 2.3.0 model: gpt-4o-mini temperature: 0 variables: - user_input - candidate_list - history system: | 你是客服意图分类器。只输出 JSON不要解释。 user: | 候选意图列表{{candidate_list}} 对话历史{{history}} 用户最近消息{{user_input}}为什么不直接写字符串因为模板要具备被机器理解的属性。Agent 在运行时要根据当前状态决定用哪个模板还要判断变量是否齐全调用后要解析输出。没有 meta 和变量声明这些逻辑只能散落在代码里改一处漏一处。更关键的是模板一旦作为代码资产进入版本管理你才能回答这个模板是给哪个模型用的上次改动是谁什么时候改的线上用的到底是哪个版本这类问题。1.2 模板管理的三个层次文本、变量、流程模板管理不是简单建个文件夹。我把它拆成三个层次。第一个层次是文本标准化凡是需要复用的提示词都采用统一的格式、分隔符和占位符语法避免同一个项目里出现两种变量写法。第二个层次是变量与上下文解耦模板内部不让出现具体的业务数据所有动态内容都通过变量注入。第三个层次是模板与编排流程分离模板只管这个环节怎么写代码负责下一个环节调用谁。这三个层次决定了你能走多远。只做到第一层就是文档管理做到第二层可以支撑单 Agent 的多步调用做到第三层才谈得上多 Agent 编排和复杂的条件分支。我在接手别人项目时先看模板有没有把这三个层次分开基本就能判断出这个项目后续会不会失控。1.3 从能跑到可维护中间隔着系统化如果只是写 demo提示词确实不需要管理。但 Agent 项目一旦进入多工具、多步骤阶段问题马上暴露。最常见的场景是你为了修一个意图误判在系统提示词里加了一句新规则结果三天后工具调用开始不稳定你完全不知道是不是这句话引起的。因为你手上没有基线数据也没有模板版本概念只能靠直觉来回试。另一个问题是角色污染。多个步骤共用一个 Prompt 模板时分类任务、回答任务、工具调用任务互相干扰。我见过的最典型案例同一个 system 里既要模型做 JSON 输出又要它像客服一样口语化回应结果模型经常在 JSON 里夹杂解释文字解析器直接报错。这些都不是模型变笨了而是提示词编排没有层次所有规则挤在一个模板里。所以说提示词模板管理是 Agent 工程质量的地基。它不会直接提升单次回答的上限但能显著压低项目失控的下限。没有这套地基Agent 的每一步看起来都能跑合在一起就变成了黑箱。2. 模板的工程化落地字段、变量、版本一个都不能少2.1 元信息设计每一条模板都要有身份模板不是纯文本第一个要管起来的是元信息。我在模板库中为每条模板维护下面这些字段字段示例为什么需要template_idintent_classifier全局唯一标识代码引用用version2.3.0语义化版本记录大改/小改/修复modelgpt-4o-mini不同模型的指令遵循能力、格式要求不同temperature0Agent 内部步骤通常要求确定性优先max_tokens512防止输出过长categoryclassifier / judgment / generator按用途归类owner张三模板变更的责任人updated_at2026-04-01变更时间配合 trace 定位问题statusactive / draft / deprecated避免误用旧模板所有模板在代码中以唯一 ID 被引用不要在提示词正文里写死另一个模板的内容。元信息一旦齐全你就能在出现线上事故时快速缩小排查范围。比如某次工具调用失败trace 里显示用的是 intent_classifier2.3.0owner 上次改过马上就能定位。2.2 变量注入与上下文组织把动态内容关进笼子有了元信息下一步是变量管理。模板里需要动态注入的内容非常多用户输入、工具返回、历史记录、候选列表。我建议所有变量在模板中都必须显式声明使用时通过统一的渲染函数注入。尤其在 Agent 场景工具返回的字段经常很长如果直接塞进系统提示词很容易把模型注意力带偏。另一个重点是注入顺序。模型对提示词开头和结尾的记忆更好中间内容容易被稀释。我实践中采用的口诀是身份和规则放头当前任务放尾历史记录和工具结果放中段。这样系统提示词的权威指令靠近开头当前轮用户输入靠近结尾模型不会因为中间塞了一堆工具 JSON 而忽略最重要的指令。渲染后的完整提示词不是给用户看的而是给模型看的。所以模板里变量边界一定要清晰最好是{{user_input}}这样的占位符。我在线上见过把用户消息直接拼接成系统提示词的做法那是非常危险的等于把输入内容当成了指令执行。用户消息里哪怕只有一个忽略之前的提示词整个 Agent 就会被带偏。正确做法是用户输入永远作为数据字段进入模板而不是作为指令字段拼进 system。2.3 版本管理与回归测试改模板要像改代码一样谨慎模板文件放在 Git 仓库里和普通代码一样走分支、MR、Review、合并。这是我认为模板管理最重要的一步。很多人觉得提示词改起来轻量随手在线上编辑就发布了但 Agent 是多步骤串联的一个模板的小改动可能影响后续所有环节。没有版本记录你连回滚都做不到。配合版本管理的是一套最小回归测试集。我的做法是维护大约 100 条典型输入覆盖每个模板的常见分支每次模板变更后批量跑一遍记录关键指标意图准确率、工具调用成功率、回答内容质量、平均 token 数、平均耗时。不一定每次都全自动判分但要保证核心指标没有明显退化。跑回归的时候有个容易忽略的细节要固定模型版本和参数。模型供应商侧升级模型后提示词效果会变如果你同时改了模板就很难归因。我通常会在测试脚本里记录模型标识发现指标波动时先看是不是模型版本变了。模板和代码一样要避免测试环境能过、线上现形的问题测试时用生产环境的模型别名和参数效果才可信。3. Agent提示词编排的核心逻辑单条提示词如何变成一套工作流3.1 系统提示词、用户提示词与工具返回的职责拆分Agent 跟普通聊天不同它往往要循环调用 LLM 多次每次调用都有不同的目的。如果只设计了一个 Prompt就无法应对多步场景。所以编排的第一个问题是把一份提示词变成一组提示词。我习惯把提示词按作用分成三层。第一层是全局系统提示词描述 Agent 身份、通用价值观、输出要求每个循环都带上但内容很克制不涉及具体任务。第二层是步骤级用户提示词用来引导当前这一步做什么比如基于以下工具结果判断条件是否满足。第三层是工具返回的上下文片段它不算提示词但要按固定格式注入到步骤级模板中。这里容易犯的错是把所有东西都堆在系统提示词里。我见过一个项目系统提示词写到 3000 多 token几乎把整个业务流程指令都塞进去了。真正跑起来后模型反而分不清优先级经常跳过关键步骤。拆分的价值在于全局规则一旦固定步骤模板可以小步快跑地迭代不影响其他环节。这就像厨师做菜灶台的位置和燃气规则是固定的但每道菜的菜谱应该独立管理而不是把所有菜谱抄在同一张纸上。3.2 思考-行动-观察循环中的提示词切换Agent 最常用的是 ReAct 这类思考-行动-观察循环。它每个周期至少涉及三个模板思考模板、行动模板、总结模板。用一个简化伪代码表示编排逻辑state load_state() while not state.is_final: thought call_llm(render(think, state)) if thought.is_final: state.is_final True break action call_llm(render(act, { thought: thought, tools: available_tools(state) })) observation execute_tool(action) state.add_observation(observation) answer call_llm(render(summarize, state))思考模板负责让模型判断当前信息是否足够不够就提出下一步动作。行动模板负责把思考结果转成结构化的工具调用参数。观察处理则把工具返回的内容清洗后放回上下文。三个模板要各自测试尤其是思考模板不能把工具参数格式也写进去否则模型会在思考时尝试生成 JSON导致格式错误。切换模板时还要注意状态传递。模型的输出往往会带一点多余文字我在实际编排时通常先用解析器提取关键字段解析失败就重试一次再失败才让模型修正。而不是直接把上一轮模型的原始输出原封不动灌给下一轮模板。很多看起来莫名其妙的错误其实是上一轮输出里的格式噪声污染了下一轮输入。3.3 多Agent协作时的提示词编排模式单 Agent 都搞清楚了再往上走就是多 Agent 协作。多 Agent 的本质不是多个机器人聊天而是多个独立的提示词执行单元通过消息协议协作。主控 Agent 负责拆解任务和派发子 Agent 使用自己的模板完成任务并返回结构化结果。我建议子 Agent 的提示词里必须约定返回格式至少要包含status、result、confidence三项。status表示成功、失败、还是需要更多信息result是业务结果confidence是置信度。主控 Agent 的编排模板根据这三个字段决定下一步成功就走下一环节失败就重试或转人工低置信度就触发追问。还有一条经验同一个工具被不同 Agent 调用时它的描述文本要按使用场景重写而不是共用一份工具描述。比如订单查询工具被退款判断 Agent调用时描述侧重查询售后状态被物流解释 Agent调用时描述侧重查询物流轨迹。提示词编排在工具这一层的核心就是让模型看到它此刻该关心的那一面。4. 实战案例复盘检索增强型客服Agent的提示词编排全过程4.1 需求拆解与模板清单我把一个实际项目简化成案例需要做到的是用户说一句模糊的话我要退款Agent 要通过多步检索和判断最后生成符合售后政策的回复。我先做需求拆解把任务切成五个环节每个环节对应一组模板模板ID用途关键输入变量输出格式intent_classifier判断用户意图user_input, historyJSON, 含intent和confidenceorder_parser从对话中提取订单号user_input, historyJSON, 含order_id或缺省query_rewriter把口语问题改写为检索queryuser_input, intenttextpolicy_matcher判断订单是否符合退款条件policy_chunks, order_infoJSON, 含eligible和reasonanswer_generator生成面向用户的最终话术decision, user_input, order_infotext模板之间不是顺序调用那么简单。比如order_parser的输出只有在意图是退款/退货时才需要query_rewriter依赖意图也依赖订单信息。我一开始把五个模板全放在一个系统提示词里结果模型一次只完成了前两步后面全部靠猜。拆成独立模板后每个模板只负责一件事准确率立刻上来。4.2 编排顺序与条件分支实际编排流程我用文字表达收到用户消息后先跑intent_classifier拿到意图和置信度。如果置信度低于 0.6进入澄清分支使用clarify_template反问用户。如果意图不是退款走answer_generator直接生成答复。如果意图是退款接着跑order_parser此时若没有订单号先追问订单号拿到后再继续。订单信息到位后执行知识库检索把命中的政策片段作为policy_chunks传入policy_matcher。这里的判断结论不直接返回给用户要先写进中间状态再由answer_generator转化成自然语言。之所以多这一步是为了让判断逻辑和表达语气解耦。政策判断要严谨话术要温和放在两个模板里各改各的互不影响。条件分支的编排逻辑放在代码里不要放在提示词里。让模型判断是否继续很容易失控最好是在代码中明确判断条件。比如置信度阈值、字段缺失检查、政策匹配结果这类确定性强的内容全部由代码控制提示词只负责模型擅长的事情——理解语义、归纳判断、组织表达。这条边界越清晰Agent 越稳。4.3 效果评测与迭代记录这个 Agent 我经历过几轮迭代效果数据大致如下版本主要变更订单处理准确率平均耗时备注V1单一大 prompt68%6.2s流程经常断V2拆成意图订单解析76%4.8s意图误判减少V3加入检索重写模板79%5.1s召回率提升耗时略升V4政策匹配独立判断82%4.5s拒单准确但话术生硬V5话术模板单独优化84%4.4s满意度上升每次迭代我都只改一个模板然后在同一批测试集上跑回归。V3 到 V4 那次只是增加了 policy_matcher没有动话术模板结果用户满意度反而下降了。原因很简单模型开始更严格地按政策判断但话术模板没有适配把根据政策不能退款这类判断生硬地表达出来。所以模板编排的效果评价一定要看端到端指标不能只看单点准确率。两轮之后我把判断结论和话术生成解耦才算真正解决问题。5. 编排中的失控现场模板膨胀、上下文稀释与调试反模式5.1 不要为了模板而模板哪些内容不该进模板模板管理做到后期很容易用力过猛什么内容都想模板化。我见过有人把工具描述、few-shot 示例、模型能力说明全部塞进提示词模板结果修改任一工具都要去翻模板文件模板之间互相引用根本没法维护。我的经验是模板应该只承载每次执行都需要变化但结构固定的指令部分。完全不变的内容比如通用价值观、输出格式约定可以放全局常量需要跟随工具变化的内容比如工具描述应该放工具注册表只有随轮次变化的内容比如当前任务、上下文片段才值得做模板变量。判断标准就一句话这条内容是在多个调用之间保持稳定还是随业务状态动态变化动态的部分进模板静态的部分独立管理否则模板会变成垃圾桶。5.2 上下文膨胀模板里塞太多历史记录会稀释指令Agent 多轮循环跑下来最直接的问题是上下文越来越长。你会发现系统提示词明明写得很清楚但模型到第十轮就像失了忆。原因不是模型记忆差而是模板渲染后历史记录和工具结果占据了绝大部分 token核心指令被淹没在中间。我推荐的上下文组织顺序是全局系统提示词、历史会话摘要、当前步骤模板、工具返回结果精简片段、末尾追加一行请基于以上信息执行任务。摘要模块单独用 LLM 定期把旧对话压成几百 token而不是把所有原始记录都塞进去。工具返回结果里优先保留关键字段比如只保留金额、状态码而不是一长串 JSON。这一步的收益非常直接。把历史从全文改成摘要后我的客服 Agent 最后一个环节的生成速度提升了约 20%不再出现模型把倒数第三轮的某个词当成当前指令的情况。5.3 调试技巧把每次Agent执行都变成可回放的会话最后聊调试。Agent 的报错不像普通程序那么好懂agent execution terminated due to error这类日志背后往往隐藏着一堆上下文。我的做法是给每次执行打一条完整 trace用什么模板ID和版本、渲染后的完整 prompt、每个中间步骤的输入输出、工具调用的参数和返回、最终答案。保存成可读日志并关联一次会话 ID。调试的第一步不是看代码而是看渲染后的 prompt。很多时候问题就出在变量没替换、旧模板被缓存、或者某个步骤的输出里混入了多余字符。第二步是对比两个版本的差异。直接用 diff 工具看模板渲染前后或者把新旧 prompt 各跑一次对比输出。第三步是语义回归用 LLM 判官或人工抽检判断改动后的输出是否仍符合预期。这三步走完绝大多数玄学问题都能落地成具体的因果。这个主题到这里基本聊完了。个人体会我越来越觉得提示词模板和代码一样是要被尊重、被评审、被测试的一等公民。你把它当成一次性文本它就给你一次性效果你把它当成可维护的资产Agent 的每一步才真正可控。现在我的工作流里模板改动必须走版本记录、回归测试和 trace 回放刚开始觉得麻烦但半年以后回头看这套流程省下来的时间远超管理成本。希望这篇第七篇能帮你把提示词那团乱麻理顺。