Vibe-Trading는 자연어로 트레이딩 전략을 요청하면 LLM 에이전트가 백테스트·데이터 수집·리포트 생성까지 수행해주는 '개인 트레이딩 에이전트'입니다. 암호화폐, 외환, 중국/한국/인도/베트남 주식, 글로벌 선물·옵션 등 다양한 자산군용 백테스트 엔진과 수십 개의 데이터 로더(yfinance, akshare, binance, tushare, ccxt 등)를 묶어 CLI·API 서버·MCP 서버 형태로 제공합니다. 또한 '섀도 계정(Shadow Account)'이라는 페이퍼 트레이딩 기능과 실거래 커넥터용 킬스위치(/halt, /resume)도 포함되어 있습니다.
핵심은 `agent/src/agent/loop.py`의 ReAct 스타일 AgentLoop로, LangChain/LangGraph 기반 LLM이 도구(백테스트 엔진, 데이터 로더, 리포트 생성기 등)를 선택해 호출하는 구조입니다. `agent/backtest/engines/`에는 자산군별 백테스트 엔진이, `agent/backtest/loaders/registry.py`에는 데이터 소스별 로더가 등록되어 있어 요청에 맞는 시장·데이터원을 동적으로 선택합니다. 특이한 점은 `src/agent/grounding/` 모듈로, LLM이 생성한 주장·수치를 실제 엔진 출력과 대조해 검증하는 'grounding/evidence ledger' 장치를 두어 환각(hallucination)을 억제하려 시도합니다. CLI(`cli/main.py`)는 prompt_toolkit·rich로 만든 REPL이며, 같은 도구 세트를 FastAPI(`api_server.py`)와 MCP 서버(`mcp_server.py`)로도 노출해 외부 에이전트(Claude Desktop 등)가 연결할 수 있게 합니다. Docker 빌드는 프론트엔드(React)·백엔드를 멀티스테이지로 분리하고 `requirements-lock.txt`로 해시 고정 설치를 강제해 재현성을 챙깁니다.
- STEP 01
pip install vibe-trading-ai로 설치 후 vibe-trading 명령을 처음 실행하면 .env가 없어 온보딩 마법사가 뜨고 LLM 제공자(OpenRouter, DeepSeek 등) API 키 입력을 요구받습니다.
- STEP 02
REPL이 뜨면 '/help'로 슬래시 명령 목록을 확인하고, 'BTC-USDT MACD 전략 백테스트해줘' 같은 자연어 질의를 입력하면 에이전트가 생각 과정을 스트리밍으로 보여주며 도구 호출(tool_event)을 실시간 표시합니다.
- STEP 03
백테스트가 끝나면 터미널에 수익률·샤프비율·MDD 등 지표 요약이 출력되고, 설정에 따라 agent/runs/ 아래에 리포트 아티팩트(PDF/HTML/차트)가 생성됩니다.
- STEP 04
데이터 소스에 따라 akshare, tushare, binance 등 외부 API 키나 접근 제한에 걸려 로더가 실패할 수 있고, 이 경우 loader-health 관련 에러 메시지로 원인을 알려줍니다.
- STEP 05
vibe-trading serve로 FastAPI 서버를 띄우면 React 프론트엔드(포트 5899)와 API(포트 8899)가 분리되어 뜨고, MCP 서버 모드로는 Claude Desktop 등 외부 에이전트에서 도구로 연결해볼 수 있습니다.
- STEP 06
/connector, /halt, /resume 같은 라이브 트레이딩 관련 명령은 실거래 커넥터 설정이 되어 있어야 의미가 있으며, 기본 상태에서는 백테스트/리서치 용도로만 체감됩니다.
실행 결과로 얻는 것은 전략 백테스트 수치(수익률, 샤프, MDD, 회전율 등)와 다국어(CJK, 아랍어 포함) 폰트가 포함된 PDF/HTML 리포트, 그리고 세션별 기록(agent/sessions, runs)입니다. 추가로 '섀도 계정' 기능을 통해 실거래 없이 전략을 모의 운용한 평가 리포트를, MCP/REST API를 통해서는 다른 에이전트 프레임워크에 동일 도구를 연결해 쓸 수 있는 통합 지점을 얻습니다.
백테스트 결과는 실제 시장 성과를 보장하지 않으며, 리포트 수치 역시 LLM이 생성·요약하는 경로를 거치므로 grounding 검증이 있다 해도 완전한 정확성을 담보하지는 않습니다.
다수의 데이터 로더(tushare, binance, akshare, futu, longbridge, MT5 등)가 각각 별도 계정/키/지역 제한을 요구하므로, 실제로는 원하는 시장 데이터를 받기 위해 추가 가입과 설정이 필요할 수 있습니다.
MT5 연동은 Windows 전용이며, PDF 생성은 weasyprint의 시스템 라이브러리(Pango/Cairo 등)가 없으면 HTML로 자동 다운그레이드되는 등 환경별 기능 차이가 존재합니다.
킬스위치(/halt)나 커넥터 기능이 있다고 해서 실거래 안전성이 완전히 보장되는 것은 아니며, 실거래 연결 전 반드시 별도 검증이 필요한 영역으로 보입니다.
퀀트 백테스트를 자연어로 다루고 싶은 개발자나, 여러 시장(국내외 주식·코인·선물·옵션)을 하나의 에이전트 인터페이스로 탐색하고 싶은 사람에게 적합합니다. 코드 트리에 자산군별 엔진, 로더 레지스트리, grounding 검증 모듈, CI 워크플로(test, loader-health, docker-build)와 해시 고정 의존성 관리가 모두 실존해 구조적 신뢰도는 높지만, 실거래 손익에 대한 보장은 전혀 없으므로 백테스트/리서치 도구로 접근하는 것이 안전합니다. README와 파일 구조만으로도 기능 범위와 동작 경로를 충분히 가늠할 수 있어, 직접 설치하지 않고도 이 정도 판단은 신뢰할 수 있습니다.