프레임워크
TradingAgents는 실제 트레이딩 회사의 조직 구조를 LLM 멀티에이전트로 시뮬레이션하여, 주식 매매 의사결정을 협업적으로 수행하는 오픈소스 Python 프레임워크입니다. 기술적 분석·뉴스 분석·재무 분석·감성 분석을 담당하는 4명의 애널리스트가 독립적으로 분석한 뒤, Bull vs Bear 연구원이 토론하고, 리스크 관리팀이 3관점으로 검토하여 최종 매매 신호를 생성합니다.
실제 투자회사에서는 기술 애널리스트, 뉴스 애널리스트, 재무 애널리스트, 강세론자, 약세론자, 리스크 매니저, 포트폴리오 매니저가 각자의 관점으로 토론한 후 매매를 결정합니다. TradingAgents는 이 구조를 LangGraph StateGraph로 그대로 코드화합니다.
핵심 설계는 Bull과 Bear가 서로 다른 논거를 작성하고 판정자가 종합하는 것입니다. 토론 구조 자체가 편향 감소나 투자 성과를 보장하지는 않으며 결과 검증은 별도입니다.
2026-10-27 Daily 모멘텀 7위로 관측했습니다. 기술적 관심사는 하나의 답을 만드는 데서 그치지 않고 분석 보고·대립 토론·구조화된 판정·후속 평가를 이어 붙이는 방식입니다. 순위만으로 인기 원인이나 수익 성과를 단정할 수는 없습니다.
| 현재 동작 | 설계상 의미 |
|---|---|
| 분석가 병렬 실행 | 각자 독립된 메시지 이력·도구를 쓰고 모든 보고가 모이면 연구 토론을 시작합니다. |
| 모델 계층 분리 | 빠른 분석과 종합 판단의 모델·provider를 각각 설정할 수 있습니다. 호출량과 비용도 달라집니다. |
| 지속 결정 로그 | 판정·결과·회고를 기록하고 과거 시점에 알 수 있었던 회고만 다시 읽습니다. |
| 내장 백테스트 | 종목×날짜의 판단을 평가합니다. 실제 주문 체결·현금 장부를 가진 포트폴리오 시뮬레이터는 아닙니다. |
README는 연구용 프레임워크라고 설명합니다. 이 문서의 초점은 데이터 시점·도구 격리·평가 구조이며, 특정 금융상품이나 매매 전략의 권고가 아닙니다.
| 계층 | 현재 구성 | 소스 근거 |
|---|---|---|
| 런타임 | Python 3.11 이상 | pyproject.toml의 requires-python. README의 3.13은 환경 생성 예입니다. |
| 워크플로우 | LangGraph·LangChain Core·SQLite checkpoint | graph/setup.py, langgraph-checkpoint-sqlite 의존성 |
| 모델 | OpenAI·Anthropic·Google 등의 클라이언트와 provider 레지스트리 | llm_clients/, model 카탈로그. Bedrock은 선택 extra입니다. |
| 데이터 | yfinance·stockstats·pandas 3.0.6 이상, Yahoo·Alpha Vantage·SEC 등 vendor 경로 | dataflows/vendors/, pyproject.toml |
| 기록·보고 | 로컬 결정 로그·회고·Markdown/HTML 보고 | memory/, reporting.py / report_html.py |
| CLI·배포 | Typer·Rich·Questionary, Docker, Python wheel | cli/, Dockerfile, project.scripts |
현재 필수 의존성에 Redis는 없습니다. 별도 웹 프런트엔드·운영 서버를 배포해야 쓰는 구조도 아닙니다. 모델 및 데이터 접근에 필요한 네트워크·인증·외부 비용은 선택한 provider와 vendor에 따릅니다.
입력: 종목·분석일·설정
├─ Market / Sentiment / News / Fundamentals (선택된 분석가 병렬)
│ 각 분석가는 전용 메시지 이력 + ToolNode + 도구 라운드 상한
└─ Memory Log: 이전 결정 결과 정산·과거 회고 준비
↓ 모든 첫 단계 합류
Bull ↔ Bear → Research Manager → Trader
↓
Aggressive / Conservative / Neutral 토론 → Portfolio Manager
↓
판정·보고서·결정 로그 저장
↓ 이후 가격 구간이 충분해지면 결과와 회고 정산
graph/setup.py의 _analyst_graph()는 분석가마다 별도 하위 그래프를 만들고 보고 필드 하나만 반환합니다. 도구 호출은 다른 분석가의 대화에 들어가지 않습니다. 도구 라운드 상한에 도달하면 보고서 작성을 요청하고 그 턴을 끝냅니다. 도구만 반복 호출하다 전체 재귀 한도를 소진하는 경우를 줄이는 장치입니다.
선택 분석가와 Memory Log를 START에서 분기하고 workflow.add_edge(first_steps, "Bull Researcher")로 합류합니다. 이후 연구·리스크 토론은 조건부 라우터가 관리합니다. schemas.py는 Research Manager·Trader·Portfolio Manager의 결과를 Pydantic 구조로 정의하고 다시 읽을 수 있는 보고 형식으로 렌더링합니다. 최종 평가는 Buy·Overweight·Hold·Underweight·Sell의 다섯 단계입니다.
현재 TradingMemoryLog는 종목·분석일별 결정을 중복 저장하지 않는 Markdown 로그입니다. 미정산 항목은 pending으로 남고, 충분한 가격 구간을 확보한 뒤 수익 변화·벤치마크 대비 차이·회고를 기록합니다. get_past_context(as_of=...)는 해당 분석일 이전에 결과가 알려진 항목만 포함합니다. 이는 모델 가중치를 재학습하는 과정이 아닙니다.
# memory/log.py의 실제 시점 제한
if as_of is not None:
entries = [e for e in entries
if e.get("resolved") and e["resolved"] <= as_of]memory/settlement.py는 분석일 당일 종가 뒤에 나온 뉴스가 판단에 포함될 수 있으므로 분석일 이후 첫 종가부터 결과를 평가합니다. backtest.py는 종목×날짜 셀을 독립 평가하고 평점별 방향 적중과 평균 alpha를 요약합니다. 주문 수량·체결가·현금 장부가 없으므로 투자 포트폴리오의 실제 손익 시뮬레이션으로 해석하면 안 됩니다. 셀당 모델 샘플 한 번과 비보관 텍스트 피드 때문에 결과는 완전 재현 가능한 측정도 아닙니다.
v0.7.0 README에는 사용자의 ChatGPT 구독을 쓰는 provider도 추가됐다고 안내합니다. 이는 upstream의 기능 설명이며, 이번 분석에서 로그인·모델 호출·금융 데이터 호출은 하지 않았습니다.
TradingAgents/ ├── cli/ 대화형·비대화형 실행, 보고 표시 ├── tradingagents/ │ ├── default_config.py 환경변수·기본 설정 │ ├── agents/ │ │ ├── analysts/ market/news/fundamentals/sentiment │ │ ├── researchers/ Bull/Bear │ │ ├── managers/ 연구 종합·최종 판정 │ │ ├── risk_mgmt/ 3관점 토론 │ │ └── schemas.py 구조화 판정 │ ├── graph/ 하위 분석 그래프·합류·조건부 토론 │ ├── dataflows/vendors/ Yahoo/Alpha Vantage/SEC 등 데이터 경로 │ ├── memory/ 결정 로그·결과 정산·회고 │ ├── reporting.py / report_html.py Markdown/HTML 보고 │ ├── backtest.py 종목×날짜 판단 평가 │ └── llm_clients/ provider 추상화 ├── tests/ 시점·날짜·도구·평점·provider 회귀 └── pyproject.toml / Dockerfile
3월 문서에 있던 social_media_analyst.py는 현재 sentiment_analyst.py이고, 데이터 vendor들은 하위 패키지로 나뉘었습니다. 옛 import 경로를 그대로 실습에 쓰기 전에 현재 tree를 확인합니다.
| 학습 주제 | 실제 읽을 위치 | 확인할 질문 |
|---|---|---|
| 병렬 그래프의 상태 격리 | graph/setup.py | 동시에 실행하는 분석가가 같은 메시지 키를 덮지 않게 어떻게 출력 스키마를 제한하나? |
| 도구 루프 종료 | _analyst_graph(), wrap_up | 반복 호출이 상한에 닿았을 때 보고서 작성 턴은 어떻게 끝나나? |
| 시점 무결성 | memory/log.py, settlement.py | 결정 시각·결과가 알려진 시각·평가 시작 가격을 왜 구분하나? |
| 결과 검증 | agents/schemas.py | 숫자 자리의 범위·비율·빈 값이 어떻게 처리되고 다섯 등급과 연결되나? |
| 평가 범위 | backtest.py | 독립 셀의 판단 평가에 없는 주문·현금 장부를 결과 해석에 끼워 넣지 않았나? |
| 단계 | 조건 |
|---|---|
| 소스 읽기 | 텍스트 편집기·Git. 키나 실행 환경 없이 구조를 분석할 수 있습니다. |
| 패키지 실행 | Python 3.11+, pyproject.toml 의존성. README는 conda 또는 uv의 3.13 환경 예를 제공합니다. |
| 모델·데이터 | 선택 provider/vendor에 맞는 인증·접근 권한이 필요합니다. 호스팅 모델 호출은 비용이 발생할 수 있습니다. |
| 저장 | 보고·캐시·결정 로그·checkpoint를 저장할 로컬 경로. Docker는 tradingagents_data volume을 안내합니다. |
| 하드웨어 | 현재 원본은 RAM 4GB/8GB 같은 최소치를 제시하지 않습니다. 호스팅 API와 로컬 모델의 요구는 서로 다릅니다. |
현재 필수 의존성에 Redis나 backtrader는 없으며 이를 설치 전제로 안내하지 않습니다. 분석가 수·토론 깊이·정산할 결정 수에 따라 호출량이 바뀝니다. 이 문서는 비용이나 처리 시간을 직접 측정하지 않았습니다.
README의 Python 환경 예와 pyproject.toml의 requires-python을 대조합니다. 산출물은 필수·선택 extra·문서 예시를 나눈 표입니다. 설치 스크립트를 실행할 필요는 없습니다.
setup.py에서 START 분기와 first_steps 합류, 보고 전용 출력 스키마를 찾습니다. 두 분석가의 도구 메시지가 서로 섞이지 않는 이유와 루프 상한을 도식화합니다.
가상의 결정일·결과 확정일·분석일을 세 열로 놓고 어떤 회고가 포함될지 예상합니다. get_past_context의 as_of 조건과 대조해 미래 결과가 들어갈 사례를 찾습니다.
backtest.py의 모듈 설명과 BacktestSummary.render()를 읽고 지표가 뜻하는 범위를 정리합니다. 수량·체결가·현금 장부가 없다는 점과 분석일 이후 첫 종가 기준을 설명하는 것이 완료 조건입니다.
schemas.py의 _coerce_optional_float()를 읽어 빈 문자열·비율·통화 표기·범위가 각각 어떻게 정규화되는지 표로 만듭니다. 투자 판단을 생성하지 않고 데이터 계약을 검토하는 과제입니다.
LangGraph 공식 문서 정독, StateGraph·노드·엣지·조건부 라우팅 이해, 간단한 2-노드 워크플로우 만들어보기. 참고: LangGraph 공식 튜토리얼 (langchain-ai.github.io/langgraph/)
Agent 역할 분리 패턴(Analyst, Researcher, Manager), 토론(Debate) 메커니즘 구현, 메모리 + Reflection 패턴. 참고: TradingAgents의 graph/setup.py 소스코드 정독.
yfinance API로 주가/재무 데이터 수집, 기술지표(MACD, RSI, 볼린저밴드) 이해 및 구현, pandas로 시계열 데이터 처리. 실습: 관심 종목 3개의 기술지표 대시보드 만들기.
Factory 패턴으로 멀티 프로바이더 지원, 프로바이더별 특수 기능 활용, 비용 최적화: Deep/Quick Think 모델 분리 전략. 실습: 3개 프로바이더를 지원하는 LLM 클라이언트 라이브러리 만들기.
Typer로 CLI 프레임워크 구축, Rich로 실시간 터미널 대시보드 개발, Questionary로 대화형 입력 처리. 실습: 나만의 AI 도구 CLI 대시보드 만들기.
4주차까지 배운 기술을 조합하여 미니 TradingAgents 구현. 2명의 에이전트 + 1명의 판정자로 간소화된 토론 시스템, yfinance 데이터 기반 간단한 매매 시그널 생성.
| 용어 | 이 저장소에서의 의미 |
|---|---|
| StateGraph / ToolNode | 상태를 전달하는 워크플로우 / 분석가의 도구 호출 실행 노드 |
| Debate | Bull·Bear 또는 리스크 관점별 논거를 순서와 조건으로 연결하는 과정 |
| 구조화 판정 | Pydantic 스키마의 등급·근거를 검증한 뒤 보고 형식으로 렌더링하는 결과 |
| Memory Log | 결정·미정산 상태·결과·회고를 저장하는 지속 로그. 모델 학습 가중치가 아닙니다. |
| Point-in-time | 분석일 당시 알 수 있었던 데이터·결과만 사용하는 시점 제약 |
| Alpha | 선택한 벤치마크 대비 결과 차이. 주문 체결 손익과 같지 않습니다. |
| Checkpoint | 중간 그래프 상태를 저장하고 재개하는 기록 |
| Deep / Quick tier | 종합 판단과 빠른 분석에 서로 다른 모델·provider를 연결하는 계층 |
2026-10-27 고정 커밋 e8f5503e9b86d5c2710b0c76b1f686703968c9df을 읽어 3월 문서를 개정했습니다. upstream 패키지 설치·테스트·모델 호출·금융 데이터 수집은 하지 않았습니다.