TradingAgents는 복수의 대규모 언어 모델(LLM) 에이전트가 애널리스트, 리서처, 트레이더, 리스크 매니지먼트 팀으로 나뉘어 시장 분석과 토론을 진행하도록 설계된 멀티 에이전트 금융 분석 오픈소스 프레임워크입니다. 이 시스템은 각 에이전트가 수집한 데이터를 바탕으로 상승과 하락 관점의 토론을 거쳐 최종적으로 포트폴리오 매니저의 의사결정을 도출하는 파이프라인으로 작동합니다.
처음 TradingAgents 저장소를 접하는 개발자나 퀀트 연구자는 어떤 파이썬 버전에서 환경을 격리해야 하는지, 그리고 의존성을 설치한 뒤 코드로 특정 종목 분석을 어떻게 호출해야 하는지 혼란을 겪기 쉽습니다. 여기서는 공식 저장소 가이드를 기준으로 Python 3.13 기반 가상환경 구성부터 TradingAgentsGraph 객체를 사용해 단일 티커 분석 결정을 확인하는 구체적인 절차를 다룹니다.
TradingAgents 구동을 위한 Python 3.13 가상환경 생성 및 의존성 설치
TradingAgents는 Python 3.11 이상의 환경을 요구하며, 공식 저장소에서는 Python 3.13 환경 구성을 안내합니다. 프로젝트 저장소를 복제한 뒤 시스템 전역 파이썬과 충돌하지 않도록 Conda 또는 uv를 사용해 가상환경을 분리해야 합니다.
먼저 터미널을 열고 공식 저장소를 로컬 컴퓨터로 복제한 다음 해당 디렉터리로 이동합니다.
git clone https://github.com/TauricResearch/TradingAgents.git
cd TradingAgents가상환경 관리자로 Conda를 사용하는 경우 아래 명령으로 tradingagents라는 이름의 Python 3.13 가상환경을 생성하고 활성화합니다.
conda create -n tradingagents python=3.13
conda activate tradingagents만약 빠른 패키지 관리를 위해 uv 도구를 사용한다면 프로젝트 루트에서 다음과 같이 가상환경을 생성하고 셸에 환경을 반영할 수 있습니다.
uv venv --python 3.13
source .venv/bin/activate가상환경 활성화가 완료되면 현재 디렉터리의 pyproject.toml 또는 setup.py 명세를 읽어 로컬 패키지와 필수 의존성을 한 번에 설치합니다. Conda 환경이라면 기본 pip 명령을 실행하고, uv 환경이라면 uv pip를 활용합니다.
pip install .uv 환경에서는 uv pip install . 명령을 입력하여 저장소 내 모듈과 의존성 라이브러리를 설치합니다. 이 과정이 오류 없이 끝나면 tradingagents 패키지를 로컬 파이썬 코드에서 임포트할 수 있는 기본 상태가 갖춰집니다.
.env 환경변수 구성과 LLM 공급자 재정의 방식
TradingAgents 내 각 분석 에이전트는 기저 LLM과의 통신을 통해 시장 분석과 토론 보고서를 생성합니다. 따라서 프레임워크를 구동하려면 하나 이상의 LLM API 키 설정이 필수적입니다.
저장소 루트에 포함된 예시 설정 파일을 복사하여 실제 환경변수 파일인 .env를 생성합니다.
cp .env.example .env생성된 .env 파일 내부에는 프로젝트에서 지원하는 다양한 LLM 공급자의 환경변수 항목이 정의되어 있습니다. 사용할 서비스에 맞춰 발급받은 실제 API 키 값을 입력합니다.
export OPENAI_API_KEY=your_openai_api_key_here
export GOOGLE_API_KEY=your_google_api_key_here
export ANTHROPIC_API_KEY=your_anthropic_api_key_here
export XAI_API_KEY=your_xai_api_key_here
export DEEPSEEK_API_KEY=your_deepseek_api_key_here
export GROQ_API_KEY=your_groq_api_key_here금융 데이터와 거시경제 지표 수집을 위해 제공되는 선택적 외부 데이터 키(예: FRED macro data를 위한 FRED_API_KEY, ALPHA_VANTAGE_API_KEY 등)도 필요에 따라 함께 지정할 수 있습니다.
TradingAgents의 DEFAULT_CONFIG 사전 객체는 TRADINGAGENTS_* 형태의 접두사를 가진 환경변수를 자동으로 감지하여 내부 설정을 재정의합니다. 예를 들어 TRADINGAGENTS_LLM_PROVIDER, TRADINGAGENTS_DEEP_THINK_LLM, TRADINGAGENTS_QUICK_THINK_LLM, TRADINGAGENTS_BACKEND_URL 등을 .env 파일이나 셸에 선언해 두면, 파이썬 스크립트 본문을 직접 수정하지 않고도 공급자 모델이나 백엔드 엔드포인트를 손쉽게 교체할 수 있습니다.
TradingAgentsGraph 최소 실행 스크립트 작성 및 단일 티커 분석 도출
환경 설정이 끝났다면 파이썬 스크립트에서 TradingAgentsGraph 객체를 직접 초기화하여 특정 종목과 기준 날짜를 대상으로 의사결정 파이프라인을 실행할 수 있습니다.
아래 코드는 공식 저장소에서 제공하는 최소 실행 예제로, 엔비디아(NVDA) 종목의 2026년 9월 1일 기준 데이터를 바탕으로 에이전트 전파(propagation) 과정을 거쳐 최종 결정을 출력합니다.
from tradingagents.graph.trading_graph import TradingAgentsGraph
from tradingagents.default_config import DEFAULT_CONFIG
# 설정 복사 및 그래프 객체 초기화
ta = TradingAgentsGraph(debug=True, config=DEFAULT_CONFIG.copy())
# 순방향 전파 실행 (티커 심볼, 기준 날짜)
state, decision = ta.propagate("NVDA", "2026-09-01")
# 최종 의사결정 결과 출력
print(decision)이 스크립트를 올바르게 실행하고 결과를 확인하기 위한 구체적인 절차는 다음과 같습니다.
- 프로젝트 루트 디렉터리에
run_analysis.py파일을 생성하고 위 코드를 저장합니다. - 이전에 활성화한 가상환경(
conda activate tradingagents또는source .venv/bin/activate) 상태에서python run_analysis.py명령을 실행합니다. debug=True옵션이 설정되어 있으므로 터미널 콘솔에 각 분석가 에이전트의 작업 단계, 토론 내용, 위험 관리 검토 과정이 순차적으로 기록됩니다.- 파이프라인이 정상 종료되면 마지막 줄에 포트폴리오 매니저의 최종 포지션 판단이나 권고안이 포함된
decision객체가 출력됩니다.
실행 중 실패가 발생하는 대표적인 원인과 점검 방법은 다음과 같습니다.
- 모듈 임포트 오류(ModuleNotFoundError): 가상환경이 활성화되지 않은 상태이거나
pip install .명령을 프로젝트 루트 디렉터리에서 실행하지 않았을 때 발생합니다. 가상환경 활성화 여부와 현재 경로를 다시 확인합니다. - 인증 실패(AuthenticationError 또는 API Key Missing):
.env파일에 유효한 LLM 공급자 API 키가 설정되지 않았거나 환경변수가 셸 세션에 로드되지 않은 경우입니다. 키 문자열에 오탈자가 없는지 점검해야 합니다. - 네트워크 또는 엔드포인트 도달 오류:
DEFAULT_CONFIG에 명시된 LLM 제공사의 엔드포인트 URL이나 외부 금융 데이터 소스에 방화벽 등으로 접근할 수 없는 경우 발생하므로 로컬 네트워크 연결 상태를 점검합니다.
야후 파이낸스 접미사 지원 티커 규칙과 연구용 프레임워크 주의사항
ta.propagate() 메서드에 넘겨주는 첫 번째 인자는 분석 대상 자산의 티커 심볼입니다. TradingAgents는 야후 파이낸스(Yahoo Finance)가 지원하는 모든 시장의 자산을 분석할 수 있도록 설계되어 있으며, 각 거래소별 접미사(exchange suffix) 표기법을 따릅니다.
종목 입력 시 시장별 기준에 맞춰 알파 벤치마크와 기업 식별 정보가 자동으로 확인됩니다. 지원되는 대표적인 티커 표기 규칙은 다음과 같습니다.
- 미국 시장:
AAPL,SPY등 기본 심볼 사용 - 홍콩 시장:
0700.HK(텐센트 등) - 도쿄 시장:
7203.T(토요타 등) - 런던 시장:
AZN.L(아스트라제네카 등) - 중국 A주: 상하이
600519.SS, 선전.SZ접미사 형식 - 인도 시장:
RELIANCE.NS또는.BO - 캐나다 및 호주: 각각
.TO및.AX - 가상자산:
BTC-USD,ETH-USD등 거래쌍 형식
TradingAgents 프레임워크를 실무에 도입하거나 테스트할 때는 시스템의 본질적인 운영 경계를 명확히 인식해야 합니다. 공식 문서에 따르면 TradingAgents는 순수 학술 및 연구 목적으로만 제공되는 프레임워크이며, 금융·투자 조언을 제공하지 않습니다. 기저 LLM의 종류, 샘플링 온도(temperature), 거래 주기, 외부 데이터 소스의 품질 등 비결정적인 요인에 의해 분석 결과가 크게 달라질 수 있습니다.
또한 이 프레임워크는 실계좌 증권사 브로커리지 시스템과 직접 연동되어 주문을 집행하는 도구가 아닙니다. 리스크 관리 팀과 포트폴리오 매니저가 승인한 주문 제안은 프레임워크 내부의 시뮬레이션 거래소(simulated exchange)로 전달되어 가상 체결되는 구조입니다. 따라서 이 시스템의 분석 결과를 실제 투자나 트레이딩 운영 환경에 적용하려면 별도의 증권사 브로커 API 연동, 철저한 리스크 통제 계층, 독립적인 검증 파이프라인을 별도로 구축해야 합니다.
