Agent Orchestrator

MCP-Server und lokale GUI, die Arbeit über Cursor-Agenten und externe LLM-Backends (OpenAI-kompatible APIs, Anthropic, lokales vLLM, Ollama oder einen benutzerdefinierten HTTP-Agenten) verteilt.

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

Schnellstart

Erfordert Node.js 22.13+.

npm install
cp .env.example .env

Lege API-Schlüssel in .env oder auf der GUI-Seite Backends ab – niemals in agents.config.yaml. apiKeyEnv ist der Variablenname (GEMINI_API_KEY), nicht das Secret.

# GUI (loopback only)
npm run gui

Öffne die auf stderr ausgegebene URL (http://127.0.0.1:8787?token=…). Das Session-Token wird unter .orchestrator/gui.secret gespeichert (von Git ignoriert).

Wenn Port 8787 bereits belegt ist, läuft die GUI bereits – verwende gui:stop oder öffne die vorhandene Token-URL. Das Stoppen eines lokalen Modellcontainers stoppt die GUI nicht.

Cursor: Dieses Repository enthält .cursor/mcp.json. Lade MCP nach dem Klonen einmal neu. list_agents liest Umgebungsvariablen und GUI-Secrets erneut, ohne einen vollständigen IDE-Neustart.

Related MCP server: Cloud Agent MCP Server

Chat

Die Startseite ist ein Chat-Thread. Der Kopfbereich (neuer Chat, Thread-Umschalter, Einstellungen) und der Composer bleiben auf dem Bildschirm; nur Nachrichten scrollen.

• Auto (Standard) – Steuerungswerkzeuge für Hardware/Download/Start; Debatte für Plan/Fix/Review, wenn zwei oder mehr Backends bereit sind; andernfalls ein einzelner Agent.

• Debate – Round-Table: Jedes bereite Modell spricht der Reihe nach (eine Blase pro Sprecher), dann fasst ein Closer zusammen.

• Single / Backend anpinnen – nur dieses Backend.

Während ein Sprecher läuft, zeigt ein Thinking-Chip Name, verstrichene Zeit und Phase an, damit die UI nicht eingefroren wirkt.

Schreibvorgänge und Installationen warten auf „Approve“. Implementieren/Installieren bleibt bis zum Klick auf Approve auf der Karte für ausstehende Aktionen reiner Plan. Danach darf Cursor nur innerhalb der Schreib-Allowlist schreiben. Hostweite Installationen (Paketmanager, Game-Engines, sudo) werden hervorgehoben und warten weiterhin. Externe Modelle bearbeiten niemals Dateien.

Einstellungen

Schlüssel liegen in .env und .orchestrator/secrets.env (von Git ignoriert, Modus 0600). Reload env übernimmt einen nach dem Start hinzugefügten Schlüssel.

Sicherheit

Tunnele die GUI oder vLLM nicht. Cloud-Cursor-Agenten können localhost nicht erreichen; der Orchestrator übergibt Text zwischen lokal und Cloud.

Schreib-Allowlist

Standard: dieser Workspace (WORKSPACE_CWD / workspace.cwd). Füge weitere über Einstellungen → Allowlist oder add_allowed_dir hinzu. Der Chat bietet ein Ein-Klick-Hinzufügen an, wenn du einen absoluten Pfad nennst, der nicht aufgelistet ist.

Lokale Modelle (herstellerunabhängig)

list_hardware erkennt, welche Beschleuniger vorhanden sind (NVIDIA CUDA, AMD ROCm, Intel XPU, oder CPU, wenn keine vorhanden sind). Empfehlungen verwenden gemessenen VRAM, nicht einen einzelnen Hersteller. Fehlendes NVIDIA wird nicht als „nur CPU“ behandelt, wenn eine andere GPU existiert.

Ein Katalogmodell passt, wenn die geschätzten Gewichte plus ~20% KV-Cache-Puffer ≤ VRAM pro GPU sind. Multi-GPU kann Tensor-Parallelismus nutzen, wenn ein Modell auf eine Karte nicht passt, aber auf zwei.

Lade Snapshots nach .orchestrator/models herunter (von Git ignoriert, muss auf der Allowlist bleiben). Gated-Hugging-Face-Repos benötigen HF_TOKEN in der Umgebung oder in der GUI – niemals in Git.

start_vllm wählt einen Serving-Stack basierend auf dem erkannten Backend:

• CUDA – vllm serve auf dem Host, wenn das CUDA-Wheel installiert ist

• ROCm – ROCm vLLM, falls vorhanden

• XPU – Hersteller-Docker-Images, wenn sie bereits lokal vorhanden sind; andernfalls ein Host-XPU-Build

• CPU – wird nicht als Serve-Pfad verwendet

Die API wird nur auf 127.0.0.1 veröffentlicht (Ports 8000–8099). Der Start liefert sofort (202) zurück; warte auf der Seite „Lokale Modelle“, bis /v1/models bereit ist. Der laufende Server wird automatisch als Backend registriert (Dummy-Loopback-Token, falls der Client Bearer erfordert – du kopierst keinen Schlüssel aus dem Container).

Du kannst mehrere Modelle gleichzeitig ausführen. Jede Katalog-ID erhält ihren eigenen Container, Port und ihr eigenes Backend (vllm-<catalog-slug>). Stop beendet eine Instanz; Remove from mix entfernt dieses Backend auch aus der YAML; Delete weights ist eine separate Bestätigung.

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

MCP-Tools

Standard-Spezialisten

Nur Cursor-Backends bearbeiten Dateien. Richte backend auf eine beliebige ID in agents.config.yaml.

Backend hinzufügen

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 verwendet den OpenAI-kompatiblen Endpunkt von Google. Setze eine aktuelle Modell-ID (die GUI listet IDs von Google auf, wenn der Schlüssel funktioniert). Setze keine Kommentare oder pro / flash-Listen in model.

${ENV_NAME} in YAML wird aus der Prozessumgebung expandiert.

Aus einem anderen Repository verwenden

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

Was nicht in Git ist

.env, .orchestrator/ (GUI-Token, Secrets, Chats, Allowlist, Modellgewichte, vLLM-Zustand), node_modules/ und Logs. Siehe .gitignore.