AI AGENT SYSTEMS · 01

把 Prompt 变成
可靠的系统契约

从“这次回答不错”到可测试、可审计、可回滚的 Prompt Harness

理论 任务契约与可靠性边界 实战 Python Basic + Advanced
失败现场

Demo 成功,不等于系统可靠

10:00
演示
“退款申请已通过”领导觉得效果很好
16:40
生产
同样输入,模型改口承诺立即退款没有查订单,也没有审批依据
次日
复盘
找不到当时的 Prompt、模型版本和证据无法判断是内容、模型还是代码回归

可靠性问题不是“提示词写得不够好”,而是系统没有建立行为契约。

学习地图

这一节解决三个生产问题

核心结论:模型不稳定并不可怕,可怕的是系统没有定义哪些不稳定可以接受、哪些必须被阻断。

01输出不可消费散文 → Schema
02证据边界失控补脑 → 拒答/复核
03修改无法治理手调 → Eval Gate
最终产物一个基础结构化抽取器 + 一个进阶事实核查 Prompt Harness,均为 Python。
方法论主线

从一次模型调用,到一个可靠系统组件

核心结论:可靠性不是来自某一句“神奇 Prompt”,而是来自模型外部一层层可执行的控制。

业务层Task Boundary明确任务目标、适用范围和禁止事项
输出层Schema Gate只让结构合法、字段完整的结果继续流转
事实层Evidence Gate结论必须由输入证据支持,证据不足就暴露缺口
运行层Failure Policy规定重试、降级、拒答和人工复核条件
治理层Eval & Release Gate用风险案例判断新版本是否允许发布
工程落地本节两个 Python 项目会依次实现这五层控制,而不是只演示模型回答。
理论 01

Prompt Contract 管的是行为,不是措辞

核心结论:Prompt 的价值不是写得像不像专家,而是能否清楚定义输入、输出、证据边界和失败行为。

INPUT任务 + 数据 + 证据
PROMPT CONTRACT允许做什么必须输出什么失败时怎么办
OUTPUT可验证结果
可靠行为 = 任务边界 × 输出 Schema × 证据规则 × 失败策略 × 回归评测
Contract Checklist

写 Prompt 前,先回答五个系统问题

01 任务是什么?输入客户反馈后,是做分类、摘要,还是产生可执行的下一步?不要把多个目标混成一句要求。
02 系统允许使用什么?只能使用当前输入、检索证据,还是允许调用业务工具?未授权的信息来源必须排除。
03 输出给谁消费?给人阅读可以是自然语言;给程序消费必须有字段、类型、枚举和非空约束。
04 什么情况下不能回答?证据缺失、输入冲突、超出业务范围时,必须有明确的拒答或人工复核状态。
05 怎样证明新版本更好?先定义关键评测案例和发布门槛,再修改 Prompt,而不是上线后凭感觉观察。
工程落地把这五个答案写进 Prompt、Schema、策略代码和 eval,而不是只留在需求文档里。
Bad → Good 01

不要让业务系统消费“看起来正确”的散文

核心结论:自然语言是否通顺是体验指标;字段是否稳定、含义是否明确才是系统接口指标。

“客户很生气,可能需要尽快处理一下。”

  • 情绪无法稳定枚举
  • ACME 与产品实体丢失
  • 下游不知道该走哪条流程
{
  "sentiment": "negative",
  "entities": ["ACME"],
  "risk": "high",
  "next_action": "check_refund_eligibility"
}
Schema 校验后才能进入工作流
工程落地模型输出只是候选数据。解析和验证失败时,不得调用退款、建单或通知等下游动作。
机制拆解

结构化输出不是一句“请返回 JSON”

核心结论:JSON 只保证语法可解析,Schema 才能保证字段、类型和业务含义满足契约。

1模型生成JSON 候选
2程序解析语法检查
3Schema 校验字段与枚举
4策略判断重试 / 人工
5业务执行可信输入
关键边界 模型只产生候选结果;代码拥有校验权和执行权。
Schema Gate

四类常见错误,需要四种明确判断

语法错误缺少引号、括号不闭合,JSON 无法解析。动作:有限次数格式重试
结构错误缺字段、字段名漂移、数组被输出为字符串。动作:Schema 拒绝并记录
取值错误risk 输出为 urgent,但系统只接受 low / medium / high。动作:禁止静默映射
业务错误JSON 完全合法,但 next_action 越权承诺退款。动作:业务规则或人工审核
工程落地不要用一个 try/except 包住所有失败。错误分类决定是否重试、拒绝、降级或转人工。
Basic Python

结构化客户反馈抽取器

核心结论:基础案例虽然小,但已经包含生产系统最小闭环:候选生成、验证、失败阻断和回归测试。

projects/lesson-01/basicmain.pysrc/extractor.pytests/test_extractor.pypyproject.toml
01 compare同屏比较散文和结构化结果
02 extract输入任意反馈并校验 schema
03 unittest非法输出必须被拒绝
python3 main.py compare
Basic 运行结果

Bad 和 Good 的差异可以被程序观察

lesson-01/basic · compare
BAD  > 客户似乎不满意,建议尽快跟进。

GOOD > {
  "prompt_version": "feedback-extractor.v2",
  "sentiment": "negative",
  "entities": ["ACME"],
  "risk": "high",
  "next_action": "Open a support ticket..."
}
4/4字段可校验
0静默补字段
100%回归样例通过
工程落地评测对象不是文字是否“像人”,而是关键字段、风险等级、实体和动作是否满足可执行契约。
Failure Policy

校验失败以后,系统具体怎么办?

核心结论:失败策略必须在开发前定义。无限重试会增加成本,也可能重复触发有副作用的业务动作。

格式错误携带校验错误,最多重试 1–2 次仍失败 → 降级模板
输入不完整向用户追问缺失字段不允许模型自行猜测
低风险不确定返回保守结果并记录进入抽样质检
高风险不确定停止自动流程进入人工复核队列
工程落地失败结果也要写入 trace:输入摘要、Prompt 版本、校验错误、重试次数和最终去向。
Bad → Good 02

关键词重合,不代表证据支持

核心结论:事实核查要比较 Claim 中的完整事实关系,而不是统计 Claim 和 Evidence 共享了多少词。

CLAIMGlobex 获得了 50% 折扣
EVIDENCEGlobex 申请了折扣,但审批记录缺失
错误判断SUPPORTED因为两边都有 discount
正确判断INSUFFICIENT申请 ≠ 审批 ≠ 执行
工程落地把业务事件拆成主体、动作、对象、状态和时间;任何关键关系缺失,都不能判定完整 Claim 成立。
理论 02

事实核查的核心是证据状态机

核心结论:系统需要的是可分流的证据状态,不是模型给出的一个模糊“可信度分数”。

收到 Claim
检索证据
证据完整?
直接支持 → SUPPORTED明确冲突 → CONTRADICTED缺失/模糊 → HUMAN REVIEW

置信度不能替代证据。证据不完整时,正确结果是暴露缺口。

输出契约

让每个判断都能解释、分流和追责

核心结论:Verdict 负责流程分支,Evidence 负责审计,Missing Evidence 负责指导下一步。

verdict驱动流程分支
supporting_evidence支持审计回看
missing_evidence指导补充材料
human_review_required阻断错误自动化
prompt_version定位行为版本
confidence用于排序,不越过证据门禁
工程落地高置信度不能把 insufficient 自动升级为 supported;置信度只是辅助信号,证据状态才是硬门禁。
Bad → Good 03

Prompt 修改必须进入发布流程

核心结论:Prompt 的文字变化可能改变大量下游行为,因此必须像代码变更一样经过评测、审批、发布和回滚。

线上直接改一句无版本无评测无法回滚
Git DiffEval SetRisk GateReleaseObserve

Prompt as Code 的重点不是“放进 Git”,而是行为变化可评测、可阻断、可回滚。

Advanced Python

Fact Checker Prompt Harness

核心结论:Harness 是包围模型调用的控制层,把 Prompt、证据规则、Schema、评测和审计组织成一个可交付组件。

ClaimEvidenceEval Cases
HARNESSPrompt v2Evidence GateSchema ValidatorRelease Evaluator
VerdictAudit RecordHuman Queue
python3 main.py eval
评测集

不是测“回答好不好”,而是测风险边界

核心结论:平均分会掩盖致命错误。高风险场景必须逐条通过,不能被大量简单样例抵消。

案例
风险
期望
门禁
事故有直接记录
漏掉有效证据
supported
PASS
折扣审批缺失
把申请当批准
insufficient
PASS
退款明确未批准
忽略反证
contradicted
PASS
只有关键词重合
语义补脑
insufficient
PASS
Eval Design

一个可用评测集,至少覆盖四个象限

常见 × 正常主流程能力有充分证据时能否完成任务,防止系统因为过度保守而失去业务价值。
常见 × 异常输入质量问题字段缺失、格式错误、表达模糊时,能否追问或进入失败策略。
少见 × 高风险业务事故边界反证、越权承诺、错误金额、错误审批状态必须逐条阻断。
对抗 × 高风险模型脆弱点提示注入、伪造证据、关键词诱导和冲突指令不能突破边界。
工程落地每次线上事故和人工复核误判都应沉淀为新案例,让评测集随业务风险持续增长。
生产边界

Harness 不能解决所有可靠性问题

核心结论:Prompt Harness 只负责模型行为约束;知识、工具、流程和运行时仍需要独立治理。

它能控制输出结构证据使用规则失败分流版本与回归
它不能单独控制知识库是否过期检索是否召回工具是否正确执行业务规则是否完整

Prompt Harness 是可靠系统的一层,不是整个系统。后续课程会继续补齐 RAG、工具、Agent Loop 和 Runtime。

课堂实战

从机制理解到工程交付

核心结论:实战不是照着命令运行,而是亲手制造失败、补充门禁,再证明失败不会进入生产流程。

15 minBasic

运行 compare,制造非法输出,观察 schema 如何阻断。

30 minAdvanced

新增一个高风险 claim,写入 eval set,调整规则直到门禁通过。

10 minReview

说明哪些判断必须进入人工队列,以及原因。

验收

上线前,至少回答这六个问题

核心结论:只要有一个问题无法回答,这个模型调用就仍然是 Demo,而不是可交付的系统组件。

01 输出能否被 Schema 验证?
02 证据不足是否明确拒绝?
03 高风险结果是否人工复核?
04 Prompt 版本是否进入记录?
05 关键失败样例是否进入评测集?
06 行为退化是否阻断发布?
Lesson 01 · Takeaway

不要追求控制模型的每句话。
要控制系统接受什么、拒绝什么、记录什么。

NEXT · Lesson 02 工具边界与生产级 RAG