# 多智能体模式工具定义

> 主智能体工具基于现有主智能体工具，移除旧版子智能体工具，新增多智能体专用工具。  
> 子智能体工具保留现有 8 个基础工具，新增多智能体通信工具。  
> 所有工具定义集中在 `modules/multi_agent/tools/` 目录下，不修改现有 `core/main_terminal_parts/tools_definition/`。

---

## 1. 主智能体（Team Leader）工具

主智能体 = Team Leader，其工具列表 = 现有主智能体工具（去掉旧版子智能体工具） + 多智能体专用工具。

### 1.1 从现有工具中移除

以下旧版子智能体工具不在多智能体模式中使用：

- `create_sub_agent`（旧版）
- `close_sub_agent`
- `terminate_sub_agent`（旧版）
- `get_sub_agent_status`（旧版）

### 1.2 新增/替换的多智能体工具

#### `create_sub_agent`

创建并启动一个子智能体实例。

```json
{
  "type": "function",
  "function": {
    "name": "create_sub_agent",
    "description": "创建一个子智能体实例并启动它。一个角色可以有多个实例，如 UI Operator_1、UI Operator_2。",
    "parameters": {
      "type": "object",
      "properties": {
        "agent_id": {
          "type": "integer",
          "description": "这个角色的第几个实例，从 1 开始。同一 role_id 下每个编号只能用一次。"
        },
        "role_id": {
          "type": "string",
          "description": "角色 ID，如 ui-operator、full-stack-engineer。"
        },
        "task": {
          "type": "string",
          "description": "任务描述，会作为给子智能体的首条任务发布消息。"
        },
        "run_in_background": {
          "type": "boolean",
          "description": "是否后台运行。多智能体模式下通常直接运行（false），因为需要观察输出。"
        },
        "timeout_seconds": {
          "type": "integer",
          "description": "超时时间，默认 600 秒。"
        },
        "thinking_mode": {
          "type": "string",
          "enum": ["fast", "thinking"],
          "description": "思考模式，不指定则使用角色配置。"
        },
        "model_key": {
          "type": "string",
          "description": "模型 key，不指定则使用角色配置。"
        }
      },
      "required": ["agent_id", "role_id", "task"]
    }
  }
}
```

#### `terminate_sub_agent`

强制终止指定子智能体实例。

```json
{
  "type": "function",
  "function": {
    "name": "terminate_sub_agent",
    "description": "强制终止指定子智能体实例。终止后无法恢复，但已生成的文件保留。",
    "parameters": {
      "type": "object",
      "properties": {
        "agent_id": {
          "type": "integer",
          "description": "要终止的子智能体实例编号。"
        }
      },
      "required": ["agent_id"]
    }
  }
}
```

#### `send_message_to_sub_agent`

向子智能体发送消息或运行中引导。不等待回答。

```json
{
  "type": "function",
  "function": {
    "name": "send_message_to_sub_agent",
    "description": "向指定子智能体发送消息。如果子智能体正在运行，消息会插入到当前输出流中作为引导；如果子智能体空闲，消息会触发新一轮运行。用于运行中纠正、补充上下文、追加指令。",
    "parameters": {
      "type": "object",
      "properties": {
        "agent_id": {
          "type": "integer",
          "description": "目标子智能体实例编号。"
        },
        "message": {
          "type": "string",
          "description": "要发送的消息内容。"
        }
      },
      "required": ["agent_id", "message"]
    }
  }
}
```

#### `ask_sub_agent`

向子智能体提问并等待回答。

```json
{
  "type": "function",
  "function": {
    "name": "ask_sub_agent",
    "description": "向指定子智能体提问并等待其回答。适用于需要子智能体给出明确答复的场景。",
    "parameters": {
      "type": "object",
      "properties": {
        "agent_id": {
          "type": "integer",
          "description": "目标子智能体实例编号。"
        },
        "question": {
          "type": "string",
          "description": "问题内容。"
        },
        "question_id": {
          "type": "string",
          "description": "问题唯一 ID，子智能体回答时会引用。"
        }
      },
      "required": ["agent_id", "question", "question_id"]
    }
  }
}
```

#### `answer_sub_agent_question`

回答子智能体向主智能体提出的问题。

```json
{
  "type": "function",
  "function": {
    "name": "answer_sub_agent_question",
    "description": "回答子智能体提出的问题。回答会返回到子智能体 ask_master 工具的结果中。",
    "parameters": {
      "type": "object",
      "properties": {
        "agent_id": {
          "type": "integer",
          "description": "提问的子智能体实例编号。"
        },
        "question_id": {
          "type": "string",
          "description": "问题 ID，与 ask_master 时一致。"
        },
        "answer": {
          "type": "string",
          "description": "回答内容。"
        }
      },
      "required": ["agent_id", "question_id", "answer"]
    }
  }
}
```

#### `list_active_sub_agents`

查询当前多智能体会话中所有活跃/可通信的子智能体。

```json
{
  "type": "function",
  "function": {
    "name": "list_active_sub_agents",
    "description": "查询当前多智能体会话中所有活跃或可通信的子智能体列表，包括运行中和空闲的实例。",
    "parameters": {
      "type": "object",
      "properties": {}
    }
  }
}
```

返回示例：

```json
{
  "success": true,
  "agents": [
    {
      "agent_id": 1,
      "role_id": "ui-operator",
      "display_name": "UI Operator_1",
      "status": "running",
      "summary": "设计前端配色方案"
    },
    {
      "agent_id": 2,
      "role_id": "full-stack-engineer",
      "display_name": "Full-Stack Engineer_1",
      "status": "idle",
      "summary": "等待 API 接口确认"
    }
  ]
}
```

#### `get_sub_agent_status`

查询指定子智能体的详细状态。

```json
{
  "type": "function",
  "function": {
    "name": "get_sub_agent_status",
    "description": "查询指定子智能体实例的详细状态、统计和最近输出。",
    "parameters": {
      "type": "object",
      "properties": {
        "agent_id": {
          "type": "integer",
          "description": "子智能体实例编号。"
        }
      },
      "required": ["agent_id"]
    }
  }
}
```

#### `create_custom_agent`

创建并保存自定义角色。

```json
{
  "type": "function",
  "function": {
    "name": "create_custom_agent",
    "description": "创建一个自定义角色并保存到本地，后续可通过 role_id 调用。",
    "parameters": {
      "type": "object",
      "properties": {
        "role_id": {
          "type": "string",
          "description": "角色 ID，唯一标识。"
        },
        "name": {
          "type": "string",
          "description": "角色显示名。"
        },
        "description": {
          "type": "string",
          "description": "角色简短描述。"
        },
        "model": {
          "type": "string",
          "description": "默认使用的模型。"
        },
        "thinking_mode": {
          "type": "string",
          "enum": ["fast", "thinking"],
          "description": "默认思考模式。"
        },
        "prompt": {
          "type": "string",
          "description": "角色专属 prompt。"
        }
      },
      "required": ["role_id", "name", "description", "prompt"]
    }
  }
}
```

#### `list_agents`

列出所有可用角色。

```json
{
  "type": "function",
  "function": {
    "name": "list_agents",
    "description": "列出所有可用的预置和自定义角色。",
    "parameters": {
      "type": "object",
      "properties": {}
    }
  }
}
```

---

## 2. 子智能体工具

子智能体保留现有 8 个基础工具：

- `read_file`
- `write_file`
- `edit_file`
- `run_command`
- `web_search`
- `extract_webpage`
- `search_workspace`
- `read_mediafile`

新增以下多智能体通信工具：

### 2.1 `ask_master`

向主智能体（Team Leader）提问，阻塞等待回答。

```json
{
  "type": "function",
  "function": {
    "name": "ask_master",
    "description": "向主智能体（Team Leader）提问。主智能体回答后会将结果返回到此工具调用中。",
    "parameters": {
      "type": "object",
      "properties": {
        "question": {
          "type": "string",
          "description": "问题内容。"
        },
        "question_id": {
          "type": "string",
          "description": "问题唯一 ID。"
        }
      },
      "required": ["question", "question_id"]
    }
  }
}
```

### 2.2 `ask_other_agent`

向其他子智能体提问或发送消息，阻塞等待回复。

```json
{
  "type": "function",
  "function": {
    "name": "ask_other_agent",
    "description": "向其他子智能体提问或发送消息。对方回复后会将结果返回到此工具调用中。注意：向其他子智能体提问时，必须同时直接向主智能体输出汇报。",
    "parameters": {
      "type": "object",
      "properties": {
        "target_agent_id": {
          "type": "integer",
          "description": "目标子智能体实例编号。"
        },
        "content": {
          "type": "string",
          "description": "提问或消息内容。"
        },
        "message_id": {
          "type": "string",
          "description": "消息唯一 ID。"
        }
      },
      "required": ["target_agent_id", "content", "message_id"]
    }
  }
}
```

### 2.3 `answer_other_agent`

回答其他子智能体的问题。

```json
{
  "type": "function",
  "function": {
    "name": "answer_other_agent",
    "description": "回答其他子智能体的问题。回答会返回到对方 ask_other_agent 工具的结果中。",
    "parameters": {
      "type": "object",
      "properties": {
        "source_agent_id": {
          "type": "integer",
          "description": "提问方的子智能体实例编号。"
        },
        "message_id": {
          "type": "string",
          "description": "对方提问时的 message_id。"
        },
        "answer": {
          "type": "string",
          "description": "回答内容。"
        }
      },
      "required": ["source_agent_id", "message_id", "answer"]
    }
  }
}
```

### 2.4 `list_active_sub_agents`

查询当前活跃子智能体。

```json
{
  "type": "function",
  "function": {
    "name": "list_active_sub_agents",
    "description": "查询当前多智能体会话中所有活跃或可通信的子智能体。",
    "parameters": {
      "type": "object",
      "properties": {}
    }
  }
}
```

---

## 3. 工具与消息映射

| 动作 | 工具 | 发送方 | 接收方形式 |
|------|------|--------|-----------|
| 创建子智能体 | `create_sub_agent` | Team Leader | 启动实例，首条消息以任务发布形式插入 |
| 终止子智能体 | `terminate_sub_agent` | Team Leader | 强制停止实例 |
| 向子智能体发消息/引导 | `send_message_to_sub_agent` | Team Leader | 插入子智能体 user 消息（inline 或触发新任务） |
| Team Leader 问子智能体 | `ask_sub_agent` | Team Leader | 插入子智能体 user 消息，等待回复 |
| 子智能体问 Team Leader | `ask_master` | 子智能体 | 插入 Team Leader user 消息，等待回答 |
| Team Leader 回答子智能体 | `answer_sub_agent_question` | Team Leader | 返回到 `ask_master` 工具结果 |
| 子智能体 A 问 B | `ask_other_agent` | A | 插入 B 的 user 消息（inline 或触发新任务） |
| 子智能体 B 回答 A | `answer_other_agent` | B | 返回到 A 的 `ask_other_agent` 工具结果 |
| 查询活跃子智能体 | `list_active_sub_agents` | 任意 | 返回列表 |
| 子智能体输出/汇报 | 自然 assistant 输出 | 子智能体 | 捕获后插入 Team Leader user 消息 |

---

## 4. 工具定义文件位置

- 主智能体工具：`modules/multi_agent/tools/master_tools.py`
- 子智能体工具：`modules/multi_agent/tools/agent_tools.py`
- 工具处理：`modules/multi_agent/tools/tool_handlers.py`

不修改现有 `core/main_terminal_parts/tools_definition.py` 或 `modules/sub_agent/toolkit.py`。
