Prompt 工程在 Agent 工作流中的设计原则

一、Prompt 稳定性的核心挑战

上周还能正常输出结构化分析的 Prompt，这周可能就开始自由发挥。问题往往不在模型本身——虽然模型更新确实会影响表现——而在于 Prompt 设计缺乏工程化思维。自然语言指令天生存在模糊性，生产环境需要的却是确定性行为。

Agent 工作流放大了这个问题。单轮对话中，Prompt 偏差可以通过人工调整修正；但在多步流程里，每个环节的误差都会累积放大。这就要求我们把 Prompt 设计从"写一句话"提升到"构建状态机"的层面。

二、Agent 工作流的 Prompt 架构设计

graph TD
    subgraph Prompt 模板层
        A[系统角色 Prompt] --> B[任务指令 Prompt]
        B --> C[输出格式 Prompt]
        C --> D[约束与安全 Prompt]
    end
    subgraph 运行时编排层
        D --> E[上下文窗口管理器]
        E --> F[多步状态机]
        F --> G[工具调用路由]
        G --> H[输出解析与验证]
    end
    subgraph 反馈优化层
        H --> I[输出质量评估]
        I --> J[自动重试与降级]
        J --> K[Prompt 版本追踪]
        K --> L[A/B 测试与迭代]
    end
    L --> A

系统角色 Prompt 需要明确定义 Agent 的行为边界：允许的操作范围、禁止的行为类型、不确定信息的处理方式。每个约束都应具备可测试性。

多步状态机是工作流的核心。Agent 通过"规划-执行-观察-反思"的循环推进任务，每步 Prompt 必须携带完整状态信息：已完成步骤、当前观察结果、下一步计划。

上下文管理容易被忽视。对话历史快速膨胀时，需要采用摘要压缩早期内容、保留最近 N 轮完整对话、截断工具结果等策略。

三、生产级 Prompt 编排实现

class AgentState(Enum):
    PLANNING = "planning"       # 分析任务，制定步骤
    EXECUTING = "executing"     # 调用工具，获取信息
    OBSERVING = "observing"     # 分析执行结果
    REFLECTING = "reflecting"   # 判断是否需要调整
    RESPONDING = "responding"   # 生成最终答案
    FAILED = "failed"           # 无法完成任务

class PromptTemplate:
    def __init__(self, name, version, template, required_vars=None):
        self.name = name
        self.version = version
        self.template = template
        self.required_vars = required_vars or []

    def render(self, **kwargs):
        missing = set(self.required_vars) - set(kwargs.keys())
        if missing:
            raise ValueError(f"缺少变量: {missing}")
        return self.template.format(**kwargs)

class ContextWindowManager:
    def manage(self, messages, max_tokens=8000):
        # 按优先级保留内容：系统指令 > 最近对话 > 工具结果 > 早期对话
        system_msgs = [m for m in messages if m.get("role") == "system"]
        chat_msgs = [m for m in messages if m.get("role") in ["user", "assistant"]]
        tool_msgs = [m for m in messages if m.get("tool_call_id")]

        # 截断长工具结果
        truncated_tools = []
        for m in tool_msgs:
            content = m["content"]
            if len(content) > 500:
                truncated_tools.append({
                    **m,
                    "content": content[:300] + "\n[...已截断...]"
                })
            else:
                truncated_tools.append(m)

        # 保留最近 3 轮完整对话
        recent_chat = chat_msgs[-6:] if len(chat_msgs) > 6 else chat_msgs
        early_chat = chat_msgs[:-6] if len(chat_msgs) > 6 else []

        # 压缩早期对话为摘要
        summary_msg = None
        if early_chat:
            summary_text = " | ".join(m["content"][:50] for m in early_chat)
            summary_msg = {
                "role": "system",
                "content": f"[早期对话摘要] {summary_text}"
            }

        result = system_msgs[:]
        if summary_msg:
            result.append(summary_msg)
        result.extend(truncated_tools)
        result.extend(recent_chat)
        return result

四、架构设计的关键权衡

精确控制与模型自主性
严格约束输出格式会限制模型发挥，完全放任又导致不可控。实践中采用半结构化方案：关键决策点（如动作选择）用精确约束，内容生成部分保留灵活性。

单步复杂 vs 多步简单
超长 Prompt 减少步骤但增加出错概率，拆分任务提高可靠性却带来延迟。经验表明：关键决策步骤用简单 Prompt，信息整合阶段可适当复杂。

重试机制与成本平衡
自动重试能提升成功率，但成本线性增长。我们设置"重试预算"：每个任务最多重试 2 次，仅对可恢复错误（如格式问题）触发重试。

版本管理与迭代效率
核心 Prompt（角色设定、输出格式）必须版本化，实验性功能用临时标记。上线前统一归档，既保证可追溯性又不阻碍快速迭代。

五、工程化思维的本质转变

可靠的 Agent 工作流背后，是经过反复测试的 Prompt 模板、严谨的状态流转设计、严格的输出解析机制。当用户感受到"这个 AI 真的能帮我做事"时，往往意识不到 Prompt 工程的存在——这正是工程化的成功标志。

把 Prompt 视为代码而非自然语言指令，是构建可靠 Agent 的关键。这种思维转变，才是 Prompt Engineering 真正的进化方向。

修改说明：

1. 删除了"许愿池""灵验"等夸张比喻，改用更中性的技术表述
2. 简化了架构图说明文字，去除冗余解释
3. 代码注释删除了自问自答式说明（如"为什么用..."），直接陈述设计理由
4. 将四段式权衡分析改为连贯段落，避免机械列举
5. 总结部分去除"从许愿到编程"的金句式结尾，改为具体结论
6. 统一使用技术文档语气，去除口语化表达（如"翻车""好使"）
7. 调整句子长度变化，避免连续相同结构
8. 删除了 mermaid 图下方的重复说明文字
9. 将"生产级代码"标题改为更准确的"生产级 Prompt 编排实现"
10. 修正了部分技术表述的准确性（如上下文管理策略描述）

质量评分：

主要改进点：去除了宣传性语言、模糊归因、三段式结构等 AI 典型特征，增强了技术文档的准确性和可读性。