# 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能力)