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
不要让业务系统消费“看起来正确”的散文
核心结论:自然语言是否通顺是体验指标;字段是否稳定、含义是否明确才是系统接口指标。
BAD “客户很生气,可能需要尽快处理一下。”
情绪无法稳定枚举 ACME 与产品实体丢失 下游不知道该走哪条流程
GOOD {
"sentiment": "negative",
"entities": ["ACME"],
"risk": "high",
"next_action": "check_refund_eligibility"
} Schema 校验后才能进入工作流
工程落地 模型输出只是候选数据。解析和验证失败时,不得调用退款、建单或通知等下游动作。
机制拆解
结构化输出不是一句“请返回 JSON”
核心结论:JSON 只保证语法可解析,Schema 才能保证字段、类型和业务含义满足契约。
1 模型生成 JSON 候选
→
2 程序解析 语法检查
→
3 Schema 校验 字段与枚举
→
4 策略判断 重试 / 人工
→
5 业务执行 可信输入
关键边界 模型只产生候选结果;代码拥有校验权和执行权。
Schema Gate
四类常见错误,需要四种明确判断
语法错误 缺少引号、括号不闭合,JSON 无法解析。 动作:有限次数格式重试
结构错误 缺字段、字段名漂移、数组被输出为字符串。 动作:Schema 拒绝并记录
取值错误 risk 输出为 urgent,但系统只接受 low / medium / high。 动作:禁止静默映射
业务错误 JSON 完全合法,但 next_action 越权承诺退款。 动作:业务规则或人工审核
工程落地 不要用一个 try/except 包住所有失败。错误分类决定是否重试、拒绝、降级或转人工。
Basic Python
结构化客户反馈抽取器
核心结论:基础案例虽然小,但已经包含生产系统最小闭环:候选生成、验证、失败阻断和回归测试。
projects/lesson-01/basic main.py src/extractor.py tests/test_extractor.py pyproject.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..."
}
工程落地 评测对象不是文字是否“像人”,而是关键字段、风险等级、实体和动作是否满足可执行契约。
Failure Policy
校验失败以后,系统具体怎么办?
核心结论:失败策略必须在开发前定义。无限重试会增加成本,也可能重复触发有副作用的业务动作。
格式错误 携带校验错误,最多重试 1–2 次 仍失败 → 降级模板
输入不完整 向用户追问缺失字段 不允许模型自行猜测
低风险不确定 返回保守结果并记录 进入抽样质检
高风险不确定 停止自动流程 进入人工复核队列
工程落地 失败结果也要写入 trace:输入摘要、Prompt 版本、校验错误、重试次数和最终去向。
Bad → Good 02
关键词重合,不代表证据支持
核心结论:事实核查要比较 Claim 中的完整事实关系,而不是统计 Claim 和 Evidence 共享了多少词。
CLAIM Globex 获得了 50% 折扣
EVIDENCE Globex 申请了折扣,但审批记录缺失
错误判断 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 Diff → Eval Set → Risk Gate → Release → Observe
Prompt as Code 的重点不是“放进 Git”,而是行为变化可评测、可阻断、可回滚。
Advanced Python
Fact Checker Prompt Harness
核心结论:Harness 是包围模型调用的控制层,把 Prompt、证据规则、Schema、评测和审计组织成一个可交付组件。
Claim Evidence Eval Cases
HARNESS Prompt v2 Evidence Gate Schema Validator Release Evaluator
Verdict Audit Record Human 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 min Basic 运行 compare,制造非法输出,观察 schema 如何阻断。
30 min Advanced 新增一个高风险 claim,写入 eval set,调整规则直到门禁通过。
10 min Review 说明哪些判断必须进入人工队列,以及原因。
验收
上线前,至少回答这六个问题
核心结论:只要有一个问题无法回答,这个模型调用就仍然是 Demo,而不是可交付的系统组件。
01 输出能否被 Schema 验证?
02 证据不足是否明确拒绝?
03 高风险结果是否人工复核?
04 Prompt 版本是否进入记录?
05 关键失败样例是否进入评测集?
06 行为退化是否阻断发布?
Lesson 01 · Takeaway
不要追求控制模型的每句话。要控制系统接受什么、拒绝什么、记录什么。
NEXT · Lesson 02 工具边界与生产级 RAG