471 lines
12 KiB
Markdown
471 lines
12 KiB
Markdown
# 多智能体模式工具定义
|
||
|
||
> 主智能体工具基于现有主智能体工具，移除旧版子智能体工具，新增多智能体专用工具。
|
||
> 子智能体工具保留现有 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`。
|