TradingAgents User Guide

TradingAgents is a multi-agent, LLM-powered financial trading research framework. It mirrors the structure of a real trading firm: a team of specialized AI analysts gathers market, news, sentiment, and fundamentals data; bullish and bearish researchers debate the findings; a trader drafts a transaction; a risk-management team stress-tests it; and a portfolio manager issues the final Buy / Overweight / Hold / Underweight / Sell decision. You drive the whole pipeline from an interactive command-line interface, or call it directly from Python.

Important

TradingAgents is a research framework, not investment advice. Outputs depend on the chosen language models, sampling temperature, data quality, and other non-deterministic factors. It does not place real orders. See Tauric Research's disclaimer. Treat every decision it produces as a research artifact to study, not a trade to execute.

This guide covers everything you need to install, configure, and run TradingAgents, plus how to read its output, switch language-model providers, analyze non-US and crypto markets, and resume interrupted runs.

1. Quick Start

Get from zero to a completed analysis in four steps.

# 1. Clone and enter the project
git clone https://github.com/TauricResearch/TradingAgents.git
cd TradingAgents

# 2. Create an environment and install
conda create -n tradingagents python=3.13
conda activate tradingagents
pip install .

# 3. Provide at least one LLM provider key and a market-data key
export OPENAI_API_KEY=sk-...
# (Yahoo Finance is the default data source and needs no key)

# 4. Launch the interactive CLI
tradingagents

The CLI then walks you through eight prompts (ticker, date, language, analyst team, research depth, provider, models, thinking mode) and streams a live dashboard as the agents work.

Tip

If you do not have a key for a provider when you start, the CLI detects this and prompts you to paste one mid-run, saving it to a local .env file so the analysis continues without a restart. You never have to abort just because a key was missing.

Note

Requires Python 3.10 or newer (the project's own development environment uses 3.13). The installed console command is tradingagents; you can also run the CLI directly from a source checkout with python -m cli.main.

2. Installation

2.1 Requirements

2.2 Install from source

conda

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

venv

git clone https://github.com/TauricResearch/TradingAgents.git
cd TradingAgents
python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install .

Installing the package registers the tradingagents console command (defined in pyproject.toml as cli.main:app).

2.3 Install and run with Docker

The repository ships a multi-stage Dockerfile and a docker-compose.yml.

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

To run against a local Ollama model inside Docker, use the ollama profile, which also starts an Ollama container:

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

Note

The container writes runtime data (cache, logs, decision memory) to /home/appuser/.tradingagents, which docker-compose.yml maps to a named volume (tradingagents_data) so your decision log and price cache survive across runs.

Tip

The Compose service runs with tty: true and stdin_open: true because the CLI is interactive. Keep those settings if you customize the file, or the questionnaire prompts will not work.

2.4 Verify the install

tradingagents --help

Usage: tradingagents [OPTIONS] COMMAND [ARGS]...

  TradingAgents CLI: Multi-Agents LLM Financial Trading Framework

3. Providing API Keys

TradingAgents needs two kinds of credentials: a language-model key (at least one provider) and, optionally, a market-data key (Alpha Vantage). Yahoo Finance is the default data source and needs no key.

3.1 The .env file

Copy the template and fill in the providers you use. You only need a key for the provider you actually select.

cp .env.example .env

The template contains these keys (leave the ones you do not use blank):

Important

The dual-region providers (Qwen, GLM, MiniMax) use separate accounts for their international and China endpoints. A key issued for one region will not authenticate against the other. Set the key matching the region you select in the CLI.

Note

The package loads .env automatically at import time, walking up from your current working directory. When you run the installed tradingagents command from your project directory, it finds that project's .env — not one buried in site-packages. Keys you have already exported in your shell are never overwritten by the file.

3.2 Enterprise providers (Azure OpenAI)

Azure credentials live in a separate file. Copy the enterprise template and fill it in:

cp .env.enterprise.example .env.enterprise

AZURE_OPENAI_API_KEY=
AZURE_OPENAI_ENDPOINT=https://your-resource-name.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT_NAME=
# OPENAI_API_VERSION=2024-10-21   # optional, required for non-v1 API

3.3 Letting the CLI prompt you

If you start a run and the selected provider's key is missing, the CLI stops to ask for it:

ANTHROPIC_API_KEY is not set in your environment.
? Paste your ANTHROPIC_API_KEY (will be saved to .env): ********
Saved ANTHROPIC_API_KEY to /home/you/TradingAgents/.env

The key is written to your project .env and exported into the running process, so the analysis proceeds immediately. Local Ollama does not require a key and is never prompted for one.

4. Running an Analysis (the Interactive CLI)

Launch the wizard:

tradingagents

You are guided through the following steps in order. Each step shows a boxed prompt; sensible defaults are offered where applicable.

Step 1 — Ticker symbol

Enter the symbol you want to analyze, including any exchange suffix. The input is validated (alphanumeric plus . _ - ^, max 32 characters) and uppercased.

? Enter ticker symbol (e.g. SPY, 0700.HK, BTC-USD): NVDA

Pressing Enter with no input defaults to SPY. If the ticker ends in a crypto suffix (-USD, -USDT, -USDC, -BTC, -ETH) the asset type is auto-detected as crypto and announced.

Step 2 — Analysis date

? Enter the analysis date (YYYY-MM-DD): 2026-01-15

The date is validated against YYYY-MM-DD format and cannot be in the future. TradingAgents analyzes the market as of this date — all price, indicator, and fundamentals data is filtered so the run never sees information dated after it (this prevents look-ahead bias in backtests).

Step 3 — Output language

Select the language for the analyst reports and final decision. English is the default; eleven preset languages plus a "Custom language" free-text option are offered.

Note

Internal agent debate always happens in English for reasoning quality; only the user-facing reports are translated into your chosen language.

Step 4 — Analyst team

A checkbox list lets you pick which analysts run. Press Space to toggle, a to select all, Enter to confirm. You must pick at least one.

Tip

For a crypto ticker (e.g. BTC-USD), the Fundamentals Analyst is automatically removed from the menu, since company-style fundamentals do not apply.

Step 5 — Research depth

Controls how many rounds of debate the research and risk teams conduct.

Step 6 — LLM provider

Pick the language-model provider that powers the agents.

For Qwen, GLM, and MiniMax, a follow-up prompt asks which regional endpoint to use (international vs China), because the two use different accounts and keys.

Step 7 — Thinking agents (model selection)

You pick two models:

• Quick-thinking model — used by the analysts, researchers, risk debaters, and trader for the high-volume work.
• Deep-thinking model — used by the Research Manager and Portfolio Manager for the final synthesizing decisions.

Each provider offers a curated dropdown of current model IDs, plus a "Custom model ID" option for anything not listed (and for Ollama models you have pulled yourself). OpenRouter fetches its list live; Azure asks for a deployment name.

Step 8 — Provider-specific thinking configuration

Depending on the provider you chose, a final prompt tunes reasoning behavior:

• OpenAI → Reasoning effort: Medium (default) / High / Low
• Anthropic → Effort level: High (recommended) / Medium / Low
• Google → Thinking mode: Enable Thinking (recommended) / Minimal

Watching the run

Once selections are complete, a live dashboard appears with four regions:

• Progress — every agent and team, color-coded pending → in_progress → completed.
• Messages & Tools — a rolling feed of agent messages and the data tools they call.
• Current Report — the most recently produced report section, rendered as markdown.
• Footer stats — agents completed, LLM calls, tool calls, token usage (↑ in / ↓ out), reports completed, and elapsed time.

When the pipeline finishes you will see Analysis Complete! with a per-analyst wall-time summary, and two prompts:

? Save report? [Y]:
? Save path (press Enter for default) [.../reports/NVDA_20260115_103245]:
? Display full report on screen? [Y]:

5. Reading the Output

A completed analysis produces a structured report. When you choose to save it, TradingAgents writes a folder organized by team:

reports/NVDA_20260115_103245/
├── complete_report.md        # full consolidated report
├── 1_analysts/
│   ├── market.md
│   ├── sentiment.md
│   ├── news.md
│   └── fundamentals.md
├── 2_research/
│   ├── bull.md
│   ├── bear.md
│   └── manager.md            # Research Manager's investment plan
├── 3_trading/
│   └── trader.md
├── 4_risk/
│   ├── aggressive.md
│   ├── conservative.md
│   └── neutral.md
└── 5_portfolio/
    └── decision.md           # the final Buy/Hold/Sell-style decision

Note

Only the sections that actually ran are written — if you did not select the News Analyst, there is no news.md. The consolidated complete_report.md is always written and contains a timestamped header followed by every section that was produced.

The final decision

The Portfolio Manager's decision uses a five-tier rating, from most bullish to most bearish:

The decision section carries a **Rating**: line, an **Executive Summary** (entry strategy, sizing, key risk levels, time horizon), an **Investment Thesis**, and optional **Price Target** and **Time Horizon** fields.

Tip

The Trader produces a simpler three-tier proposal (Buy / Hold / Sell) with an optional entry price, stop-loss, and position sizing — transaction direction is naturally ternary. The five-tier scale appears at the Research Manager and Portfolio Manager level, where position weighting matters.

6. Using TradingAgents from Python

You can drive the framework programmatically instead of through the CLI. Import TradingAgentsGraph, initialize it with a config, and call .propagate(ticker, date).

from tradingagents.graph.trading_graph import TradingAgentsGraph
from tradingagents.default_config import DEFAULT_CONFIG

ta = TradingAgentsGraph(debug=True, config=DEFAULT_CONFIG.copy())

# forward propagate: returns (full_state, decision)
_, decision = ta.propagate("NVDA", "2026-01-15")
print(decision)        # -> one of Buy / Overweight / Hold / Underweight / Sell

propagate() returns a tuple: the complete final state dictionary (every report and debate transcript) and the extracted rating string.

Customizing the config

Copy DEFAULT_CONFIG and override only the keys you care about:

from tradingagents.graph.trading_graph import TradingAgentsGraph
from tradingagents.default_config import DEFAULT_CONFIG

config = DEFAULT_CONFIG.copy()
config["llm_provider"] = "openai"          # openai, google, anthropic, xai, deepseek,
                                           # qwen, qwen-cn, glm, glm-cn, minimax,
                                           # minimax-cn, openrouter, ollama, azure
config["deep_think_llm"] = "gpt-5.5"       # model for the final reasoning steps
config["quick_think_llm"] = "gpt-5.4-mini" # model for the high-volume steps
config["max_debate_rounds"] = 2            # research-team debate rounds

ta = TradingAgentsGraph(debug=True, config=config)
_, decision = ta.propagate("NVDA", "2026-01-15")
print(decision)

You can also limit which analysts run by passing a list as the first argument:

# Only run the market and news analysts
ta = TradingAgentsGraph(["market", "news"], config=config)

Tip

The analyst keys are "market", "social" (the Sentiment Analyst — the wire value stays social for backward compatibility), "news", and "fundamentals".

Note

Setting debug=True streams each step and pretty-prints messages as the graph runs. With debug=False, the graph runs to completion and returns the final state in one call.

7. Configuration Without Editing Code

You can override most defaults purely through environment variables, with no code changes. Set any TRADINGAGENTS_* variable (in your shell or .env) and it replaces the matching key in DEFAULT_CONFIG. Values are coerced to the type of the existing default, so plain strings like "true" or "3" work as expected.

Tip

In the CLI, setting the provider, models, backend URL, or language via these environment variables also skips the matching interactive prompt. This makes unattended runs possible and is the right way to wire up OpenAI-compatible endpoints like LM Studio or opencode.

8. Choosing and Switching Models

8.1 Local models with Ollama

Run analyses entirely on your own hardware with Ollama. No API key is required.

# Point at a remote ollama-serve (optional — defaults to local)
export OLLAMA_BASE_URL=http://your-ollama-host:11434/v1

Then select Ollama as the provider in the CLI. The resolved endpoint is shown before model selection, and the CLI warns if the URL is missing a scheme or the usual :11434 port.

Important

Pull any model you want to use first with ollama pull <name>, then choose "Custom model ID" in the CLI and type that exact name (for example glm-4.7-flash:latest). The three suggested defaults are only a starting point — if you ask for a model you have not pulled, the run will fail when Ollama cannot find it.

8.2 OpenAI-compatible endpoints

For gateways and proxies that speak the OpenAI API (LM Studio, opencode, corporate gateways), set the backend URL and use the OpenAI provider:

export TRADINGAGENTS_LLM_PROVIDER=openai
export TRADINGAGENTS_LLM_BACKEND_URL=http://localhost:1234/v1

8.3 Reproducibility and temperature

TradingAgents is LLM-driven, so two runs of the same ticker and date can differ. To reduce variation, lower the sampling temperature and pair it with a non-reasoning model (reasoning models largely ignore temperature):

config = DEFAULT_CONFIG.copy()
config["llm_provider"] = "openai"
config["deep_think_llm"] = "gpt-4.1"     # non-reasoning model honors temperature
config["quick_think_llm"] = "gpt-4.1"
config["temperature"] = 0.0

Note

No setting makes LLM output bit-identical across runs. Live data (news, social posts) also changes over time. What is stable: the analyzed company identity is resolved deterministically from the ticker before any agent runs, and the Market Analyst grounds exact price and indicator claims in a verified data snapshot — so the framework will not silently analyze the wrong company or invent price levels.

9. Markets and Tickers

TradingAgents works with any market Yahoo Finance covers, using the exchange-suffixed ticker. Company identity and the alpha benchmark resolve automatically per market.

Tip

The framework also understands common broker-style symbols and maps them to Yahoo's convention automatically — for example gold (XAUUSD → GC=F), spot forex (EURUSD → EURUSD=X), and index CFDs (SPX500 → ^GSPC). When in doubt, the exchange-suffixed Yahoo symbol is the safest input.

Caution

If a symbol returns no data from any vendor, TradingAgents reports NO_DATA_AVAILABLE and instructs the agents not to fabricate values, rather than guessing a price. A run on an invalid or delisted ticker will produce an explicit "data unavailable" note instead of a confident-but-fake analysis.

10. Persistence and Recovery

TradingAgents keeps two kinds of state across runs.

10.1 Decision log (always on)

Every completed run appends its decision to ~/.tradingagents/memory/trading_memory.md. On the next run for the same ticker, TradingAgents:

1. Fetches the realized return over the holding window (raw and alpha vs the benchmark).
2. Generates a short reflection on whether the call was right and what to learn.
3. Injects recent same-ticker decisions plus cross-ticker lessons into the Portfolio Manager's prompt.

So each analysis carries forward what worked and what didn't. Override the path with TRADINGAGENTS_MEMORY_LOG_PATH.

Note

Outcomes are only resolved when you re-run the same ticker — that is when the realized return becomes known and gets written back. Decisions for tickers you do not re-run stay "pending" in the log until you analyze them again.

10.2 Checkpoint resume (opt-in)

Long runs can be made resumable so a crash or interruption does not waste the work already done. Enable it with the --checkpoint flag:

tradingagents analyze --checkpoint

When enabled, state is saved after each step in a per-ticker SQLite database under ~/.tradingagents/cache/checkpoints/<TICKER>.db. On a resume run for the same ticker and date you will see Resuming from step N; on a fresh run, Starting fresh. Checkpoints are cleared automatically on successful completion.

Reset all checkpoints before running:

tradingagents analyze --clear-checkpoints

The programmatic equivalent:

config = DEFAULT_CONFIG.copy()
config["checkpoint_enabled"] = True
ta = TradingAgentsGraph(config=config)
_, decision = ta.propagate("NVDA", "2026-01-15")

11. CLI Command Reference

The CLI exposes a single command, analyze, which is also the default action when you run tradingagents with no arguments.

Note

The bulk of the configuration (ticker, date, analysts, depth, provider, models, language) is gathered through the interactive prompts, not through command-line flags. To run unattended, set the TRADINGAGENTS_* environment variables from Section 7 so the matching prompts are skipped.

12. Data Sources

TradingAgents fetches market data through configurable vendors, with Yahoo Finance as the default and Alpha Vantage as an alternative. The pipeline falls back to another vendor if the primary one is rate-limited or returns nothing.

Sentiment data comes from additional public sources that need no key: StockTwits (per-symbol message stream with bullish/bearish labels) and Reddit (finance subreddits, with an automatic RSS fallback if Reddit's API blocks the request).

Tip

To use Alpha Vantage instead of Yahoo Finance, set ALPHA_VANTAGE_API_KEY and configure the data_vendors keys in your config (see the Admin Guide). You can switch vendors per category or per individual tool.

13. Troubleshooting

Error: API key for provider 'openai' is not set. Please set the OPENAI_API_KEY environment variable

Cause: The selected provider's key is not present in the environment or .env. Solution: Add the matching key to .env (see Section 3.1), or paste it when the CLI prompts you. The error message always names the exact variable to set. Prevention: Fill in .env for the providers you plan to use before starting.

Error: openai.NotFoundError: 404 page not found (with local Ollama)

Cause: The Ollama endpoint is wrong, or the requested model has not been pulled. Solution: Confirm ollama serve is running, set OLLAMA_BASE_URL to the correct http://host:11434/v1 URL, and ollama pull the model. Use the "Custom model ID" option to enter the exact pulled name. Prevention: The CLI shows the resolved Ollama endpoint and warns about missing scheme/port before model selection — read that line.

Error: tradingagents looks for glm-4.7-flash-30b:latest not glm-4.7-flash:latest

Cause: The model name you selected does not match the tag you pulled in Ollama. Solution: Run ollama list to see your exact tags, then enter that exact string via "Custom model ID". Prevention: Copy the model tag from ollama list rather than typing it from memory.

Error: Getting 403 blocked error from Reddit

Cause: Reddit's firewall increasingly blocks the public JSON search endpoint. Solution: No action needed — TradingAgents automatically falls back to Reddit's public RSS feed. RSS-sourced posts simply omit score and comment counts (the report marks them as such rather than printing fake zeros). Prevention: This is handled transparently; sentiment analysis continues with the available data.

Error: Connection Error / Connection failed with a provider

Cause: Network issue, an unreachable endpoint, or a regional-key mismatch on a dual-region provider (Qwen / GLM / MiniMax). Solution: Verify connectivity to the provider's endpoint. For dual-region providers, confirm you selected the region that matches your key (the international key will not work against the China endpoint and vice versa). Prevention: Choose the correct region prompt and set the matching *_CN_API_KEY or international key.

Issue: Reports come back in English even though I selected another language

Cause: Internal agent debate stays in English by design; only the final user-facing reports are localized. Solution: This is expected for the debate transcripts. The analyst reports and final decision should be in your chosen language. If they are not, confirm TRADINGAGENTS_OUTPUT_LANGUAGE is not overriding your CLI choice. Prevention: Pick the language at Step 3, or set TRADINGAGENTS_OUTPUT_LANGUAGE consistently.

Issue: A NO_DATA_AVAILABLE message appears in the analysis

Cause: No configured vendor returned market data for the symbol — it may be invalid, delisted, or uncovered by Yahoo Finance / Alpha Vantage. Solution: Double-check the ticker, including its exchange suffix (e.g. 0700.HK, not 0700). Try the canonical Yahoo symbol. Prevention: Use exchange-suffixed tickers from Section 9.

Issue: Two runs of the same ticker/date give different decisions

Cause: Expected behavior — LLM sampling is non-deterministic and live data shifts over time. Solution: Lower temperature and use a non-reasoning model for more repeatable output (Section 8.3). Prevention: None fully eliminates variation; treat the framework as a research scaffold, not a fixed-output tool.

Issue: UnicodeEncodeError on Windows

Cause: Historic issue with the Windows cp1252 default encoding. Solution: Update to a current version — all file I/O now uses explicit UTF-8. Use a recent Python 3.10+ build. Prevention: Keep the framework up to date.

14. Frequently Asked Questions

Q: Does TradingAgents place real trades? No. It is a research framework. The Portfolio Manager "approves" a proposal against a simulated exchange; nothing connects to a live brokerage.

Q: Which LLM provider should I use? Any of the eleven supported providers works. Pick based on cost, the models you have keys for, and whether you want to run locally (Ollama). You select a quick-thinking model for high-volume work and a deep-thinking model for the final decisions.

Q: Do I need an Alpha Vantage key? No. Yahoo Finance is the default data source and needs no key. Alpha Vantage is an optional alternative vendor.

Q: Can I run it without any cloud LLM at all? Yes — select Ollama and run local models. You still need network access to your data vendors (Yahoo Finance) unless their data is already cached.

Q: What does "research depth" actually change? The number of back-and-forth debate rounds in the research and risk teams: 1 (Shallow), 3 (Medium), or 5 (Deep). More rounds mean more thorough debate and more tokens used.

Q: Why is the Fundamentals Analyst missing for my crypto ticker? Crypto assets do not have company fundamentals, so that analyst is automatically excluded when the ticker is detected as crypto.

Q: Where are my results saved? When prompted, you choose a path (default: ./reports/<TICKER>_<timestamp>/). The framework also writes per-run state logs under ~/.tradingagents/logs/ and the decision memory under ~/.tradingagents/memory/.

Q: How do I analyze a stock "as of" a past date? Enter that date at Step 2. All price, indicator, and fundamentals data is filtered to that date so the analysis does not peek at future information. Note that live news and social data still reflect "now".

Q: What is the difference between the Trader's call and the Portfolio Manager's rating? The Trader issues a three-tier transaction direction (Buy / Hold / Sell). The Portfolio Manager issues the final five-tier rating (Buy / Overweight / Hold / Underweight / Sell), which also conveys position weighting.

Q: How do I make runs unattended (no prompts)? Set the TRADINGAGENTS_* environment variables for provider, models, backend URL, and language. The CLI skips any prompt whose value is supplied by environment.

Q: Can I limit which analysts run? Yes — in the CLI, deselect them at Step 4. Programmatically, pass a list like ["market", "news"] as the first argument to TradingAgentsGraph(...).

Q: How do I resume a run that crashed? Start it with --checkpoint enabled. If the same ticker and date are re-run with checkpointing on, it resumes from the last completed step. Use --clear-checkpoints to start over.

Q: Why did my non-US stock's "alpha" look strange before? Earlier versions benchmarked everything against SPY, so currency drift dominated the alpha for non-USD listings. The framework now picks a regional benchmark automatically per exchange suffix (e.g. Nikkei 225 for .T, Hang Seng for .HK).

15. Reference

Supported LLM providers

openai, google, anthropic, xai, deepseek, qwen, qwen-cn, glm, glm-cn, minimax, minimax-cn, openrouter, ollama, azure

Analyst keys

market, social (Sentiment Analyst), news, fundamentals

Five-tier rating scale

Buy › Overweight › Hold › Underweight › Sell

Key default settings

Default file locations

Project links

• Source: github.com/TauricResearch/TradingAgents
• Paper: arXiv:2412.20138
• Disclaimer: tauric.ai/disclaimer