JOJO e8b857f3ae docs(multi-agent): 添加多智能体模式设计文档7份

2026-07-12 02:28:47 +08:00

12 KiB

Raw Blame History

多智能体模式工具定义

主智能体工具基于现有主智能体工具，移除旧版子智能体工具，新增多智能体专用工具。
子智能体工具保留现有 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`

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

{
  "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`

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

{
  "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`

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

{
  "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`

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

{
  "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`

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

{
  "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`

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

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

返回示例：

{
  "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`

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

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

`create_custom_agent`

创建并保存自定义角色。

{
  "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`

列出所有可用角色。

{
  "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）提问，阻塞等待回答。

{
  "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`

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

{
  "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`

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

{
  "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`

查询当前活跃子智能体。

{
  "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。

12 KiB Raw Blame History Unescape Escape

多智能体模式工具定义

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

1.1 从现有工具中移除

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

create_sub_agent

terminate_sub_agent

send_message_to_sub_agent

ask_sub_agent

answer_sub_agent_question

list_active_sub_agents

get_sub_agent_status

create_custom_agent

list_agents