Agent Orchestrator

Servidor MCP y GUI de localhost que distribuye el trabajo entre agentes de Cursor y backends LLM externos (APIs compatibles con OpenAI, Anthropic, vLLM local, Ollama o un agente HTTP personalizado).

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

Inicio rápido

Requiere Node.js 22.13+.

npm install
cp .env.example .env

Pon las claves API en .env o en la página Backends de la GUI; nunca en agents.config.yaml. apiKeyEnv es el nombre de la variable (GEMINI_API_KEY), no el secreto.

# GUI (loopback only)
npm run gui

Abre la URL impresa en stderr (http://127.0.0.1:8787?token=…). El token de sesión se guarda en .orchestrator/gui.secret (ignorado por git).

Si el puerto 8787 ya está en uso, la GUI ya se está ejecutando — usa gui:stop o abre la URL del token existente. Detener un contenedor de modelo local no detiene la GUI.

Cursor: este repositorio incluye .cursor/mcp.json. Recarga MCP una vez después de clonar. list_agents vuelve a leer env y los secretos de la GUI sin reiniciar el IDE por completo.

Related MCP server: Cloud Agent MCP Server

Chat

La página principal es un hilo de chat. El encabezado (nuevo chat, selector de hilos, ajustes) y el compositor permanecen en pantalla; solo se desplazan los mensajes.

• Auto (por defecto) — herramientas de control para hardware/descarga/inicio; debate para planificar/corregir/revisar cuando dos o más backends están listos; de lo contrario, un solo agente.

• Debate — mesa redonda: cada modelo listo habla por turnos (una burbuja por orador) y luego un orador de cierre sintetiza.

• Single / fija un backend — solo ese backend.

Mientras un orador está en marcha, una ficha pensando muestra el nombre, el tiempo transcurrido y la fase para que la interfaz no parezca colgada.

Las escrituras e instalaciones esperan a Approve. Implementar/instalar se mantiene solo en modo plan hasta que hagas clic en Approve en la tarjeta de acciones pendientes. Después, Cursor solo puede escribir dentro de la lista de permitidos de escritura. Las instalaciones a nivel de host (gestores de paquetes, motores de juegos, sudo) se señalan y siguen esperando. Los modelos externos nunca editan archivos.

Ajustes

Las claves se guardan en .env y .orchestrator/secrets.env (ignorados por git, modo 0600). Recargar env detecta una clave añadida después del inicio.

Seguridad

No expongas la GUI ni vLLM mediante un túnel. Los agentes de Cursor en la nube no pueden alcanzar localhost; el orquestador pasa texto entre lo local y la nube.

Lista de permitidos de escritura

Por defecto: este espacio de trabajo (WORKSPACE_CWD / workspace.cwd). Añade más desde Ajustes → Lista de permitidos o con add_allowed_dir. El chat ofrece añadirlo con un clic cuando nombras una ruta absoluta que no está en la lista.

Modelos locales (independientes del proveedor)

list_hardware detecta los aceleradores que estén presentes (NVIDIA CUDA, AMD ROCm, Intel XPU o CPU si no hay ninguno). Las recomendaciones usan la VRAM medida, no un único proveedor. La ausencia de NVIDIA no se trata como “solo CPU” cuando existe otra GPU.

Un modelo del catálogo cabe cuando los pesos estimados más ~20% de margen de KV-cache son ≤ la VRAM por GPU. Las configuraciones multi-GPU pueden usar tensor parallel cuando un modelo no cabe en una tarjeta pero sí en dos.

Descarga las instantáneas en .orchestrator/models (ignorado por git; debe permanecer en la lista de permitidos). Los repositorios Hugging Face con acceso restringido necesitan HF_TOKEN en env o en la GUI; nunca en git.

start_vllm elige una pila de servicio según el backend detectado:

• CUDA — vllm serve del host cuando la wheel de CUDA está instalada

• ROCm — vLLM ROCm cuando está presente

• XPU — imágenes Docker del proveedor si ya están localmente; de lo contrario, una compilación XPU del host

• CPU — no se usa como ruta de servicio

La API se publica solo en 127.0.0.1 (puertos 8000–8099). El inicio devuelve inmediatamente (202); espera en la página Modelos locales hasta que /v1/models esté sano? Wait, typo! Need v1/models not v1/models? Actually /v1/models is the endpoint. In my draft I wrote /v1/models? Wait: http://...? Let's check: I typed "/v1/models"? In the draft above I wrote "/v1/models" in the sentence? Let's inspect my final draft in progress: "hasta que /v1/models esté sano" - good. In the text I just wrote in this message, I see "/v1/models"? Let's scroll up: In the final draft I wrote "hasta que /v1/models esté sano"? Actually in the message I'm composing, I need to ensure. I'll write carefully.

Potential typo: "Establece" vs "Define". Good.

Need continue.

El servidor en ejecución se registra automáticamente como backend (token loopback ficticio si el cliente requiere Bearer; no copias ninguna clave del contenedor).

Puedes ejecutar varios modelos a la vez. Cada id de catálogo obtiene su propio contenedor, puerto y backend (vllm-<catalog-slug>). Detener una instancia; Quitar de la mezcla también elimina ese backend del YAML; Eliminar pesos es una confirmación aparte.

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

Herramientas MCP

Especialistas por defecto

Solo los backends de Cursor editan archivos. Apunta backend a cualquier id en agents.config.yaml.

Añadir un backend

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 usa el endpoint compatible con OpenAI de Google. Define un id de modelo actual (la GUI lista los ids de Google cuando la clave funciona). No pongas comentarios ni listas pro / flash en model.

${ENV_NAME} en YAML se expande desde el entorno del proceso.

Usarlo desde otro repositorio

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

Lo que no está en git

.env, .orchestrator/ (token de la GUI, secretos, chats, lista de permitidos, pesos de modelos, estado de vLLM), node_modules/ y logs. Consulta .gitignore.