Agent 答对了，下游为什么还是接不住？设计可演进的交付契约

很多 Agent 故障不是“回答错了”，而是“回答无法被下一步稳定消费”。它可能把日期写成自然语言，把失败原因塞进 result，这次返回数组、下次返回对象；人读起来都对，自动化却只能靠猜。

如果一个 Agent 的产物要进入任务树、数据库、审批流或另一个 Agent，自由文本就不再只是表达方式，而是接口。专业化不能只停在角色提示词和工具清单，还要定义它交付什么、如何验证、怎样升级。

先定义结果信封，再定义业务数据

不要让每个任务自行发明“成功”和“失败”。一个最小结果信封可以是：

type Delivery<T> = {
  contract: "lead-review";
  version: "1.1";
  status: "completed" | "partial" | "blocked" | "failed";
  data?: T;
  evidence: Array<{ kind: string; ref: string }>;
  missing: string[];
  error?: { code: string; retryable: boolean; message: string };
};

这里最重要的不是字段名，而是把几件经常混在一起的事拆开：status 表示任务终态，data 是业务结果，missing 明确不完整项，error 决定是否可重试，evidence 让下游知道结论从哪里来。

null、字段缺失和空数组也必须有不同含义。比如“没有发现风险”和“风险扫描未执行”不能都返回 risks: []。前者是结论，后者是缺失。

三道门，分别拦住三类错误

第一道是结构验证。用 JSON Schema 一类机制检查必需字段、类型、枚举和额外字段。它能快速拦住 status: "done" 这种未约定状态，也能避免字段拼写漂移。

第二道是语义验证。结构合法不代表业务正确。例如 startAt 晚于 endAt，置信度超出 0 到 1，或者状态为 completed 却仍有必需项出现在 missing。这些约束需要领域验证器处理。

第三道是消费兼容。生产者通过自己的校验还不够，下游可能只支持 1.x，也可能依赖某个可选字段。消费端应先声明可接受版本和能力，再决定接收、降级还是阻塞。不要把解析异常吞掉后继续执行。

function accept(d: Delivery<unknown>) {
  assertSchema(d);
  assertSemantics(d);
  if (!supports(d.contract, d.version)) {
    return { status: "blocked", reason: "CONTRACT_UNSUPPORTED" };
  }
  return { status: "accepted" };
}

契约也要演进，不能一次定死

最常见的危险升级，是直接改字段含义。例如把 score 从 0—100 改成 0—1，即使字段类型仍是 number，旧消费者也会静默算错。

更稳妥的规则有四条：

1. 小版本只增加可选字段，不改变既有字段语义。
2. 删除字段前先废弃，观察消费者，再进入新主版本。
3. 主版本迁移期允许生产者双写或消费者双读，但必须记录实际命中的版本。
4. 测试不只验证 Schema，还保存消费者契约样例，做回归测试。

Protocol Buffers 的兼容规则提供了一个有用提醒：Schema 演进不是重命名文件那么简单，稳定标识和读写双方的升级节奏都属于协议。

失败后不要让模型继续猜

验证失败后的分流应是确定的：可修复的格式错误可以带校验报告重试一次；需要业务判断的冲突进入人工确认；版本不兼容直接阻塞并请求升级；证据缺失则返回 partial，而不是补写一个听起来合理的结论。

这也是专业 Agent 与普通聊天角色的分界。聊天角色追求“这段话像不像专家”，专业 Agent 还要对交付边界负责。在 Tipkay 的产品实践中，不同 Agent 可以拥有独立的模型、工具、Skill 和协作对象；把交付契约也纳入岗位配置，才能让职责差异真正延伸到下游验收。这里讨论的是一种工程方向，不代表任何输出天然正确。

最小落地顺序

先选一个频繁失败的下游动作，不要一开始给所有 Agent 建统一大 Schema。收集十个真实失败样本，定义结果信封和三到五个必需业务字段；在边界处加入结构与语义验证；最后再补版本和消费者契约测试。

衡量标准也应改变：不只看回答正确率，还看首次验收通过率、人工修复次数、未知字段比例、契约不兼容次数和下游静默失败数。只有这些指标下降，专业化才从“人设更像”变成“交付更稳”。

营销风险自检：通过。品牌露出 1 次，仅用于交代实践来源；删除品牌段落后技术论证仍完整。