一、协议消息概述
在子代理系统中，代理之间的通信需要遵循一套标准化的协议消息格式。协议消息（Protocol Message）是指使用预定义的JSON结构进行通信的消息，其核心特征是使用type字段唯一标识消息类型。客户端（接收方）根据type字段的值自动匹配对应的处理逻辑，实现消息的自动化处理。
协议消息的设计遵循以下原则：
- 结构化预定义：每种消息类型都有固定的字段结构，发送方和接收方共同遵守同一规范，确保通信的可靠性和可预测性
- 类型驱动处理：客户端维护一个消息类型到处理函数的映射表，收到消息后根据type字段自动路由到对应的处理器，无需手动判断
- 双向对称通信：大多数协议消息都采用请求-响应模式，请求方发送特定类型的request，接收方回复对应类型的response，形成完整的通信闭环
- 可扩展性：协议类型可以按需扩展，新增的消息类型只需要注册新的处理器即可，不影响已有协议的处理
核心概念：协议消息本质上是代理之间的一种"约定"，通过标准化格式将通信意图表达为机器可解析的结构化数据，而非自然语言文本。这使得代理能够自动理解和处理彼此的消息。
协议消息的典型场景包括：主代理通知子代理关闭的shutdown协议、子代理向主代理请求计划审批的plan_approval协议、以及代理间传递任务进度的progress协议等。本笔记重点讲解shutdown和plan_approval两种核心协议。
二、shutdown_request关闭协议
shutdown协议是主代理控制子代理生命周期的核心机制。当主代理判定子代理的任务已完成、超时或需要中止时，会通过shutdown协议向子代理发送关闭指令。
2.1 协议流程
shutdown协议采用标准的请求-响应模式，共分为四个阶段：
- 主代理发起关闭：主代理向子代理发送shutdown_request消息，其中包含reason字段说明关闭原因
- 子代理收到请求：子代理收到shutdown_request后，开始执行清理工作（如保存中间状态、释放资源等）
- 子代理回复确认：清理完成后，子代理回复shutdown_response消息，包含request_id用于关联原始请求，以及approve字段表示是否同意关闭
- 主代理确认关闭：主代理收到shutdown_response后，根据approve字段的值决定是否最终关闭子代理
2.2 消息格式示例
// 主代理 → 子代理：shutdown_request
{
"to": "subagent-01",
"summary": "主代理请求关闭子代理",
"message": {
"type": "shutdown_request",
"request_id": "req_001",
"reason": "task_completed",
"timestamp": "2026-05-08T10:00:00Z"
}
}
// 子代理 → 主代理：shutdown_response
{
"to": "main-agent",
"summary": "子代理确认关闭请求",
"message": {
"type": "shutdown_response",
"request_id": "req_001",
"approve": true,
"cleanup_status": "completed",
"timestamp": "2026-05-08T10:00:05Z"
}
}
2.3 关闭原因（reason字段）
reason字段用于告知子代理关闭的原因，常见取值包括：
- task_completed：任务正常完成，子代理可以安全关闭
- task_timeout：任务执行超时，需要强制中止
- parent_abort：主代理自身被关闭，需要级联关闭子代理
- system_shutdown：系统整体关闭，所有代理都需要终止
- error_recovery：发生不可恢复错误，需要重启代理
注意：当reason为task_timeout或error_recovery时，子代理可能会收到未完成的中间结果。子代理应当在cleanup阶段保存当前进度状态，以便后续恢复执行。
2.4 子代理的清理工作
子代理在收到shutdown_request后，需要进行以下清理操作：
- 保存当前处理进度和中间状态到持久存储
- 释放占用的系统资源（文件句柄、网络连接等）
- 终止正在运行的子任务或子子代理
- 记录关闭日志以备后续审计
- 回复shutdown_response告知主代理清理状态
三、plan_approval审批协议
plan_approval协议是子代理在执行关键决策前向主代理请求审批的机制。该协议确保子代理的重大操作得到主代理的确认，避免子代理做出超出权限范围的决策。
3.1 协议流程
- 子代理提交计划：子代理在需要执行关键操作前，向主代理发送plan_approval_request消息，包含详细的计划内容
- 主代理审查计划：主代理收到请求后，审查计划的安全性和合理性，判断是否批准执行
- 主代理回复结果：主代理回复plan_approval_response，approve字段为true表示批准，为false表示拒绝。拒绝时可附带feedback字段说明原因和改进方向
- 子代理根据反馈修改：若计划被拒绝，子代理根据feedback中的建议修改计划，然后重新提交审批，直到通过或达到最大重试次数
3.2 消息格式示例
// 子代理 → 主代理：plan_approval_request
{
"to": "main-agent",
"summary": "子代理请求计划审批",
"message": {
"type": "plan_approval_request",
"request_id": "req_002",
"plan": {
"action": "execute_command",
"target": "database_server",
"command": "SELECT * FROM users",
"estimated_impact": "read_only",
"reason": "需要查询用户数据完成报表生成"
},
"priority": "high"
}
}
// 主代理 → 子代理：plan_approval_response（拒绝）
{
"to": "subagent-01",
"summary": "主代理拒绝审批",
"message": {
"type": "plan_approval_response",
"request_id": "req_002",
"approve": false,
"feedback": "查询范围过大，请添加WHERE条件限制结果集，避免全表扫描影响数据库性能",
"suggestions": [
"添加时间范围过滤",
"限制返回行数不超过1000"
],
"timestamp": "2026-05-08T10:01:00Z"
}
}
3.3 审批策略
主代理对计划的审批决策通常基于以下策略：
- 基于风险评估：评估操作的风险等级，高风险操作为拒绝，低风险操作为批准
- 基于权限边界：检查操作是否在子代理的授权范围内，越权操作直接拒绝
- 基于资源影响：评估操作对系统资源的消耗，高消耗操作需要额外确认
- 自动通过规则：对于已确认安全的操作类型，可以配置自动通过规则，无需人工审批
3.4 反馈与重试机制
当子代理的计划被拒绝时，feedback字段提供了拒绝的原因和改进建议。子代理应当：
- 仔细解析feedback内容，理解拒绝原因
- 根据suggestions调整计划内容
- 修改完成后重新提交审批请求
- 设置最大重试次数（通常为3次），超过后停止提交并上报异常
最佳实践：子代理在首次提交计划时，应尽量详细描述操作的目的、影响范围和安全措施，以减少被拒绝的次数。预先考虑可能的风险并在计划中明确应对方案，可以提高审批通过率。
四、协议消息的JSON格式
所有协议消息统一采用JSON格式进行序列化，遵守以下标准结构：
4.1 消息外层结构
{
"to": "接收方标识",
"summary": "消息摘要（用于快速预览）",
"message": {
"type": "消息类型标识",
// 类型特定的字段...
}
}
外层结构包含三个固定字段：
- to：接收方的唯一标识，用于消息路由
- summary：简短的文本摘要，便于日志查看和调试
- message：消息体，包含type字段和协议特定的数据字段
4.2 type字段的命名规范
type字段是消息类型的唯一标识，遵循以下命名规范：
- 使用小写字母和下划线命名（snake_case）
- 格式为"动作_目标"，如shutdown_request、plan_approval_response
- 请求消息以_request结尾，响应消息以_response结尾
- 类型名称应当具有自描述性，见名知意
4.3 request_id的使用规范
request_id是关联请求和响应消息的关键字段：
- 请求方在发送request时生成唯一的request_id
- 响应方在回复response时携带相同的request_id
- 请求方通过request_id将响应匹配到对应的请求
- request_id通常采用UUID或递增序号，确保全局唯一
- 超时未收到匹配的response时，请求方可以重新发送请求
4.4 自定义字段扩展
协议消息支持按需添加自定义字段，扩展时需注意：
- 自定义字段放在message对象中，不修改外层结构
- 字段命名使用camelCase或snake_case，保持一致性
- 保持向后兼容性，新增字段不应影响已有处理逻辑
- 建议在字段注释中说明其用途和预期值范围
- 接收方对未知字段应忽略处理，而不是报错中断
// 带自定义字段的协议消息示例
{
"to": "subagent-01",
"summary": "任务进度更新",
"message": {
"type": "progress_report",
"request_id": "req_003",
"progress": 75,
"status": "processing",
"custom_fields": {
"estimated_remaining_time": "2m30s",
"memory_usage_mb": 128,
"subtask_id": "subtask-05"
}
}
}
五、协议处理的错误处理
协议消息处理过程中可能遇到多种异常情况，需要系统具备完善的错误处理机制。
5.1 超时处理
当请求方在指定时间内未收到响应时，需要执行降级策略：
- 设置超时时间：每个请求都携带一个超时阈值（如30秒），超时后自动触发降级
- 重试机制：对幂等请求可以自动重试，设置最大重试次数（通常3次），每次重试间隔递增
- 降级策略：shutdown超时可采用强制关闭；plan_approval超时可采用默认审批结果（通常为拒绝）
- 记录超时日志：所有超时事件记录详细的时间、请求方、响应方信息，便于事后分析
5.2 格式错误处理
协议消息的JSON格式错误或字段缺失时，系统应采取以下措施：
- JSON解析错误：捕获解析异常，记录原始消息内容，回复格式错误提示
- 必填字段校验：检查type、request_id等必填字段是否存在，缺失时拒绝处理
- 类型校验：验证字段值的类型是否符合预期（如approve字段是否为布尔值）
- 宽松解析策略：对非关键字段的缺失采用默认值填充，不中断处理流程
5.3 协议状态不一致恢复
在分布式环境中，请求和响应可能因为网络问题导致状态不一致，需要以下恢复机制：
- 状态持久化：请求方在发送请求前将请求状态写入持久存储
- 状态同步：接收方在处理完协议后同步更新状态，确保状态一致性
- 幂等处理：同一条请求消息重复到达时，接收方保证处理结果相同
- 状态恢复扫描：系统定时扫描处于"等待响应"状态的请求，对超时或丢失的请求进行恢复
5.4 协议日志记录和审计
完整的日志记录是协议系统可靠运行的重要保障：
- 全量记录：所有发送和接收的协议消息都记录到日志系统，包括消息内容和时间戳
- 异常告警：对超时、格式错误、状态不一致等异常事件触发告警通知
- 审计追踪：提供协议消息的完整链路追踪，从发起请求到最终响应的全过程可追溯
- 统计分析：定期统计协议消息的处理成功率、平均响应时间、异常分布等指标
核心要点总结：协议消息处理是子代理系统的通信基石。shutdown协议实现了代理的优雅关闭和生命周期管理，plan_approval协议保障了关键操作的安全可控。标准化的JSON格式和request_id机制确保了消息的可靠路由和追踪，完善的错误处理机制（超时重试、格式校验、状态恢复、日志审计）保障了系统的稳定运行。理解并掌握这些协议机制，是构建可靠的多代理协作系统的基础。