Agent Prompt 工程指南 ：从定义到自动化优化的生产级实践

Agent Prompt 工程指南 ：从定义到自动化优化的生产级实践

摘要：在 Agent 开发（如基于 LangChain 或 AutoGen）中，Prompt 不再是简单的自然语言对话，而是一套精密的指令代码（Instruction Code）。本文将深入拆解 Agent 全生命周期（角色设定、规划、工具描述、错误反思）的 Prompt 定义逻辑，提供生产环境下的代码级案例（如 XML 结构化、JSON Schema 优化），并介绍利用 DSPy 实现 Prompt 自动化编译的前沿实践。

---

一、 Agent 全流程 Prompt 定义：模块化拆解

一个健壮的 Agent 系统，其 Prompt 是模块化的。我们需要针对System（系统层）、Planner（规划层）、Executor（执行层） 和 Reflector（反思层） 分别定义指令。

1. 角色定义 (System Prompt)：确立“人设”与“硬性边界”

这是 Agent 的“宪法”。在生产中，单纯的“你是一个助手”是无效的，必须包含任务目标、行为约束和输出协议。

• 优化策略：使用 XML 标签隔离上下文，防止指令漂移。
• 生产级示例（SQL 数据分析 Agent）：

  <system_instructions>
  <role>
  你是一个资深的数据仓库专家（Data Warehouse Specialist）。你的任务是将用户的自然语言问题转化为高效、安全的 SQL 查询语句，并解释查询结果。
  </role>
  
  <context>
  当前数据库方言：PostgreSQL 14
  表结构信息：参考后续提供的 <schema> 标签。
  </context>
  
  <constraints>
  1. **只读原则**：严禁生成 INSERT, UPDATE, DELETE, DROP 等修改数据的语句。
  2. **幻觉抑制**：如果问题涉及表中不存在的字段，必须直接回复“无法查询”，禁止猜测字段名。
  3. **性能保护**：所有的 SELECT 查询必须包含 `LIMIT` 子句，最大限制为 100 行。
  4. **拒绝回答**：拒绝任何与数据分析无关的闲聊。
  </constraints>
  
  <output_format>
  必须仅返回 JSON 格式，结构如下：
  {
    "thought": "分析用户意图和表结构的思考过程",
    "sql": "生成的SQL语句",
    "is_safe": true/false
  }
  </output_format>
  </system_instructions>
  

2. 规划与推理 (Reasoning/Planning Prompt)：定义“思考路径”

这是 ReAct (Reasoning + Acting) 模式的核心。我们需要强制模型显式输出思考过程，这能显著提高复杂任务的准确率。

• 优化策略：强制绑定思维链（CoT）标签，将“思考”与“行动”解耦。
• 生产级模板：

  <instruction>
  为了回答用户的问题，你必须遵循严格的 **ReAct** 循环：
  
  1. **<thought>**：
     - 分析用户请求的核心意图。
     - 检查当前已有的信息（Context）。
     - 决定下一步是需要调用工具（Tool），还是直接回答（Answer）。
  
  2. **<call>**（如果需要使用工具）：
     - 选择最合适的工具名称。
     - 生成符合工具定义的 JSON 参数。
  
  3. **<observation>**（系统自动回填）：
     - 等待工具执行的结果。
  
  4. **<reflection>**：
     - 检查 <observation> 是否解决了问题。
     - 如果报错，分析原因并修正参数。
     - 如果信息不足，规划下一个工具调用。
  </instruction>
  
  <example>
  User: "查询特斯拉昨天的收盘价"
  Assistant:
  <thought>用户想查询股票价格，我需要使用 stock_api。特斯拉的代码是 TSLA，时间是昨天。</thought>
  <call>{"name": "stock_api", "params": {"symbol": "TSLA", "date": "2023-10-20"}}</call>
  </example>
  

3. 工具描述 (Tool Definition)：JSON Schema 优于 Docstring

LLM 并不是通过“理解”函数代码来调用工具的，而是通过阅读你提供的工具描述。在 OpenAI Function Calling 体系中，Schema 的质量决定了调用的准确率。

• 反面教材 (Bad)：

  def search_order(id):
      """查询订单"""
      pass
  

• 生产级优化 (Good)：使用 Pydantic 或 JSON Schema 描述，强调边缘情况。

  {
    "name": "search_order_details",
    "description": "根据订单ID查询详细信息。注意：此工具仅支持查询‘已支付’或‘已发货’状态的订单。如果订单处于‘草稿’状态，查询将返回空。",
    "parameters": {
      "type": "object",
      "properties": {
        "order_id": {
          "type": "string",
          "description": "以 'ORD-' 开头的 12 位唯一订单编号，例如 ORD-20231101-X9",
          "pattern": "^ORD-\\d{8}-[A-Z0-9]{2}$" 
        },
        "include_sensitive_info": {
          "type": "boolean",
          "description": "是否返回用户手机号等敏感信息，默认为 False。只有在用户明确要求‘查看联系方式’时才设为 True。"
        }
      },
      "required": ["order_id"]
    }
  }
  

  • 核心技巧：在 description 中加入 pattern（正则）和业务逻辑限制（如“仅支持已支付”），能大幅减少无效调用。

4. 错误自愈 (Self-Correction Prompt)

当 Tool 调用失败时，Agent 往往会由“幻觉”接管。我们需要插入一段“注入式 Prompt”来引导其自我修正。

• 生产级示例：

  [System Alert: Tool Execution Failed]
  工具 `sql_executor` 执行失败。
  错误信息: `Column 'revenue' does not exist in table 'sales'. Did you mean 'total_sales'?`
  
  <recovery_instruction>
  请不要放弃任务。
  1. 仔细阅读上述数据库报错信息。
  2. 你的上一条 SQL 中使用了错误的字段名。
  3. 参考 Schema 重新修正 SQL 语句。
  4. 再次尝试调用工具。
  </recovery_instruction>
  

---

二、 生产环境 Prompt 优化技巧

1. 动态 Few-Shot (RAG-based Few-Shot)

写死 3 个例子通常不够用。在生产中，我们使用向量数据库检索与当前问题最相似的 3 个历史成功案例，动态插入 Prompt。

• Prompt 结构：

  ... (System Prompt) ...
  
  <relevant_examples>
  Here are some examples of how to handle similar requests:
  
  [Example 1 - 相似度 0.89]
  User: 帮我订一张去上海的票
  Assistant:  Question: 请问您具体想要哪一天的票？
  
  [Example 2 - 相似度 0.85]
  ...
  </relevant_examples>
  
  User: {current_input}
  

2. 结构化分割符 (Delimiters)

现代模型（Claude 3.5, GPT-4o）对 XML 标签极其敏感。使用 XML 能够显著降低指令混淆，便于后处理解析。

• 推荐标签体系：
  • <context>: 注入的背景知识（RAG 检索结果）。
  • <history>: 对话历史。
  • <scratchpad>: 模型的草稿区（思维链）。
  • <final_answer>: 最终给用户的回复。

3. 思维链 (Chain of Thought) 的高级用法

• Plan-and-Solve: 对于极度复杂的任务，先让模型生成一个 Plan，再执行。

  “First, list all the steps needed to solve this problem. Then, execute them one by one.”

• Emotion Prompting (情感激励):

  “This is very important for my career.” (经论文验证，在某些逻辑任务上能提升 5%-10% 的表现)。

---

三、 迈向自动化：DSPy 与 Meta-Prompting

手动调优 Prompt 是不可持续的。未来的趋势是 “Prompt 编译”。

1. Meta-Prompting (让 AI 写 Prompt)

不要自己从零开始写。建立一个 “Prompt Expert Agent”。

• Input: “帮我写一个用于做代码审查（Code Review）的 Agent Prompt。”
• Meta-Prompt:

  你是一个精通 Prompt Engineering 的专家。请基于 CRISPE 框架 (Capacity, Role, Insight, Statement, Personality, Experiment) 为用户生成 Prompt。
  要求：

  1. 定义明确的 XML 输出结构。
  2. 包含 3 个针对边缘情况（Edge Cases）的 Few-Shot 示例。
  3. 增加防止 Prompt Injection 的安全指令。

2. DSPy (Declarative Self-improving Language Programs)

斯坦福推出的框架，核心理念是：将 Prompt 视为模型的参数（Weights），通过优化算法自动调整。

• 传统模式：手动修改 Prompt 字符串 -> 测试 -> 再修改。
• DSPy 模式：
  1. 定义 Signature（输入输出签名）：Question -> Answer。
  2. 定义 Module（逻辑流）：Retrieve -> ChainOfThought -> Answer。
  3. 定义 Metric（评估标准）：答案必须包含具体的数字。
  4. Compile (编译)：DSPy 会自动在 Prompt 中尝试不同的 Few-Shot 组合和推理指令，直到在验证集上得分最高。

---

四、 必备工具链

工具	核心价值	生产场景
LangSmith	可观测性 (Observability)	查看 Agent 实际运行时的 Prompt 到底长什么样（变量替换后），分析 Token 消耗。
Promptfoo	回归测试 (Regression Testing)	当你修改了 Prompt 的一句话，确保不会导致以前能回答的问题现在回答不了了。
DSPy	自动优化 (Optimizer)	摆脱“玄学”调优，用算法自动寻找最优 Prompt。

---

五、 总结：Prompt 工程的三个阶段

1. V1.0 (静态指令)：依靠人工经验，写死 System Prompt 和 Tools。适用于简单 Demo。
2. V2.0 (动态增强)：引入 XML 结构、JSON Schema 工具定义、RAG 动态 Few-Shot。适用于大部分生产场景。
3. V3.0 (算法编译)：引入 DSPy，将 Prompt 视为可学习的参数，配合评估管线（Evaluation Pipeline）实现自动化迭代。

最后的忠告：在 Agent 开发中，评估（Evaluation）比编写（Writing）更重要。如果你没有一套测试集来衡量 Prompt 的好坏，那么所有的优化都只是盲人摸象。