Open-Source Research Framework
TradingAgents Tutorial: Architecture, Setup, and Honest Judging
Educational content, not financial advice. TradingAgents itself is a research tool, not a brokerage or a trading signal.
TradingAgents is an open-source project from Tauric Research that assigns different large language model agents to the roles of a trading firm: analysts, researchers who debate each other, a trader, and a risk and portfolio management team. It has drawn a large amount of attention on GitHub and is described in an accompanying research paper. This tutorial walks through what the project actually does, based on its own GitHub README and its arXiv paper, how its agent roles and backtesting tool work, and how to judge any result it produces honestly rather than being impressed by how convincing the agents sound.
TradingAgents is an open-source, Apache-licensed multi-agent framework, built with LangGraph, that assigns large language models to roles modeled on a trading firm: analysts, bullish and bearish researchers who debate their findings, a trader who turns the debate into a decision, and a risk team plus a portfolio manager who approve or reject it. Approved decisions go to what the project calls a simulated exchange, not a real brokerage, so every run is a research exercise by design. It ships a backtesting tool scored against a regional benchmark, and its README states plainly it is built for research, not financial advice, with results not guaranteed to match any published figure.
Published
Free lesson · no account neededMeet ClaudeWhy Claude?6 minStart the free lessonKey Takeaways
- TradingAgents, from Tauric Research, is open source under the Apache 2.0 license and is built on LangGraph. Its own README states it is designed for research purposes and is not intended as financial, investment, or trading advice.
- Its agent roles mirror a trading firm: four parallel analysts, a bull and bear researcher team that debates their findings, a trader who turns that into a decision, and a risk team plus portfolio manager who approve or reject it.
- Approved decisions go to a simulated exchange, not a real brokerage. The README documents no live-trading integration, so running TradingAgents at all is inherently a research and paper exercise, not a path to live execution on its own.
- The project's backtesting tool scores historical decisions by realized alpha against a regional benchmark, but its README does not describe that scoring as accounting for trading commissions or slippage, which matters for judging the result honestly.
- The README is explicit that two runs of the same ticker and date can produce different decisions, because language model sampling is non-deterministic. A single backtest run, or a single convincing debate transcript, proves very little on its own.
- The paper reports testing against baseline approaches on cumulative return, Sharpe ratio, and max drawdown, with favorable results. That is the paper's own result, not an independent check, and the README says backtests won't necessarily reproduce any published number.
Copy and Paste
Prompts You Can Use Today
Interrogate a TradingAgents decision log before trusting it
I ran TradingAgents on a ticker and date and I'm pasting its decision report below, including the analyst summaries, the bull and bear debate, and the final trader and risk management reasoning. Read through it and tell me which specific claims in the report are backed by a cited data point versus which ones are the agents' own interpretation or prediction with no underlying figure attached. I want to know how much of this decision is actual evidence versus persuasive-sounding argument. Report: [paste].
This separates what the pipeline actually found from how confidently it narrated the finding, which are not the same thing.
Design an honest evaluation plan for a backtest grid
I'm about to run TradingAgents' backtest function over a grid of tickers and dates. Help me design an honest evaluation plan before I look at any results: how I should split the date range into a tuning period and a genuinely held-out out-of-sample period, how many runs I should do given that the underlying model is non-deterministic, and what I should check about whether the realized-alpha scoring accounts for trading costs before I draw any conclusion from the numbers.
Write this plan before running the backtest, not after, so the plan isn't quietly adjusted to fit a result you already like.
Explain the difference between agent debate and statistical edge
Explain, in plain language, why a multi-agent system where bullish and bearish researchers debate each other convincingly is not the same thing as evidence of a real, repeatable trading edge. Use a concrete hypothetical example of a confident-sounding debate transcript that could just as easily accompany a strategy with no edge at all, and tell me what kind of evidence, instead of argument quality, would actually distinguish the two cases.
This is the single most important mental model for evaluating any multi-agent trading framework, not just this one.
What It Is
TradingAgents, in Plain Terms
TradingAgents is an open-source multi-agent framework published by Tauric Research. According to its GitHub README, it is built with LangGraph and is designed to mirror the dynamics of a real trading firm: instead of one model doing everything, specialized agents handle research, debate, trade decisions, and risk review, and the framework coordinates how their outputs flow into a final decision.
It supports a wide range of large language model providers, including OpenAI, Google, Anthropic's Claude, xAI, and several others, plus a documented option to run on your own ChatGPT Plus or Pro subscription instead of a metered API key. That range of supported providers is one reason it has spread quickly: nothing about the framework ties a user to one specific model vendor.
The project is accompanied by a research paper on arXiv, titled "TradingAgents: Multi-Agents LLM Financial Trading Framework," by Yijia Xiao, Edward Sun, Di Luo, and Wei Wang, which the README cites directly. The paper frames the open research question this way: earlier work on using language models for finance tended to use either a single agent or a multi-agent setup limited to gathering data, leaving open whether a multi-agent system could actually copy how real trading desks debate and decide together. TradingAgents is the authors' answer to that question, implemented as runnable, open-source code rather than only a paper.
It is worth being direct about what TradingAgents is not. It is not a brokerage, it does not place real trades on its own, and its own README states plainly that it is designed for research purposes and is not intended as financial, investment, or trading advice. Nothing in this tutorial changes that, and nothing here recommends using it, or any strategy it produces, with real money.
The Architecture
Four Teams, Modeled on a Trading Firm
Per the project's own README, each team hands its output to the next.
Analyst team
A fundamentals analyst, a sentiment analyst reading news headlines and social chatter, a news analyst tracking macro events, and a technical analyst using indicators like MACD and RSI. They run at the same time, and the debate stage starts only once every report is in.
Researcher team
Bullish and bearish researchers debate the analyst reports against each other, weighing potential gains against risk before anything reaches a trade decision.
Trader agent
Composes the analyst and researcher output into an actual decision: whether to act, and the timing and size of the trade being proposed.
Risk management and portfolio manager
A risk team assesses volatility, liquidity, and other factors and reports to a portfolio manager, who approves or rejects the proposal. An approved order goes to what the README calls a simulated exchange, not a live brokerage.
Running It
Setup and the Shape of a Run
Per its README, TradingAgents needs Python 3.11 or later, installs with a standard pip install from a cloned copy of the repository, and can also run through Docker. It ships both an interactive command-line interface, which walks through choosing tickers, an analysis date, a provider, and research depth, and a Python interface where a TradingAgentsGraph object exposes a propagate method that returns a decision for a given ticker and date, along with the full report tree behind it.
A single run reads company fundamentals, news, and social sentiment up to the analysis date, runs the analyst and researcher stages, and produces a decision along with a saved report. The README also documents a persistent memory log: every completed run's decision is appended to a log on disk, and later runs read back recent decisions and a short reflection on how earlier ones played out, so the system is explicitly designed to carry some memory across separate runs rather than starting from nothing each time.
On data integrity specifically, the README describes a point-in-time design for US company fundamentals pulled from SEC filings: a run dated in the past sees the financial figures exactly as they stood on that date, including a figure that was later restated, rather than today's updated version. That is a genuinely useful property for anyone trying to avoid lookahead bias in a historical test, and it is worth checking the same logic against whatever market and data vendor you're actually testing with, since the README notes that not every data source it uses carries the same point-in-time guarantee.
Backtesting and Simulation
Why Running TradingAgents Is Inherently a Paper Exercise
It's worth being precise about a detail the project's name and architecture can obscure: TradingAgents does not document a live brokerage connection anywhere in its README. Every approved decision in the pipeline goes to what the project calls a simulated exchange. There is no separate switch described for "paper mode" versus "live mode," because the entire framework, as published, only ever simulates the trade. Treat that as the honest starting point: using TradingAgents at all is a research and paper-trading exercise unless you build a real brokerage connection yourself, which is a substantial and separate undertaking with its own risks.
The README also documents a dedicated backtesting function that runs the same pipeline across a grid of tickers and dates, generating a decision for each combination and scoring it once enough time has passed for the position to have traded. Scoring is based on realized alpha against each instrument's regional benchmark, and a decision is entered at the first closing price after its date, since the README notes that a run reads news published after that day's close.
Two details are worth checking carefully before trusting any number this produces. First, the README does not describe the backtest scoring as netting out trading commissions or slippage the way a serious backtest for a real strategy should, which was the central lesson of the companion guide on this site about building a trading bot from scratch. Until you've confirmed otherwise by reading the actual scoring code, treat any realized-alpha figure from this tool as a before-costs number. Second, the README states outright that backtest results are not guaranteed to match any published figure, and names the model, the temperature, the date range, and data quality as specific sources of variation. That is the project's own caution, not a criticism invented for this tutorial.
A Property Worth Understanding
The Same Run Can Give You a Different Answer
TradingAgents' README is unusually direct about reproducibility: because the framework is driven by language models, two runs of the same ticker and the same date can produce different decisions, and the README calls this expected behavior for a research tool built on language models, not a defect to be embarrassed about.
It names two separate sources for that variation. Language model sampling is inherently non-deterministic, even at a fixed temperature setting, and reasoning-heavy models vary the most because their internal reasoning process is itself sampled. Separately, live data changes over time: news, social posts, and sentiment sources return different content today than they did last week, even when the historical trade date being analyzed stays the same. Pinning the analysis date holds the price and indicator window fixed, but the social and news inputs still reflect whatever is current when the run actually happens.
The practical implication for anyone trying to evaluate this framework honestly is that a single run, or a single backtest pass, tells you very little. The README's own suggestion for tighter reproducibility is lowering the sampling temperature and naming a non-reasoning model, since the curated reasoning-first models it defaults to largely ignore temperature settings. Even then, variation from live data sources remains a factor outside anyone's control.
Judging It Honestly
What Separates a Real Signal From a Convincing Debate
Four checks matter more than how persuasive any single run's agent debate reads.
The backtest window
A grid run over a short or cherry-picked date range tells you little. Use a window long enough to cross different market conditions, and be honest if you kept adjusting the window until the result looked better.
Costs that may not be modeled
Confirm whether the realized-alpha scoring you're looking at accounts for trading costs at all before treating it as a tradeable number rather than a before-costs estimate.
Genuine out-of-sample data
If you tune a model choice, a provider, or an analyst selection against one date range, test the final configuration on a separate range you never touched during tuning, the same discipline that applies to any backtested trading rule.
Agents arguing is not an edge
A bull and bear researcher debate that reads as thorough and well-reasoned describes how convincingly the system argues, not whether the underlying call was actually right. Only the out-of-sample numbers answer that.
The Paper
What the Research Behind It Actually Claims
The arXiv paper behind TradingAgents describes the same role structure as the README: analyst, researcher, trader, and risk-manager agents, with bullish and bearish researchers debating market conditions before a decision is finalized. Its authors report experiments comparing the framework's trading decisions against baseline models on cumulative return, Sharpe ratio, and maximum drawdown, and describe their results as favoring the multi-agent approach in those tests.
Two caveats are worth keeping side by side with that claim. First, it's the authors' own reported result from their own experimental setup, not an independent replication, and this tutorial is not citing any specific number from it because the project's own README separately states that backtest results are not guaranteed to match any published figure. Second, a paper reporting a favorable comparison against baseline models in one evaluation period is evidence worth taking seriously, but it is not a guarantee about how the same approach performs going forward, on a market or a data provider the original study did not test, or inside a setup with live trading costs attached.
The honest way to use the paper is as a starting hypothesis, not a settled conclusion: multi-agent debate structured the way TradingAgents implements it is a plausible way to organize financial analysis, worth testing carefully on your own terms, rather than a result to take on faith because a credible-looking paper exists behind the code.
Evaluating a Framework Like This Is a Research Skill
Reading a project's own documentation closely, separating what it claims from what it actually demonstrates, and checking a result before trusting it are exactly the habits Nightschool AI's free lesson on research and critical thinking with Claude or ChatGPT is built around.
Frequently Asked Questions
Is TradingAgents affiliated with Anthropic or Claude?
No. TradingAgents is an independent open-source project from Tauric Research that happens to support many large language model providers, including Anthropic's Claude, OpenAI, Google, and others. Supporting a provider as an option is not an affiliation or endorsement in either direction.
Does TradingAgents place real trades?
Its README describes approved decisions going to a simulated exchange, with no documented live brokerage integration. Using the project as published is a research and paper-trading exercise, not a path to live execution on its own.
Is TradingAgents free and open source?
Yes. It is published under the Apache 2.0 license on GitHub, which permits free use, modification, and redistribution under that license's terms.
Can I trust a backtest result from TradingAgents?
Treat any single result cautiously. The project's own README states that two runs of the same ticker and date can differ because of how language models sample, and that backtest results are not guaranteed to match any published figure. Run a wide, genuinely out-of-sample test before drawing any conclusion.
Does TradingAgents' backtest account for trading costs?
Its README describes scoring by realized alpha against a regional benchmark, without describing that scoring as netting out commissions or slippage. Treat its backtest numbers as a before-costs estimate unless you confirm otherwise by reading the project's own code.
What does the bull versus bear researcher debate actually do?
Per the README, bullish and bearish researchers review the analyst team's reports and debate the case for and against a position before the trader agent turns that debate into a decision. It is a structured way of weighing a position's upside against its risk, not a vote that guarantees the better argument reflects reality.
Why does TradingAgents give different results each time I run it?
Its README explains this directly: language model sampling is inherently non-deterministic, reasoning-focused models vary the most, and live news and social data sources return different content as time passes even for the same historical date. The project calls this expected, not a defect.
What does the research paper behind TradingAgents claim?
The accompanying arXiv paper reports experiments comparing the framework's decisions against baseline models on cumulative return, Sharpe ratio, and maximum drawdown, with results its authors describe as favoring their approach. That is the authors' own reported result in their own evaluation, not an independent, ongoing guarantee of performance.
Do I need a paid API key to run TradingAgents?
Its README documents several options: API keys for various providers, a documented path to run on your own ChatGPT Plus or Pro subscription instead, and support for local models through Ollama. Costs and requirements depend entirely on which provider you choose.
Read the Documentation Before You Trust the Demo
The same habit that makes any AI research tool worth using.