466 lines
12 KiB
Markdown
466 lines
12 KiB
Markdown
# A2A 协议（Agent-to-Agent Protocol）
|
||
|
||
> 版本：1.0.0
|
||
> 状态：草案
|
||
> 类型：实现规范
|
||
> 基于：[灵隙原始协议（Synapse Raw Protocol） v1.0.0](./01-a2a-raw-protocol.md)
|
||
|
||
---
|
||
|
||
## 1. 概述
|
||
|
||
A2A 协议定义了两个 Agent 之间进行点对点（P2P）任务协作的完整规范，包括消息类型、交互流程、状态机、接口定义与错误处理。
|
||
|
||
### 1.1 适用场景
|
||
- 单个任务请求与响应
|
||
- 任务状态实时同步
|
||
- 任务取消
|
||
- 信息补全交互
|
||
- 人类介入决策
|
||
|
||
### 1.2 非适用场景
|
||
- 多 Agent 群组协作（参见 A2N 组群协议）
|
||
- 非 Agent 调用方接入（参见 P2A 调用协议）
|
||
|
||
---
|
||
|
||
## 2. 消息类型
|
||
|
||
### 2.1 消息类型清单
|
||
|
||
所有消息类型前缀：`p2p:`
|
||
|
||
| 消息类型 | 方向 | 说明 |
|
||
|---------|------|------|
|
||
| `p2p:task_request` | 请求方 → 执行方 | 提交任务请求 |
|
||
| `p2p:task_confirm` | 执行方 → 请求方 | 确认接受任务 |
|
||
| `p2p:task_reject` | 执行方 → 请求方 | 拒绝任务 |
|
||
| `p2p:task_need_info` | 执行方 → 请求方 | 请求补充信息 |
|
||
| `p2p:task_info_provided` | 请求方 → 执行方 | 提供补充信息 |
|
||
| `p2p:task_status_update` | 执行方 → 请求方 | 任务进度更新 |
|
||
| `p2p:task_complete` | 执行方 → 请求方 | 任务完成 |
|
||
| `p2p:task_failed` | 执行方 → 请求方 | 任务失败 |
|
||
| `p2p:task_cancel` | 请求方 → 执行方 | 取消任务 |
|
||
| `p2p:task_ack` | 双向 | 任务级确认 |
|
||
| `p2p:ack` | 双向 | 通用确认 |
|
||
| `p2p:nack` | 双向 | 通用否定确认（错误） |
|
||
| `p2p:heartbeat` | 双向 | 心跳保活 |
|
||
| `p2p:capability_query` | 双向 | 查询对方能力 |
|
||
| `p2p:capability_response` | 双向 | 返回能力清单 |
|
||
| `p2p:task_need_human` | 执行方 → 请求方 | 请求人类介入 |
|
||
| `p2p:human_decision` | 请求方 → 执行方 | 人类决策结果 |
|
||
|
||
### 2.2 消息类型完整定义
|
||
|
||
参见代码：[types/types.go](../types/types.go)
|
||
|
||
---
|
||
|
||
## 3. 任务状态机
|
||
|
||
### 3.1 状态定义
|
||
|
||
| 状态 | 说明 |
|
||
|------|------|
|
||
| `idle` | 空闲（初始状态） |
|
||
| `pending` | 待确认（已发送请求，等待确认） |
|
||
| `confirmed` | 已确认（对方接受任务） |
|
||
| `executing` | 执行中 |
|
||
| `info_needed` | 需要信息 |
|
||
| `info_provided` | 信息已提供 |
|
||
| `need_human` | 需要人类介入 |
|
||
| `human_deciding` | 人类决策中 |
|
||
| `human_approved` | 人类已批准 |
|
||
| `human_rejected` | 人类已拒绝 |
|
||
| `completed` | 已完成（终态） |
|
||
| `failed` | 已失败（终态） |
|
||
| `cancelled` | 已取消（终态） |
|
||
| `rejected` | 已拒绝（终态） |
|
||
|
||
### 3.2 状态流转图
|
||
|
||
```
|
||
请求方视角：
|
||
|
||
idle → pending → confirmed → executing → completed
|
||
↓ ↓ → failed
|
||
rejected info_needed → cancelled
|
||
↑↓
|
||
info_provided
|
||
↓
|
||
need_human
|
||
↑↓
|
||
human_decision
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 核心交互流程
|
||
|
||
### 4.1 正常任务提交流程
|
||
|
||
```
|
||
请求方 Agent 执行方 Agent
|
||
| |
|
||
|-------- task_request ------------->| 1. 提交任务
|
||
| |
|
||
|<------- task_confirm / task_reject -| 2. 确认/拒绝
|
||
| |
|
||
|<------- task_status_update --------| 3. 进度更新（多次）
|
||
| |
|
||
|<------- task_complete -------------| 4. 完成通知
|
||
| |
|
||
|-------- task_ack ----------------->| 5. 确认收到
|
||
| |
|
||
```
|
||
|
||
### 4.2 信息补全流程
|
||
|
||
```
|
||
请求方 Agent 执行方 Agent
|
||
| |
|
||
|-------- task_request ------------->|
|
||
| |
|
||
|<------- task_need_info ------------| 发现信息缺失
|
||
| |
|
||
|-------- task_info_provided ------->| 补充信息
|
||
| |
|
||
|<------- task_status_update --------| 继续执行
|
||
| |
|
||
```
|
||
|
||
### 4.3 人类介入流程
|
||
|
||
```
|
||
请求方 Agent 执行方 Agent
|
||
| |
|
||
|-------- task_request ------------->|
|
||
| |
|
||
|<------- task_need_human -----------| 需要人类决策
|
||
| |
|
||
| [人类做出决策] |
|
||
| |
|
||
|-------- human_decision ----------->| 决策结果
|
||
| |
|
||
|<------- task_status_update --------| 继续执行
|
||
| |
|
||
```
|
||
|
||
### 4.4 任务取消流程
|
||
|
||
```
|
||
请求方 Agent 执行方 Agent
|
||
| |
|
||
|-------- task_request ------------->|
|
||
| |
|
||
|-------- task_cancel -------------->| 取消任务
|
||
| |
|
||
|<------- task_ack ------------------| 确认取消
|
||
| |
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 接口规范
|
||
|
||
### 5.1 P2P 协议处理器接口
|
||
|
||
**接口定义：**
|
||
|
||
```go
|
||
type P2PProtocol interface {
|
||
// 处理收到的消息
|
||
HandleMessage(ctx context.Context, msg *UnifiedSynapseMessage) (*UnifiedSynapseMessage, error)
|
||
|
||
// 设置任务处理器
|
||
SetTaskHandler(h TaskHandler)
|
||
|
||
// 设置回调发送器
|
||
SetCallbackSender(s CallbackSender)
|
||
|
||
// 获取 Agent 端点
|
||
AgentEndpoint() AgentEndpoint
|
||
|
||
// 查询任务状态
|
||
GetTaskStatus(taskID string) (P2PTaskStatus, bool)
|
||
|
||
// 列出所有任务
|
||
ListTasks() map[string]P2PTaskStatus
|
||
}
|
||
```
|
||
|
||
**参考实现：** [p2p/protocol.go](../p2p/protocol.go)
|
||
|
||
### 5.2 任务处理器接口
|
||
|
||
```go
|
||
type TaskHandler interface {
|
||
// 执行任务并返回结果
|
||
ExecuteTask(ctx context.Context, taskType string, payload map[string]interface{}) (any, error)
|
||
|
||
// 验证任务是否可执行，返回缺失字段列表和是否可处理
|
||
ValidateTask(taskType string, payload map[string]interface{}) ([]MissingField, bool)
|
||
|
||
// 获取能力列表
|
||
GetCapabilities() []string
|
||
}
|
||
```
|
||
|
||
**说明：**
|
||
- `ExecuteTask`：实际执行业务逻辑的入口
|
||
- `ValidateTask`：在任务确认前调用，用于判断是否接受任务或需要补充信息
|
||
- `GetCapabilities`：返回 Agent 支持的任务类型列表
|
||
|
||
### 5.3 回调发送器接口
|
||
|
||
```go
|
||
type CallbackSender interface {
|
||
// 向远程 Agent 发送消息
|
||
SendCallback(ctx context.Context, endpoint string, msg *UnifiedSynapseMessage) error
|
||
}
|
||
```
|
||
|
||
**说明：**
|
||
- 传输层实现此接口
|
||
- 支持多种传输方式（HTTP、gRPC、WebSocket 等）
|
||
|
||
### 5.4 配置项
|
||
|
||
```go
|
||
type P2PConfig struct {
|
||
MaxRetries int // 最大重试次数（默认 5）
|
||
RetryBaseDelay time.Duration // 重试基础延迟（默认 2s，指数退避）
|
||
TaskTimeout time.Duration // 任务执行超时（默认 5 分钟）
|
||
HeartbeatInterval time.Duration // 心跳间隔（默认 30 秒）
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 载荷格式
|
||
|
||
### 6.1 TaskRequestPayload（任务请求）
|
||
|
||
```json
|
||
{
|
||
"task": {
|
||
"id": "task-xxx",
|
||
"type": "text_generation",
|
||
"priority": "normal",
|
||
"deadline": "2026-01-01T00:00:00Z",
|
||
"payload": {
|
||
"prompt": "写一首诗",
|
||
"style": "古典"
|
||
}
|
||
},
|
||
"context": {
|
||
"session_id": "sess-xxx",
|
||
"parent_task_id": "parent-xxx",
|
||
"correlation_id": "corr-xxx",
|
||
"metadata": {}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6.2 TaskConfirmPayload（任务确认）
|
||
|
||
```json
|
||
{
|
||
"task_id": "task-xxx",
|
||
"confirmed": true,
|
||
"estimated_duration": 120,
|
||
"expected_completion": "2026-01-01T00:02:00Z",
|
||
"capabilities_used": ["text_generation"],
|
||
"constraints": {
|
||
"max_retries": 3,
|
||
"fallback_enabled": true
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6.3 TaskRejectPayload（任务拒绝）
|
||
|
||
```json
|
||
{
|
||
"task_id": "task-xxx",
|
||
"reason": {
|
||
"code": "capability_lacking",
|
||
"message": "不支持该任务类型",
|
||
"details": null
|
||
},
|
||
"alternatives": {
|
||
"suggested_agent_id": "other-agent",
|
||
"retry_after": 300,
|
||
"partial_support": false
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6.4 TaskStatusUpdatePayload（状态更新）
|
||
|
||
```json
|
||
{
|
||
"task_id": "task-xxx",
|
||
"status": "executing",
|
||
"progress": 50,
|
||
"message": "正在生成内容",
|
||
"intermediate_result": null
|
||
}
|
||
```
|
||
|
||
### 6.5 TaskCompletePayload（任务完成）
|
||
|
||
```json
|
||
{
|
||
"task_id": "task-xxx",
|
||
"result": {
|
||
"output_type": "text",
|
||
"output": "生成的文本内容...",
|
||
"metadata": {
|
||
"tokens": 1024,
|
||
"model": "gpt-4"
|
||
}
|
||
},
|
||
"summary": "任务已完成"
|
||
}
|
||
```
|
||
|
||
### 6.6 TaskFailedPayload（任务失败）
|
||
|
||
```json
|
||
{
|
||
"task_id": "task-xxx",
|
||
"error": {
|
||
"code": "execution_error",
|
||
"message": "模型调用超时",
|
||
"recoverable": true,
|
||
"details": null
|
||
},
|
||
"partial_result": null
|
||
}
|
||
```
|
||
|
||
### 6.7 TaskNeedInfoPayload（需要信息）
|
||
|
||
```json
|
||
{
|
||
"task_id": "task-xxx",
|
||
"missing_fields": [
|
||
{
|
||
"field": "style",
|
||
"reason": "未指定生成风格",
|
||
"suggested_value": "古典",
|
||
"alternatives": ["现代", "浪漫"]
|
||
}
|
||
],
|
||
"question": "请选择生成风格",
|
||
"required_by": "2026-01-01T00:01:00Z"
|
||
}
|
||
```
|
||
|
||
### 6.8 TaskNeedHumanPayload（需要人类）
|
||
|
||
```json
|
||
{
|
||
"task_id": "task-xxx",
|
||
"reason": {
|
||
"code": "ethical_decision",
|
||
"message": "涉及伦理决策需要人工审核"
|
||
},
|
||
"context": {
|
||
"task_summary": "生成一张人物肖像",
|
||
"current_progress": 30,
|
||
"blocked_reason": "需要确认肖像使用授权"
|
||
},
|
||
"options": [
|
||
{
|
||
"field": "authorized",
|
||
"value": true,
|
||
"pros_cons": "继续生成，假设已授权",
|
||
"confidence": 70
|
||
}
|
||
],
|
||
"escalation_level": 1,
|
||
"deadline": "2026-01-01T00:05:00Z"
|
||
}
|
||
```
|
||
|
||
### 6.9 HumanDecisionPayload（人类决策）
|
||
|
||
```json
|
||
{
|
||
"task_id": "task-xxx",
|
||
"decision_id": "dec-xxx",
|
||
"reply_to": "msg-xxx",
|
||
"decided_by": {
|
||
"user_id": "user-123",
|
||
"user_name": "张三",
|
||
"role": "reviewer"
|
||
},
|
||
"decision": {
|
||
"action": "approve",
|
||
"approved_fields": {
|
||
"authorized": true
|
||
},
|
||
"rejection_reason": ""
|
||
},
|
||
"notes": "已确认授权",
|
||
"timestamp": "2026-01-01T00:03:00Z"
|
||
}
|
||
```
|
||
|
||
**完整载荷定义：** [types/types.go](../types/types.go)
|
||
|
||
---
|
||
|
||
## 7. 错误码
|
||
|
||
| 错误码 | 说明 | HTTP 状态码（如适用） |
|
||
|--------|------|---------------------|
|
||
| `message_format_invalid` | 消息格式无效 | 400 |
|
||
| `capability_lacking` | 能力不足 | 403 |
|
||
| `agent_not_ready` | Agent 未就绪 | 503 |
|
||
| `task_not_found` | 任务不存在 | 404 |
|
||
| `task_already_completed` | 任务已完成 | 409 |
|
||
| `execution_timeout` | 执行超时 | 504 |
|
||
| `execution_failed` | 执行失败 | 500 |
|
||
| `permission_denied` | 权限不足 | 403 |
|
||
| `invalid_params` | 参数无效 | 400 |
|
||
| `rate_limited` | 限流 | 429 |
|
||
|
||
**完整错误定义：** [types/errors.go](../types/errors.go)
|
||
|
||
---
|
||
|
||
## 8. 传输要求
|
||
|
||
### 8.1 HTTP 传输
|
||
- Content-Type: `application/json`
|
||
- 请求方法：`POST`
|
||
- 端点路径：由 Agent 自行定义，建议 `/synapse/callback`
|
||
- 超时：建议 30 秒
|
||
|
||
### 8.2 签名验证（可选）
|
||
- 使用 HMAC-SHA256 签名
|
||
- 签名放在 Header：`X-Synapse-Signature`
|
||
- 或放在消息体：`signature` 字段
|
||
|
||
---
|
||
|
||
## 9. 参考实现
|
||
|
||
本协议的参考实现位于 `p2p/` 目录：
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| [p2p/protocol.go](../p2p/protocol.go) | P2P 协议核心实现 |
|
||
| [types/types.go](../types/types.go) | 数据类型定义 |
|
||
| [types/errors.go](../types/errors.go) | 错误定义 |
|
||
| [transport/transport.go](../transport/transport.go) | HTTP 传输实现 |
|
||
|
||
---
|
||
|
||
## 附录 A：能力声明格式
|
||
|
||
参见 [灵隙原始协议（Synapse Raw Protocol） - Capability](./01-a2a-raw-protocol.md#44-capability能力)
|