---
title: "Handoff Contract"
type: concept
tags: [workflow, system-integration, contract, reliability]
last_updated: 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）