Noureddine RAMDI / TradingAgents: a multi-agent LLM framework simulating real-world trading firm dynamics

Created Sat, 02 May 2026 07:48:10 +0000 Modified Sat, 23 May 2026 20:41:27 +0000
937 Words
github-stars python llm multi-agent trading langgraph financial-ai

TauricResearch/TradingAgents

TradingAgents is a Python framework that models the decision-making process of a trading firm using multiple specialized large language model (LLM) agents. Instead of relying on a single AI model to analyze market data, this repo decomposes trading analysis into distinct roles handled by dedicated agents — fundamental, sentiment, news, and technical analysts — which then feed into a researcher team that debates market outlooks from bullish and bearish perspectives. This layering mimics real-world trading desks, where teams challenge each other’s views before executing trades.

Architecture and core functionality of TradingAgents

At its core, TradingAgents is built on top of LangGraph, a framework for orchestrating state machines and managing persistent memory across agents. This enables the system to maintain decision logs, inject reflections automatically, and resume from checkpoints — features critical for iterative reasoning and auditability in trading decisions.

The architecture divides the trading workflow into several agent roles:

  • Analyst agents: These specialize in different data dimensions — fundamental, sentiment, news, and technical analysis — each producing detailed insights.
  • Researcher agents: Organized into bull and bear teams, they conduct structured debates on the market outlook, critically assessing the analyst insights to reduce hallucination and improve reasoning quality.
  • Trader agent: Synthesizes the conclusions from the researchers and makes trade decisions.
  • Risk Management and Portfolio Manager agents: Evaluate and approve trades based on risk profiles and portfolio constraints.

The system supports more than 10 LLM providers, including OpenAI, Google Gemini, Anthropic Claude, xAI Grok, DeepSeek, Qwen, GLM, OpenRouter, Ollama, and Azure. This flexibility allows users to configure reasoning models for tasks requiring deep thought or quick responses.

Persistent decision memory with reflection injection helps the agents learn and improve from past errors or insights, a mechanism that enhances long-term performance.

The structured bull/bear researcher debate: a technique for reducing hallucination and improving decision quality

One of the most interesting technical design choices is the structured debate pattern implemented by the researcher agents. Instead of a monolithic AI making all decisions, opposing teams of agents take on bull and bear perspectives, critically challenging each other’s interpretations of analyst data.

This mirrors real-world trading floors where teams debate market directions to uncover biases and blind spots. By doing so, the system promotes rigorous reasoning and helps prevent the AI from making unfounded assumptions or hallucinated conclusions.

The tradeoff here is complexity: coordinating multiple agents with different roles and managing their interactions requires careful orchestration, which TradingAgents handles through LangGraph state machines. The persistence and checkpointing features also add overhead but are necessary to maintain consistency and enable resumability.

The codebase is surprisingly clean for such a complex multi-agent system, with clear role definitions and modular components. However, users should be prepared for the learning curve involved in understanding and extending this layered architecture.

Quick start with TradingAgents

To get started with TradingAgents, the README provides clear instructions to clone the repo, set up a Python 3.13 virtual environment using conda, and install the package:

git clone https://github.com/TauricResearch/TradingAgents.git
cd TradingAgents
conda create -n tradingagents python=3.13
conda activate tradingagents
pip install .

Alternatively, users can run the project using Docker Compose. After copying the .env.example file and adding their API keys, they can execute:

cp .env.example .env  # add your API keys
docker compose run --rm tradingagents

For those using local models with Ollama, a dedicated Docker profile is available:

docker compose --profile ollama run --rm tradingagents-ollama

The framework requires API keys for supported LLM providers, which can be set as environment variables. For example, to use OpenAI GPT:

export OPENAI_API_KEY=...

The interactive CLI launches with:

tradingagents

or by running the source directly:

python -m cli.main

The CLI lets you select tickers, analysis dates, LLM providers, and configure research depth. It displays live progress of the agents’ analyses, giving insight into the multi-agent reasoning at work.

verdict: who should explore TradingAgents

TradingAgents is a solid choice for developers and researchers interested in multi-agent AI systems, particularly those focused on financial markets and decision support. The structured bull/bear debate pattern is a thoughtful design to improve reliability of LLM reasoning by mimicking human trading processes.

That said, the system introduces complexity in multi-agent coordination and state management that may be overkill for simpler use cases. It depends heavily on external LLM APIs, which means API costs and rate limits can be a bottleneck in production.

If you want to experiment with specialized agent roles, persistent memory with reflection, and a robust multi-LLM provider setup, TradingAgents offers a practical, well-documented starting point. It’s less suitable if you need a plug-and-play trading bot or are wary of managing multiple API keys and environment configurations.

The code is well-structured enough to serve as a reference for building your own multi-agent LLM frameworks that require complex role specialization and debate-style reasoning.

→ GitHub Repo: TauricResearch/TradingAgents ⭐ 60,270 · Python