直接上结论提示词模板管理和Agent提示词编排是两件经常被混为一谈、但本质完全不同的事。标题里这两个关键词挨在一起恰恰说明当前Agent开发已经到了一个分水岭——单纯会写好一个Prompt已经不够用了你得管理一套Prompt并且学会把它们编排进Agent的执行流程里。这篇就是我自己的实战总结覆盖模板管理的基本方法和Agent编排的常见范式中间会穿插一些我踩过的坑和验证过的方案。适合正在做大模型应用开发、尤其是准备从单轮Prompt转向Agent开发的工程师参考。1. 提示词模板管理为什么它比想象中更重要很多人刚开始接触提示词时习惯在聊天对话框里反复试。温度调低一点重写一版换个表述再试一次试得差不多了就把最终那版复制到代码里。这个阶段其实不需要什么模板管理它本质上是文案创作。但当你开始做产品、做Agent、做团队协作时需求就变了你需要能稳定复现同一套行为需要能对比不同版本的效果需要在线上出问题时快速回滚。这时候提示词就成了一等公民——它不再是写在代码里的字符串而是一个需要被版本化管理、参数化复用、量化评估的资产。1.1 从复制粘贴到持续迭代我见过不少项目的Prompt是这么维护的prompt f 你是一个专业的客服助手。请根据以下用户问题给出回答。 用户说{user_input} 这在一两个场景下没问题但它至少有三个隐患。第一系统指令和用户指令混在一起改了一处很可能影响另一处。第二没有抽象层级所有内容扁平展开随着需求增加会迅速膨胀成几百行的面条代码。第三无法做A/B测试——你想试两版开场白不得不复制整个prompt然后各自维护。我自己在写模板管理工具前的状态就是改了一版人设结果在某个边缘case上表现变差但我不知道是哪个版本引入了问题也不知道之前那版长什么样。这就是典型的Prompt失控。真正的模板管理至少要解决这几件事把系统提示词、用户提示词、输出格式、示例分割成独立模块使用变量承载动态内容而不是每次用f-string硬拼为每一版prompt打上版本号、变更说明、测试结果沉淀出测试集评分标准让每次修改可以量化评估这里的核心转变是从写prompt变成维护prompt系统。它不再是纯写文案更像是在维护一份配置化的代码工程。1.2 模板的核心要素变量、约束、示例、评分标准如果把提示词模板拆开看一份合格的模板通常要包含四类信息角色与任务你是谁你要完成什么边界在哪里上下文与变量哪些信息是动态传入的如何传入缺失时怎么兜底约束与格式输出格式、长度、风格、禁止事项示例与评分标准给出Few-shot示例以及明确什么样的输出算合格变量设计是最容易出问题的地方。一条经验是动态内容全部走变量静态内容全部写死在模板里。看似废话但实际中很多人会把用户输入直接拼进系统提示词导致糟糕的输入污染人设。举个例子你把用户问题用{user_input}传进去是对的但你绝不能用它来拼你是{user_name}的助手请用{language}回答这类变量——一旦某个变量为空或者包含异常字符整个行为就崩了。我建议在设计变量时给每个变量定义默认值并且明确缺失时怎么办。比如语言变量默认取中文超过长度则截断敏感词则替换。这跟写前端表单校验是同一个思路。示例的摆放也有讲究。Few-shot示例不是越多越好而是要贴近真实的高频场景和困难case。我一般会准备三类示例一个普通场景一个边界场景一个最容易犯错的场景。这三个写进模板里比写十句你要认真负责管用得多。1.3 一个小型模板管理方案这里分享一个轻量级方案不需要额外平台用Git JSON就能跑起来。我习惯把模板目录结构设计成这样prompts/ ├── modules/ │ ├── role.md │ ├── constraints.md │ ├── output_format.md │ └── examples.jsonl ├── agents/ │ ├── customer_service.json │ ├── coding_assistant.json │ └── data_analyst.json └── tests/ ├── cases.jsonl └── evaluator.yaml一个Agent对应的JSON大概长这样{ name: customer_service, version: 3.2.1, role_module: prompts/modules/role.md, constraints_module: prompts/modules/constraints.md, output_format_module: prompts/modules/output_format.md, examples: prompts/modules/examples.jsonl, variables: { user_input: {required: true, max_length: 2000}, language: {default: zh, enum: [zh, en]}, user_name: {required: false, default: 用户} }, temperature: 0.3, top_p: 0.9, max_tokens: 1024 }模块化拆分的最大好处是你可以为不同Agent复用同一套角色设定同时各自覆盖不同的约束。比如客服Agent和投诉处理Agent共享同一个公司背景说明但一个要求语气亲和一个要求先了解诉求再回应。改一处所有引用它的Agent都能同步更新。配合Git我自己的习惯是每次改动都要写清楚的commit message并且在提交前跑一遍测试集。测试集不用很多二十个左右高频case就够了。跑完对比新旧两个版本的评分分数没降就合并降了就单独开来做A/B。这套流程跟代码开发的review流程完全一样只是审查的对象从函数变成了提示词。2. Agent 提示词编排从单一Prompt到多角色协同如果说模板管理解决的是提示词怎么组织那么Agent提示词编排解决的就是一堆提示词怎么协同工作。这是从单次对话走向自主执行的关键一步。一个Agent系统往往包含几十个甚至上百个提示词它们分别承担规划、推理、调用工具、整理结果、反思错误等职责。如何编排这些提示词直接决定了Agent的稳定性、可扩展性和可控性。2.1 Agent与提示词的关系先给个简单的定义Agent 提示词 工具 记忆 执行循环。提示词是Agent的思维底座决定了它怎么理解指令、怎么拆解任务、怎么选择工具。工具是Agent的手脚记忆是Agent的经验簿而执行循环则是一个外层代码框架负责调度每一步该用哪个模块。我在初学Agent时犯过一个大错试图把所有逻辑都塞进一个系统提示词里让模型自己悟。比如让模型自己决定要调用什么工具、记忆怎么组织、输出什么格式结果就是简单任务还行复杂任务经常出现漏步骤、幻觉、反复使用同一个工具空转。后来看了一些开源Agent框架才意识到Agent的稳定边界来自编排而不是来自模型自我约束。提示词里只需要让模型做好当下这一步的决策全局流程控制应该交给代码。这句话怎么理解比如ReAct模式里模型每轮只需要做两件事思考Thought和行动Action。思考用来解释当前状态行动用来选择下一次工具调用。至于整个任务分几步走、什么时候结束应该由外层循环判断而不是靠模型盯着长长的任务清单。框架层面市面上有LangChain、AutoGen、CrewAI等。我不建议死磕某一个框架而是先理解编排范式。框架会迭代范式相对稳定。掌握了范式换框架只是语法层面的切换。2.2 主流编排范式ReAct、Plan-and-Execute、多Agent协作目前我实际用过且认为值得掌握的编排范式主要有三种。ReActReason Act是最基础的也是理解其他范式的前提。它的核心是一个循环让模型先输出思考过程再决定调用什么工具拿到工具结果后继续思考直到它认为任务完成。我常用的是这个提示词模板你是一个任务执行助手。请按以下步骤工作 1. 根据当前状态用Thought描述你的思考过程。 2. 如果需要获取信息或执行操作用Action给出工具名称和参数。 3. 收到工具结果后继续生成Thought和Action直到你可以用Final Answer给出最终答复。 注意不要修改或虚构工具返回的结果。注意这里我不把任务描述写在system prompt里而是放在user message里。因为任务本身是动态的而执行规则是静态的。这样同一个执行器可以复用于不同任务这是模板管理和编排结合的一个典型例子。Plan-and-Execute是ReAct的一种变体专门解决长任务问题。它的思路是先让模型生成一个整体计划然后逐步执行每执行一步就回顾计划做调整。我在做数据分析Agent时就是用了这个模式先让Agent拆解分析步骤再逐步执行SQL查询、绘制图表、生成结论。这样即使某一步出错也只需要重试那一步而不需要整段重来。多Agent协作是目前讨论较多的方向。严格来说多Agent不是多个模型实例对话而是多个带独立职责提示词的工作单元互相协作。协作拓扑通常有三种Supervisor模式有一个管理Agent分配任务给Worker、Pipeline模式上一个Agent的输出作为下一个的输入、Mesh模式所有Agent可以互相通信。我自己的建议是先不要贪Mesh从Supervisor模式上手最稳因为它的控制流最清晰出了问题也好定位。等你的业务确实需要更灵活的拓扑再往下走。2.3 记忆、工具与技能如何进入编排很多初学者会问记忆到底应该放在提示词的哪里这其实是一个容易被误导的问题。按照我实践下来比较顺手的做法记忆是分成三层进入编排流程的短期记忆对话窗口内的上下文直接以消息历史的形式传给模型工作记忆当前任务执行过程中的临时信息放在一个独立的slot里每次循环开始时注入长期记忆跨会话的持久信息按需检索后注入上下文提示词里通常只需要预留三个占位符{chat_history}、{working_memory}、{retrieved_memory}。真正的记忆读写逻辑放在框架代码里。这样做的好处是当你需要更换记忆存储方案时完全不需要改动提示词只在代码层替换检索实现。我最初把记忆格式直接写死在prompt里结果换向量数据库时连带改了好几版prompt非常痛苦。工具描述也是编排的一部分。模型不会天然知道工具长什么样它只能通过提示词里的描述来理解工具能力。所以工具描述本身也是提示词也需要纳入模板管理。我一般会给每个工具写三句话这个工具能做什么、什么时候用它、它的输出长什么样。如果模型在测试里反复不知道该调用哪个工具大概率不是模型笨而是工具描述写得太含糊。Skill技能和Agent的区别也可以用类似方式理解一个技能是一段提示词少量工具逻辑的封装可以被不同的Agent复用Agent则是在此之上加上记忆、规划、执行循环和判定逻辑。编写Agent时我倾向于把可复用的能力沉淀为技能模块把个性化的决策逻辑放进Agent专属提示词。3. 实操一个业务Agent的提示词编排全过程前面讲了不少抽象概念这一节用一个真实场景走一遍完整过程。我选择的是一个客服工单分类与初步答复Agent因为它足够典型需要人设、需要工具调用、需要少量记忆、还需要输出结构化结果几乎覆盖了编排的所有关键点。3.1 场景设定与目标拆分假设我们要做一个客服Agent接收用户提交的工单完成三件事判断工单类型、提取关键实体、生成初步回复建议。注意它不需要直接解决用户问题而是辅助人工客服提高效率。功能确定后先把Agent拆成几个可独立维护的模块工单分类模块输出类别枚举值实体抽取模块输出结构化JSON回复生成模块基于分类和抽取结果生成回复路由模块负责任务顺序控制以及判断是否需要人工介入这四部分如果用单个prompt硬塞模型负担重不说单个分类出错时还难以定位。拆成模块后每个模块都可以单独调优甚至可以替换成不同模型或微调模型。这里用到的还是模板管理的思路模块拆开编排里再合成。3.2 提示词模块的编写分类模块的提示词我不会写得很长核心是给出类别定义和判别规则你是一个工单分类器。请将用户问题分类到以下类别之一 [退款, 物流, 售后维修, 账号安全, 其他] 规则 - 退款用户明确要求退还已支付金额。 - 物流涉及包裹配送、签收、时效、物流信息。 - 售后维修商品破损、质量问题、维修申请。 - 账号安全登录异常、密码找回、账号被盗。 - 无法明确归入以上类别时选择其他。 用户问题 {user_input} 只输出一个类别名不要输出其他文字。写这个模板时我最深的体会是类别定义要比类别名更重要。给类别加解释之后分类准确率提升非常明显因为模型不再靠猜测理解售后维修和退款在语义上其实有重叠需要规则帮忙划界。实体抽取模块则要求输出JSON从用户问题中抽取以下实体 - order_id订单号格式为数字或字母串如果没有则填null - product_name商品名称如果没有则填null - amount涉及金额的数值只填数字如果没有则填null 用户问题 {user_input} 只输出JSON不要输出解释。回复生成模块相对复杂因为它要同时利用前面模块的输出来生成文本。我采用的方法是模板变量拼接基于以下分析结果生成回复 - 工单类型{category} - 相关实体{entities} - 历史对话摘要{conversation_summary} 回复要求 1. 针对工单类型选择对应处理指引。 2. 如果实体缺失说明需要补充哪些信息。 3. 语气专业、简洁不超过3句话。 4. 如果需要人工介入在回复末尾标注[转人工]。这里有个小细节历史对话摘要不是把原始聊天记录全部塞进去而是由框架在外部先做一个摘要提取再传给生成模块。这样既控制了token消耗也避免了聊天记录里的噪音影响回复质量。3.3 参数配置与运行环境每个模块除了提示词还要配置模型参数。我的经验是分类、实体抽取这类判别型任务用低temperature回复生成这类创作型任务可以稍微提高一点。模块参数可以参考下表模块temperaturemax_tokens说明工单分类0.016只要输出一个类别不必要创作空间实体抽取0.0128严格JSON输出随机性越低越好回复生成0.3512需要一定多样性但不能失控路由判定0.032保持确定性决策参数不一定要在代码里写死放在配置文件里可观测性更好。我在编排时还会给每个模块加一个超时和异常兜底比如分类模块超时5秒则默认返回其他实体抽取模块解析JSON失败时会重试一次。这些边界情况在真实业务里会频繁出现不在编排层处理好上线后必然焦头烂额。3.4 测试与调优从单模块到全链路提示词测试要分两层走单模块测试和全链路测试。很多人一上来就跑完整Agent出了问题很难定位是哪一步导致的。我的做法是给每个模块单独写一个包含十来个case的测试文件。比如分类模块测试长这样{user_input: 我要退款商品我不想要了, expected: 退款} {user_input: 快递一直不更新三天了, expected: 物流} {user_input: 密码登录不上怀疑被盗, expected: 账号安全}跑通单模块后再跑全链路测试。全链路测试不仅看最终回复对不对还要检查中间路由分类错了没关系但实体能不能抽出回复有没有用到实体需不需要转人工的标志位是否准确调优时我的优先级顺序是先修路由和格式错误再修分类准确率最后才修回复语气。因为格式错误会导致整个链路崩掉分类错误是用户看得见的硬伤回复语气则是感知层面的优化。按照这个顺序来每个版本的迭代都会有一个明确的优化方向而不是凭感觉反复试。4. 常见问题与排查技巧实录这一节写一些我自己在真实开发中遇到的问题以及对应的排查思路。这些内容比较实用建议直接收藏。4.1 模板管理中的几个坑先说模板管理。第一个坑是模板变量命名不规范。比如{date}这种代码里传了个字符串进去哪天你为了省token传了个昨天整个提示词的含义就变了。我给变量命名加了后缀约束用户输入叫user_input日期格式化叫today_date上下文摘要叫context_summary任何变量命名必须体现它的来源。这是很小的规范但能省去后期排查的很多困惑。第二个坑是没有区分模板内部的结构化和模板之间的引用。有些模板需要内嵌另一个模板的内容如果用字符串拼接模板边界会越来越模糊。我自己的方案是需要复用的段落一律下沉到模块文件里通过变量引用绝不直接在多个模板里复制粘贴同一段文字。第三个坑是忽视模板的空值现象。变量有值很好但很多场景下变量就是空的这时候模板里会出现用户是问题是请回复。我的处理方式是在模板中使用条件渲染比如用{{#if user_name}}用户{{user_name}}{{/if}}的方式让空值时不输出这个句子。这种方式在小型模板里可以用代码预处理在复杂场景下建议引入模板引擎来维护。4.2 Agent编排中的典型错误Agent编排里最常见的错误是指令冲突和循环失控。指令冲突的情境通常出现在多模块组合时。比如系统提示词写了你是客服助手必须友好耐心而回复生成模块又写了只输出简短结论不要寒暄。模型在冲突指令下往往会做出不可预测的选择有时候冷冰冰有时候啰嗦。排查这类问题要建立指令唯一来源原则同一个维度的约束只允许在一个地方出现。友好是角色层的事长度是格式层的事两者不该混在一起。循环失控是ReAct模式里常见的坑。表现为模型陷入思考-调用-再思考-再调用的死循环甚至反复调用同一个工具却拿不到有价值的信息。我能在代码层加两个保险设置最大迭代次数比如8轮以及启用重复检测——如果连续三轮调用同一个工具且参数接近主动终止循环并触发人工介入。这些都是编排代码里的细节但确实能避免很多线上事故。第三个常见问题是记忆污染。所谓记忆污染是指历史对话或者工具返回结果里包含了与当前任务无关甚至有害的信息模型把这些信息当作参考导致输出偏差。我处理的方式是每次注入记忆前先做一次筛选只把与当前目标相关的部分放进retrieved_memory无关内容宁可少传也不要都塞给模型。4.3 问题排查速查表下面这个表是我在调试时会用到的排查清单遇到异常先逐项对照比瞎试快很多。现象可能的根因排查手段分类不准类别定义含糊/重叠检查类别规则补充反例JSON输出频繁解析失败输出格式约束不足在提示词中加入强格式声明并设置重试回调工具调用错误工具描述不清晰重写工具描述明确输入输出示例回复里出现历史任务内容记忆注入没有做筛选检查上下文执行记忆过滤Agent死循环没有循环上界代码层加最大轮数重复检测表现时好时坏temperature过高将关键决策模块temperature降为0新版本突然变差模板修改影响面过大用Git diff对照模板变更回退到上版本再补充一个定位技巧如果你怀疑是提示词问题而不是模型问题把同样的提示词放到不同模型上做对比。如果两个模型表现都差通常是指令本身有歧义如果只有一个模型表现差可能是模型能力边界的问题。这样就能区分是promptbug还是模期望差避免在错误的方向上反复调。最后分享一个我个人的小习惯每次迭代提示词后我都强制自己写一段为什么改、预期效果是什么的备注。这个备注不进入生产环境只写在Git提交信息里。几次回退排查之后你会意识到它有多值钱——它让每一次调优都有了归因而不是依靠玄学。这是我在提示词模板管理和Agent编排这两件事上最有价值的一个实践心得。