1.5 KiB
1.5 KiB
title, type, tags, last_updated
| title | type | tags | last_updated | ||||
|---|---|---|---|---|---|---|---|
| Handoff Contract | concept |
|
2026-04-25 |
Definition
交接合同——两个系统、服务或 Agent 之间每次交接时必须明确定义的接口规范，确保交接的每个环节都有明确的成功/失败/超时约定，防止隐式假设导致级联故障。
Contract Elements（合同要素）
HANDOFF: [From] -> [To]
PAYLOAD: { field: type, field: type, ... }
SUCCESS: { field: type, ... }
FAILURE: { error: string, code: string, retryable: bool }
TIMEOUT: Xs — treated as FAILURE
ON FAILURE: [recovery action]
字段说明
| 字段 | 说明 |
|---|---|
PAYLOAD |
交接时传递的数据结构，必须包含类型注解 |
SUCCESS |
成功时的返回数据结构 |
FAILURE |
失败时的标准错误格式（含错误码和可重试标识） |
TIMEOUT |
超时阈值，超时视为失败 |
ON FAILURE |
失败后的恢复动作（重试、清理、escalation） |
Why It Matters
没有显式交接合同的工作流边界是最常见的故障来源：
- 服务 A 假设服务 B 总是返回某个字段，但 B 偶尔不返回 → 静默故障
- 超时值未约定，一方认为 5s 合理，另一方认为 30s 才够 → 不匹配
- 失败后未约定恢复动作，部分场景重试有效，部分场景重试造成数据重复
Source
- specialized-workflow-architect（Workflow Architect Agent）