TradingAgents

🚀 TradingAgents 是一个多 Agent LLM 金融交易框架，利用大型语言模型模拟分析师团队、研究辩论和投资组合管理决策，以提供股票交易分析。

✨ 重点特色

基于 LangGraph 构建，提供稳健的多 Agent 编排机制
多 Agent 架构：分析师团队 → 研究团队 → 交易员 → 风险管理 → 投资组合管理
通过 langchain.chat_models.init_chat_model 构造 LLM，使用独立的 llm_provider 字段加上 model name 指定模型,支持 OpenAI、Anthropic、Google Gemini、xAI (Grok)、OpenRouter、Ollama、HuggingFace、LiteLLM
统一的 reasoning_effort 旋钮（low / medium / high / xhigh / max）会 map 到各 provider 的 native 参数（Anthropic effort、OpenAI reasoning_effort、Google thinking_level）
市场数据全由 yfinance 提供：OHLCV、基本面、技术指标、新闻与内部人交易
基于 Pydantic 的配置系统，提供严格类型检查与验证
分析结果自动保存至 results/ 目录并按团队分组
现代 src/ 布局，完整类型注解
通过 uv 进行快速依赖管理
Pre-commit 包链：ruff、mdformat、codespell、mypy、uv hooks
Pytest + coverage、MkDocs Material 文档系统

🚀 快速开始

git clone https://github.com/Mai0313/TradingAgents.git
cd TradingAgents
make uv-install               # 安装 uv（仅需一次）
uv sync                       # 安装依赖
cp .env.example .env          # 配置 API 密钥

配置 API 密钥

编辑 .env 并设置您的 LLM 供应商密钥：

# LLM 供应商（设置您使用的那一个）
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=AIza...
XAI_API_KEY=...
OPENROUTER_API_KEY=...

使用方式

Command line / 交互模式

包提供 tradingagents console script，含两个 subcommand：

uv run tradingagents tui                     # 交互式 questionary 流程
uv run tradingagents cli                     # 全部使用默认值执行
uv run tradingagents cli --ticker AAPL \
    --deep_think_llm gpt-5 \
    --quick_think_llm gpt-5-mini             # 通过 flag 覆盖
uv run tradingagents --help                  # rich 渲染的 top-level help
uv run tradingagents cli --help              # rich 渲染的 per-command flag 列表

tradingagents tui 会用一连串 questionary prompt 带你走完所有参数（ticker、日期、provider、models、辩论轮数、analyst 选择等）；tradingagents cli 是同一条流程，但完全用 command-line flag 驱动，方便写进 shell script 或 CI。两条路径跑 graph 时都会把 LangGraph 的 agent 消息通过 Rich panel 流式输出（prose 用 Markdown 渲染、tool 输出做 JSON pretty-print、payload 过长会自动截断）。python -m tradingagents <subcommand> 也走同一条 dispatcher。

程序调用

from tradingagents.config import TradingAgentsConfig
from tradingagents.graph.trading_graph import TradingAgentsGraph

config = TradingAgentsConfig(
    llm_provider="openai",
    deep_think_llm="gpt-5",
    quick_think_llm="gpt-5-mini",
    max_debate_rounds=1,
    max_risk_discuss_rounds=1,
    max_recur_limit=100,
    reasoning_effort="medium",
    response_language="en-US",
)

ta = TradingAgentsGraph(debug=True, config=config)
_, decision = ta.propagate("NVDA", "2024-05-10")
print(decision)

response_language 是来自 ResponseLanguage Literal 的 BCP 47 tag（zh-TW、zh-CN、en-US、ja-JP、ko-KR、de-DE），挑最接近你希望 agent 用的语言即可。

TradingAgentsGraph.propagate 也接受一个可选的 on_message callback（Callable[[AnyMessage], None]），每收到一则 streamed LangGraph 消息就会调用一次 — 想接自己的 renderer 时很好用，内置的 CLI / TUI 也是用这个 hook 来喂 Rich panel。

llm_provider 是 langchain.chat_models.init_chat_model 的 registry key（openai、anthropic、google_genai、xai、openrouter、ollama、huggingface、litellm)；deep_think_llm / quick_think_llm 则填该 provider 接受的 model name(gpt-5、claude-sonnet-4-6、gemini-3-pro-preview、grok-4 等）。

response_language 可控制所有 agent prompt 要求的回复语言。没有 exchange suffix 的 ticker 会自动通过 Yahoo Finance Search 解析。台股请直接传股票代码，例如 2330、2408、8069；也支持明确的 Yahoo Finance symbol，例如 2330.TW、8069.TWO、AAPL、TSM。

config = TradingAgentsConfig(
    llm_provider="openai",
    deep_think_llm="gpt-5",
    quick_think_llm="gpt-5-mini",
    max_debate_rounds=1,
    max_risk_discuss_rounds=1,
    max_recur_limit=100,
    response_language="zh-TW",
)

ta = TradingAgentsGraph(config=config)
_, decision = ta.propagate("2330", "2024-05-10")

📁 项目结构

src/
└── tradingagents/
    ├── agents/           # Agent 实现
    │   ├── analysts/     # 市场、新闻、社交、基本面分析师
    │   ├── managers/     # 研究 & 投资组合管理者
    │   ├── researchers/  # 多头 & 空头研究员
    │   ├── risk_mgmt/    # 风险管理 Agents
    │   ├── trader/       # 交易员 Agent
    │   └── utils/        # 共用 Agent 工具
    ├── dataflows/        # yfinance 数据采集
    ├── graph/            # LangGraph 交易图配置
    ├── interface/        # CLI / TUI 实现
    │   ├── cli.py        # fire 驱动的 flag runner（run_cli）
    │   ├── tui.py        # questionary 驱动的交互式 runner（run_tui）
    │   ├── display.py    # rich 版的 LangChain message renderer
    │   └── help.py       # 取代 fire pager 的 rich help
    ├── llm.py            # Chat model 构造（init_chat_model wrapper + reasoning_effort mapping）
    ├── config.py         # TradingAgentsConfig schema 与全局 singleton
    ├── __init__.py       # Top-level public API（TradingAgentsConfig、TradingAgentsGraph）
    └── __main__.py       # Console script 入口（fire dispatcher 加 rich help）

🤖 Agent 工作流程

TradingAgents 通过 LangGraph StateGraph 编排 12 个 LLM agent 加上 2 个支持组件，每次执行会依序跑过 4 个 phase，所有状态（各类 report、debate transcript、trade decision）都通过一个共用的 Pydantic AgentState 在所有节点之间传递。

Phase 1 — 分析师团队（数据采集）

四位 analyst 依序执行。每位 analyst 的 LLM 都会 bind_tools(...) 到一组以 yfinance 为 backend 的 @tool 函数，并与其专属的 ToolNode 配对，持续 loop 直到没有新的 tool call 为止。每位 analyst 结束之后会经过一个 Msg Clear node，它会发出 RemoveMessage 并补上一个 HumanMessage("Continue") placeholder（这是为了维持 Anthropic 对最后一则消息必须是 human 的要求）。

Analyst	LLM 绑定的 tools	写入 state
Market Analyst	`get_stock_data`, `get_indicators`	`market_report`
Social Media Analyst	`get_news`	`sentiment_report`
News Analyst	`get_news`, `get_global_news`	`news_report`
Fundamentals Analyst	`get_fundamentals`, `get_balance_sheet`, `get_cashflow`, `get_income_statement`	`fundamentals_report`

Market Analyst 可挑选的 technical indicator（一次最多 8 个）：close_50_sma、close_200_sma、close_10_ema、macd、macds、macdh、rsi、boll、boll_ub、boll_lb、atr、vwma。

Phase 2 — 研究辩论

Bull Researcher 与 Bear Researcher 会按照 max_debate_rounds（默认为 1，等于双方各讲一轮）互相辩论，依据 "上一位发言者是谁" 决定下一个轮到谁。每位 researcher 会先用自己的 FinancialSituationMemory 做 BM25 retrieval，把 top-k 的过往经验灌进 prompt 再开讲。
终止条件：当 count >= 2 * max_debate_rounds 时，graph 会 route 到 Research Manager（deep-thinking LLM），由它汇整整场辩论、产出 investment_plan，并填入 investment_debate_state.judge_decision。

Phase 3 — Trader

Trader（quick-thinking LLM）会读取 investment_plan 以及来自 trader_memory 的 top-k 历史经验，输出 trader_investment_plan。它的输出必须以 FINAL TRANSACTION PROPOSAL: **BUY/HOLD/SELL** 结尾。

Phase 4 — 风险辩论

三位 risk debator 以固定顺序轮流发言：Aggressive → Conservative → Neutral → Aggressive → …，循环 max_risk_discuss_rounds 轮（默认为 1，代表每种立场各发言一次）。终止条件：当 count >= 3 * max_risk_discuss_rounds 时，graph route 到 Risk Judge（由 create_risk_manager 建立的 deep-thinking LLM），由它修正 trader 的计划并写入 final_trade_decision。最后再由一个轻量的 SignalProcessor LLM 把这段自然语言决策抽成单一 token — BUY / SELL / HOLD。

支持组件

FinancialSituationMemory — 采 BM25Okapi 做 retrieval，整个流程共有 5 个 instance（bull、bear、trader、invest_judge、risk_manager）。纯 lexical 相似度，不需要任何 embedding API。
Reflector — 交易结果出炉之后，调用 TradingAgentsGraph.reflect_and_remember(returns_losses) 会针对 5 个 memory 各跑一轮 post-trade reflection，把这次的成败写回对应的 memory 供之后 retrieval 使用。

流程示意

START
  │
  ▼
[Market Analyst ⇄ tools_market] → Msg Clear
  │
  ▼
[Social Analyst ⇄ tools_social] → Msg Clear
  │
  ▼
[News Analyst ⇄ tools_news] → Msg Clear
  │
  ▼
[Fundamentals Analyst ⇄ tools_fundamentals] → Msg Clear
  │
  ▼
[Bull Researcher ⇄ Bear Researcher] × max_debate_rounds
  │
  ▼
Research Manager  →  Trader
                        │
                        ▼
[Aggressive → Conservative → Neutral] × max_risk_discuss_rounds
  │
  ▼
Risk Judge  →  SignalProcessor  →  END

每次执行的 log 会写入 results/<股票代码>/：full_states_log_<股票代码>_<日期>.json、conversation_log_<股票代码>_<日期>.txt、conversation_log_<股票代码>_<日期>.json（base path 由 TradingAgentsConfig.results_dir 决定，默认为 ./results）。

🤝 贡献

有关开发说明（包含文档、测试和 Docker 服务等），请参阅 CONTRIBUTING.md。

欢迎 Issue/PR
请遵循代码风格（ruff、类型）
PR 标题遵循 Conventional Commits

📄 授权

MIT — 详见 LICENSE。