TradingAgents/docs/api-reference.md

TradingAgents API Reference

This document provides comprehensive API documentation for the TradingAgents framework.

Core Classes

TradingAgentsGraph

Main orchestrator class for running trading analysis workflows.

from tradingagents.graph.trading_graph import TradingAgentsGraph
from tradingagents.config import TradingAgentsConfig

# Initialize with default configuration
ta = TradingAgentsGraph(debug=True, config=TradingAgentsConfig.from_env())

# Run analysis for a specific stock and date
result, decision = ta.propagate("AAPL", "2024-01-15")

Methods:

• propagate(symbol: str, date: str) -> tuple[dict, str]: Execute full trading analysis workflow
• get_memory(): Access the vector memory system for past decisions

TradingAgentsConfig

Configuration management class with environment variable support.

from tradingagents.config import TradingAgentsConfig

# Create from environment variables
config = TradingAgentsConfig.from_env()

# Create with custom values
config = TradingAgentsConfig(
    llm_provider="anthropic",
    deep_think_llm="claude-3-5-sonnet-latest",
    max_debate_rounds=3,
    online_tools=True
)

Configuration Options:

Parameter	Type	Default	Environment Variable	Description
project_dir	str	Current directory	TRADINGAGENTS_PROJECT_DIR	Base project directory
results_dir	str	"./results"	TRADINGAGENTS_RESULTS_DIR	Output directory for analysis results
data_dir	str	"/Users/yluo/Documents/Code/ScAI/FR1-data"	TRADINGAGENTS_DATA_DIR	Directory for local data storage
llm_provider	Literal	"openai"	LLM_PROVIDER	LLM provider (openai, anthropic, google, ollama, openrouter)
deep_think_llm	str	"o4-mini"	DEEP_THINK_LLM	Model for complex reasoning tasks
quick_think_llm	str	"gpt-4o-mini"	QUICK_THINK_LLM	Model for fast responses
backend_url	str	"https://api.openai.com/v1"	BACKEND_URL	API endpoint for LLM providers
max_debate_rounds	int	1	MAX_DEBATE_ROUNDS	Maximum rounds in investment debates
max_risk_discuss_rounds	int	1	MAX_RISK_DISCUSS_ROUNDS	Maximum rounds in risk discussions
max_recur_limit	int	100	MAX_RECUR_LIMIT	Maximum recursion depth for workflows
online_tools	bool	True	ONLINE_TOOLS	Enable live API calls vs cached data
default_lookback_days	int	30	DEFAULT_LOOKBACK_DAYS	Historical data range for analysis
default_ta_lookback_days	int	30	DEFAULT_TA_LOOKBACK_DAYS	Technical analysis data range

Domain Services

MarketDataService

Provides market data and technical analysis.

from tradingagents.domains.marketdata.market_data_service import MarketDataService

service = MarketDataService.build(config)

# Get market data context
context = service.get_market_data_context("AAPL", "2024-01-01", "2024-01-31")
print(f"Latest price: ${context.latest_price}")
print(f"Price change: {context.price_change_percent}%")

# Update market data
service.update_market_data("AAPL", "2024-01-01", "2024-01-31")

Methods:

• get_market_data_context(symbol, start_date, end_date) -> PriceDataContext: Get price and volume data
• get_ta_report(symbol, start_date, end_date) -> TAReportContext: Get technical analysis indicators
• update_market_data(symbol, start_date, end_date): Fetch and cache fresh market data

NewsService

Provides news analysis and sentiment scoring.

from tradingagents.domains.news.news_service import NewsService

service = NewsService.build(config)

# Get stock-specific news
context = service.get_news_context("AAPL", "2024-01-01", "2024-01-31")
print(f"Articles found: {context.article_count}")
print(f"Overall sentiment: {context.sentiment_summary.label}")

# Get global news context
global_context = service.get_global_news_context("2024-01-15")

Methods:

• get_news_context(symbol, start_date, end_date) -> NewsContext: Get stock-specific news
• get_global_news_context(date) -> GlobalNewsContext: Get general market news
• update_news(symbol, start_date, end_date): Fetch and cache fresh news articles

SocialMediaService

Provides social media sentiment analysis.

from tradingagents.domains.socialmedia.social_media_service import SocialMediaService

service = SocialMediaService.build(config)

# Get social media sentiment
context = service.get_socialmedia_stock_info("AAPL", "2024-01-15")
print(f"Posts analyzed: {context.post_count}")
print(f"Sentiment score: {context.sentiment_summary.score}")

Methods:

• get_socialmedia_stock_info(symbol, date) -> StockSocialContext: Get social media analysis
• update_socialmedia_data(symbol, date): Fetch and cache fresh social media data

FundamentalDataService

Provides financial statements and fundamental analysis.

from tradingagents.domains.marketdata.fundamental_data_service import FundamentalDataService

service = FundamentalDataService.build(config)

# Get financial statements
income_stmt = service.get_income_statement_context("AAPL", "2024-01-15")
balance_sheet = service.get_balance_sheet_context("AAPL", "2024-01-15")
cash_flow = service.get_cash_flow_context("AAPL", "2024-01-15")

Methods:

• get_income_statement_context(symbol, date) -> IncomeStatementContext: Get income statement data
• get_balance_sheet_context(symbol, date) -> BalanceSheetContext: Get balance sheet data
• get_cash_flow_context(symbol, date) -> CashFlowContext: Get cash flow data

InsiderDataService

Provides insider trading data and sentiment analysis.

from tradingagents.domains.marketdata.insider_data_service import InsiderDataService

service = InsiderDataService.build(config)

# Get insider transactions
transactions = service.get_insider_transaction_context("AAPL", "2024-01-01", "2024-01-31")
sentiment = service.get_insider_sentiment_context("AAPL", "2024-01-15")

Methods:

• get_insider_transaction_context(symbol, start_date, end_date) -> InsiderTransactionContext: Get insider trading data
• get_insider_sentiment_context(symbol, date) -> InsiderSentimentContext: Get insider sentiment analysis

AgentToolkit (Anti-Corruption Layer)

The AgentToolkit mediates between agents and domain services, providing LangChain tool decorators.

from tradingagents.agents.libs.agent_toolkit import AgentToolkit

# AgentToolkit is injected into agents automatically
# Provides @tool decorated methods for LangChain agent consumption

# Available tools:
# - get_market_data(symbol, start_date, end_date)
# - get_ta_report(symbol, start_date, end_date) 
# - get_news(symbol, start_date, end_date)
# - get_global_news(date)
# - get_socialmedia_stock_info(symbol, date)
# - get_income_statement(symbol, date)
# - get_balance_sheet(symbol, date)
# - get_cash_flow_statement(symbol, date)
# - get_insider_transactions(symbol, start_date, end_date)
# - get_insider_sentiment(symbol, date)

Context Models

PriceDataContext

Market data context returned by MarketDataService.

@dataclass
class PriceDataContext:
    symbol: str
    start_date: str
    end_date: str
    price_data: list[dict]
    latest_price: float
    price_change_percent: float
    volume_data: list[dict]
    metadata: dict[str, Any]

TAReportContext

Technical analysis context with indicators.

@dataclass 
class TAReportContext:
    symbol: str
    start_date: str
    end_date: str
    indicators: dict[str, Any]
    signals: list[str]
    metadata: dict[str, Any]

NewsContext

News analysis context with sentiment scoring.

@dataclass
class NewsContext:
    symbol: str
    start_date: str
    end_date: str
    articles: list[NewsArticle]
    article_count: int
    sentiment_summary: SentimentScore
    metadata: dict[str, Any]

StockSocialContext

Social media analysis context.

@dataclass
class StockSocialContext:
    symbol: str
    date: str
    posts: list[PostData]
    post_count: int
    sentiment_summary: SentimentScore
    engagement_metrics: EngagementMetrics
    metadata: dict[str, Any]

Error Handling

All services implement consistent error handling patterns:

try:
    context = service.get_market_data_context("AAPL", "2024-01-01", "2024-01-31")
except ServiceException as e:
    # Service-level errors (API failures, data validation)
    logger.error(f"Service error: {e}")
except ClientException as e:
    # Client-level errors (network, authentication)
    logger.error(f"Client error: {e}")
except RepositoryException as e:
    # Repository-level errors (file I/O, cache corruption)
    logger.error(f"Repository error: {e}")

Multi-LLM Provider Support

OpenAI Configuration

export LLM_PROVIDER="openai"
export OPENAI_API_KEY="your_openai_api_key"
export DEEP_THINK_LLM="gpt-4"
export QUICK_THINK_LLM="gpt-4o-mini"
export BACKEND_URL="https://api.openai.com/v1"

Anthropic Configuration

export LLM_PROVIDER="anthropic"
export ANTHROPIC_API_KEY="your_anthropic_api_key"
export DEEP_THINK_LLM="claude-3-5-sonnet-latest"
export QUICK_THINK_LLM="claude-3-haiku-latest"
export BACKEND_URL="https://api.anthropic.com"

Google Configuration

export LLM_PROVIDER="google"
export GOOGLE_API_KEY="your_google_api_key"
export DEEP_THINK_LLM="gemini-1.5-pro"
export QUICK_THINK_LLM="gemini-1.5-flash"
export BACKEND_URL="https://generativelanguage.googleapis.com"

Memory System

The framework includes a ChromaDB-based vector memory system for learning from past decisions.

# Memory is automatically managed by TradingAgentsGraph
graph = TradingAgentsGraph(debug=True, config=config)

# Access memory directly if needed
memory = graph.get_memory()
similar_situations = memory.search("AAPL analysis", k=5)

Memory Features:

• Automatic storage of decision contexts and outcomes
• Vector similarity search for similar market situations
• Learning from historical performance to improve future decisions
• Configurable retention policies

Best Practices

Service Usage Patterns

# Always read from repository first (cached data)
context = service.get_context(symbol, start_date, end_date)

# Use separate update operations for fresh data
if context.metadata.get("data_quality") == "LOW":
    service.update_data(symbol, start_date, end_date)
    context = service.get_context(symbol, start_date, end_date)

Error Resilience

# Services return contexts with quality metadata
context = service.get_market_data_context("AAPL", "2024-01-01", "2024-01-31")

if context.metadata.get("data_quality") == "HIGH":
    # Use data confidently
    latest_price = context.latest_price
else:
    # Handle degraded data quality
    logger.warning("Using cached/partial data due to API issues")

Configuration Management

# Use environment-based configuration for different environments
config = TradingAgentsConfig.from_env()

# Override specific settings for testing
test_config = config.copy()
test_config.online_tools = False  # Use cached data only
test_config.max_debate_rounds = 1  # Speed up tests