1. 提示词模板管理到底在管什么很多人第一次接触 Agent 开发注意力全在模型选型、工具调用、记忆机制上觉得提示词就是一段字符串随手写在代码里就行。等到项目里接了七八个 Agent每个 Agent 又有三四个执行阶段每个阶段都要拼一段提示词这时候你会发现代码里散落着几十段硬编码的字符串改一个措辞要翻五个文件测试环境和生产环境的提示词还不一致排查问题时根本不知道线上跑的是哪个版本。这就是提示词模板管理要解决的核心问题。提示词模板管理本质上是把提示词从代码逻辑中抽离出来变成可独立维护、可版本化、可复用、可动态填充的资产。它包含几个层面的事情模板本身的存储与组织、模板变量的定义与校验、模板的渲染与拼装、模板的版本管理与灰度发布。而 Agent 提示词编排则是在模板管理的基础上进一步解决多个 Agent、多个执行阶段之间提示词如何组合、如何传递上下文、如何控制流程的问题。打个比方模板管理像是管理一整套乐高积木的零件库每个零件有编号、有规格、有存放位置而提示词编排则是按照图纸把这些积木拼成一个完整的模型还要保证拼装顺序正确、接口对得上。没有零件库你每次拼模型都要重新生产积木没有编排你有一堆零件也不知道怎么组装。这套东西适合谁来参考如果你正在从零搭建 AI Agent或者你的 Agent 项目已经过了 demo 阶段、开始出现维护混乱的迹象那这套思路对你直接有用。如果你只是调用一下大模型 API 做简单问答可能暂时用不上但了解模板化的思路对后续扩展也有好处。2. 为什么提示词需要模板化管理2.1 硬编码提示词的三个致命伤我见过不少 Agent 项目初期为了快速验证提示词直接写在 Python 文件里用 f-string 拼接。这种做法在只有一个 Agent、一个场景的时候没问题但一旦规模上去三个问题会同时爆发。第一个问题是修改成本高且容易出错。提示词散落在各个模块中产品经理说“把客服 Agent 的语气改得更亲切一些”你得在代码里搜索所有相关字符串改完还要担心有没有漏掉某处。更麻烦的是有些提示词是拼接出来的你改了片段 A但片段 B 里还有一句类似的话没改最终效果不一致。第二个问题是无法做版本对比和回滚。硬编码的提示词跟着代码走代码提交记录里混着业务逻辑变更和提示词调整你很难单独追踪“这次效果变差是不是因为提示词改了”。想回滚到上一个版本对不起只能把整个代码回滚连带其他功能一起退回去。第三个问题是环境差异无法管理。开发环境用一套提示词方便调试生产环境用另一套更严谨的版本测试环境又要模拟各种边界情况。硬编码的情况下你只能用 if-else 判断环境变量代码里全是分支丑陋且危险。2.2 模板化带来的四个实际收益把提示词模板化之后收益是立竿见影的。第一提示词成为独立资产可以单独评审、单独测试、单独发布不再和代码逻辑耦合。第二变量注入变得可控模板里哪些地方需要动态填充、填充什么类型的数据、有没有默认值全部显式声明渲染时自动校验避免拼出半截提示词。第三复用变得自然一个“角色设定”模板可以被多个 Agent 引用一个“输出格式约束”模板可以挂在所有需要结构化输出的环节上。第四版本管理清晰每次修改生成新版本记录修改人、修改原因、生效时间出问题能快速定位和回滚。我自己的项目里把提示词从代码中抽离之后调整提示词的平均耗时从原来的二三十分钟降到了五分钟以内而且再也没有出现过“改了 A 处漏了 B 处”的情况。2.3 模板管理与编排的关系需要区分清楚模板管理解决的是“单个提示词怎么组织和维护”的问题编排解决的是“多个提示词怎么按顺序和条件组合”的问题。两者是上下游关系。你先要有高质量的、可管理的模板然后才能谈编排。如果模板本身是一团乱麻编排只会让混乱加倍。编排的核心挑战在于Agent 执行过程中上下文是不断累积的每一步的提示词需要包含之前步骤的哪些信息不同 Agent 之间如何传递状态条件分支怎么表达这些都需要在编排层设计好。3. 提示词模板的核心结构设计3.1 一个模板应该包含哪些字段设计模板结构时不要只想着“一段文本加几个占位符”。一个完整的模板定义至少应该包含以下字段字段名类型说明template_idstring模板唯一标识建议用命名空间加名称如customer_service.greetingversionstring语义化版本号如1.2.0contentstring模板正文包含变量占位符variablesarray变量定义列表每个变量有名称、类型、是否必填、默认值、描述metadataobject元信息包括作者、创建时间、标签、适用场景render_enginestring渲染引擎类型如 jinja2、mustache、自定义变量定义这块特别重要。很多人只写占位符不定义变量渲染时传什么就是什么传错了也不报错最后模型收到一段残缺的提示词输出质量下降还找不到原因。显式定义变量之后渲染前可以做类型检查和必填校验把问题拦在前面。3.2 变量占位符的语法选择占位符语法有几种常见选择。Jinja2 风格用{{ variable_name }}功能强大支持条件判断和循环但语法相对复杂而且如果变量值里本身包含{{需要转义处理。Mustache 风格用{{variable_name}}更简洁逻辑能力弱一些。还有用{variable_name}单花括号的简单但容易和正文里的花括号冲突。我的建议是如果模板逻辑简单只是单纯替换变量用 Mustache 风格就够了解析快、不易出错。如果模板里需要根据条件包含不同段落比如“如果有历史对话就插入历史对话摘要否则不插入”那 Jinja2 更合适。但要注意模板里尽量少写复杂逻辑逻辑越复杂模板越难维护也越容易出 bug。复杂逻辑应该放在编排层用代码处理模板保持相对纯粹。3.3 变量类型与校验规则变量不是只有字符串一种类型。实际项目中常见的变量类型包括字符串最常见的类型如用户姓名、问题描述。数字如置信度阈值、最大轮次。布尔值控制是否包含某个段落。列表如历史消息列表、工具列表渲染时需要遍历。对象如用户画像包含多个字段模板里通过点号访问。定义变量时除了类型还要考虑校验规则。比如字符串变量可以限制最大长度防止用户输入超长文本把提示词撑爆数字变量可以限制范围防止传入负数导致逻辑异常列表变量可以限制最大元素个数避免渲染出几千条历史消息。注意变量校验不要只做类型检查还要做业务合理性检查。比如“最大轮次”这个变量类型是数字没错但如果传了 10000虽然类型合法但实际会导致 Agent 无限循环。这类边界要在变量定义里用 min/max 约束住。4. 模板存储与加载的工程实现4.1 存储方案选型对比模板存哪里有几种常见方案各有适用场景方案优点缺点适用场景代码仓库中的文件版本管理天然支持评审方便修改需要发版非技术人员无法操作早期项目模板变动不频繁数据库动态修改支持后台管理需要额外开发管理界面版本管理要自己实现模板频繁调整有运营需求配置中心动态推送环境隔离好引入额外依赖成本较高多环境、多租户场景对象存储容量大成本低读取延迟相对高不适合高频读取模板数量极大冷热分离我自己的做法是开发阶段用代码仓库文件方便版本管理和 code review上线后如果模板调整频繁再迁移到数据库同时保留文件作为初始化和备份手段。不要一上来就搞配置中心过度设计。4.2 模板加载与缓存策略模板加载要考虑性能。如果每次渲染都从数据库或文件读取高频调用时会有明显延迟。合理的做法是加一层内存缓存缓存键用template_id version缓存失效策略有两种一是定时刷新比如每 60 秒重新加载一次二是事件驱动模板更新时主动清除缓存。缓存要注意内存占用。如果模板数量很多、单个模板很大全量缓存可能吃掉几百 MB 内存。这时候可以用 LRU 策略只缓存最近使用的模板。另外缓存要设置上限防止模板 ID 被恶意遍历导致内存溢出。# 一个简单的模板缓存实现示例 import time from collections import OrderedDict class TemplateCache: def __init__(self, max_size500, ttl_seconds60): self.max_size max_size self.ttl ttl_seconds self.cache OrderedDict() def get(self, template_id, version): key f{template_id}:{version} if key in self.cache: value, expire_at self.cache[key] if time.time() expire_at: self.cache.move_to_end(key) return value else: del self.cache[key] return None def set(self, template_id, version, content): key f{template_id}:{version} if len(self.cache) self.max_size: self.cache.popitem(lastFalse) self.cache[key] (content, time.time() self.ttl)4.3 多环境隔离的实现开发、测试、生产环境的模板要隔离但隔离方式有讲究。一种做法是每个环境独立存储互不影响另一种做法是同一份存储用环境标签区分。前者更安全后者更方便同步。我倾向于独立存储加同步工具。生产环境的模板修改必须经过审批流程不能直接改。开发环境可以随意折腾。同步工具负责把开发环境验证过的模板推送到测试环境测试通过后再推送到生产环境。每次推送记录操作日志出了问题能追溯。环境隔离还要注意变量值的差异。比如“知识库地址”这个变量开发环境指向测试知识库生产环境指向正式知识库。这类环境相关的变量值不要写在模板里而是通过环境配置注入模板只引用变量名。5. Agent 提示词编排的核心逻辑5.1 编排要解决的三个问题Agent 执行不是单轮问答而是一个多步骤的过程。以常见的 ReAct 模式为例一个完整的执行循环包括思考当前状态、决定下一步动作、执行动作、观察结果、更新状态然后进入下一轮。每一轮都需要构造提示词而每一轮的提示词内容都不一样。编排要解决的第一个问题是上下文累积与裁剪。随着轮次增加历史信息越来越多不能全部塞进提示词否则会超出模型上下文窗口也会稀释关键信息。需要设计裁剪策略保留最近 N 轮、保留关键决策点、对历史做摘要压缩。第二个问题是阶段切换。Agent 在不同阶段需要不同的提示词。规划阶段需要引导模型拆解任务执行阶段需要引导模型调用工具反思阶段需要引导模型评估结果。编排层要能根据当前状态自动选择合适的模板。第三个问题是多 Agent 协作时的信息传递。一个 Agent 的输出可能是另一个 Agent 的输入传递什么、怎么传递、格式如何约定都需要在编排层定义清楚。5.2 基于状态机的编排模型我比较推荐用状态机来建模 Agent 的提示词编排。每个状态对应一个执行阶段状态之间的转移由条件触发。每个状态绑定一个提示词模板进入状态时渲染模板、调用模型、处理输出、决定下一个状态。状态机的优势在于逻辑清晰、易于调试。你可以画出状态转移图一眼看出 Agent 可能走哪些路径。出问题时查看当前状态和历史状态转移记录很快能定位到是哪一步出了问题。一个简化的状态机定义可能长这样class AgentStateMachine: def __init__(self): self.states { planning: { template: agent.planning.v2, transitions: { has_plan: executing, need_clarification: asking, cannot_plan: failed } }, executing: { template: agent.executing.v3, transitions: { tool_call: observing, task_done: reflecting, error: retrying } }, observing: { template: agent.observing.v1, transitions: { continue: executing, replan: planning } } }每个状态的模板独立管理、独立版本化。修改执行阶段的提示词不影响规划阶段降低了变更风险。5.3 上下文窗口的动态管理上下文管理是编排中最容易出问题的地方。我踩过的坑包括历史消息越积越多导致模型开始“遗忘”早期指令工具返回结果太长把关键信息挤掉多轮对话后模型开始重复之前的内容。解决思路是分层管理上下文。把上下文分成几个区域系统指令区角色设定、核心约束始终保留、任务状态区当前目标、已完成步骤、待办事项动态更新、近期交互区最近几轮对话和工具调用滑动窗口、长期记忆区关键事实和决策按需检索注入。每个区域有独立的容量预算。比如系统指令区最多 500 token任务状态区最多 300 token近期交互区最多 2000 token长期记忆区最多 500 token。渲染提示词时按优先级拼装超出预算时从低优先级区域开始裁剪。提示上下文预算不要卡得太死留 10% 到 20% 的余量。模型输出也需要占用上下文窗口如果输入把窗口占满了输出会被截断表现为模型回答到一半突然停了。6. 模板变量注入的实操细节6.1 变量来源与注入时机模板变量从哪里来常见来源包括用户输入、系统配置、上游 Agent 输出、工具调用结果、记忆检索结果、运行时计算值。不同来源的变量注入时机不同。用户输入和系统配置在渲染前就确定直接注入即可。上游 Agent 输出和工具调用结果在运行时才产生需要在对应步骤完成后注入。记忆检索结果依赖检索触发时机可能在渲染前注入也可能在渲染过程中动态插入。注入时机影响模板设计。如果某个变量在渲染时还不确定模板里就不能直接引用需要用占位符标记后续再替换。或者把模板拆成两段先渲染确定的部分等变量就绪后再渲染剩余部分。6.2 变量转义与安全处理变量值直接拼进提示词有风险。如果变量值里包含特殊字符可能破坏模板结构。比如变量值里出现了}}Mustache 渲染时可能提前结束占位符导致后面的内容被当成正文。更严重的是如果变量值里包含恶意指令可能诱导模型执行非预期操作这就是所谓的提示词注入。处理方式分两层。第一层是语法转义渲染引擎负责把变量值里的特殊字符转义确保不会破坏模板结构。第二层是内容过滤对用户输入的变量值做检查识别并拦截明显的注入尝试比如包含“忽略之前的指令”“你现在是”这类模式。内容过滤不要做得太死否则正常用户输入也会被误拦。我的做法是对高风险变量如用户直接输入的问题描述做严格过滤对低风险变量如系统生成的 ID做基本转义即可。过滤规则可配置方便根据实际效果调整。6.3 默认值与可选变量的处理不是所有变量都必须由外部提供。有些变量有合理默认值外部不传时用默认值。比如“语言”变量默认zh-CN“语气”变量默认professional。这样模板调用方只需要关注必须指定的变量减少使用负担。可选变量的处理要小心。如果模板里引用了可选变量但外部没传渲染时可能报错或渲染出空字符串。空字符串在某些语境下会导致语义偏差比如“请用{{tone}}语气回答”渲染成“请用语气回答”模型可能困惑。更好的做法是可选变量在模板里用条件块包裹有值才渲染对应段落。{% if tone %} 请用{{ tone }}语气回答。 {% endif %}这样没传tone时整句话都不出现不会产生歧义。7. 版本管理与灰度发布7.1 模板版本号的设计模板版本号建议用语义化版本主版本号.次版本号.修订号。主版本号变更表示不兼容的修改比如变量增删、占位符语法调整次版本号变更表示向后兼容的功能增加比如新增可选变量修订号变更表示文字调整、错别字修正等不影响接口的修改。版本号不是给机器看的是给人看的。看到2.0.0就知道这个模板和1.x不兼容升级时要检查调用方。看到1.3.2就知道只是小修小补放心升级。7.2 灰度发布的实现方式新版本模板上线不要一次性全量替换。先让一小部分流量走新版本观察效果。如果指标正常逐步扩大比例如果指标下降立即回滚。灰度发布的实现方式有几种。按用户 ID 哈希分流同一用户始终走同一版本体验一致。按请求比例分流简单直接但同一用户可能一会儿新版本一会儿旧版本。按 Agent 实例分流适合多实例部署的场景。灰度期间要同时保留新旧两个版本渲染时根据分流规则选择版本。监控指标要区分版本统计否则新旧混在一起看不出差异。关键指标包括任务完成率、平均轮次、工具调用成功率、用户满意度如果有反馈渠道。7.3 版本回滚的触发条件什么情况下触发回滚不能等人工发现要设置自动监控。我一般设置这几个触发条件新版本任务完成率比旧版本低超过 5 个百分点新版本平均轮次比旧版本高超过 20%新版本出现特定错误如渲染失败、变量缺失的频率超过阈值。触发回滚后系统自动切回旧版本同时告警通知相关人员。回滚要快最好在分钟级完成。所以模板加载要支持热切换不能依赖重启服务。8. 常见问题与排查技巧实录8.1 模板渲染失败的排查路径渲染失败是最常见的问题表现是提示词拼不出来或者拼出来是残缺的。排查按以下顺序进行检查变量是否齐全对比模板定义的必填变量列表和实际传入的变量看有没有缺失。检查变量类型是否匹配比如模板期望列表实际传了字符串遍历时就会出错。检查占位符语法有没有拼写错误比如{{name}}写成了{name}或{{ name }。检查特殊字符变量值里有没有未转义的特殊字符破坏了模板结构。检查渲染引擎版本不同版本的渲染引擎行为可能有差异确认环境一致。我一般会在渲染失败时输出详细的错误信息包括模板 ID、版本、传入变量、失败位置方便快速定位。8.2 变量注入后效果异常的排查有时候渲染没报错但模型输出质量明显下降。这时候要检查注入的变量值是否合理。常见问题包括变量值太长把关键指令挤到了后面模型注意力分散变量值包含矛盾信息比如系统指令说“简洁回答”但注入的历史消息里全是长篇大论变量值格式不对比如期望 JSON 但传了纯文本模型解析困难。排查方法是把渲染后的完整提示词打印出来人工读一遍。很多时候读一遍就能发现问题。如果提示词太长可以分段检查先看系统指令区再看任务状态区最后看交互区。8.3 多 Agent 协作时的信息丢失问题多 Agent 协作时信息在传递过程中容易丢失。Agent A 的输出传给 Agent BB 可能只关注了自己需要的部分忽略了其他信息导致后续 Agent 缺少上下文。解决思路是定义清晰的信息传递协议。每个 Agent 的输出结构化明确哪些字段是给下游用的。编排层负责在传递时做字段映射和补充确保下游 Agent 拿到完整信息。同时记录信息流转日志出问题时能追溯是哪个环节丢了信息。8.4 常见问题速查表问题现象可能原因排查方法解决方案渲染报错“变量未定义”必填变量未传入检查调用方传参补传变量或设默认值渲染结果为空模板内容为空或版本错误检查模板存储和版本号修正模板内容或版本模型输出格式不对输出格式约束被变量挤掉打印完整提示词检查调整变量长度或约束位置多轮后模型重复历史消息未裁剪检查上下文管理逻辑启用滑动窗口或摘要灰度期间指标波动新旧版本流量混杂检查分流规则和监控修正分流或暂停灰度模板更新后未生效缓存未刷新检查缓存 TTL 和刷新机制手动清缓存或缩短 TTL9. 我踩过的坑与实操心得第一个坑是模板里写太多逻辑。早期为了灵活在模板里写了不少 if-else 和循环结果模板变得极其难读改一处逻辑要反复测试。后来我把复杂逻辑全部移到编排层模板只保留简单的变量替换和少量条件块维护成本大幅下降。第二个坑是变量命名太随意。一开始用a、b、c这种命名过两周自己都忘了是什么意思。后来统一用有意义的命名比如user_query、history_summary、tool_result并且每个变量都写描述情况好很多。第三个坑是忽略上下文预算。有一次上线后发现模型经常回答到一半就停了排查半天才发现是输入太长把输出空间挤没了。后来在编排层加了 token 计数和预算控制问题解决。第四个坑是灰度发布没设自动回滚。有一次新模板上线后效果变差但没人及时发现等用户投诉才处理已经影响了一批请求。后来加了自动监控和回滚类似问题再没出现过。实操心得方面我建议模板修改一定要走评审流程哪怕只是改一个词。因为提示词对模型行为的影响很微妙改一个词可能导致完全不同的输出。评审时最好有测试用例改完后跑一遍回归测试确认关键场景不受影响。另外模板的测试不要只测渲染是否成功还要测渲染结果是否符合预期。可以写断言检查渲染后的提示词是否包含关键指令、是否在合理长度范围内、变量是否正确替换。这些测试用例积累下来就是项目的安全网。最后分享一个小技巧给每个模板加一个“示例渲染结果”字段存一个典型输入下的渲染输出。这样新人接手时不用跑代码就能大致了解模板长什么样、变量怎么填。这个字段在排查问题时也很有用可以快速对比实际渲染结果和预期是否一致。
Agent提示词模板管理与编排：从硬编码到工程化实践
1. 提示词模板管理到底在管什么很多人第一次接触 Agent 开发注意力全在模型选型、工具调用、记忆机制上觉得提示词就是一段字符串随手写在代码里就行。等到项目里接了七八个 Agent每个 Agent 又有三四个执行阶段每个阶段都要拼一段提示词这时候你会发现代码里散落着几十段硬编码的字符串改一个措辞要翻五个文件测试环境和生产环境的提示词还不一致排查问题时根本不知道线上跑的是哪个版本。这就是提示词模板管理要解决的核心问题。提示词模板管理本质上是把提示词从代码逻辑中抽离出来变成可独立维护、可版本化、可复用、可动态填充的资产。它包含几个层面的事情模板本身的存储与组织、模板变量的定义与校验、模板的渲染与拼装、模板的版本管理与灰度发布。而 Agent 提示词编排则是在模板管理的基础上进一步解决多个 Agent、多个执行阶段之间提示词如何组合、如何传递上下文、如何控制流程的问题。打个比方模板管理像是管理一整套乐高积木的零件库每个零件有编号、有规格、有存放位置而提示词编排则是按照图纸把这些积木拼成一个完整的模型还要保证拼装顺序正确、接口对得上。没有零件库你每次拼模型都要重新生产积木没有编排你有一堆零件也不知道怎么组装。这套东西适合谁来参考如果你正在从零搭建 AI Agent或者你的 Agent 项目已经过了 demo 阶段、开始出现维护混乱的迹象那这套思路对你直接有用。如果你只是调用一下大模型 API 做简单问答可能暂时用不上但了解模板化的思路对后续扩展也有好处。2. 为什么提示词需要模板化管理2.1 硬编码提示词的三个致命伤我见过不少 Agent 项目初期为了快速验证提示词直接写在 Python 文件里用 f-string 拼接。这种做法在只有一个 Agent、一个场景的时候没问题但一旦规模上去三个问题会同时爆发。第一个问题是修改成本高且容易出错。提示词散落在各个模块中产品经理说“把客服 Agent 的语气改得更亲切一些”你得在代码里搜索所有相关字符串改完还要担心有没有漏掉某处。更麻烦的是有些提示词是拼接出来的你改了片段 A但片段 B 里还有一句类似的话没改最终效果不一致。第二个问题是无法做版本对比和回滚。硬编码的提示词跟着代码走代码提交记录里混着业务逻辑变更和提示词调整你很难单独追踪“这次效果变差是不是因为提示词改了”。想回滚到上一个版本对不起只能把整个代码回滚连带其他功能一起退回去。第三个问题是环境差异无法管理。开发环境用一套提示词方便调试生产环境用另一套更严谨的版本测试环境又要模拟各种边界情况。硬编码的情况下你只能用 if-else 判断环境变量代码里全是分支丑陋且危险。2.2 模板化带来的四个实际收益把提示词模板化之后收益是立竿见影的。第一提示词成为独立资产可以单独评审、单独测试、单独发布不再和代码逻辑耦合。第二变量注入变得可控模板里哪些地方需要动态填充、填充什么类型的数据、有没有默认值全部显式声明渲染时自动校验避免拼出半截提示词。第三复用变得自然一个“角色设定”模板可以被多个 Agent 引用一个“输出格式约束”模板可以挂在所有需要结构化输出的环节上。第四版本管理清晰每次修改生成新版本记录修改人、修改原因、生效时间出问题能快速定位和回滚。我自己的项目里把提示词从代码中抽离之后调整提示词的平均耗时从原来的二三十分钟降到了五分钟以内而且再也没有出现过“改了 A 处漏了 B 处”的情况。2.3 模板管理与编排的关系需要区分清楚模板管理解决的是“单个提示词怎么组织和维护”的问题编排解决的是“多个提示词怎么按顺序和条件组合”的问题。两者是上下游关系。你先要有高质量的、可管理的模板然后才能谈编排。如果模板本身是一团乱麻编排只会让混乱加倍。编排的核心挑战在于Agent 执行过程中上下文是不断累积的每一步的提示词需要包含之前步骤的哪些信息不同 Agent 之间如何传递状态条件分支怎么表达这些都需要在编排层设计好。3. 提示词模板的核心结构设计3.1 一个模板应该包含哪些字段设计模板结构时不要只想着“一段文本加几个占位符”。一个完整的模板定义至少应该包含以下字段字段名类型说明template_idstring模板唯一标识建议用命名空间加名称如customer_service.greetingversionstring语义化版本号如1.2.0contentstring模板正文包含变量占位符variablesarray变量定义列表每个变量有名称、类型、是否必填、默认值、描述metadataobject元信息包括作者、创建时间、标签、适用场景render_enginestring渲染引擎类型如 jinja2、mustache、自定义变量定义这块特别重要。很多人只写占位符不定义变量渲染时传什么就是什么传错了也不报错最后模型收到一段残缺的提示词输出质量下降还找不到原因。显式定义变量之后渲染前可以做类型检查和必填校验把问题拦在前面。3.2 变量占位符的语法选择占位符语法有几种常见选择。Jinja2 风格用{{ variable_name }}功能强大支持条件判断和循环但语法相对复杂而且如果变量值里本身包含{{需要转义处理。Mustache 风格用{{variable_name}}更简洁逻辑能力弱一些。还有用{variable_name}单花括号的简单但容易和正文里的花括号冲突。我的建议是如果模板逻辑简单只是单纯替换变量用 Mustache 风格就够了解析快、不易出错。如果模板里需要根据条件包含不同段落比如“如果有历史对话就插入历史对话摘要否则不插入”那 Jinja2 更合适。但要注意模板里尽量少写复杂逻辑逻辑越复杂模板越难维护也越容易出 bug。复杂逻辑应该放在编排层用代码处理模板保持相对纯粹。3.3 变量类型与校验规则变量不是只有字符串一种类型。实际项目中常见的变量类型包括字符串最常见的类型如用户姓名、问题描述。数字如置信度阈值、最大轮次。布尔值控制是否包含某个段落。列表如历史消息列表、工具列表渲染时需要遍历。对象如用户画像包含多个字段模板里通过点号访问。定义变量时除了类型还要考虑校验规则。比如字符串变量可以限制最大长度防止用户输入超长文本把提示词撑爆数字变量可以限制范围防止传入负数导致逻辑异常列表变量可以限制最大元素个数避免渲染出几千条历史消息。注意变量校验不要只做类型检查还要做业务合理性检查。比如“最大轮次”这个变量类型是数字没错但如果传了 10000虽然类型合法但实际会导致 Agent 无限循环。这类边界要在变量定义里用 min/max 约束住。4. 模板存储与加载的工程实现4.1 存储方案选型对比模板存哪里有几种常见方案各有适用场景方案优点缺点适用场景代码仓库中的文件版本管理天然支持评审方便修改需要发版非技术人员无法操作早期项目模板变动不频繁数据库动态修改支持后台管理需要额外开发管理界面版本管理要自己实现模板频繁调整有运营需求配置中心动态推送环境隔离好引入额外依赖成本较高多环境、多租户场景对象存储容量大成本低读取延迟相对高不适合高频读取模板数量极大冷热分离我自己的做法是开发阶段用代码仓库文件方便版本管理和 code review上线后如果模板调整频繁再迁移到数据库同时保留文件作为初始化和备份手段。不要一上来就搞配置中心过度设计。4.2 模板加载与缓存策略模板加载要考虑性能。如果每次渲染都从数据库或文件读取高频调用时会有明显延迟。合理的做法是加一层内存缓存缓存键用template_id version缓存失效策略有两种一是定时刷新比如每 60 秒重新加载一次二是事件驱动模板更新时主动清除缓存。缓存要注意内存占用。如果模板数量很多、单个模板很大全量缓存可能吃掉几百 MB 内存。这时候可以用 LRU 策略只缓存最近使用的模板。另外缓存要设置上限防止模板 ID 被恶意遍历导致内存溢出。# 一个简单的模板缓存实现示例 import time from collections import OrderedDict class TemplateCache: def __init__(self, max_size500, ttl_seconds60): self.max_size max_size self.ttl ttl_seconds self.cache OrderedDict() def get(self, template_id, version): key f{template_id}:{version} if key in self.cache: value, expire_at self.cache[key] if time.time() expire_at: self.cache.move_to_end(key) return value else: del self.cache[key] return None def set(self, template_id, version, content): key f{template_id}:{version} if len(self.cache) self.max_size: self.cache.popitem(lastFalse) self.cache[key] (content, time.time() self.ttl)4.3 多环境隔离的实现开发、测试、生产环境的模板要隔离但隔离方式有讲究。一种做法是每个环境独立存储互不影响另一种做法是同一份存储用环境标签区分。前者更安全后者更方便同步。我倾向于独立存储加同步工具。生产环境的模板修改必须经过审批流程不能直接改。开发环境可以随意折腾。同步工具负责把开发环境验证过的模板推送到测试环境测试通过后再推送到生产环境。每次推送记录操作日志出了问题能追溯。环境隔离还要注意变量值的差异。比如“知识库地址”这个变量开发环境指向测试知识库生产环境指向正式知识库。这类环境相关的变量值不要写在模板里而是通过环境配置注入模板只引用变量名。5. Agent 提示词编排的核心逻辑5.1 编排要解决的三个问题Agent 执行不是单轮问答而是一个多步骤的过程。以常见的 ReAct 模式为例一个完整的执行循环包括思考当前状态、决定下一步动作、执行动作、观察结果、更新状态然后进入下一轮。每一轮都需要构造提示词而每一轮的提示词内容都不一样。编排要解决的第一个问题是上下文累积与裁剪。随着轮次增加历史信息越来越多不能全部塞进提示词否则会超出模型上下文窗口也会稀释关键信息。需要设计裁剪策略保留最近 N 轮、保留关键决策点、对历史做摘要压缩。第二个问题是阶段切换。Agent 在不同阶段需要不同的提示词。规划阶段需要引导模型拆解任务执行阶段需要引导模型调用工具反思阶段需要引导模型评估结果。编排层要能根据当前状态自动选择合适的模板。第三个问题是多 Agent 协作时的信息传递。一个 Agent 的输出可能是另一个 Agent 的输入传递什么、怎么传递、格式如何约定都需要在编排层定义清楚。5.2 基于状态机的编排模型我比较推荐用状态机来建模 Agent 的提示词编排。每个状态对应一个执行阶段状态之间的转移由条件触发。每个状态绑定一个提示词模板进入状态时渲染模板、调用模型、处理输出、决定下一个状态。状态机的优势在于逻辑清晰、易于调试。你可以画出状态转移图一眼看出 Agent 可能走哪些路径。出问题时查看当前状态和历史状态转移记录很快能定位到是哪一步出了问题。一个简化的状态机定义可能长这样class AgentStateMachine: def __init__(self): self.states { planning: { template: agent.planning.v2, transitions: { has_plan: executing, need_clarification: asking, cannot_plan: failed } }, executing: { template: agent.executing.v3, transitions: { tool_call: observing, task_done: reflecting, error: retrying } }, observing: { template: agent.observing.v1, transitions: { continue: executing, replan: planning } } }每个状态的模板独立管理、独立版本化。修改执行阶段的提示词不影响规划阶段降低了变更风险。5.3 上下文窗口的动态管理上下文管理是编排中最容易出问题的地方。我踩过的坑包括历史消息越积越多导致模型开始“遗忘”早期指令工具返回结果太长把关键信息挤掉多轮对话后模型开始重复之前的内容。解决思路是分层管理上下文。把上下文分成几个区域系统指令区角色设定、核心约束始终保留、任务状态区当前目标、已完成步骤、待办事项动态更新、近期交互区最近几轮对话和工具调用滑动窗口、长期记忆区关键事实和决策按需检索注入。每个区域有独立的容量预算。比如系统指令区最多 500 token任务状态区最多 300 token近期交互区最多 2000 token长期记忆区最多 500 token。渲染提示词时按优先级拼装超出预算时从低优先级区域开始裁剪。提示上下文预算不要卡得太死留 10% 到 20% 的余量。模型输出也需要占用上下文窗口如果输入把窗口占满了输出会被截断表现为模型回答到一半突然停了。6. 模板变量注入的实操细节6.1 变量来源与注入时机模板变量从哪里来常见来源包括用户输入、系统配置、上游 Agent 输出、工具调用结果、记忆检索结果、运行时计算值。不同来源的变量注入时机不同。用户输入和系统配置在渲染前就确定直接注入即可。上游 Agent 输出和工具调用结果在运行时才产生需要在对应步骤完成后注入。记忆检索结果依赖检索触发时机可能在渲染前注入也可能在渲染过程中动态插入。注入时机影响模板设计。如果某个变量在渲染时还不确定模板里就不能直接引用需要用占位符标记后续再替换。或者把模板拆成两段先渲染确定的部分等变量就绪后再渲染剩余部分。6.2 变量转义与安全处理变量值直接拼进提示词有风险。如果变量值里包含特殊字符可能破坏模板结构。比如变量值里出现了}}Mustache 渲染时可能提前结束占位符导致后面的内容被当成正文。更严重的是如果变量值里包含恶意指令可能诱导模型执行非预期操作这就是所谓的提示词注入。处理方式分两层。第一层是语法转义渲染引擎负责把变量值里的特殊字符转义确保不会破坏模板结构。第二层是内容过滤对用户输入的变量值做检查识别并拦截明显的注入尝试比如包含“忽略之前的指令”“你现在是”这类模式。内容过滤不要做得太死否则正常用户输入也会被误拦。我的做法是对高风险变量如用户直接输入的问题描述做严格过滤对低风险变量如系统生成的 ID做基本转义即可。过滤规则可配置方便根据实际效果调整。6.3 默认值与可选变量的处理不是所有变量都必须由外部提供。有些变量有合理默认值外部不传时用默认值。比如“语言”变量默认zh-CN“语气”变量默认professional。这样模板调用方只需要关注必须指定的变量减少使用负担。可选变量的处理要小心。如果模板里引用了可选变量但外部没传渲染时可能报错或渲染出空字符串。空字符串在某些语境下会导致语义偏差比如“请用{{tone}}语气回答”渲染成“请用语气回答”模型可能困惑。更好的做法是可选变量在模板里用条件块包裹有值才渲染对应段落。{% if tone %} 请用{{ tone }}语气回答。 {% endif %}这样没传tone时整句话都不出现不会产生歧义。7. 版本管理与灰度发布7.1 模板版本号的设计模板版本号建议用语义化版本主版本号.次版本号.修订号。主版本号变更表示不兼容的修改比如变量增删、占位符语法调整次版本号变更表示向后兼容的功能增加比如新增可选变量修订号变更表示文字调整、错别字修正等不影响接口的修改。版本号不是给机器看的是给人看的。看到2.0.0就知道这个模板和1.x不兼容升级时要检查调用方。看到1.3.2就知道只是小修小补放心升级。7.2 灰度发布的实现方式新版本模板上线不要一次性全量替换。先让一小部分流量走新版本观察效果。如果指标正常逐步扩大比例如果指标下降立即回滚。灰度发布的实现方式有几种。按用户 ID 哈希分流同一用户始终走同一版本体验一致。按请求比例分流简单直接但同一用户可能一会儿新版本一会儿旧版本。按 Agent 实例分流适合多实例部署的场景。灰度期间要同时保留新旧两个版本渲染时根据分流规则选择版本。监控指标要区分版本统计否则新旧混在一起看不出差异。关键指标包括任务完成率、平均轮次、工具调用成功率、用户满意度如果有反馈渠道。7.3 版本回滚的触发条件什么情况下触发回滚不能等人工发现要设置自动监控。我一般设置这几个触发条件新版本任务完成率比旧版本低超过 5 个百分点新版本平均轮次比旧版本高超过 20%新版本出现特定错误如渲染失败、变量缺失的频率超过阈值。触发回滚后系统自动切回旧版本同时告警通知相关人员。回滚要快最好在分钟级完成。所以模板加载要支持热切换不能依赖重启服务。8. 常见问题与排查技巧实录8.1 模板渲染失败的排查路径渲染失败是最常见的问题表现是提示词拼不出来或者拼出来是残缺的。排查按以下顺序进行检查变量是否齐全对比模板定义的必填变量列表和实际传入的变量看有没有缺失。检查变量类型是否匹配比如模板期望列表实际传了字符串遍历时就会出错。检查占位符语法有没有拼写错误比如{{name}}写成了{name}或{{ name }。检查特殊字符变量值里有没有未转义的特殊字符破坏了模板结构。检查渲染引擎版本不同版本的渲染引擎行为可能有差异确认环境一致。我一般会在渲染失败时输出详细的错误信息包括模板 ID、版本、传入变量、失败位置方便快速定位。8.2 变量注入后效果异常的排查有时候渲染没报错但模型输出质量明显下降。这时候要检查注入的变量值是否合理。常见问题包括变量值太长把关键指令挤到了后面模型注意力分散变量值包含矛盾信息比如系统指令说“简洁回答”但注入的历史消息里全是长篇大论变量值格式不对比如期望 JSON 但传了纯文本模型解析困难。排查方法是把渲染后的完整提示词打印出来人工读一遍。很多时候读一遍就能发现问题。如果提示词太长可以分段检查先看系统指令区再看任务状态区最后看交互区。8.3 多 Agent 协作时的信息丢失问题多 Agent 协作时信息在传递过程中容易丢失。Agent A 的输出传给 Agent BB 可能只关注了自己需要的部分忽略了其他信息导致后续 Agent 缺少上下文。解决思路是定义清晰的信息传递协议。每个 Agent 的输出结构化明确哪些字段是给下游用的。编排层负责在传递时做字段映射和补充确保下游 Agent 拿到完整信息。同时记录信息流转日志出问题时能追溯是哪个环节丢了信息。8.4 常见问题速查表问题现象可能原因排查方法解决方案渲染报错“变量未定义”必填变量未传入检查调用方传参补传变量或设默认值渲染结果为空模板内容为空或版本错误检查模板存储和版本号修正模板内容或版本模型输出格式不对输出格式约束被变量挤掉打印完整提示词检查调整变量长度或约束位置多轮后模型重复历史消息未裁剪检查上下文管理逻辑启用滑动窗口或摘要灰度期间指标波动新旧版本流量混杂检查分流规则和监控修正分流或暂停灰度模板更新后未生效缓存未刷新检查缓存 TTL 和刷新机制手动清缓存或缩短 TTL9. 我踩过的坑与实操心得第一个坑是模板里写太多逻辑。早期为了灵活在模板里写了不少 if-else 和循环结果模板变得极其难读改一处逻辑要反复测试。后来我把复杂逻辑全部移到编排层模板只保留简单的变量替换和少量条件块维护成本大幅下降。第二个坑是变量命名太随意。一开始用a、b、c这种命名过两周自己都忘了是什么意思。后来统一用有意义的命名比如user_query、history_summary、tool_result并且每个变量都写描述情况好很多。第三个坑是忽略上下文预算。有一次上线后发现模型经常回答到一半就停了排查半天才发现是输入太长把输出空间挤没了。后来在编排层加了 token 计数和预算控制问题解决。第四个坑是灰度发布没设自动回滚。有一次新模板上线后效果变差但没人及时发现等用户投诉才处理已经影响了一批请求。后来加了自动监控和回滚类似问题再没出现过。实操心得方面我建议模板修改一定要走评审流程哪怕只是改一个词。因为提示词对模型行为的影响很微妙改一个词可能导致完全不同的输出。评审时最好有测试用例改完后跑一遍回归测试确认关键场景不受影响。另外模板的测试不要只测渲染是否成功还要测渲染结果是否符合预期。可以写断言检查渲染后的提示词是否包含关键指令、是否在合理长度范围内、变量是否正确替换。这些测试用例积累下来就是项目的安全网。最后分享一个小技巧给每个模板加一个“示例渲染结果”字段存一个典型输入下的渲染输出。这样新人接手时不用跑代码就能大致了解模板长什么样、变量怎么填。这个字段在排查问题时也很有用可以快速对比实际渲染结果和预期是否一致。
