Finance Agent

一个 LangGraph 智能体，在自定义 MCP 服务器（yfinance 量化工具）和新闻工具之间路由自然语言股票问题，并通过手工构建的评估集进行验证。

构建目的是弥补两项技能差距：设计 MCP 服务器（工具表面、描述即路由逻辑）以及具备路由判断的智能体编排。

架构

User Query
    │
    ▼
┌─────────┐
│  route  │  3-way classifier: quant / news / both
└────┬────┘
     │
     ├──────────────────────┬─────────────────────
     ▼                      ▼
┌─────────┐           ┌──────────┐
│  quant  │           │   news   │
│ (ReAct) │           │  (ReAct) │
└────┬────┘           └────┬─────┘
     │                     │
     └──────────┬───────────┘
                │
        ┌───────┴────────┐
        │                │
        ▼                ▼
┌──────────────┐   ┌───────────┐
│finish_single │   │ synthesize│
│   _source    │   │           │
└──────┬───────┘   └─────┬─────┘
       │                 │
       └────────┬─────────┘
                ▼
             Answer

节点：

• route — 对查询进行分类；不调用工具，仅做决策

• quant — 带 5 个 MCP 工具的 ReAct 智能体；根据问题选择合适的工具

• news — 带 get_recent_news 的 ReAct 智能体；处理新闻/背景类问题

• finish_single_source — 单路径查询的直通节点；将结果提升为 answer

• synthesize — 将 quant 和 news 的输出整合为针对“both”查询的统一答案

对于 "both" 查询，quant 和 news 并发运行；LangGraph 会等待两者都完成后再执行 synthesize。

Related MCP server: Yahoo Finance MCP Server

MCP 服务器 — 量化工具

五个工具，每个工具针对一种问题形态：

工具描述包含明确的否定用例（“不适用于 X，X 属于工具 Y”）——这是必需的，因为多个工具的参数形态相似，否则路由器会难以区分。

设置

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env  # add your ANTHROPIC_API_KEY

用法

python -m agent.graph "What's Tesla's P/E ratio?"
python -m agent.graph "Why did NVDA drop this week?"
python -m agent.graph "Has AMZN's stock kept pace with its revenue growth?"

评估

pytest evals/test_agent.py -v

18 个查询，涵盖四类：quant、news、both 和对抗性。对抗性用例包括关键词陷阱（用新闻语言包装量化问题）和错误前提查询（关于价格变动的断言，必须先验证再解释）。

结果：15/18 → 18/18，在修正了两个脆弱的 ticker 字符串断言，并向路由器提示词添加了错误前提分类规则之后。

关键设计决策

1. 工具描述即路由逻辑。 每个工具描述都明确说明它不处理什么。如果没有否定用例，参数形态重叠的工具（例如 get_stock_price 和 get_price_history_stats 都接受 ticker + 日期类参数）会让 LLM 路由器感到困惑。

2. 新闻作为普通 LangGraph 工具，而非第二个 MCP 服务器。 直觉是“第二个 MCP 服务器 = 可复用的构建块”。但深入思考：可复用于什么？没有具体的第二个消费者存在。第二个 MCP 服务器意味着需要启动和管理第二个子进程；而普通 @tool 只是一个进程内的函数。进程边界的开销没有对应的收益。

3. 路由器分类意图，智能体选择工具。 路由器只做三分类——它不选择调用哪个量化工具。LLM 工具选择（将查询匹配到 5 个工具描述之一）是灵活/非确定性的工作，应属于 quant ReAct 循环内部，而不是重复到路由器提示词中。

4. 综合必须调和，而非拼接。 综合提示词明确指示模型将量化数据和新闻背景连接成一个连贯的答案。“不要只是分别列出两者——将它们连接起来。”没有这一点，“both”路径会产生两段拼接在一起的文字，而不是真正的答案。