TradingAgents 实操指南：从零搭建一个多智能体金融分析框架

本文基于 TauricResearch/TradingAgents 开源项目撰写，聚焦于安装、配置与运行的完整流程。需要提前说明的是，该框架官方定位为研究工具，其交易表现受模型选择、温度参数、数据质量等多重因素影响，不构成任何投资建议。请以学习多智能体协作逻辑的心态来使用它。

一、这个项目是什么？

TradingAgents 用 LLM 驱动的多个智能体，模拟真实交易公司的组织分工：

TradingAgents 智能体协作结构示意

注：上图为项目官方架构图，展示了从分析师团队到组合经理的完整决策链路。*

用一张简化的流程图来理解它的协作逻辑：

flowchart TD
    A[分析师团队
基本面 / 情绪 / 新闻 / 技术] --> B[研究员团队
多头 vs 空头 结构化辩论]
    B --> C[交易员 Agent
综合报告形成交易决策]
    C --> D[风险管理团队
波动率 / 流动性 / 风险评估]
    D --> E[组合经理
批准或拒绝提案]
    E -->|批准| F[模拟交易所执行]
    E -->|拒绝| G[决策终止]

    style A fill:#e1f5fe
    style B fill:#fff3e0
    style C fill:#f3e5f5
    style D fill:#ffebee
    style E fill:#e8f5e9

关键设计*：四位分析师并行工作，各自使用独立工具；等全部报告完成后，研究辩论才开始。这种"先收集、再辩论"的结构，是为了避免单一视角过早主导结论。

二、环境准备与安装

2.1 前置要求

项目	要求
Python	3.11 或更高（官方示例用 3.13）
包管理	pip 或 uv 均可
LLM API	至少一个提供商的 Key（OpenAI / Google / Anthropic / DeepSeek 等）
可选	Docker（用于容器化运行）

2.2 克隆并创建虚拟环境

git clone https://github.com/TauricResearch/TradingAgents.git
cd TradingAgents

# 方式一：conda
conda create -n tradingagents python=3.13
conda activate tradingagents

# 方式二：uv（更快）
uv venv --python 3.13
source .venv/bin/activate

2.3 安装依赖

# 使用 pip
pip install .

# 或使用 uv
uv pip install .

2.4 配置 API Key

复制示例环境文件，填入你自己的密钥：

cp .env.example .env

然后在 .env 中按需设置（只需配置你实际使用的提供商）：

# OpenAI
export OPENAI_API_KEY=sk-...

# DeepSeek（性价比之选）
export DEEPSEEK_API_KEY=...

# Google Gemini
export GOOGLE_API_KEY=...

# Anthropic Claude
export ANTHROPIC_API_KEY=...

# 可选：FRED 宏观数据（免费）
export FRED_API_KEY=...

# 可选：Alpha Vantage 数据源
export ALPHA_VANTAGE_API_KEY=...

提示：如果你使用 ChatGPT Plus/Pro 订阅而非 API Key，可在 CLI 的提供商菜单中选择 "Subscription"，或设置 llm_provider: "chatgpt"，然后执行 tradingagents login chatgpt 完成浏览器登录。该登录态保存在 ~/.tradingagents/chatgpt-auth.json。

2.5 Docker 运行（可选）

不想折腾本地环境的话：

cp .env.example .env   # 填入密钥
docker compose run --rm tradingagents

运行结果、报告、记忆日志和缓存默认存放在 tradingagents_data 卷中。若想映射到宿主目录：

mkdir -p data
TRADINGAGENTS_DATA_DIR=./data docker compose run --rm tradingagents

三、CLI 快速上手

3.1 启动交互式界面

tradingagents          # 已安装的命令
# 或从源码直接运行
python -m cli.main

启动后你会看到一个交互界面，依次选择：

股票代码（ticker）
分析日期
LLM 提供商
研究深度（辩论轮数等）

上次运行的答案会作为默认值回显，直接按 Enter 即可沿用。

3.2 无交互运行（适合定时任务）

用命令行参数跳过提问，配合环境变量完成全部配置：

export TRADINGAGENTS_LLM_PROVIDER=openai
export TRADINGAGENTS_QUICK_THINK_LLM=gpt-6-luna
export TRADINGAGENTS_DEEP_THINK_LLM=gpt-6-sol
export TRADINGAGENTS_OUTPUT_LANGUAGE=Chinese
export TRADINGAGENTS_MAX_DEBATE_ROUNDS=1
export TRADINGAGENTS_MAX_RISK_ROUNDS=1

tradingagents --ticker NVDA --date 2026-09-23 \
  --analysts market,news,fundamentals \
  --save --no-show

参数说明*：

参数	作用
`--ticker`	股票代码，如 `NVDA`、`0700.HK`、`600519.SS`
`--date`	分析日期（YYYY-MM-DD）
`--analysts`	选择启用的分析师，逗号分隔
`--save`	保存报告到磁盘
`--no-show`	不自动打开报告页面
`--checkpoint`	启用断点续跑
`--clear-checkpoints`	运行前清空所有检查点

3.3 支持的市场与代码格式

TradingAgents 基于 Yahoo Finance 数据，使用带交易所后缀的代码：

美股：      AAPL, SPY
港股：      0700.HK
日股：      7203.T
英股：      AZN.L
印度：      RELIANCE.NS / .BO
加拿大：    .TO
澳洲：      .AX
A股：       600519.SS（沪市）/ 000001.SZ（深市）
加密货币：  BTC-USD, ETH-USD

四、Python API 用法

4.1 最小可运行示例

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

# 初始化图
ta = TradingAgentsGraph(debug=True, config=DEFAULT_CONFIG.copy())

# 前向传播，返回状态和决策
state, decision = ta.propagate("NVDA", "2026-09-01")
print(decision)

# 保存与 CLI 相同的报告树
ta.save_reports(state, "NVDA")

4.2 自定义配置

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

config = DEFAULT_CONFIG.copy()
config["llm_provider"] = "deepseek"        # openai / google / anthropic / deepseek / groq / ollama ...
config["deep_think_llm"] = "deepseek-reasoner"   # 复杂推理：研究经理、组合经理
config["quick_think_llm"] = "deepseek-chat"      # 快速任务：分析师、交易员
config["max_debate_rounds"] = 2
config["temperature"] = 0.0                # 降低采样随机性（推理模型会忽略此参数）

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

4.3 分层使用不同提供商

一个实用技巧：让"深度思考"层跑在更强的模型上，其余用便宜模型：

config["deep_think_provider"] = "anthropic"
config["deep_think_llm"] = "claude-opus-5-5"
# quick_think 仍走默认的 openai

4.4 传入你的实际持仓

默认情况下，智能体不知道你持有什么。传入组合后，交易员、风控和组合经理会针对你的真实仓位给出建议：

from tradingagents.portfolio import PortfolioContext

portfolio = PortfolioContext.model_validate({
    "cash": 25000.0,
    "currency": "USD",
    "positions": [
        {"ticker": "NVDA", "quantity": 120, "average_price": 150.0}
    ],
})

_, decision = ta.propagate("NVDA", "2026-09-01", portfolio=portfolio)

CLI 同样支持：

tradingagents --portfolio my_book.json

注意：positions 为空列表表示"空仓"，这与不传 portfolio 是不同的语义——不传时，智能体不会假设你是空仓。

五、持久化与回测

5.1 记忆日志（默认开启）

每次完成运行后，决策会追加到：

~/.tradingagents/memory/trading_memory.md

在后续运行的分析师工作期间，系统会自动结算已过持有期的历史决策：拉取实际收益（原始收益 + 相对区域基准的 alpha），并生成一段反思。组合经理随后会读取同一标的最新决策和其他标的的经验教训——这就是"越用越有记忆"的机制。

也可单独结算：

settled, failed = ta.settle_all_pending()

5.2 断点续跑

tradingagents --checkpoint           # 本次运行启用
tradingagents --clear-checkpoints    # 运行前清空

每个标的的检查点存在 ~/.tradingagents/cache/checkpoints/<TICKER>.db，成功完成后自动清除。

5.3 回测：评估决策质量

单次运行只能给出一个决策，无法判断系统决策质量。run_backtest 会在代码 × 日期的网格上跑同一套流程，并对已过持有窗口的决策打分：

from tradingagents.backtest import iter_grid, run_backtest, summarize

dates = iter_grid("2026-06-01", "2026-08-01", every_n_days=7)
result = run_backtest(
    ["NVDA", "AAPL"],
    dates,
    config,
    selected_analysts=["market", "news"]
)
print(summarize(result).render())

CLI 等价命令：

tradingagents backtest NVDA,AAPL --start 2026-06-01 --end 2026-08-01 --every 7

评分逻辑*：每个格子按相对区域基准的已实现 alpha 打分，并按评级分组。决策以日期后第一个收盘价入场（因为运行会读到当日收盘后的新闻）。用 run_id=result.run_id 重跑同一网格时，已完成的格子会被跳过，中断的扫描可以从断点继续。

六、可复现性的真相

这是使用本项目最需要建立的心理预期。官方文档明确说明：

flowchart LR
    A[同一 ticker + 同一日期] --> B{两次运行}
    B --> C[结果可能不同]
    C --> D1[LLM 采样非确定性
即使 temperature=0]
    C --> D2[实时数据在变
新闻/社媒反映的是'现在']
    C --> D3[推理模型变化最大
内部推理本身被采样]

    style C fill:#ffebee
    style D1 fill:#fff8e1
    style D2 fill:#fff8e1
    style D3 fill:#fff8e1

降低波动的方法*：

设置 temperature = 0.0
但要注意：推理型模型（如默认的 GPT-6 系列）基本忽略 temperature
想要更紧的可复现性，请显式指定非推理模型

已经不会漂移的部分*（项目已修复的机制）：

被分析的公司身份由 ticker 在智能体运行前确定性解析
市场分析师对精确价格和指标的陈述，锚定在已验证的数据快照上

七、实操建议与避坑清单

结合项目特性，给出几条务实的建议：

必须警惕的坑

坑	说明
把它当收益承诺	官方原话："It is not intended as financial, investment, or trading advice."
忽略数据源限制	美股基本面走 SEC EDGAR（按申报日记录，支持 point-in-time 回溯）；非美股走 Yahoo Finance，历史日期的报表会被标记为"withheld"，因为 Yahoo 无法确定当时哪些数字已公开。
历史日期读未来数据	项目已做 look-ahead 修复，但社媒和新闻源仍反映"现在"——同一历史日期的两次运行，输入数据不同。
回测结果与公开数字不符	官方明确："Backtest results are not guaranteed to match any published figure." 模型、温度、日期范围、数据质量都会影响结果。
SEC EDGAR 联系地址	SEC 要求调用方自报身份，默认会发一个项目地址。建议设置 `SEC_EDGAR_USER_AGENT="Your Name [email protected]"`，让 SEC 能联系到你而非项目方。

🔧 常见问题速查

Q：报错说缺少某个 flag 或变量？* A：无终端环境下运行时，缺失的答案会在运行开始前中止并明确指出需要设置的 flag/变量名——按提示补上即可。
Q：想用本地模型？* A：配置 llm_provider: "ollama"，默认端点 http://localhost:11434/v1，用 OLLAMA_BASE_URL 指向远程 ollama-serve。Docker 用户可用 docker compose --profile ollama run --rm tradingagents-ollama。
Q：想用 vLLM / LM Studio / llama.cpp？* A：设 llm_provider: "openai_compatible"，用 backend_url 或 TRADINGAGENTS_LLM_BACKEND_URL 指定端点。本地服务通常无需 Key。
Q：如何关闭启动时的版本检查？* A：export TRADINGAGENTS_NO_UPDATE_CHECK=1。
Q：报告除了文本还有其他格式吗？* A：保存时还会生成 complete_report.html——单页 HTML，左侧栏列出各章节，适合在浏览器、手机或打印时阅读。--no-html 可跳过。

八、项目结构速览

TradingAgents/
├── tradingagents/          # 核心包
│   ├── graph/              # LangGraph 编排
│   ├── backtest.py         # 回测网格
│   ├── portfolio.py        # 组合上下文
│   └── default_config.py   # 全部配置项
├── cli/                    # 交互式命令行
├── tests/                  # 测试
├── assets/                 # 图片资源
├── main.py                 # 入口示例
├── pyproject.toml
├── requirements.txt
├── Dockerfile
└── docker-compose.yml

完整配置项见 tradingagents/default_config.py。

九、结语

TradingAgents 的价值不在于"帮你赚钱"，而在于提供了一个结构清晰、工程完整的多智能体金融分析脚手架：并行分析师、结构化多空辩论、风控与组合经理的分层决策、记忆日志的反思机制、以及支持 point-in-time 的回测框架。这些设计本身，就是研究多智能体协作在复杂决策场景中应用的好素材。

把它当成一个可以拆开、改造、实验的研究平台，而不是一个黑箱策略——这才是这个项目正确的打开方式。

参考与引用*

项目地址：https://github.com/TauricResearch/TradingAgents
论文：Xiao, Y., Sun, E., Luo, D., & Wang, W. (2025). TradingAgents: Multi-Agents LLM Financial Trading Framework. arXiv:2412.20138.