Agent Orchestrator MCP

代理编排器MCP服务器

A. 模型上下文协议（MCP） 服务器，使主Gemini CLI代理能够在其中生成、编排和管理多个子代理 终端复用器 会议。

专为 开爪 以及Gemini CLI环境。

特性

• 基于Tmux的隔离：每个子代理都在自己的专用tmux窗格中运行。
• 会话隔离：每个执行会话的工作区和事件日志完全分离。
• 演员模型沟通：使用每个代理和主收件箱的去中心化异步消息传递。
• 自动启动：子代理在启动时会自动提示其角色和协议。
• 原生Gemini CLI：子代理实际运行 gemini 具有可配置模型的CLI实例。

建筑

会话

每次用户运行 gemini，一个新的 会话 使用唯一ID创建。会话是完全隔离的——会话a中的代理无法看到或向会话B中的代理发送消息。用户可以并行运行任意数量的会话。

graph TD
    User["User"]

    subgraph SessionA["Session A  (.agents/sessions/uuid-a/)"]
        MA["Master Agent
(Gemini CLI)"]
        MA --> SA1["Sub-Agent 1"]
        MA --> SA2["Sub-Agent 2"]
        MA --> SAN["Sub-Agent N"]
    end

    subgraph SessionB["Session B  (.agents/sessions/uuid-b/)"]
        MB["Master Agent
(Gemini CLI)"]
        MB --> SB1["Sub-Agent 1"]
        MB --> SB2["Sub-Agent 2"]
    end

    User -->|"runs"| MA
    User -->|"runs separately"| MB

    SessionA -. "fully isolated" .- SessionB

会话内部

在会话中，主代理将子代理生成到tmux窗格中。所有通信都是通过仅附加JSONL邮箱文件路由的。每个组件——主代理、每个子代理和MCP服务器本身——都可以在不保持任何进程内状态的情况下进行读写。

graph TD
    Master["Master Agent
(Gemini CLI + MCP)"]

    subgraph Tmux["tmux session: openclaw-agents"]
        P1["Pane — Sub-Agent 1
(Gemini CLI)"]
        P2["Pane — Sub-Agent 2
(Gemini CLI)"]
        PN["Pane — Sub-Agent N
(Gemini CLI)"]
    end

    subgraph FS[".agents/sessions/<session_id>/"]
        MI["master_inbox.jsonl
(messages for Master)"]
        D1["agents/agent-1/
inbox.jsonl"]
        D2["agents/agent-2/
inbox.jsonl"]
        DN["agents/agent-N/
inbox.jsonl"]
    end

    Master -->|"agent_create → spawns"| P1
    Master -->|"agent_create → spawns"| P2
    Master -->|"agent_create → spawns"| PN

    Master -->|"send_message"| D1
    Master -->|"send_message"| D2

    P1 |"wait_for_command"| D1
    P2 |"wait_for_command"| D2
    PN |"wait_for_command"| DN

    P1 -->|"send_message(target=master)"| MI
    P2 -->|"send_message(target=master)"| MI
    PN -->|"send_message(target=master)"| MI

    Master -->|"read_inbox"| MI

沟通模式

所有通信都是基于文件的，只能追加。有四种路由模式，按以下顺序显示。

sequenceDiagram
    participant Master
    participant MI as master_inbox.jsonl
    participant Inbox1 as agent-1/inbox.jsonl
    participant Agent1 as Sub-Agent 1
    participant Inbox2 as agent-2/inbox.jsonl
    participant Agent2 as Sub-Agent 2

    Note over Master,Agent2: 1 — Master sends a task to an agent
    Master->>Inbox1: send_message(payload, target="agent-1")
    Agent1->>Inbox1: wait_for_command (polls every 500 ms)
    Inbox1-->>Agent1: task + next_cursor

    Note over Master,Agent2: 2 — Agent reports result to master
    Agent1->>Agent1: execute task
    Agent1->>MI: send_message(result, target="master")
    Master->>MI: read_inbox(cursor)
    MI-->>Master: messages

    Note over Master,Agent2: 3 — Agent sends a targeted peer message
    Agent1->>Inbox2: send_message(data, target="agent-2")
    Agent2->>Inbox2: wait_for_command (polls)
    Inbox2-->>Agent2: event from Agent 1

    Note over Master,Agent2: 4 — Agent broadcasts to all peers
    Agent2->>Inbox1: send_message(data, target="all")
    Agent2->>MI: send_message(data, target="all")
    Agent1->>Inbox1: wait_for_command (polls)
    Inbox1-->>Agent1: broadcast event

先决条件

在运行此服务器之前，请确保您的系统上安装了以下内容：

• 终端复用器 （必填）：此服务器严重依赖 tmux 用于进程隔离和窗格管理。
• Node.js （v18+）：需要运行MCP服务器。
• Gemini CLI （可选）：如果您计划生成标准Gemini代理 gemini 命令应该在您的PATH中。

安装与使用

1.安装为Gemini扩展

使用此编排器的最简单方法是将其直接安装到Gemini CLI：

gemini extension install --auto-update https://github.com/kkweon/agent-orchestrator-mcp

2.策略配置（推荐）

要允许主代理管理子代理而无需不断的确认提示，您应该安装安全策略。

mkdir -p ~/.gemini/policies
# If you cloned the repo:
cp policies/agent-orchestrator.toml ~/.gemini/policies/
# Or download directly:
curl -sSL https://raw.githubusercontent.com/kkweon/agent-orchestrator-mcp/main/policies/agent-orchestrator.toml -o ~/.gemini/policies/agent-orchestrator.toml

3.独立执行（通过npx）

您还可以直接使用以下命令运行MCP服务器 npx，这对于测试或手动配置很有用：

npx @kkweon/agent-orchestrator-mcp

配置（gemini扩展名.json）

如果您需要在您的 gemini-extension.json:

{
  "mcpServers": {
    "orchestrator": {
      "command": "npx",
      "args": ["-y", "@kkweon/agent-orchestrator-mcp"]
    }
  }
}

🛠️ 工具参考

编排器工具（用于主代理）

使用这些工具来管理您的员工。

role （string）：特定角色（例如“编码员”、“审阅者”） model （字符串，可选）：要使用的特定Gemini模型| | agent_list |列出当前会话中的所有活动代理。 | *（无）* | | send_message |向一个或多个代理发送消息。使用target=“all”进行广播。 | agent_id （string）：发件人的代理ID（如果编排器正在发送，请使用“master”） message （object）：任意JSON有效载荷 target （字符串/数组）：“all”、“master”或代理UUID| | read_inbox |不阻止从收件箱读取邮件。对编排器使用agent_id='master'。 | agent_id （string）：目标收件箱（“master”或代理UUID） cursor （数字，可选）：要从中恢复的行索引| | agent_delete |终止子代理并终止其tmux窗格。 | agent_id （string）：目标代理的UUID|

内部协议工具（用于子代理）

*子代理自动使用这些工具与编排器通信。你很少需要手动调用它们。*

• wait_for_command：子代理从其子代理获取新任务的长轮询端点 inbox.
• send_message：子代理报告日志、进度和结果的端点（带 target="master")或与同行交流。

发展

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

许可证

麻省理工学院