TradingAgents/docs/API_REFERENCE.md

TradingAgents Backtest API Reference

Overview

The TradingAgents backtest module provides a comprehensive framework for backtesting trading strategies using the multi-agent LLM system.

Core Classes

TAFlowStrategy

Wrapper class for TradingAgentsGraph to use in backtesting.

from tradingagents.backtest.ta_flow_strategy import TAFlowStrategy

strategy = TAFlowStrategy(config=None, debug=False)

Parameters

• config (dict, optional): Configuration dictionary for TradingAgentsGraph
• debug (bool): Enable debug mode for detailed logging

Methods

decide(ticker: str, date: str) -> str

Get trading decision for a given ticker and date.

Parameters:

• ticker: Stock symbol (e.g., "AAPL")
• date: Date in YYYY-MM-DD format

Returns:

• One of "Buy", "Sell", or "Hold"

Example:

signal = strategy.decide("AAPL", "2024-01-01")
# Returns: "Buy"

BacktestEngine

Main backtest simulation engine.

from tradingagents.backtest.engine import BacktestEngine

engine = BacktestEngine(initial_capital=100000.0)

Parameters

• initial_capital (float): Starting capital for the simulation

Methods

run(ticker, start_date, end_date, strategy, fee_rate=0.001, slippage_rate=0.0005, progress_callback=None) -> BacktestResult

Run the backtest simulation.

Parameters:

• ticker (str): Stock symbol
• start_date (str): Start date (YYYY-MM-DD)
• end_date (str): End date (YYYY-MM-DD)
• strategy (TAFlowStrategy): Strategy object to generate signals
• fee_rate (float): Trading fee as percentage of trade value
• slippage_rate (float): Slippage as percentage of price
• progress_callback (callable, optional): Callback for progress updates

Returns:

• BacktestResult object with all simulation data

Example:

result = engine.run(
    ticker="NVDA",
    start_date="2024-01-01",
    end_date="2024-03-31",
    strategy=strategy,
    fee_rate=0.001,
    slippage_rate=0.0005
)

BacktestResult

Data class containing complete backtest results.

Attributes

• ticker (str): Stock symbol
• start_date (str): Backtest start date
• end_date (str): Backtest end date
• initial_capital (float): Starting capital
• final_capital (float): Ending capital
• trades (List[Trade]): List of all trades executed
• equity_curve (List[float]): Daily portfolio values
• daily_returns (List[float]): Daily return percentages
• metrics (PerformanceMetrics): Strategy performance metrics
• buy_hold_metrics (PerformanceMetrics): Buy & hold comparison metrics
• dates (List[str]): Trading dates

PerformanceMetrics

Container for all performance metrics.

Attributes

• total_return (float): Cumulative return
• annual_return (float): Annualized return
• sharpe_ratio (float): Sharpe ratio (risk-free rate = 0)
• max_drawdown (float): Maximum drawdown percentage
• max_drawdown_duration (int): Max drawdown duration in days
• win_rate (float): Percentage of winning trades
• profit_factor (float): Total profits / Total losses
• total_trades (int): Total number of trades
• volatility (float): Annualized volatility

BacktestRepository

Repository for storing and retrieving backtest results.

from tradingagents.backtest.persistence import BacktestRepository

repository = BacktestRepository(db_path="results.sqlite")

Methods

save_backtest(result: BacktestResult, config: dict) -> int

Save backtest result to database.

Returns:

• ID of saved backtest

get_backtest(backtest_id: int) -> dict

Retrieve backtest by ID.

list_backtests(ticker=None, start_date=None, end_date=None, limit=100) -> List[BacktestSummary]

List backtests with optional filters.

ReportManager

Manage HTML report generation and storage.

from tradingagents.backtest.output import ReportManager

manager = ReportManager(reports_dir="reports/")

Methods

save_report(result: BacktestResult, ticker: str, start_date: str, end_date: str) -> Path

Generate and save HTML report.

Returns:

• Path to saved report

Complete Example

from tradingagents.backtest.ta_flow_strategy import TAFlowStrategy
from tradingagents.backtest.engine import BacktestEngine
from tradingagents.backtest.persistence import BacktestRepository
from tradingagents.backtest.output import ReportManager, TerminalReporter
from tradingagents.default_config import DEFAULT_CONFIG

# Configure strategy
config = DEFAULT_CONFIG.copy()
config["online_tools"] = False  # Force offline mode
config["max_debate_rounds"] = 1  # Reduce for faster testing

# Initialize components
strategy = TAFlowStrategy(config=config, debug=True)
engine = BacktestEngine(initial_capital=100000)

# Run backtest
result = engine.run(
    ticker="AAPL",
    start_date="2024-01-01",
    end_date="2024-03-31",
    strategy=strategy,
    fee_rate=0.001,
    slippage_rate=0.0005
)

# Display results
reporter = TerminalReporter()
reporter.display_summary(result.metrics, result.buy_hold_metrics)

# Save to database
repository = BacktestRepository()
backtest_id = repository.save_backtest(result, config)
print(f"Saved with ID: {backtest_id}")

# Generate HTML report
manager = ReportManager()
report_path = manager.save_report(result, "AAPL", "2024-01-01", "2024-03-31")
print(f"Report saved to: {report_path}")

Configuration Options

Strategy Configuration

config = {
    "online_tools": False,  # Always False for backtesting
    "deep_think_llm": "gpt-4",  # LLM for complex decisions
    "quick_think_llm": "gpt-4o-mini",  # LLM for quick decisions
    "max_debate_rounds": 3,  # Number of debate rounds
    "llm_provider": "openai",  # LLM provider
    "backend_url": None,  # Custom backend URL
}

Position Management Rules

The backtest engine follows these position management rules:

1. No Position → Buy Signal: Open long position
2. No Position → Sell Signal: Open short position
3. Long Position → Sell Signal: Close long, open short
4. Short Position → Buy Signal: Close short, open long
5. Any Position → Hold Signal: Maintain current position

Fee and Slippage Calculation

• Buy Price: market_price × (1 + slippage_rate)
• Sell Price: market_price × (1 - slippage_rate)
• Trading Fee: trade_value × fee_rate

Error Handling

The system includes comprehensive error handling:

• Strategy Errors: Return "Hold" signal on error
• Data Errors: Raise ValueError with descriptive message
• Persistence Errors: Log error and re-raise

Performance Considerations

• LLM Calls: Each trading day requires one LLM call
• Caching: Use offline mode to leverage cached data
• Batch Processing: Process multiple tickers sequentially
• Memory: Results are stored in memory during simulation

Extending the Framework

Custom Strategy

class CustomStrategy:
    def decide(self, ticker: str, date: str) -> str:
        # Your logic here
        return "Buy"  # or "Sell" or "Hold"

# Use with BacktestEngine
engine = BacktestEngine()
result = engine.run(ticker="AAPL", strategy=CustomStrategy(), ...)

Custom Metrics

from tradingagents.backtest.metrics import MetricsCalculator

class CustomMetricsCalculator(MetricsCalculator):
    def calculate(self, equity_curve, trades, initial_capital, start_date, end_date):
        metrics = super().calculate(...)
        # Add custom calculations
        metrics.custom_metric = self._calculate_custom_metric(...)
        return metrics