# 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](https://tauric.ai/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.

```bash
# 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

| Requirement | Detail |
|---|---|
| Python | 3.10+ (3.13 recommended) |
| Install method | `pip install .` from a clone, or Docker |
| Market data | Yahoo Finance (default, no key) or Alpha Vantage (key required) |
| LLM provider | At least one of: OpenAI, Google, Anthropic, xAI, DeepSeek, Qwen, GLM, MiniMax, OpenRouter, Azure OpenAI, or local Ollama |
| Network | Outbound HTTPS to your chosen LLM provider and data vendors |

### 2.2 Install from source

=== "conda"

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

=== "venv"

    ```bash
    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`.

```bash
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:

```bash
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

```bash
tradingagents --help
```

```text
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.

```bash
cp .env.example .env
```

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

| Environment variable | Provider |
|---|---|
| `OPENAI_API_KEY` | OpenAI (GPT) |
| `GOOGLE_API_KEY` | Google (Gemini) |
| `ANTHROPIC_API_KEY` | Anthropic (Claude) |
| `XAI_API_KEY` | xAI (Grok) |
| `DEEPSEEK_API_KEY` | DeepSeek |
| `DASHSCOPE_API_KEY` | Qwen — International endpoint |
| `DASHSCOPE_CN_API_KEY` | Qwen — China endpoint |
| `ZHIPU_API_KEY` | GLM via Z.AI (international) |
| `ZHIPU_CN_API_KEY` | GLM via BigModel (China) |
| `MINIMAX_API_KEY` | MiniMax — Global endpoint |
| `MINIMAX_CN_API_KEY` | MiniMax — China endpoint |
| `OPENROUTER_API_KEY` | OpenRouter |
| `ALPHA_VANTAGE_API_KEY` | Alpha Vantage (market data) |

> [!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:

```bash
cp .env.enterprise.example .env.enterprise
```

```text
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:

```text
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:

```bash
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.

```text
? 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

```text
? 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.

| Analyst | What it studies |
|---|---|
| Market Analyst | Price action and technical indicators (MACD, RSI, Bollinger Bands, moving averages) |
| Sentiment Analyst | Yahoo News, StockTwits, and Reddit chatter distilled into a sentiment read |
| News Analyst | Company news, macro/global headlines, and insider transactions |
| Fundamentals Analyst | Financial statements, ratios, and key metrics |

> [!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.

| Choice | Debate rounds | Use for |
|---|---|---|
| Shallow | 1 | Quick reads, lower token cost |
| Medium | 3 | A balanced default |
| Deep | 5 | Thorough, in-depth analysis |

### Step 6 — LLM provider

Pick the language-model provider that powers the agents.

| Provider | Notes |
|---|---|
| OpenAI | GPT family; uses the OpenAI Responses API |
| Google | Gemini family |
| Anthropic | Claude family |
| xAI | Grok family |
| DeepSeek | DeepSeek chat / reasoner |
| Qwen | Alibaba DashScope — prompts for International vs China region |
| GLM | Zhipu — prompts for Z.AI (international) vs BigModel (China) |
| MiniMax | Prompts for Global vs China region |
| OpenRouter | Live model list fetched from the OpenRouter API |
| Azure OpenAI | Uses your Azure deployment name |
| Ollama | Local or remote models; surfaces the resolved endpoint |

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:

```text
? 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:

```text
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:

| Rating | Meaning |
|---|---|
| **Buy** | Strongest bullish conviction |
| **Overweight** | Lean bullish |
| **Hold** | Evidence genuinely balanced |
| **Underweight** | Lean bearish |
| **Sell** | Strongest bearish conviction |

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)`.

```python
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:

```python
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:

```python
# 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.

| Environment variable | Overrides | Example |
|---|---|---|
| `TRADINGAGENTS_LLM_PROVIDER` | LLM provider | `openai` |
| `TRADINGAGENTS_DEEP_THINK_LLM` | Deep-thinking model | `gpt-5.4` |
| `TRADINGAGENTS_QUICK_THINK_LLM` | Quick-thinking model | `gpt-5.4-mini` |
| `TRADINGAGENTS_LLM_BACKEND_URL` | Provider endpoint URL | (custom gateway) |
| `TRADINGAGENTS_OUTPUT_LANGUAGE` | Report language | `Chinese` |
| `TRADINGAGENTS_MAX_DEBATE_ROUNDS` | Research debate rounds | `3` |
| `TRADINGAGENTS_MAX_RISK_ROUNDS` | Risk debate rounds | `2` |
| `TRADINGAGENTS_CHECKPOINT_ENABLED` | Enable checkpoint resume | `true` |
| `TRADINGAGENTS_BENCHMARK_TICKER` | Alpha benchmark override | `^GSPC` |
| `TRADINGAGENTS_TEMPERATURE` | Sampling temperature | `0.0` |
| `TRADINGAGENTS_RESULTS_DIR` | Where run logs are written | `/data/logs` |
| `TRADINGAGENTS_CACHE_DIR` | Price/checkpoint cache directory | `/data/cache` |
| `TRADINGAGENTS_MEMORY_LOG_PATH` | Decision-log file path | `/data/memory.md` |

> [!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.

```bash
# 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:

```bash
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):

```python
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.

| Market | Example tickers |
|---|---|
| US | `AAPL`, `SPY` |
| Hong Kong | `0700.HK` |
| Tokyo | `7203.T` |
| London | `AZN.L` |
| India (NSE / BSE) | `RELIANCE.NS`, `.BO` |
| Canada | `.TO` |
| Australia | `.AX` |
| China A-shares (Shanghai / Shenzhen) | `600519.SS`, `.SZ` |
| Crypto | `BTC-USD`, `ETH-USD` |

> [!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:

```bash
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:

```bash
tradingagents analyze --clear-checkpoints
```

The programmatic equivalent:

```python
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.

| Command | Description |
|---|---|
| `tradingagents` | Launch the interactive analysis wizard (runs `analyze`) |
| `tradingagents analyze` | Same as above |
| `tradingagents analyze --checkpoint` | Run with checkpoint/resume enabled |
| `tradingagents analyze --clear-checkpoints` | Delete all saved checkpoints, then run fresh |
| `tradingagents --help` | Show help |
| `python -m cli.main` | Run the CLI directly from a source checkout |

| Flag | Effect |
|---|---|
| `--checkpoint` | Save state after each node so a crashed run can resume |
| `--clear-checkpoints` | Force a fresh start by deleting all checkpoint databases first |

> [!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](#7-configuration-without-editing-code) 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.

| Data category | Default vendor | Alternative |
|---|---|---|
| Stock price (OHLCV) | yfinance | alpha_vantage |
| Technical indicators | yfinance | alpha_vantage |
| Fundamentals | yfinance | alpha_vantage |
| News & insider data | yfinance | alpha_vantage |

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](#31-the-env-file)), 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](#9-markets-and-tickers).

### 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](#83-reproducibility-and-temperature)).
**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

| Setting | Default |
|---|---|
| LLM provider | `openai` |
| Deep-thinking model | `gpt-5.5` |
| Quick-thinking model | `gpt-5.4-mini` |
| Output language | `English` |
| Research debate rounds | `1` |
| Risk debate rounds | `1` |
| Default data vendor (all categories) | `yfinance` |
| Default benchmark (US tickers) | `SPY` |
| Checkpointing | off |

### Default file locations

| Path | Holds |
|---|---|
| `~/.tradingagents/logs/` | Per-run state logs |
| `~/.tradingagents/cache/` | Cached price data |
| `~/.tradingagents/cache/checkpoints/<TICKER>.db` | Resume checkpoints |
| `~/.tradingagents/memory/trading_memory.md` | Decision log |

### Project links

- Source: [github.com/TauricResearch/TradingAgents](https://github.com/TauricResearch/TradingAgents)
- Paper: [arXiv:2412.20138](https://arxiv.org/abs/2412.20138)
- Disclaimer: [tauric.ai/disclaimer](https://tauric.ai/disclaimer/)

---

_Generated June 2026 from TauricResearch/TradingAgents at 04f434e. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._