/README.md

<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
> [English](./README.en.md) · [原始项目](https://github.com/TauricResearch/TradingAgents) · [上游 README](https://github.com/TauricResearch/TradingAgents/blob/HEAD/README.md)  
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

<p align="center">
  <img src="assets/TauricResearch.png" style="width: 60%; height: auto;">
</p>

<div align="center" style="line-height: 1;">
  <a href="https://arxiv.org/abs/2412.20138" target="_blank"><img alt="arXiv" src="https://img.shields.io/badge/arXiv-2412.20138-B31B1B?logo=arxiv"/></a>
  <a href="https://discord.com/invite/hk9PGKShPK" target="_blank"><img alt="Discord" src="https://img.shields.io/badge/Discord-TradingResearch-7289da?logo=discord&logoColor=white&color=7289da"/></a>
  <a href="./assets/wechat.png" target="_blank"><img alt="WeChat" src="https://img.shields.io/badge/WeChat-TauricResearch-brightgreen?logo=wechat&logoColor=white"/></a>
  <a href="https://x.com/TauricResearch" target="_blank"><img alt="X Follow" src="https://img.shields.io/badge/X-TauricResearch-white?logo=x&logoColor=white"/></a>
  <br>
  <a href="https://github.com/TauricResearch/" target="_blank"><img alt="Community" src="https://img.shields.io/badge/Join_GitHub_Community-TauricResearch-14C290?logo=discourse"/></a>
</div>

<div align="center">
  <!-- 保留这些链接。翻译将随 README 自动更新。 -->
  <a href="https://www.readme-i18n.com/TauricResearch/TradingAgents?lang=de">Deutsch</a> | 
  <a href="https://www.readme-i18n.com/TauricResearch/TradingAgents?lang=es">Español</a> | 
  <a href="https://www.readme-i18n.com/TauricResearch/TradingAgents?lang=fr">français</a> | 
  <a href="https://www.readme-i18n.com/TauricResearch/TradingAgents?lang=ja">日本語</a> | 
  <a href="https://www.readme-i18n.com/TauricResearch/TradingAgents?lang=ko">한국어</a> | 
  <a href="https://www.readme-i18n.com/TauricResearch/TradingAgents?lang=pt">Português</a> | 
  <a href="https://www.readme-i18n.com/TauricResearch/TradingAgents?lang=ru">Русский</a> | 
  <a href="https://www.readme-i18n.com/TauricResearch/TradingAgents?lang=zh">中文</a>
</div>

---

# TradingAgents：多智能体 LLM 金融交易框架

## 新闻
- [2026-07] **TradingAgents v0.3.1** 发布，包含正确性与稳定性修复：Alpha Vantage 前瞻过滤、图路由器崩溃安全、图形状感知检查点恢复、可用的加密情绪数据源、可配置的 LLM 重试预算、Bedrock API 密钥认证，以及 Claude Sonnet 5 / Fable 5 支持。完整列表请见 [CHANGELOG.md](CHANGELOG.md)。
- [2026-06] **TradingAgents v0.3.0** 发布，包含经过验证的数据访问合约、扩展的提供商注册表（NVIDIA、Kimi、Groq、Mistral、Bedrock 及任何兼容 OpenAI 的端点）、FRED 和 Polymarket 数据供应商、当前代模型目录以及 CI 门控。
- [2026-05] **TradingAgents v0.2.5** 发布，包含基于事实的情绪分析师、GPT-5.5 等模型覆盖、Qwen/GLM/MiniMax 双区域支持、``TRADINGAGENTS_*`` 环境变量可配置性及 API 密钥自动检测、远程 Ollama 支持、非美国 Alpha 基准测试以及股票代码路径遍历加固。
- [2026-04] **TradingAgents v0.2.4** 发布，包含结构化输出智能体（研究经理、交易员、投资组合经理）、LangGraph 检查点恢复、持久化决策日志、DeepSeek/Qwen/GLM/Azure 提供商支持、Docker 以及 Windows UTF-8 编码修复。
- [2026-03] **TradingAgents v0.2.3** 发布，包含多语言支持、GPT-5.4 系列模型、统一模型目录、回测日期准确性和代理支持。
- [2026-03] **TradingAgents v0.2.2** 发布，包含 GPT-5.4/Gemini 3.1/Claude 4.6 模型覆盖、五级评分体系、OpenAI Responses API、Anthropic 努力控制以及跨平台稳定性。
- [2026-02] **TradingAgents v0.2.0** 发布，包含多提供商 LLM 支持（GPT-5.x、Gemini 3.x、Claude 4.x、Grok 4.x）和改进的系统架构。
- [2026-01] **Trading-R1** [技术报告](https://arxiv.org/abs/2509.11420))发布，[终端](https://github.com/TauricResearch/Trading-R1))预计即将推出。

<div align="center">
<a href="https://www.star-history.com/#TauricResearch/TradingAgents&Date">
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=TauricResearch/TradingAgents&type=Date&theme=dark" />
   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=TauricResearch/TradingAgents&type=Date" />
   <img alt="TradingAgents 星标历史" src="https://api.star-history.com/svg?repos=TauricResearch/TradingAgents&type=Date" style="width: 80%; height: auto;" />
 </picture>
</a>
</div>

> 🎉 **TradingAgents** 正式发布！我们收到了大量关于该项目的咨询，衷心感谢社区的热情支持。
>
> 因此我们决定将本框架完全开源。期待与大家一起打造有影响力的项目！

<div align="center">

🚀 [TradingAgents](#tradingagents-框架) | ⚡ [安装与 CLI](#安装与-cli) | 🎬 [演示](https://www.youtube.com/watch?v=90gr5lwjIho)) | 📦 [包使用](#tradingagents-包) | 🤝 [贡献](#贡献) | 📄 [引用](#引用)

</div>

## TradingAgents 框架

TradingAgents 是一个多智能体交易框架，模拟了真实交易公司的运作模式。通过部署由 LLM 驱动的专业智能体——包括基本面分析师、情绪分析师、技术分析师、交易员和风险管理团队——该平台协同评估市场状况并制定交易决策。此外，这些智能体还会进行动态讨论，以确定最优策略。

<p align="center">
  <img src="assets/schema.png" style="width: 100%; height: auto;">
</p>

> TradingAgents 框架仅供研究目的。交易表现可能因多种因素而异，包括所选的后端语言模型、模型温度、交易时段、数据质量及其他非确定性因素。[不构成财务、投资或交易建议。](https://tauric.ai/disclaimer/))

本框架将复杂的交易任务分解为多个专业角色。

### 分析师团队
- **基本面分析师**：评估公司财务和业绩指标，识别内在价值和潜在风险信号。
- **情绪分析师**：汇总新闻标题、StockTwits 和 Reddit 讨论，形成单一情绪读数，以衡量短期市场情绪。
- **新闻分析师**：监测全球新闻和宏观经济指标，解读事件对市场状况的影响。
- **技术分析师**：利用技术指标（如 MACD 和 RSI）检测交易模式并预测价格走势。

<p align="center">
  <img src="assets/analyst.png" width="100%" style="display: inline-block; margin: 0 2%;">
</p>

### 研究员团队
- 包含看涨和看空研究员，他们对分析师团队提供的见解进行批判性评估。通过结构化辩论，他们在潜在收益与固有风险之间进行权衡。

<p align="center">
  <img src="assets/researcher.png" width="70%" style="display: inline-block; margin: 0 2%;">
</p>

### 交易员智能体
- 整合分析师和研究员的分析报告，做出明智的交易决策，确定交易的时机和规模。

<p align="center">
  <img src="assets/trader.png" width="70%" style="display: inline-block; margin: 0 2%;">
</p>

### 风险管理与投资组合经理
- 通过评估市场波动性、流动性及其他风险因素，持续评估投资组合风险。风险管理团队评估并调整交易策略，向投资组合经理提供评估报告以供最终决策。
- 投资组合经理批准或拒绝交易提案。若批准，订单将被发送至模拟交易所并执行。

<p align="center">
  <img src="assets/risk.png" width="70%" style="display: inline-block; margin: 0 2%;">
</p>

## 安装与 CLI

### 安装

克隆 TradingAgents：
```bash
git clone https://github.com/TauricResearch/TradingAgents.git
cd TradingAgents
```

在你喜欢的任一环境管理器中创建虚拟环境：
```bash
conda create -n tradingagents python=3.12
conda activate tradingagents
```

安装本包及其依赖：
```bash
pip install .
```

### Docker

或者通过 Docker 运行：
```bash
cp .env.example .env  # add your API keys
docker compose run --rm tradingagents
```

对于使用 Ollama 的本地模型：
```bash
docker compose --profile ollama run --rm tradingagents-ollama
```

### 必需的 API

TradingAgents 支持多种 LLM 提供商。为所选提供商设置 API 密钥：

```bash
export OPENAI_API_KEY=...          # OpenAI (GPT)
export GOOGLE_API_KEY=...          # Google (Gemini)
export ANTHROPIC_API_KEY=...       # Anthropic (Claude)
export XAI_API_KEY=...             # xAI (Grok)
export DEEPSEEK_API_KEY=...        # DeepSeek
export DASHSCOPE_API_KEY=...       # Qwen — International (dashscope-intl.aliyuncs.com)
export DASHSCOPE_CN_API_KEY=...    # Qwen — China (dashscope.aliyuncs.com)
export ZHIPU_API_KEY=...           # GLM via Z.AI (international)
export ZHIPU_CN_API_KEY=...        # GLM via BigModel (China, open.bigmodel.cn)
export MINIMAX_API_KEY=...         # MiniMax — Global (api.minimax.io)
export MINIMAX_CN_API_KEY=...      # MiniMax — China (api.minimaxi.com)
export OPENROUTER_API_KEY=...      # OpenRouter
export ALPHA_VANTAGE_API_KEY=...   # Alpha Vantage
```

对于 Azure OpenAI，将 `.env.enterprise.example` 复制为 `.env.enterprise` 并填入你的凭据。

对于 AWS Bedrock，通过 `pip install ".[bedrock]"` 安装额外依赖，设置 `llm_provider: "bedrock"`，配置 AWS 凭据（环境变量、`~/.aws/credentials` 或 IAM 角色）和 `AWS_DEFAULT_REGION`，并使用 Bedrock 模型 ID，例如 `us.anthropic.claude-opus-4-8-v1:0`。

对于本地模型，通过 `llm_provider: "ollama"` 配置 Ollama。默认端点为 `http://localhost:11434/v1`；设置 `OLLAMA_BASE_URL` 以指向远程 `ollama-serve`。使用 `ollama pull <name>` 拉取模型，并在 CLI 中为默认未列出的任何模型选择"自定义模型 ID"。

对于任何其他兼容 OpenAI 的服务器（vLLM、LM Studio、llama.cpp 或自定义代理），使用 `llm_provider: "openai_compatible"` 并通过 `backend_url`（或 `TRADINGAGENTS_LLM_BACKEND_URL`）设置端点，例如 vLLM 使用 `http://localhost:8000/v1`，LM Studio 使用 `http://localhost:1234/v1`。模型即为你的服务器所提供的模型。本地服务器无需密钥；当端点需要时设置 `OPENAI_COMPATIBLE_API_KEY`。

或者，将 `.env.example` 复制为 `.env` 并填入你的密钥：
```bash
cp .env.example .env
```

### CLI 使用

启动交互式 CLI：
```bash
tradingagents          # installed command
python -m cli.main     # alternative: run directly from source
```
你将看到一个界面，可以在其中选择所需的股票代码、分析日期、LLM 提供商、研究深度等。

### 市场与股票代码

TradingAgents 支持 Yahoo Finance 覆盖的任何市场，使用带交易所后缀的股票代码。公司标识和 Alpha 基准会自动按市场解析。

- 美国：`AAPL`、`SPY`
- 香港：`0700.HK` · 东京：`7203.T` · 伦敦：`AZN.L`
- 印度：`RELIANCE.NS`、`.BO` · 加拿大：`.TO` · 澳大利亚：`.AX`
- 中国 A 股：上海 `.SS`，深圳 `.SZ`（例如贵州茅台 `600519.SS`）
- 加密货币：`BTC-USD`、`ETH-USD`

<p align="center">
  <img src="assets/cli/cli_init.png" width="100%" style="display: inline-block; margin: 0 2%;">
</p>

界面将随结果加载而实时显示，让你可以追踪 Agent 的运行进度。

<p align="center">
  <img src="assets/cli/cli_news.png" width="100%" style="display: inline-block; margin: 0 2%;">
</p>

<p align="center">
  <img src="assets/cli/cli_transaction.png" width="100%" style="display: inline-block; margin: 0 2%;">
</p>

## TradingAgents 包

### 实现细节

我们使用 LangGraph 构建 TradingAgents，以确保灵活性和模块化。该框架支持多个 LLM 提供商：OpenAI、Google、Anthropic、xAI、DeepSeek、Qwen（阿里云 DashScope，国际与中国端点）、GLM（智谱）、MiniMax（全球 + 中国）、OpenRouter、用于本地模型的 Ollama，以及用于企业级应用的 Azure OpenAI。

### Python 使用

要在你的代码中使用 TradingAgents，可以导入 `tradingagents` 模块并初始化一个 `TradingAgentsGraph()` 对象。`.propagate()` 函数将返回一个决策。你可以运行 `main.py`，以下是一个快速示例：

```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
_, decision = ta.propagate("NVDA", "2026-01-15")
print(decision)
```

你也可以调整默认配置以设置自己的 LLM 选择、辩论轮次等。

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

config = DEFAULT_CONFIG.copy()
config["llm_provider"] = "openai"        # e.g. openai, google, anthropic, deepseek, groq, ollama; openai_compatible covers any OpenAI-compatible endpoint (vLLM, LM Studio, llama.cpp, ...)
config["deep_think_llm"] = "gpt-5.5"     # Model for complex reasoning
config["quick_think_llm"] = "gpt-5.4-mini" # Model for quick tasks
config["max_debate_rounds"] = 2

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

有关所有配置选项，请参阅 `tradingagents/default_config.py`。

## 持久化与恢复

TradingAgents 跨运行持久化两种状态。

### 决策日志

决策日志始终开启。每次完成的运行会将其决策追加到 `~/.tradingagents/memory/trading_memory.md`。下次对同一股票代码运行时，TradingAgents 会获取已实现收益（原始收益和相对于 SPY 的 Alpha 收益），生成一段反思，并将最近的同股票代码决策以及跨股票代码的经验教训注入到投资组合管理器的提示中，从而使每次分析都能继承之前有效和无效的经验。

使用 `TRADINGAGENTS_MEMORY_LOG_PATH` 覆盖路径。

### 检查点恢复

检查点恢复通过 `--checkpoint` 选择性启用。启用后，LangGraph 会在每个节点之后保存状态，从而使崩溃或被中断的运行能够从最后成功的步骤恢复，而不是从头开始。在恢复运行时，你会在日志中看到 `Resuming from step N for <TICKER> on <date>`；在新运行时，你会看到 `Starting fresh`。成功完成后检查点会被自动清除。

按股票代码划分的 SQLite 数据库位于 `~/.tradingagents/cache/checkpoints/<TICKER>.db`（使用 `TRADINGAGENTS_CACHE_DIR` 覆盖基础路径）。在运行前使用 `--clear-checkpoints` 重置所有数据库。

```bash
tradingagents analyze --checkpoint           # enable for this run
tradingagents analyze --clear-checkpoints    # reset before running
```

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

## 可复现性

TradingAgents 由 LLM 驱动，因此同一股票代码和日期的两次运行可能产生不同结果。这对基于语言模型的研究工具而言是预期行为，而非缺陷。差异来自几个不同的来源，区分它们会有所帮助。

语言模型采样是非确定性的。即使在固定温度下，提供商也无法保证跨调用的输出字节一致，而推理模型（默认的 GPT-5.x 系列，以及任何思维链模式模型）差异最大，因为其内部推理本身就是采样的。

实时数据是变动的。新闻、StockTwits 和 Reddit 会随时间返回不同的内容，因此今天的运行即便使用相同的历史交易日期，其输入也与上周的运行不同。固定分析日期可以锁定价格和指标窗口，但社交和新闻来源仍然反映"现在"。

要减少差异，可以降低采样温度。在配置中设置 `temperature`（或在 `TRADINGAGENTS_TEMPERATURE` 中设置 `.env`）；较低的值能使支持该参数的模型更具可重复性。当前精选模型以推理为主，基本忽略温度参数，因此如需更严格的可复现性，请使用非推理模型，通过自定义模型 ID 选项显式设置即可。

```python
config = DEFAULT_CONFIG.copy()
config["llm_provider"] = "openai"
config["temperature"] = 0.0
# Reasoning models ignore temperature. For tighter reproducibility, set a
# non-reasoning deep/quick model explicitly (e.g. via the Custom model ID option).
```

不再变化的部分：在任何智能体（agent）运行之前，被分析公司的身份会从股票代码（ticker）以确定性方式解析；市场分析师（market analyst）将精确的价格与指标主张建立在经核验的数据快照之上。此前多次运行出现「不同公司」或虚构价格水平的报告，已通过上述两种机制加以解决。

回测结果不保证与任何已发布数字一致。收益取决于模型、温度（temperature）、日期范围、数据质量以及上述采样方式。请将本框架视为用于研究多智能体分析的研究脚手架，而非具有固定、可复现收益的策略。

## Contributing

欢迎贡献：错误修复、文档与功能建议；过往贡献按版本在 [`CHANGELOG.md`](CHANGELOG.md) 中致谢。

## Citation

若您觉得 *TradingAgents* 对您有所帮助，请引用我们的工作 :)

```
@misc{xiao2025tradingagentsmultiagentsllmfinancial,
      title={TradingAgents: Multi-Agents LLM Financial Trading Framework}, 
      author={Yijia Xiao and Edward Sun and Di Luo and Wei Wang},
      year={2025},
      eprint={2412.20138},
      archivePrefix={arXiv},
      primaryClass={q-fin.TR},
      url={https://arxiv.org/abs/2412.20138}, 
}
```