agent-maestro

VS Code를 규정 준수 AI 플레이그라운드로 변신시키세요! Agent Maestro를 사용하면 Cline 또는 Roo를 필요할 때마다 실행할 수 있으며, OpenAI/Anthropic/Gemini 호환 API를 통해 Claude Code, Codex 또는 Gemini CLI를 즉시 연결할 수 있습니다.

강력한 API 호환성과 원클릭 설정을 통해 VS Code를 규정 준수 AI 플레이그라운드로 변신시키세요:

범용 API 호환성 (Universal API Compatibility): Anthropic (/messages), OpenAI (/chat/completions, /responses), 그리고 Gemini 호환 엔드포인트를 지원합니다. Claude Code, Codex, Gemini CLI 또는 모든 LLM 클라이언트를 원활하게 사용하세요.

컨텍스트 윈도우 관리 (Context Window Management): VS Code의 API와 모델 제공자 간의 토크나이저 (tokenizer) 차이로 인해 발생하는 컨텍스트 윈도우 초과 오류를 방지하기 위해 구성 가능한 스케일 인자 (scale factors)를 제공합니다.

원클릭 설정 (One-Click Setup): Claude Code, Codex 및 Gemini CLI의 즉각적인 통합을 위한 자동화된 구성 명령을 제공합니다.

헤드리스 AI 에이전트 제어 (Headless AI Agent Control): REST API를 통해 Roo Code 및 Cline 확장을 위한 작업을 생성하고 관리합니다.

포괄적인 API (Comprehensive APIs): /openapi.json에 있는 OpenAPI 문서와 함께 완전한 작업 라이프사이클 (task lifecycle) 관리를 제공합니다.

병렬 실행 (Parallel Execution): 내장된 MCP 서버 통합을 통해 최대 20개의 동시 Roo Code (및 Kilo Code와 같은 변형 버전) 작업을 실행할 수 있습니다.

실시간 스트리밍 (Real-time Streaming): 실시간 작업 모니터링 및 메시지 업데이트를 위해 서버 전송 이벤트 (Server-Sent Events, SSE)를 사용합니다.

유연한 구성 (Flexible Configuration): 워크스페이스 수준의 설정, 환경 변수 및 확장 프로그램 자동 검색을 지원합니다.

Agent Maestro는 귀하가 이미 지원되는 AI 코딩 확장 프로그램 중 하나를 설치했다고 가정합니다:

포괄적인 API 제어를 위한 Roo Code 또는 그 변형 버전
개인 개발 루틴을 위한 Claude Code
개인 개발 루틴을 위한 Codex
개인 개발 루틴을 위한 Gemini CLI

VS Code Marketplace에서 Agent Maestro 확장을 설치하세요. 활성화되면 Agent Maestro는 시작 시 API 서버를 자동으로 시작합니다.

커맨드 팔레트 (Command Palette)를 통해 Agent Maestro: Configure Claude Code Settings라는 단일 명령으로 Claude Code가 VS Code의 언어 모델을 사용하도록 구성할 수 있습니다.

이 명령은 .claude/settings.json을 자동으로 생성하거나 업데이트합니다.

Agent Maestro 엔드포인트(endpoint)를 사용하여 VS Code에서 사용 가능한 LLM 모델들을 채워 넣습니다.

그게 전부입니다! 이제 VS Code의 내장 언어 모델(language models)과 함께 Claude Code를 사용할 수 있습니다.

1M 컨텍스트 지원: Agent Maestro는 Claude 1M 컨텍스트 모델(예: claude-opus-4.7-1m-internal)을 지원합니다. 확장된 컨텍스트 윈도우(context window)를 사용하려면 Agent Maestro: Configure Claude Code Settings를 실행하고 원하는 1M 모델을 선택하세요. Agent Maestro는 Claude Code가 기대하는 형식으로 모델을 작성하므로 1M 경로가 일관되게 선택됩니다.

커맨드 팔레트(Command Palette)를 통해 단일 명령인 Agent Maestro: Configure Codex Settings를 사용하여 Codex가 VS Code의 언어 모델을 사용하도록 구성할 수 있습니다.

이 명령은 Agent Maestro 엔드포인트(endpoint)를 포함하여 ~/.codex/config.toml을 자동으로 생성하거나 업데이트하며, GPT-5.5를 권장 모델로 설정합니다.

커맨드 팔레트(Command Palette)를 통해 단일 명령인 Agent Maestro: Configure Gemini CLI Settings를 사용하여 Gemini CLI가 VS Code의 언어 모델을 사용하도록 구성할 수 있습니다.

다음 중 하나를 선택할 수 있습니다:

사용자 설정(~/.env): 모든 프로젝트에 적용되는 개인용 글로벌 설정
프로젝트 설정(.env 워크스페이스 내): 소스 제어(source control)에 포함되는 팀 공유 프로젝트 설정

이 명령은 다음 내용을 포함하여 .env 파일을 자동으로 생성하거나 업데이트합니다:

GOOGLE_GEMINI_BASE_URL: Agent Maestro Gemini 엔드포인트(endpoint)
GEMINI_API_KEY: 기본 인증 토큰 (이미 설정되어 있는 경우 유지됨)
GEMINI_MODEL: 사용 가능한 VS Code 언어 모델 중 선택한 모델
GEMINI_TELEMETRY_ENABLED: 기본적으로 텔레메트리(telemetry) 비활성화

또한, 첫 실행 시 인증 방법 선택을 건너뛸 수 있도록 동일한 폴더의 settings.json을 생성하거나 업데이트합니다:

{
"security": {
"auth": {
...

Agent Maestro: Fix GitHub Copilot Chat - Model is not supported error 명령을 통해 GitHub Copilot Chat에서 추가 모델을 활성화할 수 있습니다. (ref)

이 기능은 다음과 같이 작동합니다:

GitHub Copilot Chat 확장을 자동으로 찾습니다.
변경 사항을 적용하기 전에 타임스탬프가 찍힌 백업을 생성합니다.
x-onbehalf-extension-id를 제거합니다.

헤더 제한 (header restriction) - 수정 사항이 성공적으로 적용되었는지 확인합니다.

변경 사항을 적용하려면 VS Code를 다시 로드하라는 메시지가 표시됩니다.

참고: 이 수정 사항은 Copilot Chat 확장이 업데이트될 때 덮어씌워질 수 있습니다. 업데이트 후 필요한 경우 명령을 다시 실행하기만 하면 됩니다.

API 기능 탐색: http://localhost:23333/openapi.json에서 전체 OpenAPI 명세(specification)에 접속할 수 있습니다.

.

VS Code 명령: 명령 팔레트(Command Palette)를 통해 기능을 사용할 수 있습니다.

서버 관리 (Server Management):
Agent Maestro: Start API Server

프록시 API 서버를 시작합니다.

Agent Maestro: Stop API Server

프록시 API 서버를 중지합니다.

Agent Maestro: Restart API Server

프록시 API 서버를 재시작합니다.

Agent Maestro: Get API Server Status

현재 서버 상태를 확인합니다.

MCP 서버 관리 (MCP Server Management):
Agent Maestro: Start MCP Server

Model Context Protocol (MCP) 서버를 시작합니다.

Agent Maestro: Stop MCP Server

MCP 서버를 중지합니다.

Agent Maestro: Get MCP Server Status

현재 MCP 서버 상태를 확인합니다.

Agent Maestro: Install MCP Configuration

지원되는 확장을 위한 MCP 설정을 설치합니다.

확장 관리 (Extension Management):
Agent Maestro: Get Extensions Status

지원되는 AI 확장의 상태를 확인합니다.

설정 명령 (Configuration Commands):
Agent Maestro: Configure Claude Code Settings

클릭 한 번으로 Claude Code를 설정합니다.

Agent Maestro: Configure Codex Settings

클릭 한 번으로 Codex를 설정합니다.

Agent Maestro: Configure Gemini CLI Settings

클릭 한 번으로 Gemini CLI를 설정합니다.

Agent Maestro: Fix GitHub Copilot Chat - Model is not supported error

헤더 제한을 제거하여 추가 모델을 사용할 수 있도록 합니다.

Agent Maestro: Set LLM API Key

LLM API 엔드포인트에 대한 인증을 구성합니다.

개발 리소스 (Development Resources)

API 문서 (API Documentation): docs/roo-code/에서 전체 참조를 확인할 수 있습니다.

타입 정의 (Type Definitions): @roo-code/types 패키지

예제 (Examples): examples/demo-site에 있는 참조 구현 (테스트 용도)

Agent Maestro는 LLM API 엔드포인트(Anthropic, OpenAI, Gemini)에 대한 접근을 보호하기 위해 선택적인 API 키 인증 (API key authentication)을 지원합니다. 인증이 활성화되면, 이러한 엔드포인트로의 모든 요청에는 반드시 유효한 API 키가 포함되어야 합니다.

명령 팔레트 (Command Palette) 열기 (Ctrl+Shift+P / Cmd+Shift+P)
Agent Maestro: Set LLM API Key 실행
원하는 API 키 입력 (인증을 비활성화하려면 빈칸으로 남겨둠)

API 키는 VS Code의 내장 비밀 저장소 (secrets storage)를 사용하여 안전하게 저장되며 세션 간에 유지됩니다.

인증이 활성화되면, 각 제공업체(provider)의 표준 헤더 형식을 사용하여 요청에 API 키를 포함하십시오:

Anthropic API (/api/anthropic/*):

curl -H "x-api-key: YOUR_LLM_API_KEY" \

OpenAI API (/api/openai/*):

curl -H "Authorization: Bearer YOUR_LLM_API_KEY" \

Gemini API (/api/gemini/*):

curl -H "x-goog-api-key: YOUR_LLM_API_KEY" \

로컬 개발의 편의를 위해 인증은 기본적으로 비활성화 (disabled by default) 되어 있습니다.
인증이 비활성화된 경우, 프록시 (proxy)는 검증 없이 모든 요청을 수락합니다.
API 키는 타이밍 공격 (timing attacks)을 방지하기 위해 상수 시간 비교 (constant-time comparison)를 사용하여 비교됩니다.
보안 모니터링을 위해 인증 실패 시도가 로그에 기록됩니다.

환경 변수 (environment variables)를 사용하여 Agent Maestro의 서버 포트를 사용자 정의할 수 있습니다:

변수 (Variable)	설명 (Description)	기본값 (Default)
`AGENT_MAESTRO_PROXY_PORT`	프록시 서버 포트 (Proxy server port)	23333
`AGENT_MAESTRO_MCP_PORT`	MCP 서버 포트 (MCP server port)	23334

사용법 (Usage):

# 사용자 정의 포트 설정
export AGENT_MAESTRO_PROXY_PORT=8080
export AGENT_MAESTRO_MCP_PORT=8081
...

참고: 환경 변수는 확장 프로그램 설정 (extension settings)보다 우선순위가 높습니다.

프로젝트의 .vscode/settings.json 파일에 설정을 추가하여 워크스페이스(workspace)별로 Agent Maestro 설정을 구성할 수 있습니다:

{
"agent-maestro.defaultRooIdentifier": "rooveterinaryinc.roo-cline",
"agent-maestro.proxyServerPort": 23333,
...
}

사용 가능한 설정 (Available Settings):

설정 (Setting)	설명 (Description)	기본값 (Default)
`agent-maestro.defaultRooIdentifier`	사용할 기본 Roo 확장 프로그램 (Default Roo extension to use)	`"rooveterinaryinc.roo-cline"`
`agent-maestro.proxyServerPort`	프록시 서버 포트 (Proxy server port)	`23333`
`agent-maestro.mcpServerPort`	MCP 서버 포트 (MCP server port)	`23334`
`agent-maestro.anthropic.tokenCountScaleFactor`	Anthropic 토큰 수 추정치를 위한 스케일 인자 (Scale factor for Anthropic token count estimation) (범위: 1.0–2.0)	`1.25`
`agent-maestro.codex.contextWindowScaleFactor`	Codex 컨텍스트 창 (context window) 계산을 위한 스케일 인자 (Scale factor for Codex context window calculation) (범위: 0.1–2.0)	`1`

이를 통해 전역 VS Code 설정에 영향을 주지 않고 서로 다른 프로젝트에서 각기 다른 구성을 사용할 수 있습니다.

Agent Maestro는 VS Code의 언어 모델 API (Language Model API)를 통해 요청을 프록시(proxy)합니다. 이 API는 실제 모델 제공업체와는 다른 토크나이저 (tokenizer) (OpenAI의 tiktoken / O200K)를 사용합니다. 이러한 불일치로 인해 로컬에서 보고되는 토큰 수가 실제 사용량보다 적을 수 있으며, 이는 잠재적으로 요청이 모델의 컨텍스트 창 (context window)을 초과하여 예기치 않게 실패하는 원인이 될 수 있습니다.

이를 방지하기 위해 Agent Maestro는 로컬 토큰 수를 부풀려 실제 사용량에 더 가깝게 근사화할 수 있는 설정 가능한 스케일 인자 (scale factors)를 제공합니다. 서로 다른 코딩 에이전트 클라이언트는 각기 다른 접근 방식이 필요합니다:

agent-maestro.anthropic.tokenCountScaleFactor (Claude Code 및 기타 Anthropic API 클라이언트용): API 응답에서 보고되는 모든 토큰 수에 적용됩니다. 프록시는 원본 VS Code 토큰 수에 이 인자를 곱합니다 (예: 10,000 토큰 × 1.25 = 12,500 보고됨). 이는 클라이언트가 컨텍스트 제한에 도달하고 있음을 감지하고, 한계에 부딪히기 전에 자동 압축 (auto-compaction)과 같은 작업을 트리거하는 데 도움이 됩니다. 컨텍스트 창 오류가 계속 발생하면 이 값을 높이고, 사용 가능한 컨텍스트를 더 많이 사용하고 싶다면 이 값을 낮추십시오.
agent-maestro.codex.contextWindowScaleFactor (Codex용): config.toml에서 model_context_window 값을 설정할 때만 사용됩니다 (maxInputTokens × scaleFactor로 계산됨).

). 이는 Codex에게 유효한 컨텍스트 윈도우 (context window) 크기를 사전에 알려주어, Codex가 자신의 대화 기록 (conversation history)을 그에 맞춰 관리할 수 있도록 합니다.

Agent Maestro는 Anthropic의 cache_control, OpenAI의 prompt_cache_key, 그리고 Gemini의 cachedContent와 같은 일반적인 프롬프트 캐시 (prompt cache) 힌트를 지원하며, 지원되지 않는 캐시 컨트롤은 VS Code의 언어 모델 API (Language Model API)로 전달하지 않습니다. VS Code는 제공자 측의 프롬프트 캐시 읽기 또는 쓰기를 노출하지 않기 때문에, 캐시 사용 필드는 인위적인 절감액 대신 0으로 보고됩니다.

💡

최신 API 문서는 항상 /openapi.json을 참조하십시오.

REST API: http://localhost:23333/api/v1

Anthropic API: http://localhost:23333/api/anthropic

OpenAI API: http://localhost:23333/api/openai

Gemini API: http://localhost:23333/api/gemini

MCP Server: http://localhost:23334

GitHub Copilot 및 Claude Code 통합에 최적화되어 있습니다:

VS Code의 언어 모델 API (Language Model API)를 사용한 Anthropic Claude API 호환성 POST /api/anthropic/v1/messages
Anthropic 호환 메시지에 대한 토큰 계산 (Token counting) POST /api/anthropic/v1/messages/count_tokens

Codex 및 OpenAI 모델 통합에 최적화되어 있습니다:

VS Code의 언어 모델 API (Language Model API)를 사용한 OpenAI Chat Completions API 호환성 POST /api/openai/v1/chat/completions
VS Code의 언어 모델 API (Language Model API)를 사용한 OpenAI Responses API 호환성 POST /api/openai/v1/responses

Gemini CLI 통합에 최적화되어 있습니다:

VS Code의 언어 모델 API (Language Model API)를 사용한 Google Gemini API 호환성 POST /api/gemini/v1beta/models/{model}:generateContent
Gemini API를 위한 스트리밍 (Streaming) 지원 POST /api/gemini/v1beta/models/{model}:streamGenerateContent
Gemini 호환 메시지에 대한 토큰 계산 (Token counting) POST /api/gemini/v1beta/models/{model}:countTokens

실시간 스트리밍 (real-time streaming)을 지원하는 풀 기능 에이전트 통합:

SSE 스트리밍을 사용하여 새로운 RooCode 작업 생성 POST /api/v1/roo/task
SSE 스트리밍을 사용하여 기존 작업에 메시지 전송 POST /api/v1/roo/task/{taskId}/message
작업 수행 (pressPrimaryButton, pressSecondaryButton, cancel, resume) POST /api/v1/roo/task/{taskId}/action
현재 RooCode 설정 가져오기 GET /api/v1/roo/settings
사용 가능한 RooCode 모드 가져오기 GET /api/v1/roo/modes

VS Code의 언어 모델 (Language Model) 생태계에 직접 액세스:

lm.registerTool()을 통해 등록된 모든 도구 목록 나열 GET /api/v1/lm/tools
사용 가능한 VS Code 언어 모델 (Language Model) API 채팅 모델 목록 나열 GET /api/v1/lm/chatModels

기본 통합 지원:

새로운 Cline 작업 생성 (기본 지원) POST /api/v1/cline/task
OpenAPI v3 명세 완료 GET /openapi.json

Agent Maestro는 API 요청이 실패할 때 상세한 오류 진단(error diagnostics) 내용을 자동으로 기록합니다. 확장이 실행될 때마다 워크스페이스 루트에 타임스탬프가 찍힌 로그 파일이 생성됩니다: {YYYY}-{MM}-{DD}_{HH}-{MM}-{SS}-{mmm}-debug.log}

해당 세션 동안 발생하는 모든 오류는 동일한 파일에 추가됩니다.

기록되는 내용: 요청 페이로드 (Request payload), 변환된 VSCode LM 메시지, 오류 상세 정보, 확장 메타데이터, 모델 ID, 엔드포인트 (endpoint), 그리고 타임스탬프.

지원되는 엔드포인트 (Supported endpoints):

agent-maestro

요약

핵심 포인트

.

댓글