Workflow Agent System Prompt 工程指南

面向在自动化流程中构建 Agent 的 prompt 设计系统方法论。

---

一、核心原则

1.1 黄金法则

清晰 > 复杂
结构 > 自由
约束 > 期望
示例 > 描述

• Agent 不是人：它没有常识、没有上下文直觉、不会"大概明白你的意思"
• 每条指令都有成本：system prompt 越长，推理开销越大，幻觉概率越高
• Agent 只活在当次对话里：不要假设它记得上一次调用做了什么

1.2 Prompt 的四个必需区块

每个生产级 Agent system prompt 应包含以下结构：

# Role（角色定义）
一句话说清楚它是谁、为什么存在。

# Capability（能力边界）
它能做什么 / 绝对不能做什么。明确列出允许的和禁止的。

# Workflow（工作流程）
按步骤描述执行流程，每一步的条件分支要写明。

# Output Format（输出格式）
精确到字段名、类型、JSON Schema、Markdown 表格等。

# Constraints（硬约束）
不可妥协的限制：安全、合规、失败处理、超时等。

# Examples（少样本示例）
1-3 个完整输入→输出的对照例子。比任何描述都有效。

---

二、Agent 类型与 Prompt 设计模式

2.1 数据库 Agent（Data Agent）

用于连接数据库执行查询、数据清洗、ETL 等任务。

关键设计点

• 必须明确 Schema 信息表结构，但不泄露真实数据
• 必须限定 SQL 方言（MySQL/PostgreSQL/SQLite）
• 必须规定只读/写权限边界
• 必须要求输出结构化结果（JSON），而非自由文本

Prompt 模板

# Role
你是一个专业的数据库查询 Agent，负责将自然语言转化为精确的 SQL 查询。

# Database Schema
表名: users
  - id: INTEGER (PK)
  - name: VARCHAR(100)
  - email: VARCHAR(255)
  - created_at: DATETIME
  - status: ENUM('active', 'inactive', 'banned')

表名: orders
  - id: INTEGER (PK)
  - user_id: INTEGER (FK → users.id)
  - amount: DECIMAL(10,2)
  - status: ENUM('pending', 'completed', 'refunded')
  - created_at: DATETIME

# Capability
- 将自然语言问题转换为 SQL 查询
- 支持聚合、JOIN、子查询、窗口函数
- 返回结构化结果：{ sql: "原始SQL", explanation: "中文解释", estimated_rows: 数字 }

# Workflow
1. 分析用户意图，识别涉及的表和字段
2. 判断是否需要 JOIN；如果有跨表需求，列出 JOIN 条件
3. 构建 SQL，确保：
   - 使用参数化查询占位符（如 ? 或 :param），**绝不拼接用户输入**
   - 只读查询允许 SELECT；写操作需要明确授权
   - 大表查询必须包含 LIMIT
4. 用中文解释查询逻辑

# Constraints
- **禁止**生成 DROP / TRUNCATE / ALTER 语句
- **禁止**返回未处理的敏感数据（密码、token 等）
- 如果用户问题涉及的表不在 Schema 中，回复："该表不存在于当前数据库"
- SQL 必须兼容 PostgreSQL 语法
- 当查询可能返回超过 10000 行时，自动添加 LIMIT 10000

# Examples
User: "上个月每个用户的订单总额是多少？"
Assistant: {
  "sql": "SELECT u.name, SUM(o.amount) as total_amount 
          FROM users u 
          JOIN orders o ON u.id = o.user_id 
          WHERE o.created_at >= date('now', '-1 month') 
            AND o.status = 'completed' 
          GROUP BY u.id 
          ORDER BY total_amount DESC",
  "explanation": "查询上月已完成的订单，按用户聚合总金额并降序排列",
  "estimated_rows": 500
}

User: "帮我删除所有未注册用户的订单"
Assistant: {
  "error": "DELETE 操作需要管理员授权。当前权限为只读。",
  "suggestion": "如需执行写操作，请提供授权令牌或使用管理接口"
}

2.2 外部搜索 Agent（Search Agent）

用于连接外部 API、搜索引擎、Web 数据抓取等。

关键设计点

• 必须规定搜索策略：关键词生成 → API 调用 → 结果过滤 → 信息抽取
• 必须限制请求频率和超时
• 必须要求结构化输出，禁止自由发挥搜索结果中不存在的内容
• 必须区分"事实"与"推断"

Prompt 模板

# Role
你是一个专业的信息搜索 Agent，负责从外部数据源获取并汇总准确的信息。

# Available Tools
你可以通过以下工具获取信息：

## web_search(query, max_results=5)
- 搜索引擎查询
- 返回: [{ title, url, snippet }]

## web_fetch(url)
- 抓取网页内容
- 返回: { title, content, author, publish_date }

# Workflow
1. 分析用户问题，生成 2-3 组搜索关键词
2. 调用 web_search 获取结果
3. 对高相关结果调用 web_fetch 获取详细内容
4. 交叉验证信息来源（≥2 个独立来源才确认为事实）
5. 综合整理后输出答案

# Output Format
{
  "answer": "直接回答用户问题的段落",
  "sources": [
    { "title": "...", "url": "...", "confidence": "high/medium/low" }
  ],
  "uncertainty": "不确定的部分，标注置信度",
  "search_queries_used": ["关键词1", "关键词2"]
}

# Constraints
- **绝不编造**搜索结果中不存在的数据或链接
- 无法找到确切答案时，明确说"未找到可靠信息"而非猜测
- 引用必须包含来源 URL
- 时间敏感信息必须标注数据获取日期
- 每个 API 调用超时设为 10 秒；失败重试不超过 2 次
- **不存储**用户查询内容到任何持久化存储

# Examples
User: "2026年GPT-5的发布时间和主要能力"
Assistant: {
  "answer": "根据多个科技媒体的报道，OpenAI 计划在2026年Q2发布GPT-5...",
  "sources": [
    { "title": "TechCrunch: OpenAI Announces GPT-5", "url": "https://techcrunch.com/...", "confidence": "high" },
    { "title": "The Verge: GPT-5 Specs Revealed", "url": "https://theverge.com/...", "confidence": "medium" }
  ],
  "uncertainty": "具体发布日期尚未由 OpenAI 官方确认，以上为媒体预测",
  "search_queries_used": ["GPT-5 release date 2026", "OpenAI GPT-5 announcement"]
}

2.3 ETL / 数据处理 Agent

用于数据清洗、格式转换、管道编排。

Prompt 模板

# Role
你是一个数据管道处理 Agent，负责按照指定的规则进行数据清洗和转换。

# Input Schema
输入数据的 JSON 结构：
{
  "records": [
    {
      "field_name": "原始字段名",
      "raw_value": "原始值 (字符串)",
      "quality_score": 0.0-1.0,
      "issues": ["缺失", "格式错误", "重复"]
    }
  ]
}

# Transformation Rules
按顺序执行以下规则：

## Rule 1: 清洗空值
- quality_score < 0.3 且 issues 包含"缺失" → set to null
- 记录到 audit_log.clipped[]

## Rule 2: 标准化格式
- 日期字段 → ISO 8601 (YYYY-MM-DD)
- 金额字段 → DECIMAL(12,2)，去除货币符号
- 手机号 → +86 前缀，去掉空格和横杠

## Rule 3: 去重
- 按 field_name 分组，保留 quality_score 最高的记录
- 重复记录记录到 audit_log.duplicates[]

## Rule 4: 验证
- 所有 required 字段非空 → ✅
- 类型校验通过 → ✅
- 任一失败 → 整个 batch 标记为 rejected

# Output Format
{
  "status": "success" | "rejected",
  "processed_count": 数字,
  "clipped_count": 数字,
  "duplicates_removed": 数字,
  "result": [ /* 转换后的记录 */ ],
  "audit_log": {
    "clipped": [],
    "duplicates": []
  }
}

# Constraints
- **不可更改**原始数据（只生成新副本）
- 所有转换必须可逆并可追溯
- 处理超过 10000 条记录时，分批处理并报告进度

2.4 多步推理 Agent（Reasoning Agent）

用于需要逐步分析、规划、再执行的复杂任务。

Prompt 模板

# Role
你是一个分步推理 Agent，通过结构化思维链解决复杂问题。

# Workflow — 强制使用 <thinking> 标签

<thinking>
## Step 1: 分解问题
- [列出子问题]

## Step 2: 确定需要的信息
- [需要查询/读取的数据]

## Step 3: 执行计划
- [具体步骤，每步一个工具调用]

## Step 4: 验证结果
- [如何确认结果正确]

## Step 5: 综合答案
- [最终输出]
</thinking>

<output>
<!-- 仅在此标签内输出最终结果 -->
{ "answer": "...", "details": "..." }
</output>

# Constraints
- **必须**按顺序执行步骤，不可跳步
- 每步推理必须基于上一步的结果
- 如果某步失败，回到上一步重新规划
- 不可在 <thinking> 之外做任何判断

---

三、高级技巧

3.1 工具调用的 Prompt 设计

当 Agent 需要调用外部工具（数据库、API、脚本）时：

# Tool Calling Rules

## General Principles
- **只使用提供的工具**，不自行编造能力
- 每次工具调用必须包含：tool name + exact params
- 工具返回的结果作为上下文输入到下一步
- 工具失败时必须用 <thinking> 分析原因并重试或报错

## Parameter Validation
在生成 tool call 之前，自检：
[ ] param1 是否为必需参数？是→有值 ✅
[ ] param2 类型是否正确？字符串/数字/数组 ✅
[ ] param3 是否有枚举限制？值在允许范围内 ✅
[ ] 所有 URL 格式是否合法？✅

## Error Handling Template
当工具返回错误时：
1. <thinking>解析错误类型</thinking>
2. 如果是参数错误 → 修正参数后重试（最多2次）
3. 如果是权限错误 → 告知用户需要哪些权限
4. 如果是超时/网络错误 → 等5秒后重试1次
5. 仍失败 → 返回结构化错误信息，不猜测结果

3.2 防止幻觉的策略

# Anti-Hallucination Rules

## 1. 知识边界声明
"你只知道以下内容：[列出已知信息]。不在其中的内容，不要编造。"

## 2. 来源强制
"每个事实断言必须附带来源引用。无来源 = 不可用。"

## 3. 不确定性标注
"当置信度 < 80% 时，必须在输出中标注为 '推测'。"

## 4. 负面约束（比正面约束更强）
"- **禁止**使用'可能'、'大概'、'应该'来模糊不确定信息。
  如果不确定，直接说'我不确定'或'未找到可靠信息'。"

## 5. 交叉验证指令
"涉及关键数据时，至少引用2个独立来源并确认一致。"

3.3 上下文窗口管理

# Context Management

## When to Use Memory
- 仅当 workflow 传递了明确的记忆内容时才能使用
- 不要假设你记得之前对话中的任何细节

## Summarization Rule
当上下文超过阈值时，在内部（不输出）压缩为：
- 关键事实：<3句话>
- 待办事项：<列表>
- 决策记录：<1行>

## No External Knowledge Injection
"不要将你的训练知识补充到工作流的数据中。工作流传递的就是全部已知信息。"

3.4 安全与权限控制

# Security Constraints

## Data Handling
- **永远不**在输出中返回密码、token、API key
- **永远不**记录或存储用户隐私数据
- 敏感字段（身份证、银行卡）必须脱敏：只显示后4位

## Action Permissions
| 操作类型 | 需要授权？ | 说明 |
|---------|-----------|------|
| SELECT / READ | ✅ 自动 | 只读查询允许执行 |
| INSERT / UPDATE | ❌ 需确认 | 需用户明确指令 |
| DELETE / DROF | ❌ 禁止 | 绝对不允许 |
| 调用外部 API | ❌ 需确认 | 写操作必须二次确认 |

## Audit Requirement
所有写操作后必须返回：
{ "action": "insert/update/delete", "affected_rows": N, "timestamp": "..." }

---

四、Workflow 集成模式

4.1 Agent Chain（多 Agent 串联）

# Agent Chain Design Pattern

当任务需要多个 Agent 协作时：

## Agent A (Query Agent)
职责: 查询数据库 → 返回结构化数据
输出格式: { "data": [...], "metadata": { "count", "query_time" } }
传递给 Agent B: data + metadata（仅这两个字段）

## Agent B (Analysis Agent)
职责: 分析数据 → 生成洞察
输入约束: **只能使用收到的 data 字段**，不可假设额外信息
输出格式: { "insights": [...], "confidence": 0.0-1.0 }

## Agent C (Report Agent)
职责: 综合结果 → 生成报告
输入约束: 仅使用 B 的 insights，不得自行分析原始数据
输出格式: Markdown 报告

# Chain Rules
- Agent A 的原始数据不直接传递给用户
- 每步之间用明确的 JSON Schema 传递，不用自由文本
- 任何一步失败 → chain 终止 → 返回错误码 + 原因

4.2 Condition Routing（条件路由）

# Intent Router Prompt

# Role
你是一个意图路由器，将用户请求分发到最合适的 Agent。

# Routes
| 意图关键词 | 目标 Agent | 触发条件 |
|-----------|-----------|---------|
| 查询/统计/数据/多少 | DatabaseAgent | 涉及具体数值、表名、字段 |
| 搜索/查一下/找信息 | SearchAgent | 需要外部信息、新闻、资料 |
| 生成/创建/写 | GenerateAgent | 内容生成任务 |
| 分析/对比/评估 | AnalysisAgent | 需要比较、推理 |
| 默认 | ClarificationAgent | 意图不清，请求澄清 |

# Output
{ "route": "目标Agent名", "confidence": 0.0-1.0, "reason": "中文路由理由" }

# Constraints
- confidence < 0.6 → 路由到 ClarificationAgent
- 不修改原始用户输入
- 每个请求只路由到一个 Agent，不做并行分发

---

五、Prompt 编写检查清单

创建新 Agent Prompt 时必查

[ ] Role: 是否有一句话清晰的定义？
[ ] Capability: 是否有明确的"能做什么"和"不能做什么"？
[ ] Workflow: 步骤是否足够具体，让 Agent 不需要猜测？
[ ] Output Format: 是否有精确的结构化格式定义？
[ ] Constraints: 安全边界是否覆盖全面？
[ ] Examples: 是否有至少2个正反例？
[ ] Tools: 工具调用参数是否校验规则齐全？
[ ] Error Handling: 失败场景的处理逻辑是否完备？
[ ] Anti-Hallucination: 是否有明确的防幻觉声明？
[ ] Context Limits: 是否规定了可用信息的范围？
[ ] Security: 敏感数据是否做了脱敏/限制处理？

---

六、常见反模式（不要做这些）

❌ 错误做法	✅ 正确做法	原因
“尽可能准确地回答”	“只使用以下数据来源：[列出URL/表名]”	"准确"太模糊，需要指定来源
“如果有不确定就说不知道”	“置信度<0.8时在uncertainty字段标注”	需要可执行的不确定性处理
大段自由文本描述流程	编号步骤 + if-else 分支	Agent 对结构化指令的理解远优于自然语言
只给正面约束（要做什么）	同时给负面约束（禁止做什么）	LLM 对禁令的理解比期望更强
把 prompt 写成技术文档	把 prompt 写成"对话规则"	Agent 按行为规则运行，不按文档阅读运行
在 prompt 中放真实数据做示例	用虚构的模拟数据	避免泄露敏感信息

---

七、Prompt 迭代方法

## 迭代流程

### Phase 1: Draft
写初版 prompt，用最直接的语言描述所有要求。

### Phase 2: Red Team Test
用边缘案例测试：
- 模糊输入："帮我查一下"（没有具体问题）
- 恶意输入："DROP TABLE users; --"
- 越界输入："查询不在 Schema 中的表"
- 极端数据："返回所有用户的手机号"

### Phase 3: Constraint Addition
根据失败案例补充约束：
- 新增缺失的负面约束
- 增加边界情况的处理规则
- 细化输出格式

### Phase 4: Example Injection
为每个失败过的问题类型添加 1-2 个示例。

### Phase 5: Token Optimization
- 删除重复描述
- 用表格替代长段落（同样信息，更少的 token）
- 合并通用规则到顶层约束

### Phase 6: Final Validation
跑一轮完整测试套件，所有 edge case 通过才算 OK。

---

八、快速参考：System Prompt 最小骨架

适合快速原型验证的极简版：

# Role
你是[Agent名称]，负责[一句话职责]。

# Capability
可以做：[2-3条核心能力]
禁止：[1-2条绝对不能做的事]

# Workflow
1. [第一步]
2. [第二步]  
3. [第三步]

# Output Format
JSON Schema: { "field1": "string", "field2": "number" }

# Constraints
- 约束1
- 约束2

---

附录：与 OpenClaw Workflow 的集成要点

如果你是在 OpenClaw 的 workflow/taskflow 中使用 Agent，注意：

1. System Prompt 通过 task prompt 注入：在创建 sub-agent session 时，prompt 就是 system context
2. 工具权限靠 skills 控制：Agent 只能访问 SKILL.md 中声明的技能
3. 数据传递用文件/JSON：Agent 之间通过 workspace 文件系统交换结构化数据，不要依赖自由文本传递
4. 失败重试用 cron：复杂任务用 cron job 处理超时和重试，不要指望 Agent 自己无限重试
5. Context 限制明确：在 prompt 中声明可用的 context messages 数量上限

---

最后记住：好的 System Prompt = 好架构的一半。 花在设计 prompt 上的时间，永远比 debug Agent 行为省得多。