TradingAgents/.github/copilot-instructions.md

TradingAgents 프로젝트 가이드라인

프로젝트 개요

멀티 에이전트 LLM 데이 트레이딩 프레임워크. LangGraph 기반 5단계 파이프라인(분석→토론→트레이딩→리스크→포트폴리오)으로 주식 매매 의사결정을 수행한다. Discord 봇 + 한국투자증권 API 연동으로 실제 자동매매를 지원한다.

빌드 및 실행

pip install -e .                  # 개발 설치
tradingagents analyze             # CLI 대화형 분석
python bot.py                     # Discord 봇 (자동 데이트레이딩)
python main.py                    # 직접 분석 예제
docker-compose up                 # 컨테이너 배포

• Python 3.10+ 필수
• .env 파일에 API 키 설정 필요 (LLM, Discord, KIS)

아키텍처

핵심 디렉터리

디렉터리	역할
tradingagents/agents/	에이전트 팀 (analysts, researchers, trader, risk_mgmt, managers)
tradingagents/dataflows/	데이터 벤더 추상화 (yfinance/AlphaVantage)
tradingagents/graph/	LangGraph 오케스트레이션, 상태 관리
tradingagents/llm_clients/	LLM 프로바이더 팩토리 (openai, anthropic, google 등)
cli/	Typer 기반 대화형 CLI

진입점

파일	용도
bot.py	Discord 봇 (슬래시 커맨드 + 자동 스케줄)
main.py	Python 직접 사용 예제
kis_client.py	한국투자증권 REST API 클라이언트
trade_history.py	SQLite 거래 기록 관리

5단계 파이프라인

1. 애널리스트 (병렬): 시장/소셜/뉴스/펀더멘털 → 각 리포트
2. 리서치 토론: 강세 vs 약세 연구원 → 리서치 매니저 중재
3. 트레이더: 리포트 + BM25 메모리 기반 투자 계획 수립
4. 리스크 토론: 공격/중립/보수 → 리스크 심판
5. 포트폴리오 매니저: 최종 BUY/HOLD/SELL 결정

코드 컨벤션

에이전트 패턴

• 에이전트 생성: create_* 팩토리 함수 (예: create_market_analyst(llm))
• 그래프 노드: node_func(state) → updated_state 형태
• 도구: LangChain 도구 바인딩, 벤더 추상화 레이어로 라우팅
• 상태: AgentState TypedDict로 단계 간 데이터 전달

설정 관리

• tradingagents/default_config.py의 DEFAULT_CONFIG dict를 복사하여 사용
• LLM 프로바이더, 토론 라운드, 데이터 벤더 등 중앙 관리
• 환경변수: .env 파일 참조 (API 키, 스케줄, 한도 등)

LLM 클라이언트

• create_llm_client(provider, model, **kwargs) 팩토리로 생성
• 지원: openai, anthropic, google, xai, ollama, openrouter
• Google: thinking_level, OpenAI: reasoning_effort 파라미터

데이터 벤더

• dataflows/interface.py에서 도구별 벤더 라우팅
• 기본: yfinance (무료), 대안: AlphaVantage (유료)
• 벤더 실패 시 자동 폴백

주의사항

• KIS API는 KIS_VIRTUAL=true로 모의투자 먼저 테스트
• bot.py의 자동매매 스케줄(09:30/15:20 KST)은 실제 주문 실행 — 신중하게 수정
• 커밋 메시지는 한국어로 간결하게 작성
• Docker 배포 시 data/, results/, reports/ 볼륨 마운트 필수