Agent Orchestrator

Cursor エージェントと外部 LLM バックエンド（OpenAI 互換 API、Anthropic、ローカル vLLM、Ollama、カスタム HTTP エージェント）に作業をルーティングする MCP サーバーおよび localhost GUI。

Chat (GUI or MCP)
  → Auto router (control tools | single agent | multi-agent debate)
      → Cursor (local or cloud) — can edit allowlisted directories
      → External models — text only
      → Local model server on 127.0.0.1 — never public

クイックスタート

Node.js 22.13+ が必要です。

npm install
cp .env.example .env

API キーは .env または GUI の バックエンド ページに置きます。agents.config.yaml には決して置かないでください。apiKeyEnv は変数名（GEMINI_API_KEY）であり、シークレットそのものではありません。

# GUI (loopback only)
npm run gui

stderr に出力された URL（http://127.0.0.1:8787?token=…）を開いてください。セッショントークンは .orchestrator/gui.secret に保存されます（gitignore 対象）。

ポート 8787 がすでに使用中の場合は GUI がすでに起動しています。gui:stop を使用するか、既存のトークン URL を開いてください。ローカルモデルのコンテナを停止しても GUI は停止しません。

Cursor: このリポジトリには .cursor/mcp.json が含まれています。クローン後に MCP を一度リロードしてください。list_agents は IDE を完全に再起動しなくても env と GUI のシークレットを再読み込みします。

Related MCP server: Cloud Agent MCP Server

チャット

ホームはチャットスレッドです。ヘッダー（新規チャット、スレッド切り替え、設定）とコンポーザーは画面に固定され、メッセージだけがスクロールします。

• Auto（デフォルト）— ハードウェア/ダウンロード/起動には制御ツールを使用。2 つ以上のバックエンドが利用可能な場合は計画/修正/レビューに debate を使用。それ以外は単一エージェント。

• Debate — ラウンドテーブル方式。利用可能な各モデルが順番に発言し（話し手ごとに 1 つのバブル）、最後にクローザーが統合します。

• Single / バックエンドを固定 — そのバックエンドのみを使用。

スピーカー実行中は、thinking チップに名前、経過時間、フェーズが表示されるため、UI がフリーズしているように見えません。

書き込みとインストールは Approve を待ちます。 保留中のアクションカードで Approve をクリックするまで、実装/インストールはプランのみの状態です。その後、Cursor は書き込み許可リスト内のみに書き込めます。ホスト全体へのインストール（パッケージマネージャー、ゲームエンジン、sudo）は注意喚起され、引き続き待機します。外部モデルがファイルを編集することはありません。

設定

キーは .env と .orchestrator/secrets.env（gitignore 対象、モード 0600）に保存されます。Reload env は起動後に追加されたキーを読み込みます。

セキュリティ

GUI や vLLM をトンネリングしないでください。クラウドの Cursor エージェントは localhost に到達できません。オーケストレーターはローカルとクラウドの間でテキストを渡します。

書き込み許可リスト

デフォルト: このワークスペース（WORKSPACE_CWD / workspace.cwd）。追加するには、設定 → 許可リストまたは add_allowed_dir を使用します。チャットでは、リストにない絶対パスを指定すると、ワンクリックで追加できます。

ローカルモデル（ベンダー非依存）

list_hardware は、存在するアクセラレータ（NVIDIA CUDA、AMD ROCm、Intel XPU、またはいずれもない場合は CPU）をプローブします。推奨は単一ベンダーではなく実測 VRAM に基づきます。別の GPU が存在する場合、NVIDIA がないことは「CPU のみ」とは見なされません。

カタログモデルが収まる条件は、推定ウェイトに KV キャッシュ用の約 ~20% のヘッドルームを加えた値が GPU あたりの VRAM 以下であることです。1 枚のカードには収まらないが 2 枚には収まるモデルは、マルチ GPU でテンソル並列を使用できます。

スナップショットを .orchestrator/models（gitignore 対象、許可リストに含まれる必要があります）にダウンロードします。ゲート付き Hugging Face リポジトリでは、env または GUI に HF_TOKEN が必要です。git には決して入れないでください。

start_vllm は、検出されたバックエンドからサービングスタックを選択します:

• CUDA — CUDA ホイールがインストールされている場合はホストで vllm serve

• ROCm — 存在する場合は ROCm vLLM

• XPU — ベンダーの Docker イメージがすでにローカルにある場合はそれを使用。それ以外はホストの XPU ビルド

• CPU — サービングパスとしては使用しない

API は 127.0.0.1 のみで公開されます（ポート 8000–8099）。起動は即座に戻ります（202）。/v1/models が正常になるまで、ローカルモデルページで待機してください。実行中のサーバーは自動的にバックエンドとして登録されます（クライアントが Bearer を要求する場合はダミーのループバックトークン。コンテナからキーをコピーする必要はありません）。

複数のモデルを同時に実行できます。各カタログ ID には独自のコンテナ、ポート、バックエンド（vllm-<catalog-slug>）が割り当てられます。Stop で 1 つのインスタンスを停止。Remove from mix は YAML からそのバックエンドも削除します。Delete weights は別の確認操作です。

pip install -r scripts/requirements-hf.txt   # downloads
# Then install the vLLM build that matches your GPU (CUDA, ROCm, or vendor XPU/Docker).

MCP ツール

デフォルトのスペシャリスト

ファイルを編集できるのは Cursor バックエンドのみです。backend は agents.config.yaml 内の任意の ID を指します。

バックエンドを追加する

backends:
  groq:
    type: openai
    baseUrl: https://api.groq.com/openai/v1
    model: llama-3.3-70b-versatile
    apiKeyEnv: GROQ_API_KEY

specialists:
  groq-reviewer:
    description: Fast external review
    backend: groq
    fallback: reviewer

Gemini は Google の OpenAI 互換エンドポイントを使用します。現在のモデル ID を1 つ設定します（キーが有効な場合、GUI に Google の ID 一覧が表示されます）。model にコメントや pro / flash のリストを入れないでください。

YAML 内の ${ENV_NAME} はプロセス環境から展開されます。

別のリポジトリから使用する

{
  "mcpServers": {
    "agent-orchestrator": {
      "type": "stdio",
      "command": "/absolute/path/to/this-repo/node_modules/.bin/tsx",
      "args": ["/absolute/path/to/this-repo/src/index.ts"],
      "env": {
        "AGENT_ORCHESTRATOR_CONFIG": "/absolute/path/to/this-repo/agents.config.yaml",
        "WORKSPACE_CWD": "${workspaceFolder}",
        "CURSOR_API_KEY": "${env:CURSOR_API_KEY}"
      }
    }
  }
}

git に含まれないもの

.env、.orchestrator/（GUI トークン、シークレット、チャット、許可リスト、モデルの重み、vLLM の状態）、node_modules/、ログ。.gitignore を参照してください。