Agent项目的复杂度往往不是死在模型能力上而是死在提示词的管理上。我做过几个从0到1的Agent项目早期觉得“提示词不就是写一段话嘛”后来发现当Agent开始调用工具、多轮对话、多个角色协作的时候提示词已经不是一段文案而是一套需要版本管理、变量注入、动态编排的工程资产。这套东西做不好Agent的表现会越来越不稳定——今天能回答明天答非所问换一个场景就崩。这篇内容背景是我在企业级Agent平台建设中的实战复盘核心围绕两件事提示词模板管理和Agent提示词编排。适合正在搭Agent的开发者、提示词工程师以及准备把Agent从demo推向生产环境的团队参考。1. 先想清楚提示词为什么会从“一条文案”变成“一套工程”1.1 单体Prompt的极限在哪里单体Prompt就是一段话到底把角色设定、任务说明、背景资料、输出格式全塞进几万字符里。demo阶段这么干完全没问题甚至显得很省事。但一旦进入真实业务你会撞到四个墙。第一个墙是复用墙。同样的工具说明、同样的数据字典、同样的安全约束在不同场景里反复复制粘贴改一处漏一处。第二个墙是测不准。你改了一个中段的小约束不知道影响的是前面的角色一致还是后面的输出格式因为整段都是“锅里的粥”没有分层。第三个墙是上下文的隐性膨胀。为了保险把能想到的都写进去结果重要指令被淹没在大量背景文字里模型的注意力被稀释关键行为反而失灵。第四个墙是热更新困难。线上跑得好好的Agent你想微调一下语气或安全策略必须重新生成整条提示词再走发布风险无限放大。我在一个Agent项目里真正下决心重构是因为一次严重的线上事故为了修复一个工具误调用问题我在单体Prompt末尾追加了一条“不要乱调用工具”的说明结果系统在后续三天开始拒绝调用所有工具业务方直接炸了。问题不是出在模型身上而是出在我的提示词没有结构追加约束和原始指令产生了冲突。1.2 Agent场景给提示词带来的四个新变量单体Prompt时代我们把人当唯一读者但Agent场景下提示词的读者有两个模型和Agent执行框架本身。执行框架需要从提示词中解析出“工具调用边界”“终止条件”“状态说明”这要求提示词具有机器可读的稳定性。我总结了Agent提示词相对普通Prompt的四个新变量。一是动态性。Agent在运行中会不断产生中间结果、工具返回值、环境状态这些信息必须通过模板变量实时注入而不是静态写死。二是组合性。一个Agent往往由多段提示词构成主System、工具描述、反思提示、收尾提示它们需要按执行阶段排列组合。三是可观测性。Prompt背后需要有trace机制否则出了问题你根本不知道是哪段提示词在哪个环节产生了错误行为。四是记忆管理。Agent的记忆不是日志而是要在提示词中以“保留摘要截断历史恢复要点”的形式组织否则上下文窗口会被撑爆。吴恩达的Agent教程里反复强调一个观点Agent不是模型能力变了而是用结构化流程释放模型能力。提示词编排就是结构化流程中最重要的那根骨架。很多人热衷于研究Agent框架选型、工具生态却对提示词这个最上游的变量不重视这在我看来是本末倒置。1.3 怎么判断自己该上“模板管理”了不需要等到出了事故才动手。我建议用三条标准自测。第一条你的Agent里有多少条提示词是重复出现的比如多个Agent都要用到“数据脱敏规则”或“品牌语气规范”如果超过三处就应该抽出来做成模板。第二条你的提示词多久改一次业务上几乎每周都会调整产品话术、策略约束如果你每次都是全量改说明管理方式已经跟不上节奏。第三条你的Agent是不是多角色协作一旦涉及主Agent、子Agent、工具Agent这种嵌套结构每段的职责必须清晰切分否则你无法定位是哪段提示词在“带节奏”。我见过最夸张的案例是一个团队把整套Agent的System Prompt放在一个Java常量类里靠手动注释管理版本某次合并代码时把两条互相矛盾的指令拼到了一起上线后Agent开始自问自答。这不是个例是单体Prompt在规模化路上的必然结局。2. 提示词模板管理把提示词当成代码一样去维护2.1 模板的最小结构不只是一段字符串很多人理解的模板管理就是用变量替换文本。真正可用的是结构化的模板单元。我习惯把一个提示词模板定义为四个部分元信息、变量声明、正文模板、评测用例。元信息包含模板ID、名称、版本号、适用场景、负责人。变量声明要把模板中所有占位符集中列出标明类型、必填性、默认值、来源。正文模板就是真正的提示词内容里面用特定语法标记变量位置。评测用例是模板的“单元测试”每个模板至少要有三组输入输出样例用于验证渲染结果和实际效果。这个结构看起来简单但给工程带来的收益很大。首先修改模板时可以快速判断影响面其次变量注入产生的错误可以迅速定位是数据问题还是模板问题最关键的是提示词模板终于可以被纳入正常研发流程评审、测试、上线都有据可查。具体到实现我常用JSON Schema描述模板。以下是一个简化示例{ template_id: agent_core_system, version: 2.3.0, scenario: generic_agent_system_prompt, variables: [ {name: role_profile, type: string, required: true, source: config}, {name: tool_descriptions, type: string, required: true, source: tool_registry}, {name: safety_rules, type: array, required: false, default: []} ], content_template: 你是{role_profile}。你有以下工具可用\n{tool_descriptions}\n安全规则{safety_rules}, test_cases: [ {input: {...}, expected_output_contains: [你有以下工具可用]} ] }2.2 变量注入的三个坑格式、长度、缺省变量注入是模板管理最不起眼却最容易出问题的地方。我踩过的坑按出现频率排序如下。第一个是格式丢失。模板变量内部如果有换行、列表、表格注入到字符串后可能破坏原有的Markdown结构导致模型解析混乱。解决方法是在变量声明里明确“这个是列表格式的”渲染时用统一的列表序列化器避免变量自己带着不规整的换行符。第二个是长度失控。工具描述动辄几千字安全策略几千字角色设定又几千字全部注入后System Prompt轻松突破两万字符。结果模型虽然能塞下但执行质量急剧下降。我后来强制要求每个模板单元在渲染后统计字符数超过预算直接报警。第三个是缺省不兜底。有些变量在特定场景没有值比如一个Agent不需要工具但模板里引用了tool_descriptions。如果渲染时只做“空字符串替换”模型会认为工具列表为空逻辑没问题但如果你忘了替换模板里就会残留一个{tool_descriptions}原文。这个非常隐蔽因为模型有时候能自己脑补有时候不能。我的建议是渲染时对所有未匹配变量做统一哨兵标记并强制走测试用例校验。2.3 版本管理与回归提示词也需要CI提示词模板一旦可以独立版本化就要引入回归机制。我见过太多团队某个模板改了以后一类Agent行为变了但没人知道是哪个变更引起的。我的做法是给每条模板的每个版本建立一个“行为快照”。“行为快照”不是看文本Diff而是看这个模板对一组固定输入的行为输出。具体来说就是准备一批标准测试问题分别在模板V1和V2下跑同一套Agent跑完记录输出关键指标是否调用正确工具、回答是否包含禁用词、格式是否合规等。然后对比Diff。这套机制跑起来以后你会发现提示词维护从“玄学”变成了“可回归的工程”。有一次我把安全规则从数组格式改成自然语言段落文本上看起来更通顺了但行为快照显示模型开始在输出里泄露系统提示词。因为自然语言段落让模型把规则当成了“对话内容”而不是“系统约束”。这就是回归测试的价值——它帮你抓住那些文本层面看不出来的行为差。版本管理上我建议直接复用Git的已有习惯。每个模板是一个目录命名规则为模板名/版本号/版本号用语义化版本。线上始终引用固定版本号而不是引用分支或latest。等到业务稳定后再通过发布流程统一推进版本。2.4 落地形态从目录到Prompt仓库模板管理的最终形态是形成一个公司级的“提示词仓库”。这个仓库里三类东西一定要有基础原子模板、业务组合模板、Agent编排清单。基础原子模板只干一件最小的事。比如“脱敏规则提示词”“代码生成风格提示词”“翻译语气提示词”它们是积木块。业务组合模板则把这些积木按业务场景拼起来比如“电商客服Agent的系统提示词”“数据分析Agent的系统提示词”。它们的区别在于基础原子模板不关心业务组合模板关心。Agent编排清单则是把多个模板按Agent的执行流程串起来第一阶段用启动模板第二阶段用工具选择模板第三阶段用反思模板。这个清单本身就是一份Agent提示词编排的设计文档。我记得MCP生态火起来以后很多人把注意力放在工具接入上觉得工具多了Agent就强了。但工具再强提示词没有给模型建立选择工具的依据和边界工具越多Agent反而越容易乱。提示词仓库的作用就是在工具能力和模型行为之间画一条清晰的线。3. Agent提示词编排让多段Prompt按决策逻辑协同3.1 编排的本质是“谁在什么条件下说什么话”Agent提示词编排不是把模板简单拼到一起而是为Agent的每个执行阶段准备对应的提示词并明确触发条件和切换逻辑。我还原一下实际执行链路。主Agent启动时读取System Prompt确定角色和能力边界当需要外部信息时生成工具调用请求工具描述在此刻决策中起关键作用工具返回后Agent进入解释与整合阶段此时需要把中间结果拼回上下文如果发现答案不理想会触发反思或纠正阶段。每一段的提示词都不一样不能让一段System Prompt从头管到尾。说得直白一些编排就是定义“谁在什么条件下说什么话”。System Prompt说“你是一个数据分析师”这是一层工具描述说“你可以调用SQL查询工具”这是第二层反思模板说“如果查询结果为空请检查是否存在数据库连接问题”这是第三层。缺了任何一层Agent的行为都不完整。我见过不少新手在做Agent时把工具调用失败的兜底逻辑写在System Prompt里结果模型在正常场景下也会变得谨慎动不动就拒绝执行。这就是没做阶段划分把后阶段的反思约束前移到了启动阶段干扰了主决策。3.2 四类核心提示词System、Tool、Reflection、Transition我按照Agent执行阶段把编排中的提示词分成四类。每类在模板仓库里都是独立的可复用单元。第一类是System Prompt负责角色、目标、边界、输出偏好。它的原则是稳定和抽象尽量把业务细节留在运行时注入。第二类是Tool Prompt负责每个工具的功能说明、输入输出规范、使用约束。Tool Prompt不需要在System Prompt里全量出现而应该在工具被选中时动态拼装。这也是当前Agent框架较常用的做法工具注册表返回描述提示词编排器按需加载。第三类是Reflection Prompt负责自我检查和纠错。典型内容如“检查你的上一步输出是否符合格式要求”“如果与预期不符说明原因并重新作答”。这类提示词是很多Agent项目缺失的却往往是最能提升最终效果的部分。第四类是Transition Prompt负责阶段之间的衔接比如“工具已返回结果请基于结果回答用户问题”“请判断当前是否所有信息已获取完毕若需要更多信息则继续调用工具”。这四类的比例和内容决定了一个Agent的“性格”。有的Agent总是显得啰嗦是因为Transition Prompt写得模糊模型不知道该结束还是该追问。有的Agent总爱自作主张是因为Reflection Prompt缺失模型没有自我约束环节。3.3 上下文窗口预算提示词也要算着花Agent开发中上下文窗口是硬成本。很多模型支持128K甚至更长上下文但这不意味着你可以放任自流。上下文越长模型对中段指令的遵循度越差推理延迟越高成本也越高。我在每个Agent的编排配置里都会明确各部分的上下文预算。通常System Prompt控制在3000字符以内占比2%左右工具描述按需加载总量控制在8000字符左右历史对话保留最近N轮并做摘要压缩每轮工具返回结果控制在3000字符以内过长就会被截断或摘要。至于记忆我的做法是在进程中使用“工作记忆”也就是把Agent执行过程中的关键状态已获取信息、待确认项、已用工具在提示词中以结构化字段实时维护。这与“长期记忆”不同工作记忆是当前任务上下文的一部分。实践中我发现把工作记忆从历史对话中单独划出来注入到System Prompt的尾部模型的稳定性和健忘率都会明显改善。3.4 多Agent协作时的提示词边界多Agent协作比单Agent更考验编排能力因为每个Agent都有自己的System Prompt而它们之间的协作方式也必须用提示词说清楚。我在一个客服数据分析的组合Agent项目里设计了三个Agent前台客服Agent、后台查询Agent、质检Agent。前台Agent负责对话后台Agent负责SQL查询质检Agent负责审核输出。它们的System Prompt各自独立但必须互相知道对方的存在和边界。前台客服Agent的System Prompt里有一句话“如果你需要数据分析支持请调用后台分析Agent等待其返回后你再回答用户。你不需要解释你的分析过程。”后台分析Agent的System Prompt里有另一句话“你只回答结构化数据结论不负责向用户解释。你的输出会由前台客服Agent整合。”质检Agent则说“你只检查语气、合规性和信息真实性不修改内容只输出通过或拒绝。”这三段提示词拼在一起就是一个简单的多Agent协作协议。协议不复杂但如果没有明确边界三个Agent之间就会出现严重的信息泄露和职责混乱。我最常见的问题是后台Agent开始扮演客服和用户对话前台Agent开始编造查询结果。这些问题的根源都在提示词边界模糊。3.5 一个可直接复用的编排蓝图如果你准备从零搭一个单Agent项目我建议直接用下面这个编排蓝图它是我在多轮改版后沉淀下来的通用形态。首先是启动段包含System Prompt 全局工作记忆结构。System Prompt定义角色和边界工作记忆定义状态字段信息收集进度、工具使用历史、待确认问题列表。其次是工具决策段由模型在需要外部信息时触发工具描述通过工具注册表动态加载。再次是结果处理段工具返回后模型依据Transition Prompt判断是否继续调用工具还是进入回答阶段。最后是反思段当模型准备输出最终答案前先过一次Reflection Prompt检查格式和合规。整个流程用一段伪代码表达大概是这样def run_agent(user_input): messages load_system_prompt_with_memory(agent_id, working_memory) messages.append({role: user, content: user_input}) while True: response chat_model(messages) if response.needs_tool_call(): tool_desc load_tool_description(response.tool_name) messages.append({role: assistant, content: format_tool_request(response)}) messages.append({role: tool, name: response.tool_name, content: execute_tool(response.tool_name, response.arguments)}) continue if response.should_reflect(): reflect_prompt render_template(reflection_template, {answer: response.content}) reflection chat_model(reflect_prompt) if reflection.is_bad(): messages.append({role: user, content: 请根据以下修正建议重新回答 reflection.suggestions}) continue return response.content这个蓝图的核心要点是每一轮循环都有明确的提示词入口不会出现“一段提示词管全程”的情况。实测下来这种结构在可调试性和行为稳定性上都比单体Prompt高一个档次。4. 实操记录用Python搭建一个轻量提示词模板管理与编排示例4.1 目录结构与加载层实现我跑过很多项目最终的模板仓库目录结构基本稳定为prompt_repo/ ├── atomic/ # 基础原子模板 │ ├── safety_rules.yaml │ ├── tool_usage.md │ └── output_format.md ├── composite/ # 业务组合模板 │ ├── customer_service.yaml │ └── data_analyst.yaml ├── agents/ # Agent编排清单 │ ├── qa_agent.json │ └── customer_agent.json └── tests/ # 模板回归测试 ├── cases/ └── run_tests.py原子模板用Markdown写内容组合模板用YAML做变量映射Agent编排清单用JSON描述执行阶段。三种格式各司其职Markdown保证内容可读YAML方便人工维护变量映射JSON适合程序解析执行链路。加载层的实现很简单核心就是一个模板渲染函数。我常用Jinja2做渲染因为它天然支持变量、循环和条件判断比手写字符串替换更安全。加载时先读YAML元信息再读内容模板最后注入变量。如果变量缺失或类型不符直接抛异常不静默兜底。注意在Prompt模板渲染里宁可在渲染期报错也不要让模型去猜缺失变量。静默替换是后续所有诡异行为的温床。4.2 System提示词模板的编写和生效边界一次实战里我需要做一个“商品推荐Agent”。它的System Prompt看起来是这样的template_id: product_recommender_system version: 1.4.0 variables: - name: agent_role default: 你是商城资深导购熟悉所有在售商品与促销规则 - name: memory_state source: runtime_working_memory - name: policy_notes source: policy_config content: | {agent_role} 工作记忆实时更新 {memory_state} 推荐规则每轮必须遵守 {policy_notes}生效边界要注意几点。第一System Prompt内容越靠前被遵循的程度越高。我把“工作记忆”放到角色描述之后就是要保证它被优先关注。第二动态内容memory_state不能太长我限制在1500字符内超出自动压缩为要点式摘要。第三policy_notes来自配置中心它可以被运营人员热更新而无需重新部署Agent。这个模板在运行时每秒都可能被不同用户复用因此模板加载层做了缓存按“模板ID版本号变量指纹”作为缓存键。只要策略或记忆不变化就不会重复渲染。4.3 工具描述模板与ReAct循环的衔接商品推荐Agent需要调用两个工具商品搜索工具和用户画像读取工具。工具描述模板我单独维护没有写死在System Prompt里。工具描述模板的结构是这样的## 工具{tool_name} 功能{tool_description} 输入参数 {input_schema} 使用注意事项 {usage_notes} 输出格式 {output_schema}每个工具的输入输出Schema从代码里的函数签名自动生成避免了手工维护Schema和实际代码不一致的问题。这一步很关键因为工具描述一旦和设备实际入参不一致模型就会频繁生成错误调用参数。在ReAct循环中我的实现遵循一个原则模型只有在需要外部信息时才会看到工具描述平时不给它看。这样做的原因是如果所有工具描述常驻上下文模型会倾向于“为了用工具而用工具”甚至连简单的乘法都要调用计算器。按需加载工具描述后工具误调用率明显下降。整个ReAct循环的提示词拼装逻辑是用户提问进来后先放System Prompt和用户问题模型如果要调用工具再动态追加该工具描述替换占位符工具返回后追加工具结果节点然后继续循环。每一轮循环后都要压缩历史重点保留原问题、上一轮工具名、工具返回摘要、模型基于返回的新判断。4.4 Reflection模板让Agent学会自我纠错Reflection模板是我后来加的也是被验证最奏效的一个部分。它的内容很简单但角色很关键你是一个质量检查员。以下是一段Agent输出的回答请检查 1. 回答是否直接回答了用户问题 2. 是否存在编造数据或推测性信息 3. 是否在无关场景下泄露了系统内部指令 4. 回答格式是否清晰易读。 请以JSON格式输出结构为 {is_ok: true/false, problems: [..., ...], suggestions: ...}在Agent准备输出最终答案前模型会先生成一个候选回答然后调用Reflection模板进行分析。如果返回is_ok为false模型会根据suggestions重新组织答案。这个机制让最终输出的质量有了一个“质检关口”。有一个反面案例我必须提醒不要把Reflection Prompt写得过于严苛。我第一版写了“回答必须全对不允许任何不确定性”结果模型为了追求确定性开始拒绝回答不熟悉的内容回答率暴跌。后来的版本改成“优先诚实回答不确定时明确说明禁止编造”效果立刻正常。Reflection的职责是纠错不是施压。4.5 整体联调时要监控的四个点位模板和编排都做好了联调阶段我建议重点监控四个点位。第一首次工具决策是否正确。也就是用户问题进来后Agent是否在“该调用工具”时调用工具在“不该调用”时不调用。第二工具返回后的解释质量。常见问题是Agent直接把JSON返回给用户这时候要检查Transition模板是否明确要求“用自然语言解释结果”。第三上下文长度变化。每轮循环后统计token消耗尤其关注System Prompt是否被截断或遗忘。第四Reflection触发率。如果一个Agent的Reflection几乎从不触发说明Prompt设计可能让模型认为没有必要质检。我习惯在联调阶段给每个Agent跑一套固定的30个用例内容覆盖正常问题、边界条件、非法输入、上下文超长场景。跑完自动生成行为报告和上一次版本做Diff。只要行为Diff超出预期就暂停发布。5. 常见问题与排查技巧实录5.1 Agent突然“变笨”先查模板还是先查上下文遇到Agent行为劣化我的第一反应不是换模型也不是调温度参数而是先把这条请求的完整提示词打印出来看。大多数“变笨”都是上下文结构被破坏而不是模型状态变化。最常见的情况是工具返回结果太长把System Prompt的注意力挤掉了。排查方法是检查上下文各段落的token占比。如果发现工具返回内容占了70%以上优先做输出截断。还有一个隐蔽问题模型在中间轮次把System Prompt“忘掉”了。我的解决方案是在多轮对话中每隔几轮或每次工具调用后把精简版的System Prompt重新注入一次保证角色边界始终在场。5.2 模板变量注入失败与转义陷阱有一次运营在策略配置里写了“请用{RMB}报价”结果系统把{RMB}当成模板变量去匹配导致渲染异常。这是模板引擎的转义问题。我的解决办法有两个层面。第一模板变量的命名风格统一为$变量名$或{{变量名}}并禁止业务配置里出现同样的包裹符。第二业务配置中的特殊字符先做转义处理。Jinja2里可以通过构建自定义环境把未定义变量设置为“保留原文”而不是报错但这只适合运行时兜底不适合配置校验。5.3 多轮对话里System Prompt被“冲掉”的规避多轮对话越长早期指令失效的概率越高。我试过把System Prompt放在最前面、最后面、中间不同位置结论是最前面仍然最有效但需要在关键节点重复关键约束。实操中我采用了一个“锚点注入”的策略每当Agent执行完一次工具调用准备回答用户时把System Prompt里的核心安全规则不超过200字符在消息末尾再注入一次。这样做额外消耗的token很少却让安全规则的遵循度提升非常明显。如果你发现Agent在长对话中开始跑偏先检查有没有做这个锚点机制。5.4 回滚版本后效果不一致明明回滚到了V1.2行为却和当初的V1.2不一样。这种情况我遇到过不止一次。原因是提示词模板只是行为的一部分还受三个额外变量影响模型版本你回滚了提示词但模型已经从旧版升级到新版、工具行为工具返回值格式可能变了、运行时状态上下文记忆的格式演进。所以一次真正的回滚必须连同“当时的模型版本”“当时的工具Schema快照”一起回滚光回滚文本模板是不够的。我在企业落地时会把“模型版本工具Schema版本提示词版本”打包成一个EnvSnapshot。每次发布出一个快照出问题就整包回滚。这比只回滚提示词要可靠得多。5.5 问题排查速查表我把高频问题整理成一张表遇到问题直接对号入座。现象可能原因优先排查动作Agent拒绝调用工具工具描述缺失或System Prompt里混入了“谨慎使用工具”的约束打印完整提示词检查工具描述是否注入工具调用频繁但结果很差工具描述加载时机不对模型被工具带偏改为按需加载工具描述输出格式不稳定输出格式约束放在System Prompt中段被其他内容淹没把输出约束移动到System Prompt靠前或放到Reflection模板长对话后半段行为漂移上下文被历史消息占满System Prompt锚定失效启用摘要压缩锚点注入模板渲染内容里出现残留变量名变量未做缺省兜底或转义处理检查渲染日志的表面替换覆盖率回滚后仍然行为不一致只回滚了提示词模型或工具版本未回滚使用EnvSnapshot整包回滚收尾的一点体会这套提示词模板管理和Agent提示词编排的方法论是我在一次又一次线上踩坑后逐渐沉淀出来的。如果说有什么最值得分享的经验那就是不要迷信单个提示词的“文采”要相信结构、版本和可观测性。把提示词当成代码来维护Agent就会变得稳定可控把它当成文案来写Agent就会像一匹随时脱缰的马。下一期我准备继续拆解Agent框架选型与工具编排的配合细节如果你在模板管理或编排上有什么好问题欢迎带着场景来交流。
Agent提示词模板管理与编排：从单体Prompt到工程化落地
Agent项目的复杂度往往不是死在模型能力上而是死在提示词的管理上。我做过几个从0到1的Agent项目早期觉得“提示词不就是写一段话嘛”后来发现当Agent开始调用工具、多轮对话、多个角色协作的时候提示词已经不是一段文案而是一套需要版本管理、变量注入、动态编排的工程资产。这套东西做不好Agent的表现会越来越不稳定——今天能回答明天答非所问换一个场景就崩。这篇内容背景是我在企业级Agent平台建设中的实战复盘核心围绕两件事提示词模板管理和Agent提示词编排。适合正在搭Agent的开发者、提示词工程师以及准备把Agent从demo推向生产环境的团队参考。1. 先想清楚提示词为什么会从“一条文案”变成“一套工程”1.1 单体Prompt的极限在哪里单体Prompt就是一段话到底把角色设定、任务说明、背景资料、输出格式全塞进几万字符里。demo阶段这么干完全没问题甚至显得很省事。但一旦进入真实业务你会撞到四个墙。第一个墙是复用墙。同样的工具说明、同样的数据字典、同样的安全约束在不同场景里反复复制粘贴改一处漏一处。第二个墙是测不准。你改了一个中段的小约束不知道影响的是前面的角色一致还是后面的输出格式因为整段都是“锅里的粥”没有分层。第三个墙是上下文的隐性膨胀。为了保险把能想到的都写进去结果重要指令被淹没在大量背景文字里模型的注意力被稀释关键行为反而失灵。第四个墙是热更新困难。线上跑得好好的Agent你想微调一下语气或安全策略必须重新生成整条提示词再走发布风险无限放大。我在一个Agent项目里真正下决心重构是因为一次严重的线上事故为了修复一个工具误调用问题我在单体Prompt末尾追加了一条“不要乱调用工具”的说明结果系统在后续三天开始拒绝调用所有工具业务方直接炸了。问题不是出在模型身上而是出在我的提示词没有结构追加约束和原始指令产生了冲突。1.2 Agent场景给提示词带来的四个新变量单体Prompt时代我们把人当唯一读者但Agent场景下提示词的读者有两个模型和Agent执行框架本身。执行框架需要从提示词中解析出“工具调用边界”“终止条件”“状态说明”这要求提示词具有机器可读的稳定性。我总结了Agent提示词相对普通Prompt的四个新变量。一是动态性。Agent在运行中会不断产生中间结果、工具返回值、环境状态这些信息必须通过模板变量实时注入而不是静态写死。二是组合性。一个Agent往往由多段提示词构成主System、工具描述、反思提示、收尾提示它们需要按执行阶段排列组合。三是可观测性。Prompt背后需要有trace机制否则出了问题你根本不知道是哪段提示词在哪个环节产生了错误行为。四是记忆管理。Agent的记忆不是日志而是要在提示词中以“保留摘要截断历史恢复要点”的形式组织否则上下文窗口会被撑爆。吴恩达的Agent教程里反复强调一个观点Agent不是模型能力变了而是用结构化流程释放模型能力。提示词编排就是结构化流程中最重要的那根骨架。很多人热衷于研究Agent框架选型、工具生态却对提示词这个最上游的变量不重视这在我看来是本末倒置。1.3 怎么判断自己该上“模板管理”了不需要等到出了事故才动手。我建议用三条标准自测。第一条你的Agent里有多少条提示词是重复出现的比如多个Agent都要用到“数据脱敏规则”或“品牌语气规范”如果超过三处就应该抽出来做成模板。第二条你的提示词多久改一次业务上几乎每周都会调整产品话术、策略约束如果你每次都是全量改说明管理方式已经跟不上节奏。第三条你的Agent是不是多角色协作一旦涉及主Agent、子Agent、工具Agent这种嵌套结构每段的职责必须清晰切分否则你无法定位是哪段提示词在“带节奏”。我见过最夸张的案例是一个团队把整套Agent的System Prompt放在一个Java常量类里靠手动注释管理版本某次合并代码时把两条互相矛盾的指令拼到了一起上线后Agent开始自问自答。这不是个例是单体Prompt在规模化路上的必然结局。2. 提示词模板管理把提示词当成代码一样去维护2.1 模板的最小结构不只是一段字符串很多人理解的模板管理就是用变量替换文本。真正可用的是结构化的模板单元。我习惯把一个提示词模板定义为四个部分元信息、变量声明、正文模板、评测用例。元信息包含模板ID、名称、版本号、适用场景、负责人。变量声明要把模板中所有占位符集中列出标明类型、必填性、默认值、来源。正文模板就是真正的提示词内容里面用特定语法标记变量位置。评测用例是模板的“单元测试”每个模板至少要有三组输入输出样例用于验证渲染结果和实际效果。这个结构看起来简单但给工程带来的收益很大。首先修改模板时可以快速判断影响面其次变量注入产生的错误可以迅速定位是数据问题还是模板问题最关键的是提示词模板终于可以被纳入正常研发流程评审、测试、上线都有据可查。具体到实现我常用JSON Schema描述模板。以下是一个简化示例{ template_id: agent_core_system, version: 2.3.0, scenario: generic_agent_system_prompt, variables: [ {name: role_profile, type: string, required: true, source: config}, {name: tool_descriptions, type: string, required: true, source: tool_registry}, {name: safety_rules, type: array, required: false, default: []} ], content_template: 你是{role_profile}。你有以下工具可用\n{tool_descriptions}\n安全规则{safety_rules}, test_cases: [ {input: {...}, expected_output_contains: [你有以下工具可用]} ] }2.2 变量注入的三个坑格式、长度、缺省变量注入是模板管理最不起眼却最容易出问题的地方。我踩过的坑按出现频率排序如下。第一个是格式丢失。模板变量内部如果有换行、列表、表格注入到字符串后可能破坏原有的Markdown结构导致模型解析混乱。解决方法是在变量声明里明确“这个是列表格式的”渲染时用统一的列表序列化器避免变量自己带着不规整的换行符。第二个是长度失控。工具描述动辄几千字安全策略几千字角色设定又几千字全部注入后System Prompt轻松突破两万字符。结果模型虽然能塞下但执行质量急剧下降。我后来强制要求每个模板单元在渲染后统计字符数超过预算直接报警。第三个是缺省不兜底。有些变量在特定场景没有值比如一个Agent不需要工具但模板里引用了tool_descriptions。如果渲染时只做“空字符串替换”模型会认为工具列表为空逻辑没问题但如果你忘了替换模板里就会残留一个{tool_descriptions}原文。这个非常隐蔽因为模型有时候能自己脑补有时候不能。我的建议是渲染时对所有未匹配变量做统一哨兵标记并强制走测试用例校验。2.3 版本管理与回归提示词也需要CI提示词模板一旦可以独立版本化就要引入回归机制。我见过太多团队某个模板改了以后一类Agent行为变了但没人知道是哪个变更引起的。我的做法是给每条模板的每个版本建立一个“行为快照”。“行为快照”不是看文本Diff而是看这个模板对一组固定输入的行为输出。具体来说就是准备一批标准测试问题分别在模板V1和V2下跑同一套Agent跑完记录输出关键指标是否调用正确工具、回答是否包含禁用词、格式是否合规等。然后对比Diff。这套机制跑起来以后你会发现提示词维护从“玄学”变成了“可回归的工程”。有一次我把安全规则从数组格式改成自然语言段落文本上看起来更通顺了但行为快照显示模型开始在输出里泄露系统提示词。因为自然语言段落让模型把规则当成了“对话内容”而不是“系统约束”。这就是回归测试的价值——它帮你抓住那些文本层面看不出来的行为差。版本管理上我建议直接复用Git的已有习惯。每个模板是一个目录命名规则为模板名/版本号/版本号用语义化版本。线上始终引用固定版本号而不是引用分支或latest。等到业务稳定后再通过发布流程统一推进版本。2.4 落地形态从目录到Prompt仓库模板管理的最终形态是形成一个公司级的“提示词仓库”。这个仓库里三类东西一定要有基础原子模板、业务组合模板、Agent编排清单。基础原子模板只干一件最小的事。比如“脱敏规则提示词”“代码生成风格提示词”“翻译语气提示词”它们是积木块。业务组合模板则把这些积木按业务场景拼起来比如“电商客服Agent的系统提示词”“数据分析Agent的系统提示词”。它们的区别在于基础原子模板不关心业务组合模板关心。Agent编排清单则是把多个模板按Agent的执行流程串起来第一阶段用启动模板第二阶段用工具选择模板第三阶段用反思模板。这个清单本身就是一份Agent提示词编排的设计文档。我记得MCP生态火起来以后很多人把注意力放在工具接入上觉得工具多了Agent就强了。但工具再强提示词没有给模型建立选择工具的依据和边界工具越多Agent反而越容易乱。提示词仓库的作用就是在工具能力和模型行为之间画一条清晰的线。3. Agent提示词编排让多段Prompt按决策逻辑协同3.1 编排的本质是“谁在什么条件下说什么话”Agent提示词编排不是把模板简单拼到一起而是为Agent的每个执行阶段准备对应的提示词并明确触发条件和切换逻辑。我还原一下实际执行链路。主Agent启动时读取System Prompt确定角色和能力边界当需要外部信息时生成工具调用请求工具描述在此刻决策中起关键作用工具返回后Agent进入解释与整合阶段此时需要把中间结果拼回上下文如果发现答案不理想会触发反思或纠正阶段。每一段的提示词都不一样不能让一段System Prompt从头管到尾。说得直白一些编排就是定义“谁在什么条件下说什么话”。System Prompt说“你是一个数据分析师”这是一层工具描述说“你可以调用SQL查询工具”这是第二层反思模板说“如果查询结果为空请检查是否存在数据库连接问题”这是第三层。缺了任何一层Agent的行为都不完整。我见过不少新手在做Agent时把工具调用失败的兜底逻辑写在System Prompt里结果模型在正常场景下也会变得谨慎动不动就拒绝执行。这就是没做阶段划分把后阶段的反思约束前移到了启动阶段干扰了主决策。3.2 四类核心提示词System、Tool、Reflection、Transition我按照Agent执行阶段把编排中的提示词分成四类。每类在模板仓库里都是独立的可复用单元。第一类是System Prompt负责角色、目标、边界、输出偏好。它的原则是稳定和抽象尽量把业务细节留在运行时注入。第二类是Tool Prompt负责每个工具的功能说明、输入输出规范、使用约束。Tool Prompt不需要在System Prompt里全量出现而应该在工具被选中时动态拼装。这也是当前Agent框架较常用的做法工具注册表返回描述提示词编排器按需加载。第三类是Reflection Prompt负责自我检查和纠错。典型内容如“检查你的上一步输出是否符合格式要求”“如果与预期不符说明原因并重新作答”。这类提示词是很多Agent项目缺失的却往往是最能提升最终效果的部分。第四类是Transition Prompt负责阶段之间的衔接比如“工具已返回结果请基于结果回答用户问题”“请判断当前是否所有信息已获取完毕若需要更多信息则继续调用工具”。这四类的比例和内容决定了一个Agent的“性格”。有的Agent总是显得啰嗦是因为Transition Prompt写得模糊模型不知道该结束还是该追问。有的Agent总爱自作主张是因为Reflection Prompt缺失模型没有自我约束环节。3.3 上下文窗口预算提示词也要算着花Agent开发中上下文窗口是硬成本。很多模型支持128K甚至更长上下文但这不意味着你可以放任自流。上下文越长模型对中段指令的遵循度越差推理延迟越高成本也越高。我在每个Agent的编排配置里都会明确各部分的上下文预算。通常System Prompt控制在3000字符以内占比2%左右工具描述按需加载总量控制在8000字符左右历史对话保留最近N轮并做摘要压缩每轮工具返回结果控制在3000字符以内过长就会被截断或摘要。至于记忆我的做法是在进程中使用“工作记忆”也就是把Agent执行过程中的关键状态已获取信息、待确认项、已用工具在提示词中以结构化字段实时维护。这与“长期记忆”不同工作记忆是当前任务上下文的一部分。实践中我发现把工作记忆从历史对话中单独划出来注入到System Prompt的尾部模型的稳定性和健忘率都会明显改善。3.4 多Agent协作时的提示词边界多Agent协作比单Agent更考验编排能力因为每个Agent都有自己的System Prompt而它们之间的协作方式也必须用提示词说清楚。我在一个客服数据分析的组合Agent项目里设计了三个Agent前台客服Agent、后台查询Agent、质检Agent。前台Agent负责对话后台Agent负责SQL查询质检Agent负责审核输出。它们的System Prompt各自独立但必须互相知道对方的存在和边界。前台客服Agent的System Prompt里有一句话“如果你需要数据分析支持请调用后台分析Agent等待其返回后你再回答用户。你不需要解释你的分析过程。”后台分析Agent的System Prompt里有另一句话“你只回答结构化数据结论不负责向用户解释。你的输出会由前台客服Agent整合。”质检Agent则说“你只检查语气、合规性和信息真实性不修改内容只输出通过或拒绝。”这三段提示词拼在一起就是一个简单的多Agent协作协议。协议不复杂但如果没有明确边界三个Agent之间就会出现严重的信息泄露和职责混乱。我最常见的问题是后台Agent开始扮演客服和用户对话前台Agent开始编造查询结果。这些问题的根源都在提示词边界模糊。3.5 一个可直接复用的编排蓝图如果你准备从零搭一个单Agent项目我建议直接用下面这个编排蓝图它是我在多轮改版后沉淀下来的通用形态。首先是启动段包含System Prompt 全局工作记忆结构。System Prompt定义角色和边界工作记忆定义状态字段信息收集进度、工具使用历史、待确认问题列表。其次是工具决策段由模型在需要外部信息时触发工具描述通过工具注册表动态加载。再次是结果处理段工具返回后模型依据Transition Prompt判断是否继续调用工具还是进入回答阶段。最后是反思段当模型准备输出最终答案前先过一次Reflection Prompt检查格式和合规。整个流程用一段伪代码表达大概是这样def run_agent(user_input): messages load_system_prompt_with_memory(agent_id, working_memory) messages.append({role: user, content: user_input}) while True: response chat_model(messages) if response.needs_tool_call(): tool_desc load_tool_description(response.tool_name) messages.append({role: assistant, content: format_tool_request(response)}) messages.append({role: tool, name: response.tool_name, content: execute_tool(response.tool_name, response.arguments)}) continue if response.should_reflect(): reflect_prompt render_template(reflection_template, {answer: response.content}) reflection chat_model(reflect_prompt) if reflection.is_bad(): messages.append({role: user, content: 请根据以下修正建议重新回答 reflection.suggestions}) continue return response.content这个蓝图的核心要点是每一轮循环都有明确的提示词入口不会出现“一段提示词管全程”的情况。实测下来这种结构在可调试性和行为稳定性上都比单体Prompt高一个档次。4. 实操记录用Python搭建一个轻量提示词模板管理与编排示例4.1 目录结构与加载层实现我跑过很多项目最终的模板仓库目录结构基本稳定为prompt_repo/ ├── atomic/ # 基础原子模板 │ ├── safety_rules.yaml │ ├── tool_usage.md │ └── output_format.md ├── composite/ # 业务组合模板 │ ├── customer_service.yaml │ └── data_analyst.yaml ├── agents/ # Agent编排清单 │ ├── qa_agent.json │ └── customer_agent.json └── tests/ # 模板回归测试 ├── cases/ └── run_tests.py原子模板用Markdown写内容组合模板用YAML做变量映射Agent编排清单用JSON描述执行阶段。三种格式各司其职Markdown保证内容可读YAML方便人工维护变量映射JSON适合程序解析执行链路。加载层的实现很简单核心就是一个模板渲染函数。我常用Jinja2做渲染因为它天然支持变量、循环和条件判断比手写字符串替换更安全。加载时先读YAML元信息再读内容模板最后注入变量。如果变量缺失或类型不符直接抛异常不静默兜底。注意在Prompt模板渲染里宁可在渲染期报错也不要让模型去猜缺失变量。静默替换是后续所有诡异行为的温床。4.2 System提示词模板的编写和生效边界一次实战里我需要做一个“商品推荐Agent”。它的System Prompt看起来是这样的template_id: product_recommender_system version: 1.4.0 variables: - name: agent_role default: 你是商城资深导购熟悉所有在售商品与促销规则 - name: memory_state source: runtime_working_memory - name: policy_notes source: policy_config content: | {agent_role} 工作记忆实时更新 {memory_state} 推荐规则每轮必须遵守 {policy_notes}生效边界要注意几点。第一System Prompt内容越靠前被遵循的程度越高。我把“工作记忆”放到角色描述之后就是要保证它被优先关注。第二动态内容memory_state不能太长我限制在1500字符内超出自动压缩为要点式摘要。第三policy_notes来自配置中心它可以被运营人员热更新而无需重新部署Agent。这个模板在运行时每秒都可能被不同用户复用因此模板加载层做了缓存按“模板ID版本号变量指纹”作为缓存键。只要策略或记忆不变化就不会重复渲染。4.3 工具描述模板与ReAct循环的衔接商品推荐Agent需要调用两个工具商品搜索工具和用户画像读取工具。工具描述模板我单独维护没有写死在System Prompt里。工具描述模板的结构是这样的## 工具{tool_name} 功能{tool_description} 输入参数 {input_schema} 使用注意事项 {usage_notes} 输出格式 {output_schema}每个工具的输入输出Schema从代码里的函数签名自动生成避免了手工维护Schema和实际代码不一致的问题。这一步很关键因为工具描述一旦和设备实际入参不一致模型就会频繁生成错误调用参数。在ReAct循环中我的实现遵循一个原则模型只有在需要外部信息时才会看到工具描述平时不给它看。这样做的原因是如果所有工具描述常驻上下文模型会倾向于“为了用工具而用工具”甚至连简单的乘法都要调用计算器。按需加载工具描述后工具误调用率明显下降。整个ReAct循环的提示词拼装逻辑是用户提问进来后先放System Prompt和用户问题模型如果要调用工具再动态追加该工具描述替换占位符工具返回后追加工具结果节点然后继续循环。每一轮循环后都要压缩历史重点保留原问题、上一轮工具名、工具返回摘要、模型基于返回的新判断。4.4 Reflection模板让Agent学会自我纠错Reflection模板是我后来加的也是被验证最奏效的一个部分。它的内容很简单但角色很关键你是一个质量检查员。以下是一段Agent输出的回答请检查 1. 回答是否直接回答了用户问题 2. 是否存在编造数据或推测性信息 3. 是否在无关场景下泄露了系统内部指令 4. 回答格式是否清晰易读。 请以JSON格式输出结构为 {is_ok: true/false, problems: [..., ...], suggestions: ...}在Agent准备输出最终答案前模型会先生成一个候选回答然后调用Reflection模板进行分析。如果返回is_ok为false模型会根据suggestions重新组织答案。这个机制让最终输出的质量有了一个“质检关口”。有一个反面案例我必须提醒不要把Reflection Prompt写得过于严苛。我第一版写了“回答必须全对不允许任何不确定性”结果模型为了追求确定性开始拒绝回答不熟悉的内容回答率暴跌。后来的版本改成“优先诚实回答不确定时明确说明禁止编造”效果立刻正常。Reflection的职责是纠错不是施压。4.5 整体联调时要监控的四个点位模板和编排都做好了联调阶段我建议重点监控四个点位。第一首次工具决策是否正确。也就是用户问题进来后Agent是否在“该调用工具”时调用工具在“不该调用”时不调用。第二工具返回后的解释质量。常见问题是Agent直接把JSON返回给用户这时候要检查Transition模板是否明确要求“用自然语言解释结果”。第三上下文长度变化。每轮循环后统计token消耗尤其关注System Prompt是否被截断或遗忘。第四Reflection触发率。如果一个Agent的Reflection几乎从不触发说明Prompt设计可能让模型认为没有必要质检。我习惯在联调阶段给每个Agent跑一套固定的30个用例内容覆盖正常问题、边界条件、非法输入、上下文超长场景。跑完自动生成行为报告和上一次版本做Diff。只要行为Diff超出预期就暂停发布。5. 常见问题与排查技巧实录5.1 Agent突然“变笨”先查模板还是先查上下文遇到Agent行为劣化我的第一反应不是换模型也不是调温度参数而是先把这条请求的完整提示词打印出来看。大多数“变笨”都是上下文结构被破坏而不是模型状态变化。最常见的情况是工具返回结果太长把System Prompt的注意力挤掉了。排查方法是检查上下文各段落的token占比。如果发现工具返回内容占了70%以上优先做输出截断。还有一个隐蔽问题模型在中间轮次把System Prompt“忘掉”了。我的解决方案是在多轮对话中每隔几轮或每次工具调用后把精简版的System Prompt重新注入一次保证角色边界始终在场。5.2 模板变量注入失败与转义陷阱有一次运营在策略配置里写了“请用{RMB}报价”结果系统把{RMB}当成模板变量去匹配导致渲染异常。这是模板引擎的转义问题。我的解决办法有两个层面。第一模板变量的命名风格统一为$变量名$或{{变量名}}并禁止业务配置里出现同样的包裹符。第二业务配置中的特殊字符先做转义处理。Jinja2里可以通过构建自定义环境把未定义变量设置为“保留原文”而不是报错但这只适合运行时兜底不适合配置校验。5.3 多轮对话里System Prompt被“冲掉”的规避多轮对话越长早期指令失效的概率越高。我试过把System Prompt放在最前面、最后面、中间不同位置结论是最前面仍然最有效但需要在关键节点重复关键约束。实操中我采用了一个“锚点注入”的策略每当Agent执行完一次工具调用准备回答用户时把System Prompt里的核心安全规则不超过200字符在消息末尾再注入一次。这样做额外消耗的token很少却让安全规则的遵循度提升非常明显。如果你发现Agent在长对话中开始跑偏先检查有没有做这个锚点机制。5.4 回滚版本后效果不一致明明回滚到了V1.2行为却和当初的V1.2不一样。这种情况我遇到过不止一次。原因是提示词模板只是行为的一部分还受三个额外变量影响模型版本你回滚了提示词但模型已经从旧版升级到新版、工具行为工具返回值格式可能变了、运行时状态上下文记忆的格式演进。所以一次真正的回滚必须连同“当时的模型版本”“当时的工具Schema快照”一起回滚光回滚文本模板是不够的。我在企业落地时会把“模型版本工具Schema版本提示词版本”打包成一个EnvSnapshot。每次发布出一个快照出问题就整包回滚。这比只回滚提示词要可靠得多。5.5 问题排查速查表我把高频问题整理成一张表遇到问题直接对号入座。现象可能原因优先排查动作Agent拒绝调用工具工具描述缺失或System Prompt里混入了“谨慎使用工具”的约束打印完整提示词检查工具描述是否注入工具调用频繁但结果很差工具描述加载时机不对模型被工具带偏改为按需加载工具描述输出格式不稳定输出格式约束放在System Prompt中段被其他内容淹没把输出约束移动到System Prompt靠前或放到Reflection模板长对话后半段行为漂移上下文被历史消息占满System Prompt锚定失效启用摘要压缩锚点注入模板渲染内容里出现残留变量名变量未做缺省兜底或转义处理检查渲染日志的表面替换覆盖率回滚后仍然行为不一致只回滚了提示词模型或工具版本未回滚使用EnvSnapshot整包回滚收尾的一点体会这套提示词模板管理和Agent提示词编排的方法论是我在一次又一次线上踩坑后逐渐沉淀出来的。如果说有什么最值得分享的经验那就是不要迷信单个提示词的“文采”要相信结构、版本和可观测性。把提示词当成代码来维护Agent就会变得稳定可控把它当成文案来写Agent就会像一匹随时脱缰的马。下一期我准备继续拆解Agent框架选型与工具编排的配合细节如果你在模板管理或编排上有什么好问题欢迎带着场景来交流。
