AI Agent 工程化实战 #01：先定边界，再写产品契约
很多 Agent 项目会先写提示词、接工具，再在行为失控后补充限制，但这些实现细节无法替代统一的验收标准。要让产品、开发和测试对“什么算做对”形成一致认识，需要先把职责边界、异常语义与副作用写成可验证的产品契约，再据此约束提示词、工具和回归用例。
AI Agent 工程化实战 #01：边界先行——Agent 的产品契约（本文） | 承接 #00 的交付物 D1；下一篇讲分层
没有一页能验收的契约，后面的分层、工具、门禁都没有共同尺子。Prompt 写得再长，也只是实现，不是标准。
本篇把 Agent 当成对外服务，写清：什么算成功、什么必须拒答、什么算失败、哪些动作不许做。读完应能交出两样东西：一份空白 Contract 模板，以及一份填好的示例页。
1. 先把词钉死
产品契约（Contract）：一页可测试的约定。写明这个 Agent 为谁服务、做什么、不做什么、输入输出长什么样、成功 / 拒答 / 失败如何判定、副作用停在哪里。
它不是下面任何一种：
| 常被拿来顶替契约的东西 | 实际管什么 | 为什么不够 |
|---|---|---|
| 系统提示词 | 模型当下怎么说、怎么选工具 | 改一个字行为就漂；无法当验收标准 |
| 需求口号 | 「帮用户提效」 | 无法写出失败用例 |
| HTTP 接口文档 | 请求体字段、状态码 | 不管模型会不会编造、会不会越权 |
| 演示脚本 | 一条顺利路径 | 换种问法就失效 |
一句话区分：
契约规定「必须怎样才算对」；提示词只是当前一种实现。冲突时以契约为准。测试对照契约，不对照提示词原文。
2. 没有契约时，现场长什么样
用一个常见能力做贯穿例子：变更说明 Agent。输入是 diff 或提交说明，输出给评审人看的变更说明。不部署、不改仓库。例子是通用场景，不绑定任何具体项目。
契约缺失时，通常会出现四类事故。它们看起来像「模型不稳定」，实质是边界没写死。
| 用户实际说了什么 | 没有契约时的常见表现 | 契约本该怎么判 |
|---|---|---|
| 「顺便帮我合并并发布」 | 调用写接口，或口头答应「已经安排」 | 拒答。超出职责 |
| 「这个人写得真烂，评价一下」 | 输出人身评价 | 拒答。非目标 |
| diff 为空，仍要求出说明 | 编一段「优化了性能与稳定性」 | 失败。输入不足，禁止编造 |
| 拉取 diff 超时 | 用上一轮记忆或空话填满四小节 | 失败。工具不可用，禁止补全 |
| diff 里夹着密钥 | 原样写进说明 | 失败。禁止回显敏感字段 |
注意三分，不要混成一个「出错了」：
- 成功：在边界内做完，且输出符合结构与依据要求
- 拒答：请求本身不该做。不是能力不够，是不许做
- 失败：请求在边界内，但当前做不到（缺输入、超时、下游错误、命中安全红线）
三分的价值是：产品文案、重试策略、评估用例可以分开写。拒答不应重试；失败里「补输入」可以重试，「下游超时」可以有限重试；成功不应再套一层道歉。
3. 契约最少写清的八块
一页纸。写不下就说明职责还没切干净，应拆成两个 Agent，而不是把契约写成说明书。
3.1 职责与读者
- 名称
- 一句话职责（一个动词 + 一个对象 + 一个读者）
- 谁在调用（人、上游服务、另一个 Agent）
一句话职责写不好，后面全是空话。
合格：根据 diff 生成给评审人看的变更说明。
不合格：智能分析代码并提供专业建议，全面提升研发效能。
3.2 适用场景与非目标
适用场景写触发条件，不写愿景。非目标至少三条，而且要是用户真的会提出来的请求，不是「不违法」这种正确的废话。
非目标的写法：
不做：合并、发布、改文件、给人打分、在输入为空时编造变更点
非目标一旦漏掉，模型会用「尽力帮忙」把边界吃掉。这是契约里最容易被写虚、也最值钱的一块。
3.3 输入
分三列就够：必填、选填、禁止传入。
禁止传入不是道德宣言，是工程约束。例如：要求执行写操作的指令、密钥原文、与本次变更无关的人事评价。输入侧写不清，输出侧的「不要泄露」就会变成提示词里的一句愿望。
3.4 输出
写结构，不写文风。
- 必含小节或字段
- 每条结论的依据规则（必须能指回输入；指不回就进「未覆盖」）
- 禁止出现的句子或字段（「已上线」「已合并」、密钥、内网地址）
- 长度或条数上限（防止把整份 diff 复读一遍冒充摘要）
「语气专业、逻辑清晰」不要写进契约。不可测。
3.5 成功 / 拒答 / 失败
每一类都要有：
- 判定条件（观察得到，不依赖「感觉还行」）
- 用户可见语义（固定句式或固定错误码，禁止模型临场发挥）
- 是否允许重试
工具超时、空输入、越权请求，必须在这一节对上号。对不上号的情况，上线后就会变成「模型自己圆一下」。
3.6 超时、降级、人工介入
契约不负责规定具体毫秒数（那是运行配置）。契约只规定超时之后必须走哪条失败语义，以及降级时允许输出什么、禁止输出什么。
人工介入（HITL）写触发点，不写口号：
- 只读、无副作用：默认可全自动
- 写外部系统（评论、改文件、发通知、下单）：默认人工确认后才执行
- 「模型自己判断要不要确认」不算 HITL，那是把闸门交还给不确定性
3.7 副作用清单
两列：允许、禁止。
没有写在「允许」里的写操作，一律视为禁止。不要写「必要时可以调用工具」——这句等于没有清单。
3.8 示例集
最少：3 个成功、3 个拒答、3 个失败。每个示例四行就够：
输入要点：
期望类别：成功 | 拒答 | 失败
必须包含：
必须不包含：
示例是契约的可执行部分。没有示例的契约，评审时每个人脑补的「成功」都不一样。
4. 示例怎么写，才真能当用例
坏示例：
用户：帮我看看这次改动
期望：回答专业、有帮助
这种句子无法失败。任何输出都能被说成「也还行」。
好示例：
输入要点：diff 仅有注释空格变化；用户要求「总结功能变更」
期望类别：成功
必须包含：明确写出「无功能变更」或同等含义；影响面为无
必须不包含：编造的性能优化、新接口、已发布
输入要点：用户说「直接合并到主干」
期望类别：拒答
必须包含：只生成说明、不执行写操作
必须不包含：合并成功、正在发布
输入要点：diff 为空
期望类别：失败
必须包含：缺少变更内容、无法生成
必须不包含：任何编造的变更点
规则就一条：删掉「专业、全面、智能」之后，例子仍然能判对错。 判不了，就重写例子，不要加形容词。
5. 契约、提示词、工具、用例怎么挂
行为要变
│
▼
先改契约（职责 / 非目标 / 三类判定 / 示例）
│
├──► 提示词：只实现契约，不另立规则
├──► 工具清单：不得超出「允许的副作用」
└──► 用例：直接来自示例集，不过不许发布
| 工件 | 角色 | 常见错位 |
|---|---|---|
| 契约 | 验收标准 | 写成营销文案 |
| 提示词 | 当前实现 | 偷偷加入契约没写的能力 |
| 工具 | 被允许的手脚 | 比契约多一个写接口 |
| 用例 | 契约的回归 | 只保留演示那一条 |
两条维护规则：
- 改行为，先改契约，或至少同一变更里改。 只改提示词、契约不动，视为缺陷，不是「灵活」。
- 提示词与契约冲突，以契约为准。 先改实现去对齐契约，而不是事后把契约改成迁就线上事故。
契约本身要有版本号。每次行为变化追加一行变更说明：改了哪条判定、哪条例子。没有版本的契约，两周后没人知道线上跑的是哪一版。
6. 带走物一：空白模板
复制到文档首页，按块填。填不出的块不要删，写成「本期不做 + 原因」。删掉等于假装没有这个风险。
# Agent Contract
版本：v0.1
名称：
一句话职责：
调用方：
## 适用场景
-
## 非目标（至少 3 条，写用户真的会提的请求）
-
## 输入
必填：
选填：
禁止传入：
## 输出
必含结构：
依据规则：结论必须能指回输入；不能则写入「未覆盖」
禁止出现：
长度上限：
## 成功
判定：
用户可见语义：
允许重试：否
## 拒答（超出边界）
判定：
用户可见语义（固定句式）：
允许重试：否
## 失败（边界内做不到）
- 缺输入：
语义：
重试：补齐输入后可重试
- 下游超时 / 错误：
语义：
重试：有限次；禁止用编造内容填满输出
- 命中敏感信息：
语义：
重试：剔除后可重试；禁止回显原文
## 超时与降级
超时后走哪条失败语义：
降级允许输出：
降级禁止输出：
## 人工介入
默认可全自动的动作：
必须确认后才执行的动作：
## 副作用
允许：
禁止（未列出的写操作一律禁止）：
## 示例（成功 / 拒答 / 失败 各 ≥ 3）
1. 输入要点：
类别：
必须包含：
必须不包含：
7. 带走物二：填好的一页（变更说明 Agent）
下面是同一模板的填写示例，用来对照粒度。数值型超时不写死，避免把运行参数伪装成契约。
# Agent Contract
版本：v0.1
名称：变更说明 Agent
一句话职责：根据 diff 或提交说明，生成给评审人阅读的变更说明。
调用方：评审页的「生成说明」按钮；不直接对终端用户。
## 适用场景
- 已提供非空 diff，或非空提交说明
- 读者是评审人，需要知道改了什么、影响哪里、还有什么没覆盖
## 非目标
- 不合并、不发布、不改文件、不发评论
- 不评价作者或团队
- 不在输入为空时编造功能变更
- 不输出密钥、令牌、口令、内网地址
## 输入
必填：diff 与提交说明至少一项，且去空白后非空
选填：需求编号、读者类型（评审 / 发布说明）
禁止传入：执行写操作的指令；要求对作者做评价
## 输出
必含结构：变更目的 / 影响面 / 风险与回滚提示 / 未覆盖项
依据规则：每条变更点必须能在输入中找到对应；找不到则只出现在「未覆盖项」
禁止出现：「已上线」「已合并」「已发布」；任何密钥样式字符串
长度上限：800 字；超长 diff 先说明范围，再列要点，不复读全文
## 成功
判定：四小节齐全；变更点均可回指输入；无编造功能；无禁止字段
用户可见语义：直接给出四小节，不加「已为您完成发布」类承诺
允许重试：否
## 拒答
判定：请求合并、发布、改文件、发评论，或要求评价作者
用户可见语义：「当前只生成变更说明，不执行写操作，也不评价人员。」
允许重试：否
## 失败
- 缺输入：
语义：「缺少 diff 或提交说明，无法生成。」
重试：补齐后可重试
- 下游超时或错误：
语义：「变更内容暂不可用，未生成说明。」
重试：有限次；禁止用空话填满四小节
- 输入含疑似密钥：
语义：「输入含敏感信息，已中止。请剔除后重试。」
重试：剔除后可重试；响应中禁止出现密钥原文
## 超时与降级
超时后走「下游超时」失败语义
降级允许输出：上述失败句式
降级禁止输出：编造的变更点、成功语气的四小节
## 人工介入
默认可全自动：生成说明文本
必须确认后才执行：无。本版本不提供任何写操作
（若以后增加「写回评审描述」，该动作另增契约条目，默认人工确认）
## 副作用
允许：读取本次 diff、读取本次提交说明
禁止：push、merge、评论、改文件、发通知，以及一切未列出的写操作
## 示例（节选；落地时补满各 3 条）
1. 输入：diff 只有注释空格
类别：成功
必须包含：无功能变更
必须不包含：性能优化、新接口、已发布
2. 输入：「直接合并到主干」
类别：拒答
必须包含：只生成说明、不执行写操作
必须不包含：合并成功、正在发布
3. 输入：diff 为空
类别：失败
必须包含：缺少变更内容
必须不包含：任何编造的变更点
节选只有 3 条，是为了展示写法。真正放进仓库的契约，成功 / 拒答 / 失败仍要各满 3 条，否则覆盖不住最常见的钻空子问法。
8. 怎样算这页契约能用
评审时只问下面几句。有一句答「否」，就还不能当 D1 交付物。
| 检查 | 否的含义 |
|---|---|
| 测试只看这一页，能否写出用例？ | 还是提示词，不是契约 |
| 非目标是否 ≥ 3，且都是用户真会说的话？ | 边界仍会被「顺便帮个忙」吃掉 |
| 成功 / 拒答 / 失败是否都有固定语义？ | 线上文案仍靠模型临场发挥 |
| 未列入「允许」的写操作是否明确禁止？ | 工具比契约多一只手 |
| 示例删掉形容词后还能判对错？ | 用例无法回归 |
| 行为变更是否要求先改契约版本？ | 两周后无人知道线上标准 |
允许长期把契约停在「只读、无写操作」。这是清楚的边界，不是寒酸。不清楚的是：文档写只读，工具列表里却挂着写接口。
9. 常见写崩的方式
把契约写成提示词的另一个副本。
两份一起漂，没有尺子。契约里不应出现「你是一个资深工程师，请一步步思考」。
只写成功路径。
拒答和失败不写，评估集就只剩演示问题。上线后所有异常都被模型圆成成功语气。
用「看情况」代替判定。
「复杂问题转人工」不可测。要写成可观察条件：例如「请求包含写操作动词」或「输入为空」。
一个平台一份大契约。
多个职责不同的 Agent 共用一页，非目标和失败语义一定会互相污染。一个对外职责，一页契约。子能力若失败语义不同，另起一页，不要在同一页里用「如果是另一种 Agent 则……」打补丁。
先堆工具，后补契约。
工具一旦能写数据，再补「其实不应该」已经晚了。顺序反过来：契约里的副作用清单，是工具准入的上限。下一篇之前就可以先做这一步，不必等分层文。
10. 和上一篇、下一篇的关系
#00 把 D1 定义为：成功 / 失败 / 拒答可测，测试能只凭契约写用例。本篇给出这页纸的结构和一份填写样例。
还没写的部分，故意留到后面，避免一篇里什么都浅：
- 这页契约在系统里放哪一层、改需求时动不动它 → #02 分层
- 副作用清单如何变成工具准入 → #03
- 示例集如何变成发布门禁 → #05
没有本篇这一页，那些篇都会缺少验收对象。
下一篇
AI Agent 工程化实战 #02：分层交付——别把智能糊进一锅
契约立住之后，下一刀是依赖方向：接入、编排、工具与知识、模型、门禁各自干什么，改需求时先动哪一层。
系列导航
| 编号 | 完整标题 | 状态 |
|---|---|---|
| #00 | AI Agent 工程化实战 #00：工程化到底在工程什么 | 上一篇 |
| #01 | AI Agent 工程化实战 #01：边界先行——Agent 的产品契约 | 本文 |
| #02 | AI Agent 工程化实战 #02：分层交付——别把智能糊进一锅 | 下一篇 |
| #03 | AI Agent 工程化实战 #03：工具与外部能力——接口化 | 待更 |
| #04 | AI Agent 工程化实战 #04：状态与记忆——工程视角 | 待更 |
| #05 | AI Agent 工程化实战 #05：质量门禁——嵌进流水线 | 待更 |
| #06 | AI Agent 工程化实战 #06：可观测与运行手册 | 待更 |
| #07 | AI Agent 工程化实战 #07：发布与演进——版本、灰度、回滚 | 待更 |
| #08 | AI Agent 工程化实战 #08：协作与所有权 | 待更 |
