AlpacaTradingAgent: 향상된 다중 에이전트 Alpaca 거래 프레임워크
🚀 AlpacaTradingAgent - 원래의 TradingAgents 프레임워크를 기반으로 구축된 독립적인 향상 버전이며, 자신의 Alpaca 계정에서 AI 에이전트를 테스트하거나 사용하려는 Alpaca 사용자에게 특별히 설계되었습니다.
이 프로젝트는 Tauric Research가 만든 원래 TradingAgents 프레임워크에서 영감을 받은 독립적인 업그레이드 버전으로, 실시간 Alpaca 통합, 암호화폐 지원, 자동 거래 기능 및 향상된 웹 인터페이스를 추가했습니다.
면책 조항: 본 프로젝트는 교육 및 연구 목적으로만 제공됩니다. 이는 금융, 투자 또는 거래에 대한 조언이 아닙니다. 거래에는 위험이 따르므로, 사용자는 어떠한 거래 결정을 내리기 전에 자체 실사(due diligence)를 수행해야 합니다.
<div align="center">
🚀 향상된 기능 | ⚡ 설치 및 설정 | 📦 패키지 사용 | 🌐 웹 인터페이스 | 📖 완벽 가이드 | 🤝 기여하기 | 📄 인용
⏱️ 처음이신가요? QUICKSTART.md — 약 5분 만에 첫 분석 · 🏗️ ARCHITECTURE.md — 파이프라인 작동 방식
</div>
향상된 기능 (Enhanced Features)
Windows 사용자는 터미널이나 Python 설치 없이 AlpacaTradingAgent.exe를 열 수 있습니다. 빠른 시작을 위해 이 파일 옆에 _internal 폴더를 보관하십시오. API 설정, 연결 확인, 저장소 및 빌드 지침은 데스크톱 가이드를 참조하십시오.
AlpacaTradingAgent는 Alpaca 사용자를 위해 특별히 설계된 강력한 새로운 기능을 도입합니다:
🔄 실시간 Alpaca 통합 (Real-Time Alpaca Integration)
- 라이브 트레이딩 (Live Trading): 실시간 거래 실행을 위해 Alpaca API와 직접 통합됩니다.
- 모의 및 라이브 트레이딩 (Paper & Live Trading): 모의 거래(테스트)와 실제 자금을 사용한 라이브 트레이딩 모두를 지원합니다.
- 마진 트레이딩 (Margin Trading): 공매도 기능을 포함하여 마진 계좌에 대한 전체 지원을 제공합니다.
- 포트폴리오 관리 (Portfolio Management): 실시간 포트폴리오 추적, 포지션 모니터링 및 주문 관리를 수행합니다.
📈 듀얼 자산 지원: 주식 및 암호화폐 (Dual Asset Support: Stocks & Crypto)
- 다중 자산 분석 (Multi-Asset Analysis): 단일 세션에서 전통 주식과 암호화폐를 모두 분석합니다.
- 암호화폐 형식 (Crypto Format): 암호화폐 분석을 위해 적절한 암호화폐 형식(예:
BTC/USD, ETH/USD)을 사용합니다.
- 혼합 포트폴리오 (Mixed Portfolios): 다각화된 분석을 위해 "NVDA, ETH/USD, AAPL"와 같은 혼합 심볼 입력을 지원합니다.
- 전용 데이터 소스 (Dedicated Data Sources): 기본 암호화폐 데이터를 위한 CoinDesk/CryptoCompare 호환 암호화폐 뉴스 및 DeFi Llama를 제공합니다.
🤖 향상된 다중 에이전트 시스템 (Enhanced Multi-Agent System) (5개 에이전트)
- 시장 분석가 (Market Analyst): 전반적인 시장 상황과 추세를 평가합니다.
- 소셜 감성 분석가 (Social Sentiment Analyst): 소셜 미디어 감정과 대중의 의견을 분석합니다.
- 뉴스 분석가 (News Analyst): 금융 뉴스 및 이벤트를 모니터링하고 해석합니다.
- 기초 분석가 (Fundamental Analyst): 기업 재무 상태와 내재 가치를 평가합니다.
- 거시 분석가 (Macro Analyst): 거시경제 지표와 연방준비제도(Federal Reserve) 데이터를 분석합니다.
- 병렬 실행 (Parallel Execution): 모든 5명의 분석가가 동시에 실행되어 더 빠른 분석을 제공하며, API 과부하를 방지하기 위해 설정 가능한 지연 시간을 갖습니다.
🧠 다중 제공업체 LLM 런타임(Multi-Provider LLM Runtime)
- 현재 모델 카탈로그: GPT-6 Astra, Gemini 3.8, Claude Fable 5.1, Opus 5, Sonnet 5, Grok 4.6, MiniMax M2.7, DeepSeek V4, Qwen 3.8, GLM-5.2를 지원합니다.
- 제공업체 선택: OpenAI, 로컬 OpenAI 호환 엔드포인트, Google Gemini, Anthropic Claude, xAI, MiniMax, DeepSeek, Qwen, GLM, OpenRouter, Ollama, Azure OpenAI를 지원합니다.
- 제공업체별 제어 기능: GPT-6/GPT-5 추론 모델에는 OpenAI 응답 API(OpenAI Responses API)를 사용하고, Gemini의 사고 수준은 패밀리 단위로 검증하며, Claude의 노력(effort)은 네이티브
output_config를 통해 전송하고, Grok의 추론 노력도 노출합니다.
- 향후 호환성: 모든 제공업체는 사용자 정의 모델 ID를 수용하지만, 내장 카탈로그는 공식 제공업체 문서를 기반으로 선별되어 유지됩니다.
- 비용 안전 기본값: 기본 모델은
gpt-5.4-nano와 gpt-5.4-mini로 유지되며, 새로운 플래그십 모델을 선택하는 것은 명시적입니다.
- 로컬 호환성:
OPENAI_USE_LOCAL 및 OPENAI_BASE_URL은 핵심 LLM 호출을 로컬 OpenAI 호환 백엔드로 계속 라우팅합니다.
🧾 구조화된 결정, 메모리, 그리고 재개(Structured Decisions, Memory, and Resume)
- 실행 가능한 최종 행동: 최종 결정은 Alpaca 실행을 위해
BUY/HOLD/SELL 또는 LONG/NEUTRAL/SHORT를 보존합니다.
- 자문 평점: 상위 스트림 스타일의 평점은 메타데이터로만 취급되며 Alpaca 주문을 직접적으로 유발하지 않습니다.
- 구조화된 출력 폴백(Fallback): 리서치 매니저, 트레이더, 위험 관리자는 지원되는 경우 구조화된 스키마를 사용하며, 그렇지 않은 경우에는 자유 텍스트로 우아하게 재시도합니다.
- 영구 결정 로그: 완료된 결정은 마크다운 메모리 로그에 기록되며, 나중에 가상의 고정 기간 자산 수익률 및 성찰(reflections)과 평가됩니다. 이는 실현되지 않은 계좌 이익이 아닙니다.
- 체크포인트 재개(Checkpoint Resume): 선택적 심볼별 SQLite 체크포인트는 실패한 LangGraph 실행을 재개할 수 있게 하며, 성공적인 실행은 자동으로 정리합니다.
- 안전 경로: 보고서(Report), 캐시(cache), 체크포인트, 로그 경로는
BTC/USD -> BTC_USD와 같은 암호화폐 심볼을 포함하여 안전한 티커 구성 요소를 사용합니다.
연구 및 위험 기본값 (Research and risk defaults)
Tauric paper는 전문적인 연구, 반대 주장 및 별도의 위험 검토를 동기로 합니다. 이 역사적 실험은 오늘날의 모델에 대한 처방전이 아니며 보장된 수익률도 아닙니다. 현재 상위 구현체는 기본적으로 한 번의 토론 라운드를 사용합니다. 이 포크(fork)는 반박을 허용하기 위해 Medium (연구 3회 및 위험 3회)에서 시작합니다. 이는 운영상의 선택일 뿐, 실험적으로 증명된 최적값은 아닙니다.
웹 검색은 이제 선택된 깊이(low, medium 또는 high coverage)를 따릅니다. tradingagents/default_config.py의 세 가지 *_fast_profile 설정에서도 여전히 좁은 검색을 선택할 수 있습니다. News는 티커 헤드라인을 처리하고 Macro는 광범위한 이벤트를 처리하여 중복된 글로벌 검색을 방지합니다. 검색 출력 예산은 모델 추론 및 인용된 증거를 위한 공간을 남기기 위해 4,096 토큰으로 설정되었으며, 프롬프트는 여전히 간결한 보고서를 요청합니다. 이는 이전 fast profile보다 시간이 더 오래 걸리고 비용이 더 많이 들 수 있습니다. 모델 선택 및 추론 제어는 연구 깊이와 독립적으로 유지되며, 저장된 모델 선택은 보존됩니다. 다른 제공업체가 에이전트를 실행할 때에도 OpenAI web-search 도구는 여전히 OpenAI 키를 필요로 합니다.
포지션 사이징(Position sizing)은 기본적으로 활성화되어 있습니다. 각 신규 진입은 계획된 손절매가(planned stop)에서 자본금 위험의 1% 및 자본금 명목액(equity notional)의 20%로 제한되며, 총 노출 한도는 80%이고 요청된 거래 금액이 추가적인 상한선으로 작용합니다. 별도의 집중도 방어 장치(concentration guard)는 단일 심볼에 대한 총 노출을 25%로 제한합니다. 기존의 변동성(volatility), 상관관계(correlation) 및 시장 국면 조정은 사이징을 더욱 낮출 수 있습니다. 일일 손실 3% 또는 하락폭(drawdown) 10%는 새로운 위험을 중단시킵니다. 이러한 임계값은 공백 기간이나 서비스 장애 동안 최대 실현 손실을 보장하지 않습니다. 모의 거래(Paper trading), 롱 온리 모드(long-only mode) 및 수동 실행이 기본값으로 유지됩니다. 구성을 더 좋다고 간주하기 전에, 여러 기간에 걸쳐 거래 및 API 비용 이후 순수익, 하락폭, 그리고 벤치마크 성과를 평가해야 합니다.
⚡ 자동 거래 및 스케줄링 (Automated Trading & Scheduling)
- 시장 시간 거래 (Market Hours Trading): 시장 시간에 자동 실행
- 예약 분석 (Scheduled Analysis): N시간마다 설정 가능한 반복 분석
- 자동 실행 (Auto-Execution): 에이전트 추천 기반의 선택적 자동 거래 실행
- 스마트 스케줄링 (Smart Scheduling): 다양한 자산 클래스의 시장 시간을 준수함
🌐 고급 웹 인터페이스 (Advanced Web Interface)
- 다중 심볼 대시보드 (Multi-Symbol Dashboard): 여러 심볼을 동시에 분석하고 거래할 수 있음
- 진행 상황 추적 (Progress Tracking): 각 심볼의 분석 상태를 보여주는 실시간 진행 테이블
- 인터랙티브 차트 (Interactive Charts): 기술 지표와 함께 라이브 Alpaca 데이터 통합
- 탭 기반 리포트 (Tabbed Reports): 쉬운 탐색이 가능한 정리된 분석 보고서
- 채팅 스타일 토론 (Chat-Style Debates): 에이전트 간의 토론을 대화 스레드로 시각화
- 포지션 관리 (Position Management): 현재 포지션, 최근 주문 확인 및 UI에서 직접 청산 가능
- 모델 구성 (Model Configuration): 제공자(provider), 모델, 제공자별 파라미터, 출력 언어, 체크포인트 재개 지점을 UI에서 선택
전체 가이드 (Complete Guide)
자동 거래를 위한 AlpacaTradingAgent 웹 UI 사용에 대한 심층적이고 단계별 가이드는 Dev.to의 전체 가이드를 확인하세요:
AlpacaTradingAgent 프레임워크 (AlpacaTradingAgent Framework)
AlpacaTradingAgent는 실제 거래 회사의 역동성을 반영하는 다중 에이전트(multi-agent) 거래 프레임워크입니다. 전문화된 LLM 기반 에이전트들을 협업하여 배포함으로써, 이 플랫폼은 여러 자산 클래스에 걸쳐 시장 상황을 평가하고 Alpaca API를 통해 정보에 입각한 거래 결정을 실행합니다.
<p align="center">
<img src="https://raw.githubusercontent.com/huygiatrng/AlpacaTradingAgent/HEAD/assets/schema.png" style="width: 100%; height: auto;"></p>
AlpacaTradingAgent 프레임워크는 연구 및 교육 목적으로 설계되었습니다. 거래 성과는 선택된 배경 언어 모델(backbone language models), 모델 온도, 거래 기간, 데이터 품질 및 기타 비결정적 요소 등 여러 요인에 따라 달라질 수 있습니다. 이는 금융, 투자 또는 거래 조언으로 의도되지 않았습니다.
저희의 향상된 프레임워크는 복잡한 거래 작업을 전문화된 역할로 분해하는 동시에 실시간 시장 연결성 및 실행 기능을 제공합니다.
강화 분석가 팀 (Enhanced Analyst Team) (5개 에이전트)
- 시장 분석가 (Market Analyst): 전반적인 시장 상황, 섹터 트렌드, 시장 심리 지표를 평가합니다.
- 소셜 감성 분석가 (Social Sentiment Analyst): Reddit, OpenAI 웹 검색 감성 및 공공 시장 서사를 분석합니다.
- 뉴스 분석가 (News Analyst): 금융 뉴스, 실적 발표, 시장에 영향을 미치는 글로벌 이벤트를 모니터링합니다.
- 기본 분석가 (Fundamental Analyst): 회사 재무 상태, 실적 보고서 및 내재 가치 계산을 평가합니다.
- 거시 경제 분석가 (Macro Analyst): FRED API를 사용하여 연준(Federal Reserve) 데이터, 경제 지표 및 거시경제 동향을 분석합니다.
연구원 팀 (Researcher Team)
- 분석가 팀이 제공한 통찰력을 비판적으로 평가하는 강세(bullish) 및 약세(bearish) 연구원으로 구성됩니다. 구조화된 토론을 통해 잠재적 이익과 내재적 위험 사이의 균형을 맞추며, 이제 주식 및 암호화폐 시장 모두에 대한 향상된 지원 기능을 제공합니다.
트레이더 에이전트 (Trader Agent)
- 분석가와 연구원으로부터 보고서를 작성하여 정보에 입각한 거래 결정을 내립니다. Alpaca API를 통해 직접 실행하며, 거래의 시점, 규모 및 방향(롱/숏)을 결정합니다.
위험 관리 및 포트폴리오 매니저 (Risk Management and Portfolio Manager)
- 주식과 암호화폐 자산 전반에 걸쳐 포트폴리오 위험을 지속적으로 평가합니다. 증거금 요건, 포지션 규모 및 전체 포트폴리오 노출도를 모니터링합니다. Alpaca 통합을 통해 실시간 위험 평가와 포지션 관리를 제공합니다.
설치 및 설정 (Installation and Setup)
설치 (Installation)
AlpacaTradingAgent 클론하기:
git clone https://github.com/huygiatrng/AlpacaTradingAgent.git
cd AlpacaTradingAgent
종속성 설치:
pip install -r requirements.txt
필수 API 설정
실시간 거래를 포함한 전체 기능을 사용하려면 다음 API 키들을 설정해야 합니다:
-
샘플 환경 파일 복사:
-
.env 파일 수정: 여기에 사용자의 API 키를 입력합니다:
필수 API
