1. 从一次失败的Agent调用说起

那天下午，我正试图用LangChain的Deep Agents框架构建一个简单的数据分析助手。我的想法很直接：让Agent调用一个Python工具，对用户上传的CSV文件进行描述性统计。我按照官方示例，配置了工具、设定了目标，信心满满地运行。结果，Agent返回的是一堆逻辑混乱、答非所问的文本，它甚至试图去“理解”文件路径的情感色彩，而不是执行pandas.describe()。那一刻我意识到，问题不在工具，也不在大模型，而在于我完全忽略了驱动整个Agent行为的核心——System Prompt（系统提示词）。

在LangChain Deep Agents的架构里，System Prompt绝非一个简单的“你是一个有帮助的助手”的声明。它是一个经过精密计算、多层叠加的复合指令体，是Agent的“宪法”和“行为准则”。很多开发者，包括最初的我，都栽在了对它的轻视上。我们以为配置好工具链就万事大吉，却不知一个构建不当的System Prompt，足以让最强大的模型和工具组合变得毫无用处。本文将深入LangChain Deep Agents的源码，拆解其System Prompt的组装逻辑，揭示那四层叠加结构背后的设计哲学与潜规则。理解这些，你才能从“能用Agent”进阶到“精通Agent”，真正掌控其行为边界与效能。

2. 解剖Deep Agents的System Prompt：四层盔甲是如何穿上的

Deep Agents的System Prompt并非凭空生成，它是一套模块化、层次化的组装结果。通过追踪源码（主要集中在langchain/agents/deep_agents/目录下的相关类，如DeepAgent及其父类），我们可以清晰地看到其构建路径。整个过程就像给Agent穿上四层盔甲，每一层都承担着特定的职责，共同定义了Agent的最终形态。

2.1 第零层：Base Prompt —— 模型的出厂设置

在LangChain介入之前，大语言模型本身有一个默认的、极简的System Prompt。例如，某些模型可能预设为“You are a helpful AI assistant.”。这一层是模型的“出厂设置”，Deep Agents通常不会直接修改它，但它是所有后续叠加的基础。我们需要意识到它的存在，因为当上层的指令不够强力或清晰时，模型可能会不自觉地回退到这一层默认行为模式中。

注意：不同模型厂商（如OpenAI、Anthropic、Google）的Base Prompt差异巨大。有些允许完全覆盖，有些则会在后台隐式拼接。这是导致同一套Agent代码在不同模型上表现迥异的第一个潜在原因。

2.2 第一层：Role & Goal Definition —— 定义身份与核心使命

这是Deep Agents框架显式添加的第一层，也是最重要的一层。它直接回答了“你是谁？”和“你要干什么？”这两个根本问题。源码中，这部分内容通常由DeepAgent类的_construct_system_message或类似方法组装。

这一层的模板通常包含以下核心要素：

1. 身份（Role）：明确告知模型它现在扮演的角色，例如“你是一个专业的数据分析助手”、“你是一个代码安全审查专家”。
2. 核心目标（Goal）：清晰陈述Agent的终极任务，例如“你的目标是帮助用户分析数据，并给出洞察”、“你的任务是审查代码片段中的安全漏洞”。
3. 工作边界（Boundary）：初步划定范围，比如“你只能使用我提供给你的工具，不能自行编造信息”。

在源码里，你可能会看到类似下面的逻辑（伪代码表示）：

role_goal_prompt = f""" 你是一个{agent_role}。 你的核心目标是：{agent_goal}。 你必须遵循以下原则： - 始终专注于你的目标。 - 仅使用提供的工具来完成任务。 """

潜规则一：越具体，越强大。“数据分析助手”不如“精通Pandas和NumPy，擅长从数据分布中发现异常点的数据分析专家”来得有效。目标描述也应尽可能具体化、场景化。

2.3 第二层：Tool & Capability Injection —— 注入能力与使用规范

定义了角色和目标后，接下来就要告诉Agent“你能用什么”。这一层将用户定义的工具（Tools）及其使用规范注入到System Prompt中。LangChain会自动将工具的函数名、描述、参数列表格式化成一个清晰的文本块，拼接到提示词中。

关键点在于，工具的描述（description）至关重要。模型主要依靠描述来理解工具的用途。一个模糊的描述如“处理数据”，会导致模型误用或滥用工具。一个清晰的描述应是：“此工具用于计算输入DataFrame的数值型列的描述性统计，包括计数、均值、标准差、最小值、四分位数和最大值。输入应为df（一个Pandas DataFrame对象）。”

此外，这一层还会加入工具使用的通用规范：

• 如何解析用户请求以决定调用哪个工具。
• 工具调用的输出格式应如何理解。
• 如果一次工具调用无法解决问题，应如何规划后续步骤。

潜规则二：工具描述是给模型看的“产品说明书”。要站在模型的角度，用自然语言清晰、无歧义地说明功能、输入和预期输出。避免使用代码术语，多用“做什么”、“得到什么”这样的句式。

2.4 第三层：Process & Reasoning Constraints —— 约束思维链与流程

这是最体现“Deep”思考的一层，它试图约束模型的内部推理过程，引导其进行结构化思考。Deep Agents 借鉴了诸如“Chain-of-Thought”、“ReAct”等范式，在System Prompt中明确要求模型按照特定步骤进行思考。

典型的约束指令包括：

• 分步思考：“在回答之前，你必须按以下步骤思考：1. 理解用户问题的本质。2. 检查可用工具中哪个能解决。3. 规划工具调用序列。4. 执行并整合结果。”
• 输出格式：“你的最终输出必须是一个完整的分析报告，包含概述、关键发现和建议三部分。”
• 错误处理：“如果工具调用失败或返回错误，分析可能的原因，并尝试替代方案或明确告知用户限制。”
• 禁止行为：“严禁虚构工具参数，严禁在未调用工具的情况下声称已完成任务。”

在源码中，这部分通常以固定的“思考框架”模板出现，与具体的角色、工具解耦，是一种通用的流程控制机制。

潜规则三：过程约束是防止模型“偷懒”或“胡思乱想”的护栏。它强制模型展示其工作记忆，使得Agent的行为更加可预测、可调试。但约束过多会降低灵活性，需要权衡。

2.5 第四层：Session & Context Awareness —— 会话上下文与记忆

最后一层是动态的，它包含了当前会话的上下文信息。这可能包括：

• 对话历史：之前的几轮问答，让Agent具备短期记忆。
• 用户偏好：在会话中用户表现出的特定要求（如“请用中文回答”）。
• 任务中间状态：对于复杂任务，之前步骤的结果或状态。

Deep Agents 的AgentExecutor会在运行过程中，将之前的对话历史（作为ChatMessageHistory）加入到传递给模型的上下文列表中。虽然严格来说，对话历史更多是以HumanMessage/AIMessage的形式存在于消息列表（Message List）中，而非System Prompt本身，但从模型接收的完整上下文视角看，它构成了影响模型行为的最后一层“情境化”信息。

潜规则四：上下文是双刃剑。它能让Agent更连贯，但也可能引入干扰或导致提示词膨胀（超出模型上下文窗口）。需要合理管理历史长度，有时甚至需要主动总结或过滤历史。

3. 源码追踪：组装逻辑的实相与细节

让我们深入到代码层面，看看这四层是如何被具体组装的。以langchain.agents.DeepAgent的一个典型实现路径为例（请注意，LangChain代码迭代快，以下基于常见模式分析）：

组装入口通常在一个名为create_prompt或_construct_system_message的方法中。它会依次调用或拼接多个组件：

1. 获取基础角色/目标模板：这可能来自一个类属性base_template，或者由用户通过参数system_message传入。
2. 工具列表格式化：调用tools_to_prompt(tools)函数，将Tool对象列表转换为一段格式化的文本描述。这个函数会提取每个工具的name和description，并按照一定格式（如Markdown列表）排列。
3. 流程指令拼接：有一个固定的instructions模板字符串，定义了思考步骤、输出格式等。这个模板通常是硬编码在类定义中或从一个配置文件中加载。
4. 最终拼接：执行类似f”{base_template}\n\n## Available Tools:\n{tools_prompt}\n\n## Instructions:\n{instructions}”的操作，生成完整的System Prompt字符串。

一个需要警惕的细节是转义和格式化。如果工具描述或用户目标中包含大括号{}、反斜杠\等字符，在拼接时可能引发格式字符串错误或导致模型误解。稳健的代码会对这些内容进行适当的清理或转义。

另一个细节是顺序重要性。研究发现，大语言模型对提示词开头和结尾部分的内容更为敏感。因此，将最重要的角色定义放在最前面，将关键的行为约束放在最后面，有时能获得更好的遵循效果。Deep Agents的源码中，拼接顺序通常是固定的，但了解这一点有助于你在自定义模板时进行优化。

4. 潜规则实战：调试与优化你的System Prompt

理解了四层结构，我们就可以像调试代码一样调试System Prompt。当你的Agent行为异常时，可以按层排查：

1. 行为偏离目标：检查第一层（Role & Goal）。目标描述是否足够清晰、无歧义？是否与工具能力匹配？尝试将目标写得极度具体，甚至包含负面示例（“不要做X”）。
2. 工具调用错误或不用工具：检查第二层（Tool & Capability）。工具描述是否准确？模型是否能从描述中理解输入输出？尝试用更口语化、场景化的语言重写工具描述。例如，将“query: str”描述为“你需要提供一个搜索关键词，比如‘最新的机器学习论文’”。
3. 思维过程混乱或步骤缺失：检查第三层（Process & Reasoning Constraints）。思考步骤指令是否明确？是否要求模型“逐步输出思考过程”？可以强化指令，如“你必须先输出‘思考：’段落，然后再输出‘回答：’段落”。
4. 遗忘上下文或表现不一致：检查第四层（Session & Context）。是否传递了正确的对话历史？历史是否过长导致关键指令被挤出上下文窗口？考虑使用ConversationSummaryBufferMemory等记忆组件来压缩历史。

一个高效的调试方法是将组装好的完整System Prompt打印出来。在LangChain中，你可以在调用agent_executor.invoke()之前，通过访问agent.llm_chain.prompt.messages[0].content（具体路径可能因版本而异）来获取完整的System Prompt文本。仔细阅读这个文本，站在模型的角度思考，它是否清晰无误地传达了所有必要信息？

优化技巧：少即是多，但关键信息必须重复。不要试图在System Prompt中塞进所有可能的规则。重点突出核心身份、核心任务和核心约束。对于非常重要的指令（如“必须使用工具”），可以在不同层级以不同方式强调。同时，使用清晰的章节标题（如## 角色、## 工具、## 步骤）可以帮助模型更好地解析提示词结构。

5. 超越默认：自定义组装策略与高级模式

Deep Agents提供的四层叠加是一个稳健的默认策略，但并非金科玉律。在复杂场景下，你可能需要自定义组装逻辑。

策略一：动态Prompt生成。根据用户输入或会话状态，动态调整System Prompt。例如，当检测到用户查询涉及“安全”时，在Role层临时加入“你现在是安全专家”的声明。这可以通过自定义一个BaseChatModel的包装器，在_call方法中动态修改传入的system_message来实现。

策略二：分层激活与衰减。并非所有层在所有时刻都需要全功率。对于长对话，可以在后续轮次中简化Process层指令（因为模型可能已经进入状态），或者将一些固定的约束转移到更底层的模型调用参数中（如果模型支持）。

策略三：元Prompt技巧。在真正的System Prompt之前，添加一层更高级的指令，用于指导模型如何理解后续的System Prompt。例如：“以下是一份给你的工作说明书。请仔细阅读并严格遵守说明书的每一个部分。你的表现将根据你对说明书的遵循程度来评估。”这听起来有点“套娃”，但对于某些难以约束的模型，能显著提升指令遵循率。

策略四：工具描述的LLM优化。与其手动编写工具描述，不如用另一个LLM调用（或离线过程）来优化。输入工具的函数签名和代码注释，让LLM生成一段更自然、更全面的描述。这能确保工具描述的质量和一致性。

实现这些高级模式，意味着你可能需要部分重写或继承Deep Agents中负责Prompt组装的类，例如自定义一个DeepAgentCustomPrompt类，重写其_construct_system_message方法。这需要你对LangChain的类继承结构和Prompt的组装流程有更深的理解。

6. 常见陷阱与长效维护建议

在长期使用和开发基于Deep Agents的应用时，以下几个陷阱需要格外留意：

陷阱一：提示词冲突。当四层指令之间存在矛盾时，模型行为会不可预测。例如，Role层说“你是诗人”，但Tool层只提供了数学计算工具。务必确保各层指令协同一致。

陷阱二：上下文窗口耗尽。过多的工具（每个都有长描述）、过长的流程指令、完整的对话历史，很容易让生成的Prompt超出模型的上下文窗口。解决方案包括：使用工具检索（只放入相关工具）、压缩工具描述、总结对话历史、或者升级到拥有更长上下文窗口的模型。

陷阱三：对模型特性的忽视。不同的模型对System Prompt的敏感度、格式偏好不同。为Claude优化的Prompt可能不适合GPT-4。最佳实践是为你的主要目标模型进行专门的Prompt调优，并进行充分的测试。

陷阱四：过度工程化。追求一个完美的、能处理所有边界的System Prompt往往是徒劳的。更好的方法是构建一个“足够好”的基础Prompt，然后通过RAG（检索增强生成）技术，在运行时动态注入具体的、针对当前问题的额外知识和指令。例如，将产品文档作为检索库，在用户询问特定功能时，将相关文档片段作为上下文插入。

为了长效维护，我建议：

1. 将System Prompt模板化、版本化。不要将Prompt硬编码在业务逻辑中。使用配置文件或模板文件来管理，并像管理代码一样进行版本控制。
2. 建立Prompt测试集。针对你的Agent常见任务，构建一组标准测试用例。每次修改Prompt后，运行测试集，量化评估其效果（如任务完成率、工具调用准确率）。
3. 实施监控与日志。在生产环境中，记录下每次调用实际使用的完整Prompt（脱敏后）以及模型的输出。这为事后分析异常行为提供了宝贵的数据。

回到我最初的那个失败的数据分析Agent。在深入System Prompt之后，我重写了Role层，将其定义为“一个严格按步骤操作、只信赖工具输出的数据分析机器人”；我细化了工具描述，明确说明了输入必须是一个Pandas DataFrame对象；我在Process层强制要求它先输出“分析计划”。重新运行后，Agent变得条理清晰，精准地调用工具并给出了完美的统计摘要。那一刻我明白，驾驭LangChain Deep Agents，乃至任何Agent框架，真正的起点和支点，就在于你能否理解和塑造那个无声的“宪法”——System Prompt。它看似只是一段文本，却从根本上定义了智能体的灵魂与能力边界。