第 15 期：意图识别密码 — System Prompt 与 Tool Description 高级调优

⏱ 预计阅读 11 分钟 更新于 2026/4/9

为什么 Agent 有时"不听话"？

你给 Agent 配了 5 个工具，但它要么在不该调用工具时调用了，要么在该调用时选错了，要么干脆"自己编"了一个不存在的工具名。

这一切的根源在于：System Prompt 和 Tool Description 才是 Agent 的"操纵杆"。

graph TB
    subgraph "影响 Agent 决策的因素 (权重排序)"
        SP[📝 System Prompt
定义角色与行为边界
权重: ⭐⭐⭐⭐⭐]
        TD[🔧 Tool Descriptions
定义何时用什么工具
权重: ⭐⭐⭐⭐]
        MC[🧠 Model Choice
模型能力上限
权重: ⭐⭐⭐]
        T[🌡️ Temperature
输出随机度
权重: ⭐⭐]
    end
    
    SP --> TD --> MC --> T
    
    style SP fill:#ff6d5b,stroke:#e55a4e,color:#fff
    style TD fill:#8b5cf6,stroke:#7c3aed,color:#fff

1. System Prompt 高级结构

// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
// 生产级 System Prompt 模板 (6 段式)
// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

const systemPrompt = `
## 1. 角色定义 (Identity)
你是"小智"，AgentUpdate.ai 的 AI 技术支持助手。
你由 n8n + GPT-4o 驱动，专门负责解答用户关于自动化工作流的问题。

## 2. 核心能力 (Capabilities)
你拥有以下工具:
- calculator: 用于精确数学计算
- web_search: 用于查询最新信息（如最新版本号、发布日期）
- query_docs: 用于检索 AgentUpdate.ai 的官方文档
- create_ticket: 用于创建工程师支持工单

## 3. 决策规则 (Decision Rules)
- 如果问题可以从你的训练知识中直接回答 → 直接回答，不调用工具
- 如果问题涉及精确计算 → 使用 calculator
- 如果问题涉及"最新/在2026年/目前" → 使用 web_search
- 如果问题涉及 AgentUpdate 产品细节 → 使用 query_docs
- 如果你无法解决问题 → 使用 create_ticket 并告知用户

## 4. 行为规范 (Behavior)
- 使用中文回答，技术术语保留英文原文
- 回答不超过 300 字
- 关键命令用代码块包裹
- 禁止编造不存在的功能或 API

## 5. Few-Shot 示例 (Examples)
用户: "n8n 最新版本是什么？"
你的行为: 调用 web_search("n8n latest version 2026") → 获取结果 → 回答

用户: "计算 5000 个节点每月的执行费用"  
你的行为: 调用 calculator("5000 * 0.002 * 30") → 回答

用户: "我的工作流执行失败了，错误码 502"
你的行为: 调用 query_docs("502 error troubleshooting") → 回答

## 6. 禁区 (Boundaries)
- 不讨论竞品（Zapier/Make）的定价或优劣对比
- 不生成任何与工作流无关的内容
- 不编造不存在的 n8n 节点名称
`;

2. Few-Shot 引导技巧

Few-Shot（少量示例）是最有效的 Agent 行为校准手段之一：

graph TB
    subgraph "Few-Shot 引导效果对比"
        subgraph "无示例"
            Q1["用户: 北京到上海多远？"] --> A1["🤖 使用 web_search
❌ 应该直接回答"]
        end
        
        subgraph "有示例 (System Prompt 中)"
            Ex["示例: '法国首都是哪？'
→ 直接回答，不调用工具"]
            Q2["用户: 北京到上海多远？"] --> A2["🤖 约 1318 公里
✅ 直接回答"]
        end
    end
    
    style Ex fill:#22c55e,stroke:#16a34a,color:#fff
// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
// System Prompt 中的 Few-Shot 示例格式
// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

// ✅ 好的 Few-Shot (展示决策过程):
// """
// ### 示例对话
// 用户: "JavaScript 的 map 函数怎么用？"
// 分析: 这是通用编程知识，不需要任何工具
// 行为: 直接回答
// 回复: "map() 用于遍历数组..."
//
// 用户: "帮我算一下 1234 * 5.678 / 3.14"
// 分析: 涉及精确计算，使用 calculator 工具
// 行为: 调用 calculator("1234 * 5.678 / 3.14")
// 回复: "计算结果是 2229.87"
// """

// ⚠️ 每种工具至少给一个正面示例 + 一个反面示例 (不该用的时候)

3. Tool Description 的 WHAT-WHEN-NOT 三段式

// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
// 每个 Tool 的 Description 都应包含三段
// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

const toolDescription = `
WHAT: 根据产品 SKU 编号查询实时库存数量和仓库位置。
      输入参数: sku (字符串，如 "SKU-2026-001")
      返回格式: {"stock": 42, "warehouse": "上海仓", "lastUpdated": "2026-04-09"}

WHEN: 仅当用户明确询问以下内容时使用:
      - "XX 产品还有多少库存？"
      - "XX 在哪个仓库？"
      - "XX 还有货吗？"

NOT:  以下情况不要使用此工具:
      - 用户询问产品价格 (用 query_pricing 工具)
      - 用户询问订单状态 (用 query_order 工具)
      - 用户在闲聊或问非产品相关的问题
`;

4. 调试 Agent 工具选择

graph TB
    subgraph "Agent 调试清单"
        Test[测试用户输入] --> Check1{Agent 调用了正确的工具?}
        
        Check1 -->|"✅ 是"| Check2{参数传递正确?}
        Check1 -->|"❌ 否"| Fix1["修改 Tool Description
或 System Prompt"]
        
        Check2 -->|"✅ 是"| Check3{回复质量满意?}
        Check2 -->|"❌ 否"| Fix2["检查 $fromAI() 参数名
是否与描述匹配"]
        
        Check3 -->|"✅ 是"| Done[✅ 调优完成]
        Check3 -->|"❌ 否"| Fix3["调整 Temperature
或添加 Few-Shot 示例"]
    end
    
    style Fix1 fill:#ef4444,stroke:#dc2626,color:#fff
    style Fix2 fill:#f59e0b,stroke:#d97706,color:#fff
    style Fix3 fill:#3b82f6,stroke:#2563eb,color:#fff
// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
// 调试技巧: 查看 Agent 的内部推理
// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

// 在 n8n 编辑器中, 执行工作流后:
// 1. 点击 AI Agent 节点
// 2. 切换到 "Output" Tab
// 3. 展开 "Logs" 部分
// 4. 你会看到:
//    - LLM 的原始推理过程
//    - Tool Call 的请求与响应
//    - 最终合成回复的过程
//
// 这是 n8n Agent 最强大的调试武器！
// 在其他平台(如 Claude/ChatGPT)，你看不到这些内部日志

模块三总结

mindmap
  root((模块三: AI Agent 核心))
    Ep 11 模型接入
      凭证配置
      模型选型对比
      LLM Chain 基础
      Temperature 调优
    Ep 12 对话机器人
      Chat Trigger
      AI Agent 节点
      Agentic Loop
      System Prompt 设计
    Ep 13 记忆管理
      Window Buffer
      Session 隔离
      消息注入原理
      Memory 类型对比
    Ep 14 工具接入
      Function Calling 机制
      内置工具集
      HTTP Request Tool
      Tool Description 法则
    Ep 15 高级调优
      6段式 System Prompt
      Few-Shot 引导
      WHAT-WHEN-NOT 三段式
      Agent 调试流程

下一步

恭喜完成模块三！你的 Agent 已经具备了"思考 + 记忆 + 行动"的完整能力。从 Ep 16 开始，我们进入 RAG 知识库 领域——让 Agent 不仅聪明，还拥有你企业独有的"领域知识"。