The Problem

Financial research teams need a coordinated workflow where multiple specialist LLM agents (fundamental, sentiment, technical) exchange analyses and reach a unified trading decision. Building that orchestration from scratch requires handling data ingestion, agent state, inter‑agent communication, and result persistence – all of which are error‑prone and hard to reproduce.

What This Does

TradingAgents provides a ready‑made multi‑agent framework that mirrors a trading desk. Core agent classes live under tradingagents/agents/ (e.g., fundamentals_analyst.py, market_analyst.py, news_analyst.py). Shared utilities such as agent_utils.py and memory.py manage LLM prompts, embeddings, and situation memories.

Data ingestion is implemented in tradingagents/dataflows/ – modules like alpha_vantage.py, googlenews_utils.py, and y_finance.py fetch market data, news, and fundamentals via external APIs.

The graph engine in tradingagents/graph/ (especially trading_graph.py and setup.py) builds a directed workflow where each agent is a node; the graph drives the sequence of calls and propagates state between agents.

The CLI (cli/main.py) ties everything together, offering an interactive console that steps through the analysis, displays intermediate messages, and writes final reports to results_dir.

How It Is Wired

Execution starts at the analyze function in cli/main.py (line 1104). It creates the results directory, then calls run_analysis (line 738).

  • run_analysis orchestrates the core loop, invoking the graph via setup_graph (from tradingagents/graph/setup.py).
  • setup_graph builds a TradingAgentsGraph instance (defined in tradingagents/graph/trading_graph.py) and registers tool nodes for each agent.
  • The graph’s propagate method walks the node list, calling each agent’s primary method (run or similar) which lives in the analyst and manager modules.

Key downstream calls:

  • Data fetches – e.g., get_indicator → _make_api_request (in tradingagents/dataflows/alpha_vantage_common.py) reach out to external services (Alpha Vantage, Google News, Yahoo Finance).
  • Memory handling – add_situations and get_memories (in tradingagents/agents/utils/memory.py) store and retrieve embeddings, invoking an LLM model via openai.py or google.py.
  • Reporting – update_report_section (in cli/main.py) writes markdown files under the results folder.

The most connected modules are tradingagents/agents/__init__.py (imports 15 others, part of a circular dependency with agent_states.py) and tradingagents/graph/trading_graph.py (imports 11 modules). These hubs have the largest blast radius: a change to their import list or public API can cascade across >10 files.

Two import cycles are present (agents/__init__.py ↔ agents/utils/agent_states.py). They increase cognitive load and risk of runtime import errors; breaking them by moving shared constants to a dedicated module would reduce instability.

How To Use It

# Clone the repository
git clone https://github.com/moses-y/TradingAgents
cd TradingAgents

# Install dependencies (pip is the implied manager)
pip install -r requirements.txt   # or: pip install -e .  (uses setup.py/pyproject.toml)

# Provide required API keys in a .env file based on .env.example
# Example (Alpha Vantage, OpenAI, Google):
#   ALPHAVANTAGE_API_KEY=your_key
#   OPENAI_API_KEY=your_key
#   GOOGLE_API_KEY=your_key

# Run the interactive CLI
python -m cli.main

The CLI walks the user through ticker selection, date range, and displays each agent’s contribution. Results are written to results_dir (created under the current working directory).

Real‑World Use

A quant research team can embed the framework in an automated overnight pipeline: a cron job runs python -m cli.main --ticker=AAPL --start=2024-01-01 --end=2024-01-31. The pipeline captures the generated markdown report, archives it, and feeds the final trading signal into an execution engine. Because agents are modular, a team can replace the risk_manager node with a proprietary model without touching the rest of the graph.

Code Health & Issues

  • High – No test suite – 53 source files, 0 test files. Add at least one test per public entry point and a CI step to run them.
  • High – No CI pipeline – No .github/workflows/ or other CI config. Add a GitHub Actions workflow that runs pip install -e . && pytest on push/PR.
  • Medium – No dependency lockfile – pyproject.toml and requirements.txt are present but no uv.lock or requirements-lock.txt. Enable Dependabot (.github/dependabot.yml) to keep packages up‑to‑date.
  • High – Import cycle – tradingagents/agents/__init__.py ↔ tradingagents/agents/utils/agent_states.py. Break the cycle by extracting shared enums/types to a new module.
  • High – Duplicated analyst code – Repeated 6‑line blocks across the four analyst files. Consolidate common logic into a helper (e.g., agent_utils.py).
  • Medium – File opened without context manager – tradingagents/dataflows/local.py uses raw open(). Switch to with open(...) as f: to guarantee closure.
  • High – Deep nesting – Functions in cli/main.py and several dataflow modules exceed 8 indentation levels, hampering readability. Refactor with early returns or helper functions.

The Bottom Line

TradingAgents delivers a functional multi‑agent LLM trading sandbox with clear module boundaries and a usable CLI, but the codebase suffers from high coupling, duplicated logic, and a lack of automated testing or CI. It is suitable for research prototypes or teams willing to invest in refactoring and test coverage before production use.