Agent Orchestrator

MCP 서버 및 localhost GUI로, Cursor 에이전트와 외부 LLM 백엔드(OpenAI 호환 API, Anthropic, 로컬 vLLM, Ollama, 사용자 지정 HTTP 에이전트) 간에 작업을 라우팅합니다.

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의 Backends 페이지에 넣으세요. 절대 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에 저장됩니다(git 무시 대상).

8787 포트가 이미 사용 중이면 GUI가 이미 실행 중인 것입니다. gui:stop을 사용하거나 기존 토큰 URL을 여세요. 로컬 모델 컨테이너를 중지해도 GUI는 중지되지 않습니다.

Cursor: 이 저장소에는 .cursor/mcp.json이 포함되어 있습니다. 클론 후 MCP를 한 번 리로드하세요. list_agents는 IDE 전체를 재시작하지 않고도 env와 GUI 비밀값을 다시 읽습니다.

Related MCP server: Cloud Agent MCP Server

채팅

홈은 채팅 스레드입니다. 헤더(새 채팅, 스레드 전환기, 설정)와 작성기는 화면에 유지되고 메시지만 스크롤됩니다.

• Auto (기본값) — 하드웨어/다운로드/시작에는 제어 도구를 사용하고, 백엔드가 둘 이상 준비된 경우 계획/수정/검토에는 debate를 사용하며, 그 외에는 단일 에이전트를 사용합니다.

• Debate — 라운드 테이블: 준비된 각 모델이 차례로 발언(발언자마다 말풍선 하나)한 다음, 마무리 담당이 종합합니다.

• Single / 백엔드 고정 — 해당 백엔드만 사용합니다.

발언자가 실행되는 동안 thinking 칩에 이름, 경과 시간, 단계가 표시되어 UI가 멈춘 것처럼 보이지 않습니다.

쓰기와 설치 작업은 Approve를 기다립니다. 구현/설치는 보류 작업 카드에서 Approve를 클릭하기 전까지 계획 전용으로 유지됩니다. 이후 Cursor는 쓰기 허용 목록 안에서만 쓸 수 있습니다. 호스트 전체 설치(패키지 관리자, 게임 엔진, sudo)는 별도로 표시되며 여전히 승인을 기다립니다. 외부 모델은 파일을 편집하지 않습니다.

설정

키는 .env와 .orchestrator/secrets.env에 저장됩니다(git 무시 대상, 모드 0600). Reload env는 시작 후 추가된 키를 다시 읽습니다.

보안

GUI나 vLLM을 터널링하지 마세요. 클라우드 Cursor 에이전트는 localhost에 도달할 수 없습니다. 오케스트레이터는 로컬과 클라우드 사이에 텍스트만 전달합니다.

쓰기 허용 목록

기본값: 이 워크스페이스(WORKSPACE_CWD / workspace.cwd). 추가 항목은 Settings → Allowlist 또는 add_allowed_dir로 추가하세요. 채팅에서 목록에 없는 절대 경로를 언급하면 원클릭 추가를 제안합니다.

로컬 모델(벤더 중립적)

list_hardware는 현재 있는 모든 가속기를 탐지합니다(NVIDIA CUDA, AMD ROCm, Intel XPU, 또는 아무것도 없으면 CPU). 권장 사항은 특정 벤더가 아닌 측정된 VRAM을 사용합니다. 다른 GPU가 있으면 NVIDIA가 없어도 “CPU only”로 취급하지 않습니다.

카탈로그 모델은 예상 가중치에 KV-cache 여유분 약 20%를 더한 값이 GPU당 VRAM 이하일 때 fits로 간주합니다. 모델이 카드 한 장에는 맞지 않지만 두 장에는 맞는 경우 멀티 GPU에서 tensor parallel을 사용할 수 있습니다.

스냅샷을 .orchestrator/models에 다운로드하세요(git 무시 대상, 허용 목록에 유지해야 함). 게이트된 Hugging Face 저장소는 env 또는 GUI에 HF_TOKEN이 필요하며, git에는 절대 넣지 마세요.

start_vllm은 감지된 백엔드에서 서빙 스택을 선택합니다:

• CUDA — CUDA wheel이 설치된 경우 호스트에서 vllm serve 실행

• ROCm — ROCm vLLM이 있으면 사용

• XPU — 벤더 Docker 이미지가 이미 로컬에 있으면 사용하고, 그렇지 않으면 호스트 XPU 빌드 사용

• CPU — 서빙 경로로 사용되지 않음

API는 127.0.0.1에서만 공개됩니다(포트 8000–8099). 시작은 즉시 반환됩니다(202). /v1/models가 정상이 될 때까지 Local models 페이지에서 기다리세요. 실행 중인 서버는 자동으로 백엔드로 등록됩니다(클라이언트가 Bearer를 요구하는 경우 더미 루프백 토큰 사용 — 컨테이너에서 키를 복사할 필요가 없습니다).

여러 모델을 동시에 실행할 수 있습니다. 각 카탈로그 ID는 자체 컨테이너, 포트, 백엔드를 갖습니다(vllm-<catalog-slug>). 인스턴스 하나를 Stop하세요. 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 백엔드만 파일을 편집할 수 있습니다. agents.config.yaml의 아무 ID에 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는 Google의 OpenAI 호환 엔드포인트를 사용합니다. 하나의 현재 모델 ID를 설정하세요(키가 작동하면 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를 참조하세요.