第21章 Agent 间通信协议 —— 子代理的标准化对话
目录
上一篇我们深入了子代理隔离机制。本章我们看 Agent 间通信协议——标准化对话机制。
Agent 间通信是什么
一句话定义：主 Agent 与子 Agent 的标准化对话格式——请求、结果、状态、错误。
Agent Communication Protocol = 标准化对话格式 定位：多智能体架构的通信标准，统一协作对话
图表
代码
graph LR
Main[主 Agent] -->|请求
Agent工具调用| Sub[子 Agent]
Sub -->|结果
标准化格式| Main
Sub -->|状态
执行状态| Main
Sub -->|错误
错误信息| Main
Main[发送方]
Sub[接收方]graph LR
Main[主 Agent] -->|请求
Agent工具调用| Sub[子 Agent]
Sub -->|结果
标准化格式| Main
Sub -->|状态
执行状态| Main
Sub -->|错误
错误信息| Main
Main[发送方]
Sub[接收方]graph LR
Main[主 Agent] -->|请求
Agent工具调用| Sub[子 Agent]
Sub -->|结果
标准化格式| Main
Sub -->|状态
执行状态| Main
Sub -->|错误
错误信息| Main
Main[发送方]
Sub[接收方]graph LR
Main[主 Agent] -->|请求<br/>Agent工具调用| Sub[子 Agent]
Sub -->|结果<br/>标准化格式| Main
Sub -->|状态<br/>执行状态| Main
Sub -->|错误<br/>错误信息| Main
Main[发送方]
Sub[接收方]核心机制：
- 请求协议：主 Agent 发送标准化请求
- 结果协议：子 Agent 返回标准化结果
- 状态协议：子 Agent 报告执行状态
- 错误协议：子 Agent 返回标准化错误
为什么需要通信协议
没有协议的问题
图表
代码
graph TB
subgraph NoProtocolProblem["没有协议的问题"]
P1[格式混乱
返回格式不统一]
P2[解析困难
主Agent难以解析]
P3[信息丢失
关键信息遗漏]
P4[协作低效
沟通效率低]
end
style NoProtocolProblem fill:#FFE0E0graph TB
subgraph NoProtocolProblem["没有协议的问题"]
P1[格式混乱
返回格式不统一]
P2[解析困难
主Agent难以解析]
P3[信息丢失
关键信息遗漏]
P4[协作低效
沟通效率低]
end
style NoProtocolProblem fill:#FFE0E0graph TB
subgraph NoProtocolProblem["没有协议的问题"]
P1[格式混乱
返回格式不统一]
P2[解析困难
主Agent难以解析]
P3[信息丢失
关键信息遗漏]
P4[协作低效
沟通效率低]
end
style NoProtocolProblem fill:#FFE0E0graph TB
subgraph NoProtocolProblem["没有协议的问题"]
P1[格式混乱<br/>返回格式不统一]
P2[解析困难<br/>主Agent难以解析]
P3[信息丢失<br/>关键信息遗漏]
P4[协作低效<br/>沟通效率低]
end
style NoProtocolProblem fill:#FFE0E0| 问题 | 说明 | 影响 |
|---|---|---|
| 格式混乱 | 子 Agent 返回格式不统一 | 主 Agent 难以处理 |
| 解析困难 | 主 Agent 需要解析多种格式 | 处理逻辑复杂 |
| 信息丢失 | 关键信息可能遗漏 | 决策信息不完整 |
| 协作低效 | 沟通效率低 | 协作效率下降 |
协议的好处
图表
代码
graph TB
subgraph ProtocolBenefits["协议的好处"]
B1[格式统一
标准化返回格式]
B2[易于解析
主Agent统一处理]
B3[信息完整
关键信息标准化]
B4[协作高效
沟通效率高]
end
style ProtocolBenefits fill:#E0FFE0graph TB
subgraph ProtocolBenefits["协议的好处"]
B1[格式统一
标准化返回格式]
B2[易于解析
主Agent统一处理]
B3[信息完整
关键信息标准化]
B4[协作高效
沟通效率高]
end
style ProtocolBenefits fill:#E0FFE0graph TB
subgraph ProtocolBenefits["协议的好处"]
B1[格式统一
标准化返回格式]
B2[易于解析
主Agent统一处理]
B3[信息完整
关键信息标准化]
B4[协作高效
沟通效率高]
end
style ProtocolBenefits fill:#E0FFE0graph TB
subgraph ProtocolBenefits["协议的好处"]
B1[格式统一<br/>标准化返回格式]
B2[易于解析<br/>主Agent统一处理]
B3[信息完整<br/>关键信息标准化]
B4[协作高效<br/>沟通效率高]
end
style ProtocolBenefits fill:#E0FFE0| 好处 | 说明 | 价值 |
|---|---|---|
| 格式统一 | 标准化返回格式 | 易于处理 |
| 易于解析 | 主 Agent 统一处理逻辑 | 解析简单 |
| 信息完整 | 关键信息标准化包含 | 决策完整 |
| 协作高效 | 沟通效率高 | 协作顺畅 |
通信协议的组成
四种核心协议
图表
代码
graph TB
subgraph Protocols["四种核心协议"]
Request[请求协议
主Agent发送]
Result[结果协议
子Agent返回]
Status[状态协议
执行状态]
Error[错误协议
错误信息]
end
Request --> Sub[子 Agent]
Sub --> Result --> Main[主 Agent]
Sub --> Status --> Main
Sub --> Error --> Maingraph TB
subgraph Protocols["四种核心协议"]
Request[请求协议
主Agent发送]
Result[结果协议
子Agent返回]
Status[状态协议
执行状态]
Error[错误协议
错误信息]
end
Request --> Sub[子 Agent]
Sub --> Result --> Main[主 Agent]
Sub --> Status --> Main
Sub --> Error --> Maingraph TB
subgraph Protocols["四种核心协议"]
Request[请求协议
主Agent发送]
Result[结果协议
子Agent返回]
Status[状态协议
执行状态]
Error[错误协议
错误信息]
end
Request --> Sub[子 Agent]
Sub --> Result --> Main[主 Agent]
Sub --> Status --> Main
Sub --> Error --> Maingraph TB
subgraph Protocols["四种核心协议"]
Request[请求协议<br/>主Agent发送]
Result[结果协议<br/>子Agent返回]
Status[状态协议<br/>执行状态]
Error[错误协议<br/>错误信息]
end
Request --> Sub[子 Agent]
Sub --> Result --> Main[主 Agent]
Sub --> Status --> Main
Sub --> Error --> Main| 协议类型 | 发送方 | 接收方 | 内容 |
|---|---|---|---|
| 请求协议 | 主 Agent | 子 Agent | Agent 工具调用 |
| 结果协议 | 子 Agent | 主 Agent | 执行结果 |
| 状态协议 | 子 Agent | 主 Agent | 执行状态 |
| 错误协议 | 子 Agent | 主 Agent | 错误信息 |
请求协议
Agent 工具调用格式
一句话定义：主 Agent 通过 Agent 工具派发子 Agent。
{
"name": "Agent",
"parameters": {
"subagent_type": "code-reviewer", // 子 Agent 类型
"prompt": "审查 app.ts 文件的代码质量", // 任务描述
"description": "代码审查任务" // 可选：任务简介
}
}请求参数详解
| 参数 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
| subagent_type | string | ✅ 必填 | 子 Agent 类型 | “code-reviewer” |
| prompt | string | ✅ 必填 | 任务描述 | “审查 app.ts” |
| description | string | ⚠️ 可选 | 任务简介 | “代码审查” |
子 Agent 类型列表
常见子 Agent 类型：
| subagent_type | 专用领域 | 典型任务 |
|---|---|---|
| “code-reviewer” | 代码审查 | 审查代码质量、安全、性能 |
| “security-reviewer” | 安全审查 | OWASP Top 10 漏洞检查 |
| “tdd-guide” | 测试开发 | 编写单元测试、集成测试 |
| “doc-updater” | 文档生成 | 生成 README、API 文档 |
| “planner” | 规划 | 制定实现计划、任务拆解 |
| “build-error-resolver” | 构建错误 | 解决编译、构建问题 |
请求示例
代码审查请求：
{
"name": "Agent",
"parameters": {
"subagent_type": "code-reviewer",
"prompt": "审查 /src/app.ts 文件的代码质量，重点关注：\n1. 代码可读性\n2. 函数复杂度\n3. 命名规范\n4. 潜在 Bug",
"description": "代码质量审查"
}
}安全审查请求：
{
"name": "Agent",
"parameters": {
"subagent_type": "security-reviewer",
"prompt": "审查 /src/auth.ts 文件的安全问题，检查 OWASP Top 10 漏洞",
"description": "安全漏洞审查"
}
}测试编写请求：
{
"name": "Agent",
"parameters": {
"subagent_type": "tdd-guide",
"prompt": "为 /src/validate.ts 文件编写单元测试，覆盖率目标 80%",
"description": "单元测试编写"
}
}结果协议
结果返回格式
一句话定义：子 Agent 完成任务后返回标准化结果。
{
"result_type": "success", // 结果类型：success/failure/partial
"subagent_type": "code-reviewer", // 子 Agent 类型
"content": "...", // 结果内容
"metadata": {
"files_analyzed": 1, // 分析的文件数
"issues_found": 5, // 发现的问题数
"execution_time": "30 seconds" // 执行时间
}
}结果字段详解
| 字段 | 类型 | 说明 | 示例 |
|---|---|---|---|
| result_type | string | 结果类型 | “success” / “failure” / “partial” |
| subagent_type | string | 子 Agent 类型 | “code-reviewer” |
| content | string | 结果内容（核心） | 审查报告、测试结果等 |
| metadata | object | 元数据（可选） | 执行统计、文件列表等 |
结果类型说明
| result_type | 说明 | 含义 |
|---|---|---|
| success | 成功完成 | 任务完全完成 |
| failure | 执行失败 | 任务无法完成 |
| partial | 部分完成 | 任务部分完成 |
结果示例
代码审查成功结果：
[code-reviewer] 审查完成
## 审查报告
### 文件：/src/app.ts
**总体评分**：B（良好）
### 发现的问题
| 行号 | 问题类型 | 严重程度 | 说明 |
|------|---------|---------|------|
| 15 | 复杂度 | 中 | 函数 `processData` 复杂度过高（15） |
| 32 | 命名 | 低 | 变量 `x` 命名不清晰 |
| 45 | 安全 | 高 | SQL 查询未使用参数化 |
| 58 | 性能 | 中 | 循环中重复计算 |
| 72 | Bug | 高 | 未处理空值情况 |
### 建议修改
1. **SQL 查询参数化**（优先级：高）
```typescript
// 当前：const query = `SELECT * FROM users WHERE id = ${id}`;
// 建议：const query = 'SELECT * FROM users WHERE id = ?';- 添加空值处理（优先级：高）
if (data === null) { return defaultValue; }
审查完成，发现 5 个问题，建议优先修复 2 个高优先级问题。
**测试编写成功结果**：
```markdown
[tdd-guide] 测试编写完成
## 测试结果
### 创建文件
- /src/validate.test.ts（新建）
### 测试覆盖
- 函数覆盖率：85%
- 行覆盖率：82%
- 分支覆盖率：78%
### 测试数量
- 单元测试：12 个
- 通过：10 个
- 失败：2 个（已修复）
### 测试命令
```bash
npm test validate.test.ts测试编写完成，覆盖率 82%，达到目标 80%。
**部分完成结果**：
```markdown
[code-reviewer] 审查部分完成
## 审查报告
### 已完成
- 文件：/src/app.ts（审查完成）
- 发现 5 个问题
### 未完成
- 文件：/src/utils.ts（超出上下文限制）
### 建议
- 继续审查 utils.ts 文件（派发新的子 Agent）
---
**审查部分完成，建议继续审查剩余文件。**状态协议
执行状态报告
一句话定义：子 Agent 报告执行过程中的状态。
图表
代码
graph LR
Sub[子 Agent] -->|Status: initializing| Main[主 Agent]
Sub -->|Status: executing| Main
Sub -->|Status: completing| Main
Sub -->|Status: done| Maingraph LR
Sub[子 Agent] -->|Status: initializing| Main[主 Agent]
Sub -->|Status: executing| Main
Sub -->|Status: completing| Main
Sub -->|Status: done| Maingraph LR
Sub[子 Agent] -->|Status: initializing| Main[主 Agent]
Sub -->|Status: executing| Main
Sub -->|Status: completing| Main
Sub -->|Status: done| Maingraph LR
Sub[子 Agent] -->|Status: initializing| Main[主 Agent]
Sub -->|Status: executing| Main
Sub -->|Status: completing| Main
Sub -->|Status: done| Main状态类型
| 状态 | 说明 | 含义 |
|---|---|---|
| initializing | 初始化 | 子 Agent 初始化中 |
| executing | 执行中 | 子 Agent 执行 Loop |
| completing | 完成中 | 子 Agent 生成结果 |
| done | 完成 | 子 Agent 任务完成 |
状态报告格式
{
"status": "executing",
"subagent_type": "code-reviewer",
"progress": {
"current_step": "reading files",
"steps_completed": 2,
"steps_total": 5
}
}状态报告示例
初始化状态：
[code-reviewer] 初始化中...
正在加载 System Prompt，准备审查文件。执行中状态：
[code-reviewer] 执行中...
已完成：
- Read /src/app.ts
当前步骤：
- Grep 搜索代码模式
进度：2/5 步骤完成完成中状态：
[code-reviewer] 完成中...
正在生成审查报告，整合分析结果。完成状态：
[code-reviewer] 完成
审查报告已生成，返回给主 Agent。错误协议
错误返回格式
一句话定义：子 Agent 执行失败时返回标准化错误。
{
"result_type": "failure",
"subagent_type": "code-reviewer",
"error": {
"error_type": "file_not_found",
"error_message": "文件 /src/app.ts 不存在",
"error_code": "ENOENT"
},
"suggestion": "检查文件路径或创建文件"
}错误字段详解
| 字段 | 类型 | 说明 | 示例 |
|---|---|---|---|
| result_type | string | “failure” | “failure” |
| subagent_type | string | 子 Agent 类型 | “code-reviewer” |
| error_type | string | 错误类型 | “file_not_found” |
| error_message | string | 错误消息 | “文件不存在” |
| error_code | string | 错误代码 | “ENOENT” |
| suggestion | string | 建议操作 | “检查文件路径” |
错误类型列表
| error_type | 说明 | 原因 |
|---|---|---|
| file_not_found | 文件不存在 | Read 文件失败 |
| permission_denied | 权限拒绝 | 用户拒绝操作 |
| tool_execution_error | 工具执行错误 | 工具调用失败 |
| context_overflow | 上下文溢出 | messages 超出窗口 |
| timeout | 执行超时 | 执行时间过长 |
| unknown | 未知错误 | 其他错误 |
错误示例
文件不存在错误：
[code-reviewer] 执行失败
**错误类型**：file_not_found
**错误消息**：文件 /src/app.ts 不存在
**错误代码**：ENOENT
**建议**：检查文件路径，或先创建文件。
---
主 Agent 可选择：
1. 创建文件后再审查
2. 调整审查路径
3. 跳过审查权限拒绝错误：
[tdd-guide] 执行失败
**错误类型**：permission_denied
**错误消息**：用户拒绝写入测试文件
**错误代码**：PERM_DENY
**建议**：请求用户批准写入操作，或调整测试文件路径。
---
主 Agent 可选择：
1. 请求用户批准
2. 调整文件路径
3. 跳过测试编写上下文溢出错误：
[code-reviewer] 执行失败
**错误类型**：context_overflow
**错误消息**：上下文超出窗口限制（200K tokens）
**错误代码**：OVERFLOW
**建议**：拆解任务，派发多个子 Agent 分批审查。
---
主 Agent 可选择：
1. 拆解为多个审查任务
2. 只审查部分文件
3. 使用传递隔离减少上下文通信协议的设计原则
设计原则
图表
代码
graph TB
subgraph DesignPrinciples["通信协议设计原则"]
D1[格式标准化
统一返回格式]
D2[信息完整
包含关键信息]
D3[易于解析
主Agent易处理]
D4[错误明确
错误类型标准化]
D5[建议可行
提供解决建议]
endgraph TB
subgraph DesignPrinciples["通信协议设计原则"]
D1[格式标准化
统一返回格式]
D2[信息完整
包含关键信息]
D3[易于解析
主Agent易处理]
D4[错误明确
错误类型标准化]
D5[建议可行
提供解决建议]
endgraph TB
subgraph DesignPrinciples["通信协议设计原则"]
D1[格式标准化
统一返回格式]
D2[信息完整
包含关键信息]
D3[易于解析
主Agent易处理]
D4[错误明确
错误类型标准化]
D5[建议可行
提供解决建议]
endgraph TB
subgraph DesignPrinciples["通信协议设计原则"]
D1[格式标准化<br/>统一返回格式]
D2[信息完整<br/>包含关键信息]
D3[易于解析<br/>主Agent易处理]
D4[错误明确<br/>错误类型标准化]
D5[建议可行<br/>提供解决建议]
end| 原则 | 说明 | 实现方式 |
|---|---|---|
| 格式标准化 | 统一返回格式 | 使用固定字段结构 |
| 信息完整 | 包含关键信息 | 包含 result_type、content、metadata |
| 易于解析 | 主 Agent 易处理 | Markdown 或 JSON 格式 |
| 错误明确 | 错误类型标准化 | 使用 error_type 分类 |
| 建议可行 | 提供解决建议 | 提供具体的解决建议 |
通信协议的典型流程
完整通信流程
图表
代码
sequenceDiagram
participant Main as 主 Agent
participant AgentTool as Agent 工具
participant Sub as 子 Agent
Main->>AgentTool: 发送请求（Agent 工具调用）
AgentTool->>Sub: 创建子 Agent
Sub-->>Main: 状态：initializing
Sub->>Sub: 执行 Loop
Sub-->>Main: 状态：executing
Sub->>Sub: 完成任务
Sub-->>Main: 状态：completing
Sub->>AgentTool: 返回结果（标准化格式）
AgentTool-->>Main: 返回结果
Main->>Main: 处理结果
Main->>Main: 决策下一步sequenceDiagram
participant Main as 主 Agent
participant AgentTool as Agent 工具
participant Sub as 子 Agent
Main->>AgentTool: 发送请求（Agent 工具调用）
AgentTool->>Sub: 创建子 Agent
Sub-->>Main: 状态：initializing
Sub->>Sub: 执行 Loop
Sub-->>Main: 状态：executing
Sub->>Sub: 完成任务
Sub-->>Main: 状态：completing
Sub->>AgentTool: 返回结果（标准化格式）
AgentTool-->>Main: 返回结果
Main->>Main: 处理结果
Main->>Main: 决策下一步sequenceDiagram
participant Main as 主 Agent
participant AgentTool as Agent 工具
participant Sub as 子 Agent
Main->>AgentTool: 发送请求（Agent 工具调用）
AgentTool->>Sub: 创建子 Agent
Sub-->>Main: 状态：initializing
Sub->>Sub: 执行 Loop
Sub-->>Main: 状态：executing
Sub->>Sub: 完成任务
Sub-->>Main: 状态：completing
Sub->>AgentTool: 返回结果（标准化格式）
AgentTool-->>Main: 返回结果
Main->>Main: 处理结果
Main->>Main: 决策下一步sequenceDiagram
participant Main as 主 Agent
participant AgentTool as Agent 工具
participant Sub as 子 Agent
Main->>AgentTool: 发送请求（Agent 工具调用）
AgentTool->>Sub: 创建子 Agent
Sub-->>Main: 状态：initializing
Sub->>Sub: 执行 Loop
Sub-->>Main: 状态：executing
Sub->>Sub: 完成任务
Sub-->>Main: 状态：completing
Sub->>AgentTool: 返回结果（标准化格式）
AgentTool-->>Main: 返回结果
Main->>Main: 处理结果
Main->>Main: 决策下一步错误处理流程
图表
代码
sequenceDiagram
participant Main as 主 Agent
participant Sub as 子 Agent
Main->>Sub: 发送请求
Sub->>Sub: 执行 Loop
Sub->>Sub: 遇到错误
Sub-->>Main: 返回错误（标准化格式）
Main->>Main: 分析错误
Main->>Main: 决策策略
alt 重试
Main->>Sub: 重新派发（调整参数）
else 调整策略
Main->>Main: 调整下一步动作
else 跳过
Main->>Main: 跳过该任务
endsequenceDiagram
participant Main as 主 Agent
participant Sub as 子 Agent
Main->>Sub: 发送请求
Sub->>Sub: 执行 Loop
Sub->>Sub: 遇到错误
Sub-->>Main: 返回错误（标准化格式）
Main->>Main: 分析错误
Main->>Main: 决策策略
alt 重试
Main->>Sub: 重新派发（调整参数）
else 调整策略
Main->>Main: 调整下一步动作
else 跳过
Main->>Main: 跳过该任务
endsequenceDiagram
participant Main as 主 Agent
participant Sub as 子 Agent
Main->>Sub: 发送请求
Sub->>Sub: 执行 Loop
Sub->>Sub: 遇到错误
Sub-->>Main: 返回错误（标准化格式）
Main->>Main: 分析错误
Main->>Main: 决策策略
alt 重试
Main->>Sub: 重新派发（调整参数）
else 调整策略
Main->>Main: 调整下一步动作
else 跳过
Main->>Main: 跳过该任务
endsequenceDiagram
participant Main as 主 Agent
participant Sub as 子 Agent
Main->>Sub: 发送请求
Sub->>Sub: 执行 Loop
Sub->>Sub: 遇到错误
Sub-->>Main: 返回错误（标准化格式）
Main->>Main: 分析错误
Main->>Main: 决策策略
alt 重试
Main->>Sub: 重新派发（调整参数）
else 调整策略
Main->>Main: 调整下一步动作
else 跳过
Main->>Main: 跳过该任务
end通信协议的实现
Agent 工具实现
# Agent 工具实现
def execute_agent_tool(tool_params):
subagent_type = tool_params["subagent_type"]
prompt = tool_params["prompt"]
# 1. 创建子 Agent
sub_agent = create_subagent(subagent_type, prompt)
# 2. 报告初始化状态
report_status("initializing", subagent_type)
# 3. 执行子 Agent Loop
try:
result = run_agent_loop(sub_agent)
# 4. 报告完成状态
report_status("done", subagent_type)
# 5. 返回标准化结果
return {
"result_type": "success",
"subagent_type": subagent_type,
"content": result.content,
"metadata": result.metadata
}
except Exception as e:
# 6. 返回标准化错误
return {
"result_type": "failure",
"subagent_type": subagent_type,
"error": {
"error_type": classify_error(e),
"error_message": str(e),
"error_code": e.code if hasattr(e, 'code') else "UNKNOWN"
},
"suggestion": generate_suggestion(e)
}主 Agent 处理实现
# 主 Agent 处理子 Agent 结果
def handle_subagent_result(result):
result_type = result["result_type"]
if result_type == "success":
# 处理成功结果
content = result["content"]
metadata = result["metadata"]
# 追加到 messages
messages.append({
"role": "user",
"content": content
})
# 根据结果决策下一步
decide_next_step(content, metadata)
elif result_type == "failure":
# 处理错误
error = result["error"]
suggestion = result["suggestion"]
# 根据错误类型调整策略
adjust_strategy(error, suggestion)
elif result_type == "partial":
# 处理部分完成
content = result["content"]
# 决策是否继续
decide_continue(content)本章小结
- 通信协议定义：主 Agent 与子 Agent 的标准化对话格式
- 没有协议问题：格式混乱、解析困难、信息丢失、协作低效
- 协议好处：格式统一、易于解析、信息完整、协作高效
- 四种协议：请求协议、结果协议、状态协议、错误协议
- 请求协议：Agent 工具调用（subagent_type、prompt、description）
- 结果协议：result_type、subagent_type、content、metadata
- 状态协议：initializing、executing、completing、done
- 错误协议：error_type、error_message、error_code、suggestion
- 错误类型：file_not_found、permission_denied、tool_execution_error、context_overflow、timeout
- 设计原则：格式标准化、信息完整、易于解析、错误明确、建议可行
- 实现方式：Agent 工具创建子 Agent，执行 Loop，返回标准化结果
预告：下一篇我们进入第七部分——从零构建自己的 Harness。
相关内容
- 第01章 Agent 的 70 年简史 —— 从符号推理到深度学习
- 第02章 LLM 时代的 Agent 革命 —— 2023-2026 爆发期
- 第03章 Harness 概念溯源 —— "模型是大脑，Harness是身体"
- 第04章 Harness 核心架构 —— 四层模型详解
- 第05章 Harness vs Agent vs Model —— 三者关系辨析
收录于 合集・01-AI 工具与智能体/07-Harness 27
如果这篇文章对你有帮助，欢迎请我喝杯咖啡 ☕
支付宝
微信