企业官网建设流程全解析

我做Agent开发这几年，最大的教训是：提示词模板这件事，早期越不重视，后期越要加倍还。最近手里一个项目就是典型，Agent在某个工具链上连续触发同样的错误，日志里反复出现任务异常终止，我排查了两天，最后发现问题根源非常朴素——System Prompt里一句工具调用规则的变量名和记忆模块的占位符撞了。从那以后我养成了一个习惯：接到Agent项目，最先动手的永远是提示词目录结构和模板编排方案，而不是Agent主循环代码。

这篇就专门聊提示词模板管理和Agent提示词编排，适合正在做Agent开发、接工具、搭多Agent协作，以及被“提示词越改越乱”困扰的人。我会从为什么模板管理是Agent工程化的地基讲起，再拆一个可复用的ReAct提示词编排实例，最后把记忆、工具选择、多Agent协作这几个高频场景的编排思路和踩坑经验一起说透。

1. 提示词模板为什么管不住，Agent就没法稳定

1.1 传统提示词是一次性消耗品，Agent提示词是行为准则

很多团队把Agent提示词当成普通LLM提示词来写，这是最大的认知偏差。普通单次调用里，你给模型一段话，它返回一段话，这件事就结束了。提示词写得差一点，影响的是单次回答质量，重试一次成本很低。

但Agent的System Prompt不是这样——它会被反复加载，参与几十轮甚至几百轮的工具调用、记忆检索、状态更新。它更像一份常驻岗位的“员工手册”，模型要在一整个任务生命周期里持续按照这套规则行动。一个员工手册写得含糊不清，员工会在各种边界场景里自由发挥；一份提示词写得含糊，模型就会在工具选择、输出格式、状态记录上反复横跳。

所以Agent提示词必须具备三个传统提示词很少考虑的特性：可维护性（能分模块迭代不影响其他部分）、可组合性（能按当前任务动态拼装不同模块）、可观测性（每次变更能对应到行为变化）。这三个特性不会自然出现，必须靠工程手段管理出来。

1.2 模板管理失控的三种典型症状

我复盘过多个项目，发现提示词失控几乎都是同样的路径，症状也就那么几种。

第一种，提示词散落在代码里。某次需求要改Agent的回复风格，开发人员得先打开代码，找到那串几千字的字符串，改完还要重新部署。如果同一个提示词片段在多处复制过，问题更严重——只改了其中一处，另一处还在跑旧逻辑，行为分裂。

第二种，变量注入混乱。Agent提示词里通常要动态塞入用户名、工具列表、历史摘要、当前目标。用f-string直接内插这些变量，一旦变量内容里带换行、引号、JSON特殊字符，轻则格式损坏，重则模型解读出完全不存在的“指令”。这类问题在日志里看起来像模型“犯傻”，其实是我们往模板里灌了不可控的东西。

第三种，没有评测基线。提示词改了，Agent表现到底变好还是变坏，完全没有量化依据。今天加了两句约束，明天发现工具调用率下降，后天再删掉，循环往复。没有评测基线，提示词迭代就永远是玄学，团队只能靠感觉和情绪做决策。

1.3 模板管理系统不是AI应用里的“文档工作”

把提示词模板管理系统化，不是写一份漂亮的提示词文档，也不是简单建几个Markdown文件，而是把它当成一套轻量级的配置系统来建设。它需要存储结构、版本机制、变量约束、渲染管线、评测接口。本质上和做数据库迁移、接口层抽象没有区别。

我更愿意把它类比成后端开发的数据库表结构设计：你建表的时候如果字段类型乱来、索引缺失、命名混乱，系统后期一定出事。提示词模板就是Agent的“表结构”，早期不设计好，后期每条业务规则都往里面堆，最后就是谁也改不动的“大泥球”。

2. 提示词模板工程化：怎么组织、怎么改、怎么升级

2.1 目录结构就是模板系统的架构图

先说我现在项目里的实际目录结构，你可以直接照着抄：

agent-studio/ ├── prompts/ │ ├── base/ │ │ ├── system_core.txt │ │ ├── role_and_capability.txt │ │ ├── tool_use_rules.txt │ │ ├── response_format.txt │ │ └── safety_boundaries.txt │ ├── modules/ │ │ ├── memory/ │ │ │ ├── summarizer.prompt │ │ │ ├── query_context.prompt │ │ │ └── reflection_trigger.prompt │ │ ├── planning/ │ │ │ ├── task_decompose.prompt │ │ │ └── replan_after_error.prompt │ │ └── toolpicker/ │ │ ├── tool_prefilter.prompt │ │ └── tool_conflict_resolution.prompt │ └── templates/ │ ├── react_agent.yaml │ ├── multi_agent_coordinator.yaml │ └── data_query_agent.yaml ├── prompt_builder/ │ ├── loader.py │ ├── renderer.py │ └── validator.py └── tests/ ├── fixtures/ └── test_prompt_render.py

这个结构分了三层。base/是稳定不变的基础模块，回答风格、安全边界这类内容很少变动；modules/是功能模块，按职责拆开，记忆、规划、工具选择各自独立，改记忆相关提示词不会碰规划逻辑；templates/是面向具体Agent场景的“组装清单”，每个yaml文件声明要组合哪些base和modules，以及用什么变量填充。

这套拆分思路和前端组件化很像。你写UI不会把所有样式都塞进一个HTML文件，Agent提示词也不应该是一条几千字的长字符串。模块化之后，新增一个Agent场景只是新增一个yaml组装文件，复用已有模块，不用重写所有提示词。

2.2 版本管理要跟着评测走，而不是跟着感觉走

提示词文件进入版本管理只是第一步，更关键的是每次变更都能追溯到行为差异。我在项目里维护一张变更记录表，每次改模板必须填：

这张表的价值是让提示词迭代有了“回滚依据”。模型行为是有随机性的，今天改一句话觉得效果好，可能只是偶然；只有把变更和一组固定的评测用例绑定，才能判断真实收益。我建议每个模板仓库里都配一组最小评测集，可以是几十条固定场景的任务样本，每次模板变更后跑一遍，记录通过率、工具调用次数、上下文消耗、任务耗时的中位数。

2.3 变量分层：静态、动态、状态各管各

模板拼接失败的七成原因，都是变量边界没划清。我把Agent模板里的变量分成三类，分别管理：

• 静态配置变量：Agent名称、所属团队、可使用的语言范围、知识库标识。这类变量从配置文件读取，生命周期长，基本不变。
• 动态上下文变量：当前用户的输入、本轮目标、检索到的记忆片段、时间信息。这类变量每次对话开始时注入，需要严格的格式校验。
• 执行期状态变量：已完成步骤列表、当前待执行动作、工具返回结果、重试次数。这类变量在Agent运行过程中反复更新，最容易出现跨轮污染。

三类变量的管理策略完全不同。静态变量直接替换，做白名单校验即可；动态变量需要转义和格式化，防止内容里的特殊字符破坏模板结构；执行期状态变量必须走结构化数据（比如JSON）再渲染成文本，绝不能用f-string随意拼接。

2.4 模板渲染的选型与避坑

我之前用f-string直接拼过一段工具描述，变量里恰好有一段含双引号的JSON，结果模型的输出格式彻底乱掉，连着十几个请求全部解析失败。后来我强制要求所有模板渲染走结构化方案，Python项目里就用Jinja2，配合自定义过滤器做转义。

另一个容易踩的坑是模板里的“隐形空格”。不同模块拼接时，你很难感知到某个模块末尾多了个空行或少了换行，但在模型眼里，分隔符的变化可能影响它对模块边界的理解。我的做法是在每个模块首尾加固定注释标签，渲染后做一次lint校验，检查标签闭合和必要字段是否存在。校验不过就直接抛错，不让坏模板流向线上。

from jinja2 import Environment, FileSystemLoader, StrictUndefined env = Environment( loader=FileSystemLoader("prompts/"), undefined=StrictUndefined, trim_blocks=True, lstrip_blocks=True, ) def render_prompt(template_name, variables): tpl = env.get_template(template_name) require_vars = tpl.module.required_vars missing = [v for v in require_vars if v not in variables] if missing: raise PromptRenderError(f"missing variables: {missing}") return tpl.render(**variables)

StrictUndefined这个选项很关键，它会在变量缺失时立刻抛异常，而不是渲染成空串。空串在提示词里非常隐蔽，模型可能把空字段解读成“没有这个约束”，行为就失控了。

3. 手写ReAct Agent提示词编排：从模板到真实上下文的完整拼接

3.1 System Prompt其实是五个模块的拼装

我习惯用ReAct模式来搭Agent骨架，即思考（Thought）—行动（Action）—观察（Observation）的循环。这种模式下，System Prompt不是一段话，而是五个模块的拼装结果：

这五个模块在模板里对应不同的文件，但运行时必须拼装成一份完整的System Prompt。我见过程序员把所有模块直接顺序拼接后用\n\n分隔，效果很差。模型对各模块的敏感度不同，属于“身份与目标”的内容应该放在最前面，紧接着是能力边界，工具和记忆规则居中，输出格式放最后。越靠前的信息对模型行为影响越大，靠后的部分仅在需要时引导输出结构。

3.2 工具Schema怎么注入提示词，才不会把模型带偏

工具Schema注入是最容易被低估的环节。很多开发图省事，把所有工具的JSON Schema一股脑塞进System Prompt。工具一多，模型的选择准确率会明显下降，而且长Schema会挤占上下文预算。

我现在的做法是给模板定义一个tools变量，运行时先通过预筛选决定注入哪些工具，再渲染成统一的文本块。工具描述有三个约束：每个工具只用一句话说清触发条件；参数部分只列出必填项和高频可选参数；每个工具带一个“典型使用场景”示例。宁可描述短一点，让模型选错时通过执行报错来反馈，也好过描述太长让模型注意力涣散。

例如一个天气查询工具的Schema注入模块，模板里长这样：

可用工具列表： 1. tool: get_weather 用途: 查询指定城市未来三天的天气。仅当用户询问天气、温度、降水时调用。 必填参数: - city: 城市中文名 示例: {"city": "北京"}

这种写法比直接把OpenAPI Schema原文塞进去要稳定得多。不要担心模型“看不懂”完整Schema，Agent场景下我们更需要在提示词里做信息降维，把工具描述压到模型最容易消费的形态。

3.3 输出格式约束与Action解析的平衡

手写ReAct循环时，最痛苦的是解析模型输出。我踩过一个大坑，原来模板里要求模型先输出一段自然语言思考，再输出JSON格式动作。结果模型经常把JSON包在Markdown代码块里，或者思考文本里带了冒号导致解析器误判。

调优之后的输出格式模板大致这样约束：

你的每一次行动必须严格按以下格式输出，不要输出其他内容： Thought: 对当前状态的简短分析，最多两句话。 Action: get_weather Action Input: {"city": "北京"}

只保留三个字段，减少模型自由发挥的空间。解析端也别逞强，先按整段匹配，失败再用正则定位Action:行。如果连续两次解析失败，让Agent转入“澄清模式”——不是报错退出，而是请求用户重新表述，这比直接抛异常用户体验好得多。

这里有个平衡问题：格式约束太松，解析容易崩；约束太死，模型在复杂场景下会把动作写成无法识别的形式，导致死循环。我目前的经验是把“输出格式”模块只约束“动作”层面的格式，思考部分允许自由文本，反正思考部分不参与机器解析。

3.4 多轮对话里提示词怎么重组，才不会让上下文失控

Agent对话不是单轮的，每一轮结束之后，System Prompt之外还要拼上历史消息、工具结果、当前状态。很多项目把所有历史全部塞进上下文，很快就到达模型窗口上限。

我在模板编排里把Agent的上下文分成三个区：

模板里预留short_memory和long_memory两个变量。滚动区放最近几轮原始对话，压缩区放结构化摘要。摘要不是简单“总结对话”，而是提炼“任务进展、已完成动作、遗留问题、用户偏好”。压缩区更新时，我还要求记忆模块同时标记哪些信息已不可靠，避免Agent被过期摘要带偏。

4. 复杂Agent场景下的编排策略：记忆、工具与多Agent

4.1 记忆模块的提示词编排：工作区、摘要与反射

如果Agent只处理单轮任务，记忆模块可有可无。但做数据分析、长文档处理、多阶段调研这类任务，记忆机制直接决定Agent能不能跑完整个任务不出乱子。我在模板里给记忆模块设计了三类提示词。

工作区提示词负责记录“当前正在处理的事情”。每次工具调用结束后，会把关键中间结果压写成一条结构化条目，模板要求模型判断：这条结果对最终目标有没有影响？有就写入，没有就丢弃。这个判断本身也是靠提示词引导的，所以模板里必须写明写入标准，否则模型会什么都往里塞。

摘要提示词负责定期压缩历史。我参考了反思模式的做法，每隔固定轮数触发一次简短的总结。总结模板会要求模型从“已完成、进行中、卡点、下一步”四个维度复述状态。别小看这个结构，它比自然语言总结可靠得多，后续Agent回溯状态时能直接按字段取用。

反射提示词我一开始舍不得用，因为增加Token消耗。后来发现它值得：在任务失败或工具连续报错时，反射模板会强制模型输出“失败原因假设、证据、可调整策略”三段内容。这个机制能把很多“错误重试”变成“策略调整”，任务成功率肉眼可见地提升。

4.2 动态工具选择与MCP工具的模板注入

现在做Agent基本绕不开MCP这种工具接入方式。MCP工具是动态注册的，每次会话初工具列表都可能不一样，所以提示词模板无法写死工具集合，必须在运行时把MCP注册表的工具列表转成模板变量注入。

我在template里的toolpicker模块设计了三个过滤规则，模板会引导模型先过滤再行动：只考虑命名空间匹配当前任务的工具；只列出必填参数在上下文中可获取的工具；如果某个工具在最近N轮内连续失败过，降级优先级或直接排除。这三个过滤不是硬编码逻辑，而是写进工具选择提示词里的决策规则，让模型结合上下文判断。

还有一个实用小技巧：MCP工具描述通常由服务端自动生成，可能不够口语化。模板层我会加一个轻量重写步骤，让模型对工具描述做“压缩重写”并缓存。比如某个数据库查询工具的原始描述有300字，压缩后只剩80字，工具选择准确率反而更高。这背后的原理很简单——提示词里信息越聚焦，模型越容易做出正确路由。

4.3 多Agent协作时的提示词竞态与传递规则

多Agent协作场景下，提示词编排最大的坑是“上下文污染”。一个主Agent把完整上下文原封不动传给子Agent，子Agent不仅浪费大量Token，还可能被主Agent的无关思考带偏。

我现在做多Agent项目，坚持一条原则：每个子Agent只接收“任务派发单”，而不是全量对话历史。任务派发单是一种结构化的提示词模板，包含任务目标、输入数据摘要、约束条件、期望输出格式、关联上下文指针。子Agent在执行时如果需要更多信息，通过工具或共享存储主动拉取，而不是全部塞进提示词。

主Agent和子Agent之间还需要约定变量命名空间。来自主Agent的变量统一加upper_前缀，子Agent自己的状态变量用sub_前缀。否则多个子Agent并行运行时，各自内部状态变量的名称一旦冲突，渲染结果就会串味，表现层面就是“Agent突然提到一份它根本没见过的工作计划”。我用过的项目里出过好几次这种诡异问题，最后全部归结为变量作用域没隔离。

4.4 让模板自带安全边界，别等运行时补救

安全边界不应该写在代码里，而应该同时写进提示词模板，并且随模板版本管理。我的做法是在base/safety_boundaries.txt里专门留一段“绝对禁止”清单，内容随Agent场景调整。比如一个写SQL的Agent，禁止执行增删改操作；一个能上网的Agent，禁止点击下载链接；一个能读文件的Agent，禁止读取指定目录之外的内容。

这段限制需要写得具体，不能只说“注意安全”。模型对抽象指令的执行非常不稳定，必须给可判断的条件。比如“如果工具返回结果中包含个人敏感信息，立即停止输出原始字段，改用脱敏摘要”。这种明确条件比“保护用户隐私”有效得多。

另外，安全边界模块也要做版本管理。每种边界变更，都要像功能模块一样走评测和审批流程，不能临时改一段话就上线。我看到有些团队把安全边界写死在代码常量里，每次调整都要发版，反而导致团队为了省事而长期不更新边界，风险更大。

5. 我踩过的一些坑，以及排查提示词问题的实用思路

5.1 变量名冲突引发的“看似灵异”行为

有一次Agent在回答中突然生成了记忆摘要的内容，现场定位了很久。最后发现模板里用了两个同名变量：一个是task_state，来自记忆模块；另一个也是task_state，来自执行期状态更新模块。后者渲染时覆盖了前者，模型看到的“历史状态”其实是当前状态，导致回答上下文混乱。

这个问题最好的解法是像4.3节说的那样，在命名空间层做隔离，模块前缀强制规范。同时渲染器里要有重复变量检测，发现同名变量但来源不同就抛异常。这类问题不能靠人眼盯代码解决，必须靠工具自动拦住。

5.2 模板里写的工具能力和真实工具行为不一致

还有一个高频坑是模板里的工具描述和工具实际行为脱节。比如一个文件搜索工具的提示词里写着“返回最多20条匹配结果”，实际工具只返回了5条；模型等不到预期数量的结果，会反复调用同一工具，直到触发agent execution terminated due to error或类似的终止反馈。

我后来把工具描述和工具实现拉通做了一套自检用例：每个工具的描述都配了2至3个固定输入，测试环境直接跑一遍，验证“描述中的能力声明”和“工具的返回结构”是否一致。这个做法一开始有点费时间，但非常值。很多看起来像模型不聪明的问题，其实是提示词描述的“纸面能力”和工具实际的“真实能力”之间出现了裂缝。

5.3 先分清楚是提示词问题还是框架问题

排查看似复杂的Agent异常，我有一条铁律：先绕开提示词，用一个最简单的固定输出测试同一个工具链。如果最简单的提示词也出错，说明框架或工具层有问题，这时候别再调模板，纯粹浪费时间。

反过来也一样，如果框架层一切正常，换个场景模板就出问题，那就把注意力完全放在模板和变量上。快速定位的另一个技巧是开prompt构建日志。我在渲染器里埋了一个钩子，每次都把“模板名、变量值、渲染后完整提示词、模型输出摘要”落盘。查问题的时候直接看渲染产物，而不是靠回忆猜模板里写了什么。这一步对我来说几乎是排查效率翻倍的关键。

5.4 提示词问题排查速查表

我自己现在排查复杂提示词问题，基本是巡着这套表走，能省掉大量试错时间。

最后再说一点个人体会。很多人以为提示词编排是“写作文”，其实更接近“设计接口”。模板的边界、变量、版本、评测，每一样都是工程问题而不是文案问题。刚接触Agent开发的朋友，建议第一件事就是从一个小Agent开始，把它的提示词拆成模块、纳入版本、配一份最小评测集。这个基础打好了，后面接工具、做多Agent协作、上生产环境时，会少踩很多用“加班排查”来埋单的坑。