金融研究 AI Agent v1：架构与实现

Finance Research AI Agent v1: Architecture and Implementation

版本: v1.0 日期: 2026-10-26 作者: MomoFinance Architecture Team 适用读者: AI 产品经理、AI 架构师、金融科技工程团队、独立投研人员 License: 内部技术文档

---

摘要 (Executive Summary)

本文记录了 Finance Research AI Agent v1 的完整设计与实现。该系统是一个面向 buyside 研究员、独立投资人与小型 FOF 的多 Agent 金融研究工具，能跨越 TradFi 与 Crypto 两个数据域，主动调用财报、链上数据、新闻和合规数据库完成深度研究任务。

核心特征：

• 5 Agent 协作架构（Coordinator + Macro/Equity/Crypto/Compliance）
• 17 个工具，覆盖 Yahoo / SEC EDGAR / FRED / Etherscan / Dune / Coingecko / DeFiLlama / OFAC / Tavily
• LangGraph 状态机 + Anthropic 原生 tool use + Voyage finance-2 embedding + Cohere rerank-3
• Hybrid RAG（BM25 + 向量 + Cohere rerank），Qdrant 自部署
• 三层 Memory（Redis session / Mem0 long-term / Postgres procedural）
• 三层 Guardrails（input scan / 工具 sandbox / output scrub + disclaimer）
• 三层 Eval（PR-级 30 cases / 每日 100 cases / 每周 30 红队）
• 全云端 LLM（Claude Opus 4.7 + Sonnet 4.6 + Haiku 4.5），按场景路由

v1 目标 metric：

• 中位 latency 22s，p95 <30s
• 中位 cost $0.05-0.10/query
• 30 条 golden test pass rate ≥85%（基于内测）
• hallucination rate <5%

部署模式：Docker compose + FastAPI + Redis + Qdrant + Elasticsearch + Langfuse cloud。

---

目录

• 第 1 章 项目概览
• 第 2 章 产品定位
• 第 3 章 系统架构
• 第 4 章 多 Agent 设计
• 第 5 章 RAG 实施细节
• 第 6 章 Memory 策略
• 第 7 章 Eval 体系
• 第 8 章 Cost 与 Latency 优化
• 第 9 章 Safety 与 Guardrails
• 第 10 章 部署与运维
• 第 11 章 评估结果（v1）
• 第 12 章 经验教训
• 第 13 章 路线图
• 附录 A 完整 API 规范
• 附录 B 关键 prompt 模板
• 附录 C 工具 schema 索引

---

第 1 章 项目概览

1.1 项目动机

1.1.1 行业痛点

当下金融研究领域的几大主流工具呈现出鲜明的分化：

中间地带——跨 TradFi 与 Crypto、有主动 agent 能力、价格友好 的研究工具——是空缺的。

1.1.2 我们的位置

              Bloomberg          AlphaSense          Perplexity         OURS
TradFi深度       ★★★★★             ★★★★               ★★                 ★★★
Crypto/Onchain   ★                ★                  ★★                 ★★★★
主动Agent        ★★               ★★                 ★                  ★★★★★
跨资产桥接       ★★               ★                  ★                  ★★★★
价格友好         ★                 ★★                 ★★★★★              ★★★★

我们 v1 不追求超越 Bloomberg 的 TradFi 数据深度（那需要 $1500+/月 的 CapIQ 加上 Refinitiv 等数据源）。我们押注跨域桥接 + 主动 agent：让一个研究员对一句问题"BlackRock BUIDL 与传统货币基金对比"得到完整研究，而不是要在 5 个工具之间跳转。

1.2 v1 范围

包含

• 5 个核心 Agent（Coordinator + 4 specialist）
• 17 个工具（Yahoo / EDGAR / FRED / Etherscan / Dune / Coingecko / DeFiLlama / OFAC / Tavily / 计算器 / RAG）
• Hybrid RAG over SEC filings（前 SP500 公司）+ DeFi 白皮书 corpus
• CLI + REST API
• 30 条 golden test
• 基础 guardrails（input scan + output disclaimer）
• Langfuse trace 集成
• Anthropic prompt caching

不包含（留给后续版本）

• Web UI（Next.js）— v1.1
• Long-term watch（定时 polling）— v1.1
• Telegram bot — v1.1
• Portfolio attribution（Brinson/Fama-French）— v1.2
• Multi-tenant + RBAC — v1.5
• Self-host LLM fallback — v1.5

1.3 文档来源

本架构文档基于 56 天连续学习（Day 121-176）的实战累积：

• Day 121-134：LLM 基础（Transformer/Decoder/Attention）+ Prompt Engineering（CoT/ToT/Few-shot）
• Day 135-148：RAG 进阶（Hybrid retrieval / Multi-vector / HyDE / RAGAS / 财报抽取）
• Day 149-162：Agent 架构（ReAct / MCP / LangGraph / Memory / Function Calling 错误处理）
• Day 163-176：LLMOps（vLLM / 推理优化 / Cost / Eval / Langfuse / Safety / Red Teaming）

每一个组件背后都有过去 56 天某一天对应的笔记与代码原型。

---

第 2 章 产品定位

2.1 一句话定位

「为 buyside 研究员与独立投资人服务的、能跨 TradFi 与 Crypto 的、带主动调研能力的 AI 研究助理。」

英文版本：

"An AI research copilot that bridges TradFi and Crypto, with proactive investigation capabilities, built for buyside researchers and independent investors."

2.2 目标用户与典型场景

用户 Persona 1：Sarah（30 岁，多空对冲基金 PM）

• 背景：管理 $200M AUM，主要标的为美股科技 + 部分 crypto/RWA。
• 日常：早上 7am 看 Bloomberg、9:30am-4pm 盯盘、晚上写交易日记。
• 痛点：科技股研究需要 Bloomberg + AlphaSense + 自己的 Excel 模型，对 BlackRock BUIDL / Ondo USDY 等 RWA 标的没有合适工具。
• 典型 query：
  • "对比 NVDA 和 AVGO 最近 3 季度的 GenAI 业务披露和增长率"
  • "BUIDL 链上前 5 大持仓地址是谁？过去一周转账模式有变化吗？"
  • "美 10Y 利率破 5.0% 后，BTC 与 SPX 的 30-day rolling correlation 走势"

用户 Persona 2：Mike（38 岁，crypto-native 独立 trader）

• 背景：自营 trading $5M，活跃 Twitter（@maxis_finance），写月度 Substack。
• 日常：链上扫合约、OnchainOG / Lookonchain / Arkham 交叉验证、推特发现一手。
• 痛点：每次发现新协议都要：手动读 doc、跑 Dune、跨平台拼数据，30 分钟起。
• 典型 query：
  • "Pendle 最近 30 天 PT/YT 的 fixed yield 和 implied APY 走势"
  • "EigenLayer LRT 协议中 Restaking 集中度变化"
  • "EtherFi 上周新增的 Operator 是谁？有 OFAC 风险吗？"

用户 Persona 3：Liu（45 岁，香港小型 FOF 资产配置者）

• 背景：管理 $50M 多策略 FOF，包括传统股债 + crypto + RWA。
• 日常：月度 review、季度 reallocation、合规 due diligence。
• 痛点：跨资产 portfolio 归因 / 合规审查 / 风险预警需要多工具拼凑。
• 典型 query：
  • "上传 portfolio.csv，给出过去 30 天 P&L 归因"
  • "0xabc... 这个钱包是否在 OFAC SDN 上？资金来源是哪里？"
  • "如果美 10Y 上行 25bp，我组合的 60/40 部分预期回撤多少？"

2.3 用户故事（User Stories）

Story 1：宏观研究

As a buyside macro 研究员 I want 一句话提问"美联储加息后 3 个月，2Y/10Y 利差与 BTC 走势相关性"，agent 自动拉数据并出结论 So that 我不用花 2 小时在 Bloomberg + Excel 拼图

Story 2：单标的深度研究

As an equity 研究员 I want 输入"NVDA Q3 GenAI 业务质地变化，对比 AMD 同口径" So that 我能在 30 分钟内做完原本半天的研究

Story 3：Portfolio 复盘

As a FOF 配置者 I want 上传 CSV，agent 给出 30 天归因 + 文字总结 So that 月度 review 自动化 80%

Story 4：快讯监控

As a crypto 研究员 I want 设置长期 watch："任何 BUIDL/USDY 相关新闻或链上活动" So that 关键事件 5 分钟内拿到结构化推送

Story 5：合规审查

As a 小型基金合规官 I want 输入钱包地址，agent 给制裁/合规报告 So that 5 分钟完成 due diligence 而不是 5 小时

Story 6：跨资产对比

As a macro PM I want 对比 SPX/IEF/GLD/BTC/BUIDL 的 Sharpe / max drawdown / correlation So that 快速建立资产配置 baseline

Story 7：财报会议解读

As an equity 研究员 I want "AAPL FY26Q1 earnings call"，agent 给关键 Q&A 摘要 + 管理层 tone So that 错过 live call 也不错过 alpha

2.4 非功能需求（NFR）

---

第 3 章 系统架构

3.1 总体架构（Layered View）

┌──────────────────────────────────────────────────────────────────────────┐
│                            Layer 0: Client                               │
│   Web UI (Next.js)*  │  Telegram Bot*  │  CLI  │  REST API  │  Webhook* │
└──────────────────────────────────┬───────────────────────────────────────┘
                                   │ HTTPS / SSE streaming
┌──────────────────────────────────┴───────────────────────────────────────┐
│                       Layer 1: API Gateway                               │
│   Kong / Envoy  │  JWT auth  │  Rate limit  │  Cost meter  │  WAF       │
└──────────────────────────────────┬───────────────────────────────────────┘
                                   │
┌──────────────────────────────────┴───────────────────────────────────────┐
│                Layer 2: Guardrails (Input)                               │
│   Prompt-injection scan  │  PII redaction  │  Topic check  │  RAG ACL  │
└──────────────────────────────────┬───────────────────────────────────────┘
                                   │
┌──────────────────────────────────┴───────────────────────────────────────┐
│                  Layer 3: Orchestrator (LangGraph)                       │
│                                                                          │
│       ┌────────────────────────────────────────────────────────┐        │
│       │                Coordinator Agent                        │        │
│       │   (router + planner + final synthesizer; Opus 4.7)     │        │
│       └──────┬──────────────┬──────────────┬─────────┬─────────┘        │
│              │              │              │         │                  │
│       ┌──────▼─────┐  ┌─────▼─────┐  ┌─────▼─────┐ ┌─▼──────────┐       │
│       │ Macro Agt  │  │ Equity    │  │ Crypto    │ │ Compliance │       │
│       │ (Sonnet)   │  │ Agt(Sonnet)│  │ Agt(Sonnet)│ │ Agt(Opus)  │       │
│       └──────┬─────┘  └─────┬─────┘  └─────┬─────┘ └─────┬──────┘       │
│              └──────────────┴──────────────┴────────────┘                │
│                              │                                           │
│                       Shared State (TypedDict)                           │
└──────────────────────────────┬───────────────────────────────────────────┘
                               │ tool calls (Anthropic native + MCP)
┌──────────────────────────────┴───────────────────────────────────────────┐
│                      Layer 4: Tools (MCP Servers)                        │
│                                                                          │
│   ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐│
│   │ Financial    │  │ Onchain      │  │ News         │  │ Calc & Viz   ││
│   │ Data         │  │ Data         │  │ Stream       │  │              ││
│   │ - CapIQ      │  │ - Etherscan  │  │ - Tavily     │  │ - finance    ││
│   │ - FRED       │  │ - Dune       │  │ - NewsAPI    │  │ - matplotlib ││
│   │ - Yahoo      │  │ - Coingecko  │  │ - SeekingAlpha│ │              ││
│   │ - SEC EDGAR  │  │ - DeFiLlama  │  │              │  │              ││
│   └──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘│
└──────────────────────────────┬───────────────────────────────────────────┘
                               │
┌──────────────────────────────┴───────────────────────────────────────────┐
│                      Layer 5: RAG & Memory                               │
│   ┌────────────────┐  ┌────────────────┐  ┌──────────────────────────┐  │
│   │ Vector DB      │  │ BM25 Index     │  │ Memory                   │  │
│   │ Qdrant         │  │ Elasticsearch  │  │ - Mem0 (long-term)       │  │
│   │ Voyage finance-2│  │                │  │ - Chroma (semantic)     │  │
│   │ + Cohere rerank│  │                │  │ - Redis (session)        │  │
│   └────────────────┘  └────────────────┘  └──────────────────────────┘  │
└──────────────────────────────┬───────────────────────────────────────────┘
                               │
┌──────────────────────────────┴───────────────────────────────────────────┐
│                Layer 6: Data Infrastructure                              │
│   Doc Store (S3)  │  Time-series DB (TimescaleDB)  │  Graph DB (Neo4j) │
│   Document Lake: 10-K, 10-Q, transcripts, research notes, whitepapers   │
└──────────────────────────────┬───────────────────────────────────────────┘
                               │
┌──────────────────────────────┴───────────────────────────────────────────┐
│                Layer 7: Eval & Observability                             │
│   Langfuse (traces) │ ClickHouse (logs) │ Prometheus │ Grafana          │
│   Eval harness: 100 golden cases / 30 red-team cases / weekly CI         │
└──────────────────────────────┬───────────────────────────────────────────┘
                               │
┌──────────────────────────────┴───────────────────────────────────────────┐
│                Layer 8: Safety (Output)                                  │
│   PII scrub │ Compliance disclaimer auto-insert │ Output coherence       │
└──────────────────────────────────────────────────────────────────────────┘

* = post-MVP

3.2 LangGraph 状态机

                         START
                           │
                           ▼
                    ┌──────────────┐
                    │ input_guard  │  (injection scan)
                    └──────┬───────┘
                           │
                           ▼
                    ┌──────────────┐
                    │   route()    │  Coordinator: intent + plan
                    └──────┬───────┘
                           │ conditional fan-out
            ┌──────────────┼─────────────┬─────────────┐
            ▼              ▼             ▼             ▼
       ┌────────┐    ┌─────────┐    ┌─────────┐  ┌────────────┐
       │ macro  │    │ equity  │    │ crypto  │  │ compliance │
       │ (Son.) │    │ (Son.)  │    │ (Son.)  │  │  (Opus)    │
       └───┬────┘    └────┬────┘    └────┬────┘  └─────┬──────┘
           │              │              │              │
           └──────────────┼──────────────┴──────────────┘
                          ▼
                   ┌──────────────┐
                   │  synthesize  │  Coordinator: fuse → answer
                   └──────┬───────┘
                          │
                          ▼ conditional (cost / iter cap)
                   ┌──────────────┐         ┌────────┐
                   │ output_guard │ -->     │ abort  │
                   └──────┬───────┘         └───┬────┘
                          │                     │
                          └─────► END ◄─────────┘

3.3 关键序列图：典型 query "BUIDL vs SHV 一周对比"

sequenceDiagram
    participant U as User
    participant API as FastAPI
    participant O as Orchestrator
    participant IG as InputGuard
    participant Co as Coordinator(Opus)
    participant CR as CryptoAgent(Sonnet)
    participant EQ as EquityAgent(Sonnet)
    participant T as Tools
    participant RAG as RAG
    participant OG as OutputGuard
    participant LF as Langfuse

    U->>API: POST /v1/query
    API->>O: run_query
    O->>LF: start trace
    O->>IG: scan_input
    IG-->>O: safe=true
    O->>Co: route()
    Co->>Co: Opus 4.7 routing
    Co-->>O: intent=["crypto","equity"], plan
    par 并行 fan-out
        O->>CR: crypto_node
        CR->>T: get_token_info("buidl")
        CR->>T: get_defi_tvl("buidl")
        CR->>T: query_dune(holders)
        T-->>CR: aggregated data
        CR-->>O: sub_results[0]
    and
        O->>EQ: equity_node
        EQ->>T: get_stock_price("SHV","1mo")
        EQ->>RAG: parse_filing(SHV, factsheet)
        RAG-->>EQ: chunks
        EQ-->>O: sub_results[1]
    end
    O->>Co: synthesize
    Co->>Co: Opus fuse
    Co-->>O: answer
    O->>OG: scrub_output (advice scrub + disclaimer)
    OG-->>O: final answer
    O->>LF: end trace, score
    O-->>API: result
    API-->>U: JSON

3.4 数据流（Data Flow）

---

第 4 章 多 Agent 设计

4.1 为什么用多 Agent

决策矩阵

加权得分：多 agent 显著占优。

关键论据

1. 上下文压缩：单 agent 的 system prompt 必须包含全部 17 个工具的 schema，token 数约 5K。多 agent 把工具按域切分，equity agent 只看 5 个工具 schema（约 1.5K token），单次调用 input 节省 ~70%。

2. 专业化 prompt：宏观研究的提问方式（时间序列、相关性、政策影响）和链上研究（地址、合约、交易模式）截然不同。单 agent 的"通才 prompt" 必然两边都不深；多 agent 各自专精，prompt 可以优化到 5-10 轮迭代。

3. 并行：典型跨域 query 的 sub-agents 可以并行。在 LangGraph 中，conditional edge 自动 fan-out，asyncio 在底层处理 I/O 并发。本项目实测 BUIDL vs SHV 跨域 query 从串行 ~34s 降到并行 ~22s，节省 35%。

4. 独立 eval 与 ownership：每个 agent 有自己的 golden test 子集（equity 8 cases / crypto 7 cases / macro 5 cases / compliance 5 cases / cross 5 cases）。组织上可以让"金融数据 team"维护 equity agent，"crypto team"维护 crypto agent。

4.2 5 个 Agent 详解

4.2.1 Coordinator

关键 prompt（精简）

Routing system：

You are the Coordinator of a financial research multi-agent system.

Sub-agents available: macro, equity, crypto, compliance.

Output strict JSON:
{ "intent": ["macro","equity"], "plan": "..." }

Rules:
- Multi-agent for cross-asset queries.
- Always include compliance for wallet addresses or contracts.
- JSON only, no prose.

Synthesize system：

You are the Coordinator in synthesizer mode. Below are sub-agent results.

Tasks:
1) Combine into a coherent answer.
2) Cite each fact by (agent, tool).
3) Flag conflicts explicitly.
4) NEVER fabricate numbers.
5) Default 200-400 words; bullets for comparisons.
6) Research framing only - no advice.

Conflict handling

如果 Equity agent 和 Crypto agent 给出冲突结论（例如 BUIDL 的 yield 一个说 5.10%、一个说 4.85%），Coordinator 用以下策略：

1. 检查数据时间戳，取最新
2. 检查数据源可靠度（CapIQ > Coingecko > 自计算）
3. 如果都接近，输出范围 + 解释偏差来源
4. 如果差距大且无法判断，明确给出"两源数据冲突"+ 双方数字

4.2.2 Macro Agent

典型 query：

• "美联储 11 月议息后 BTC 与 SPX 30-day correlation"
• "中国 PMI 反弹对铜价影响"
• "10Y 利率破 5.0% 后 60/40 portfolio 模拟"

4.2.3 Equity Agent

核心场景：单标的深度研究、同业对比、估值口径。

关键设计：parse_filing 用 RAG 而不是直接读全文。理由是：

• 10-K 全文 ~100K token，全塞进上下文成本高
• 但全文 RAG 又可能漏关键章节
• 折中：按 SEC 规定的 Item 编号（Item 1A Risk Factors / Item 7 MD&A）做 metadata-aware chunking + 段落级 retrieval

4.2.4 Crypto Agent

关键挑战：链上数据"原始" 程度高，需要多次组合调用：

• query_dune 一次拉前 100 holders
• 对前 5 holders 各调用一次 get_eth_balance + get_eth_txs
• 这就是 1 + 10 = 11 次 tool call，所以 max_iters 给到 8（其中 1 次拉 holders + 多个并行 balance queries 算 1 turn）

4.2.5 Compliance Agent

为什么用 Opus 而不是 Sonnet：合规误判（false negative）的代价极高（监管罚款百万级），所以这里不省钱。

核心流程：

1. check_ofac_sdn(target)
   → 如直接命中：HIGH RISK 退出
2. trace_funds(target, depth=2)
   → 检查上游 2 跳
3. 对每个上游节点 check_ofac_sdn
   → 任何上游命中：MEDIUM-HIGH RISK
4. 检查是否经过已知 mixer（Tornado Cash, Sinbad, Wasabi）
5. 输出 risk_score 0-100 + reasoning chain

4.3 Agent 间协议

Shared State（TypedDict）

class AgentState(TypedDict):
    # Input
    query: str
    user_id: str
    session_id: str

    # Routing
    intent: list[str]
    plan: str

    # Sub-agent outputs (parallel writes via add reducer)
    sub_results: Annotated[list[dict], add]

    # Final
    answer: str
    citations: list[dict]

    # Cost tracking
    total_input_tokens: int
    total_output_tokens: int
    total_cost_usd: float

    # Iteration safety
    iterations: int

sub_results 标准格式

每个 sub-agent 必须返回：

{
    "agent": "equity",            # agent 名
    "answer": "...",              # 该 agent 的本地最终回答（自然语言）
    "citations": [                # tool 调用记录
        {"tool": "get_financials", "args": {...}, "agent": "equity"},
        ...
    ],
    "iterations": 4,              # 用了几轮
    "cost_usd": 0.034,            # 本 agent 花的钱（可选）
    "data": {...},                # 结构化数据（可选，给下游用）
}

---

第 5 章 RAG 实施细节

5.1 文档语料

v1 语料范围

* AlphaSense API 不开放，v1 用 transcripts.io 替代。

Chunking 策略

财报：按 SEC Item 章节 + 段落 + 800 token cap：

Item 1A. Risk Factors
└── 子章节 1：Cybersecurity
    └── 段落 1
    └── 段落 2
└── 子章节 2：Supply chain
    ...

每个 chunk metadata：

{
    "ticker": "NVDA",
    "doc_type": "10-K",
    "fiscal_year": 2026,
    "item": "1A",          # SEC item number
    "subsection": "Cybersecurity",
    "chunk_idx": 3,
    "page": 24,
    "filing_url": "https://sec.gov/...",
}

Earnings transcripts：按 Q&A 对切，每对一个 chunk：

{
    "ticker": "NVDA",
    "doc_type": "transcript",
    "section": "qa",
    "speaker": "Jensen Huang, CEO",
    "topic": "data center growth",  # 用 LLM 后处理打 tag
    "chunk_idx": 7,
}

DeFi 白皮书：semantic chunking（用 LangChain 的 SemanticChunker）+ section metadata。

5.2 Embedding：Voyage finance-2

为什么 Voyage finance-2

Voyage finance-2 在自测 SP500 financials retrieval benchmark 上比 OpenAI 高 ~12%。这个优势来源于 Voyage 用金融语料专门 fine-tune，对"PE ratio"、"adjusted EBITDA"、"goodwill impairment" 这类金融术语理解更准。

索引流程

from voyageai import Client
from qdrant_client import QdrantClient
from qdrant_client.models import VectorParams, Distance, PointStruct

vc = Client(api_key=...)
qdrant = QdrantClient(url=...)

qdrant.recreate_collection(
    collection_name="finance_docs",
    vectors_config=VectorParams(size=1024, distance=Distance.COSINE),
)

batch = []
for chunk_id, chunk in enumerate(all_chunks):
    if len(batch) >= 128:
        emb = vc.embed([c.text for c in batch],
                       model="voyage-finance-2",
                       input_type="document").embeddings
        qdrant.upsert(collection_name="finance_docs", points=[
            PointStruct(id=c.id, vector=e, payload=c.metadata | {"text": c.text})
            for c, e in zip(batch, emb)
        ])
        batch = []
    batch.append(chunk)

成本估算：500K chunks × ~600 token average × $0.12/1M = $36 一次性。

5.3 Hybrid Retrieval

为什么需要 Hybrid

纯向量：对"PE ratio"、"goodwill impairment" 等概念性 query 强；但对"NVDA"、"$1.2B"、具体股票代码 / 数字这类精确 token 召回弱。

纯 BM25：相反，对精确 token 强，但同义、改写query 召回差。

Hybrid（BM25 + 向量 + RRF）综合两者，nDCG@10 比单独高 ~10%。

实现：Reciprocal Rank Fusion（RRF）

def rrf_merge(bm25_hits: list, vec_hits: list, k: int = 60) -> list:
    """RRF: score(d) = Σ 1/(k + rank_i(d)) over all retrievers."""
    scores = {}
    for rank, h in enumerate(bm25_hits):
        scores[h.id] = scores.get(h.id, 0) + 1 / (k + rank)
    for rank, h in enumerate(vec_hits):
        scores[h.id] = scores.get(h.id, 0) + 1 / (k + rank)
    sorted_ids = sorted(scores.items(), key=lambda x: -x[1])
    return [{"id": id, "rrf_score": s} for id, s in sorted_ids]

Reranker：Cohere rerank-3

RRF top-50 后再用 Cohere rerank-3 取 top-10：

• 输入：query + 50 documents
• 输出：50 个 relevance score（0-1）
• 取 top 10

为什么需要 rerank？因为 BM25 + 向量都是 first-stage retrieval，关注 recall（"宁可多召回也别漏"）；rerank 是 second-stage，关注 precision（在召回集里挑最相关的）。Cohere rerank-3 比 BAAI/bge-reranker-large 在金融领域的 nDCG@10 高约 8%（自测）。

完整 retrieval pipeline

query
  │
  ▼
[HyDE expansion] (可选) - 用 LLM 生成假想答案，再去检索
  │
  ▼
┌─────────────────┐    ┌─────────────────┐
│  BM25 top-50    │    │  Vector top-50  │
│  (Elastic)      │    │  (Qdrant)       │
└────────┬────────┘    └────────┬────────┘
         │                      │
         └──────RRF merge───────┘
                  │
                  ▼ top-50
         ┌────────────────┐
         │ Cohere rerank-3│
         └────────┬───────┘
                  │ top-10
                  ▼
              context

性能 metric（自测，500K chunks 索引上）

总检索延迟 380ms 在金融场景可接受（vs LLM 生成的 8s+）。

5.4 RAG 与长上下文的混合策略

Claude Opus 4.7 支持 1M context。一份 10-K 大约 100K token，理论可全文塞入。

决策树

incoming query
  │
  ▼
RAG retrieve top-10
  │
  ▼
  rerank score top-1 > 0.7?
   │
   ├── YES: 用 RAG 走主流程
   │
   └── NO: query 是否包含 "整份 10-K"、"全文"、"详细列出所有 risk factors" 等全局推理标志？
            │
            ├── YES: fallback 长上下文
            │   └── 把整份 filing 塞入（启用 Anthropic prompt caching，下次调用 90% off）
            │
            └── NO: 维持 RAG，但提示 "RAG confidence 低，结果可能不全"

Anthropic Prompt Caching 加成

长上下文模式开启时，filing 全文（~100K token）作为 cached block：

• 首次调用：100K × $15/1M = $1.50（input cost）
• 后续相同 filing：100K × $1.50/1M = $0.15（cached input cost，90% off）

只要同一个 filing 在缓存 TTL（5min）内被多次访问（例如同一研究 session），平均成本比纯 RAG 还低（因为 RAG 的 LLM call 也要 cost）。

---

第 6 章 Memory 策略

6.1 三层架构

6.2 Session Memory（Redis）

async def append_message(session_id: str, role: str, content: str):
    key = f"session:{session_id}:msgs"
    await redis.rpush(key, json.dumps({"role": role, "content": content}))
    await redis.expire(key, 86400)

async def get_history(session_id: str, limit: int = 20) -> list[dict]:
    key = f"session:{session_id}:msgs"
    raw = await redis.lrange(key, -limit, -1)
    return [json.loads(r) for r in raw]

每次 query 启动时把最近 5-10 条消息注入 Coordinator prompt。

6.3 Long-term Memory（Mem0）

Mem0 用 LLM 主动抽取"事实"：

[user] 我主要研究 RWA 赛道，特别是 BlackRock BUIDL 和 Ondo USDY
[mem0 抽取] {"fact": "user focuses on RWA: BUIDL, USDY", "category": "preference"}

后续每次新 query，Mem0 retrieve 用户相关 facts 注入 system prompt：

This user's known preferences:
- Focuses on RWA tokens: BUIDL, USDY
- Holds 5% portfolio in BTC
- Bearish on US 10Y yield

效果：用户问"分析最近的链上活动"时，Coordinator 自动倾向于 RWA 而不是要用户每次澄清。

6.4 Procedural Memory（研究模板）

某些研究有固定流程，比如"分析任意股票"：

template: equity_full_analysis
steps:
  - tool: get_stock_price
    args: {ticker: "{{ticker}}", period: "1y"}
  - tool: compute_pe_ev_ebitda
    args: {ticker: "{{ticker}}"}
  - tool: get_financials
    args: {ticker: "{{ticker}}", statement: "income", freq: "quarterly"}
  - tool: parse_filing
    args: {ticker: "{{ticker}}", filing_type: "10-K", section: "MD&A"}
  - tool: get_news
    args: {query: "{{ticker}} latest"}
synthesis_prompt: |
  Produce a 1-page equity research note covering:
  - Price action 1y
  - Valuation (PE / EV/EBITDA vs peers)
  - Recent earnings trajectory
  - MD&A highlights
  - Recent news catalysts

Equity agent 检测到"分析 NVDA"这类完整 query 时，可直接套用 template，节省 routing + planning latency。

6.5 Memory 注入策略

每次 Coordinator 启动前：

async def assemble_prompt_context(state: AgentState) -> str:
    # 1. Session history (last 5 turns)
    history = await get_history(state["session_id"], limit=10)

    # 2. Long-term facts (top 5 relevant)
    facts = mem0.search(query=state["query"], user_id=state["user_id"], limit=5)

    # 3. Build context block
    return f"""
## User profile (from long-term memory):
{format_facts(facts)}

## Recent conversation:
{format_history(history)}

## Current query:
{state["query"]}
"""

---

第 7 章 Eval 体系

7.1 三层 Eval

7.2 Golden Test 设计

Schema

@dataclass
class GoldenCase:
    id: str
    query: str
    expected_intent: list[str]      # 必须命中的 intent
    expected_keywords: list[str]    # 答案中必须出现的关键词（≥ 50%）
    must_call_tools: list[str]      # 必须调用的 tools
    must_cite_source: bool          # 是否必须有 citations

30 cases 分布

示例 cases

{"id":"eq-001","query":"What was NVDA's GenAI revenue in Q3 2026?","expected_intent":["equity"],"expected_keywords":["NVDA","data center","revenue"],"must_call_tools":["parse_filing","get_financials"],"must_cite_source":true}
{"id":"eq-002","query":"Compare AAPL and MSFT trailing PE","expected_intent":["equity"],"expected_keywords":["PE","AAPL","MSFT"],"must_call_tools":["compute_pe_ev_ebitda"],"must_cite_source":true}
{"id":"cr-001","query":"What is BUIDL token's onchain TVL trend?","expected_intent":["crypto"],"expected_keywords":["BUIDL","TVL"],"must_call_tools":["get_defi_tvl"],"must_cite_source":true}
{"id":"cr-002","query":"Who are the top 5 holders of USDC on Ethereum?","expected_intent":["crypto"],"expected_keywords":["USDC","holder"],"must_call_tools":["query_dune"],"must_cite_source":true}
{"id":"mc-001","query":"What is the current 10-year treasury yield?","expected_intent":["macro"],"expected_keywords":["10-year","yield"],"must_call_tools":["get_macro_series"],"must_cite_source":true}
{"id":"co-001","query":"Is address 0x... on OFAC SDN?","expected_intent":["compliance"],"expected_keywords":["OFAC"],"must_call_tools":["check_ofac_sdn"],"must_cite_source":true}
{"id":"x-001","query":"Compare BTC and gold returns over past 12 months","expected_intent":["macro","crypto"],"expected_keywords":["BTC","gold","return"],"must_call_tools":["get_token_info","get_macro_series"],"must_cite_source":true}

评分逻辑

async def run_one(case: GoldenCase) -> dict:
    out = await run_query(case.query)
    answer = out["answer"].lower()
    keyword_hit = sum(1 for kw in case.expected_keywords if kw.lower() in answer)
    keyword_pass = keyword_hit >= max(1, len(case.expected_keywords) // 2)
    tool_calls = [c["tool"] for c in out["citations"]]
    tool_pass = all(t in tool_calls for t in case.must_call_tools)
    intent_pass = set(case.expected_intent).issubset(set(out["intent"]))
    return {
        "id": case.id,
        "intent_pass": intent_pass,
        "keyword_pass": keyword_pass,
        "tool_pass": tool_pass,
        "all_pass": intent_pass and keyword_pass and tool_pass,
    }

7.3 Hallucination 检测（LLM Judge）

每条 final answer 用 Opus 做 self-check：

You are a fact-checker. Below is an AI's answer and the trace of tool calls it made.

Answer: {answer}

Tool trace: {citations + tool outputs}

Task: Identify every numeric claim in the answer (e.g. "5.10%", "$520M", "Q3 2026").
For each claim, check whether it appears in the tool trace data.

Output JSON:
{
  "claims": [
    {"text": "...", "found_in_trace": true/false, "source_tool": "..."},
    ...
  ],
  "hallucination_score": 0.0-1.0
}

阈值：单条 hallucination_score > 0.1 标黄；批量平均 > 0.05 阻止 deploy。

7.4 Red Team 30 cases

ASR (Attack Success Rate) 目标：< 10%。

7.5 CI/CD 集成

# .github/workflows/eval.yml
on:
  pull_request:
    paths: ["src/**", "prompts/**", "config.yaml"]

jobs:
  l1-deterministic:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
      - run: pip install -r requirements.txt
      - env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC }}
        run: python -m src.eval.runner --suite=l1
      - run: |
          if [ $(jq '.pass_rate' eval_result.json) -lt 0.8 ]; then
            echo "L1 pass rate < 80%"; exit 1; fi

每日 cron 跑 L2，结果推送到 Slack + Langfuse dashboard。

---

第 8 章 Cost 与 Latency 优化

8.1 成本拆解（典型 query）

以 BUIDL vs SHV query 为例：

上述未启用 caching；启用后 ~$0.094。

8.2 优化手段

8.2.1 Anthropic Prompt Caching（主要省 ~50%）

将 system prompt + tool schemas 标记为 cached。Anthropic 提供 5 分钟 TTL 的 ephemeral cache。

resp = await client.messages.create(
    model="claude-sonnet-4-6",
    system=[{
        "type": "text",
        "text": SYSTEM_PROMPT,
        "cache_control": {"type": "ephemeral"},  # 标记为 cache
    }],
    tools=EQUITY_TOOLS,  # tools 自动 cache
    messages=...,
)

实测每个 sub-agent 的 system+tools 大约 2K token，cache 命中后 input cost 降为：

• Sonnet: 2000 × ($3 - $0.30)/1M = 省 $0.0054 per call
• 一个完整 query 涉及 ~6 次 LLM call → 总省 ~$0.03 / query

注意 Anthropic cache 有最低 1024 token，所以小型 prompt 可能不适合。

8.2.2 模型路由（次要省 ~30%）

按场景路由：

• 简单分类 / 提取 → Haiku 4.5（$0.80/1M in）
• 多步 reasoning + tool use → Sonnet 4.6（$3/1M）
• 路由 + 合成 + 合规 → Opus 4.7（$15/1M）

如果不分级全用 Opus，cost 会翻 5 倍。

8.2.3 Tool 层 Cache（次要）

aiocache TTL：

• Yahoo / FRED：60s
• Etherscan：30s
• Filings：24h（filing 永远不变）
• News：5min

8.2.4 Cost Cap

def loop_check(state) -> Literal["synthesize", "abort"]:
    if state["iterations"] >= 15: return "abort"
    if state["total_cost_usd"] >= 0.50: return "abort"
    return "synthesize"

防止 bug 死循环烧钱。

8.3 Latency 优化

8.3.1 Streaming（首字节 < 3s）

LangGraph 原生支持 SSE：

async for event in COMPILED_GRAPH.astream_events(initial, version="v1"):
    if event["event"] == "on_chat_model_stream":
        chunk = event["data"]["chunk"]
        yield chunk.content  # 推送给前端

8.3.2 并行 fan-out

LangGraph conditional edge 自动并行。BUIDL+SHV query 串行 ~34s，并行 ~22s（节省 35%）。

8.3.3 Tool 内并行

Equity agent 内部一次 LLM turn 可返回多个 ToolUseBlock；用 asyncio.gather 并行执行：

tool_results = await asyncio.gather(*[
    dispatch(tu.name, tu.input) for tu in tool_use_blocks
])

8.3.4 LangGraph Checkpointing（恢复中断）

from langgraph.checkpoint.postgres import PostgresSaver
checkpointer = PostgresSaver.from_conn_string(POSTGRES_DSN)
graph = builder.compile(checkpointer=checkpointer)

任务可在中断后从 last node resume，避免重做。

---

第 9 章 Safety 与 Guardrails

9.1 Defense in Depth（4 层）

[1] API Gateway: rate limit + JWT + WAF
       │
[2] Input guard: injection scan + PII redact + topic check
       │
[3] Tool sandbox: timeout + resource cap + circuit breaker
       │
[4] Output guard: advice scrub + disclaimer + fact-check

9.2 Input Guard

Prompt Injection 检测

正则 + 小模型 dual-check：

INJECTION_PATTERNS = [
    r"ignore (previous|all|prior) instructions",
    r"system:?\s*(prompt|message)",
    r"</?system>",
    r"you are now",
    r"act as",
    r"pretend (you are|to be)",
]

async def scan_input(query: str) -> dict:
    if INJECTION_RE.search(query):
        return {"safe": False, "reason": "injection pattern"}
    # 高敏感场景再加 prompt-guard 86M 小模型 cross-check
    return {"safe": True}

PII Redaction（Microsoft Presidio）

from presidio_analyzer import AnalyzerEngine
from presidio_anonymizer import AnonymizerEngine

analyzer = AnalyzerEngine()
anonymizer = AnonymizerEngine()

def redact_pii(text: str) -> tuple[str, list]:
    results = analyzer.analyze(text=text, language="en")
    anonymized = anonymizer.anonymize(text=text, analyzer_results=results)
    return anonymized.text, [r.entity_type for r in results]

9.3 Tool Sandbox

每个工具有：

• 超时（default 15s，Dune 120s）
• 重试（tenacity backoff）
• 资源 cap（result 大小 1MB）
• Circuit breaker（连续 3 次失败熔断 60s）

9.4 Output Guard

投资建议短语 scrub

ADVICE_PHRASES = [
    r"\byou should (buy|sell|invest|short)\b",
    r"\bguaranteed? returns?\b",
    r"\bwill (rise|fall|moon|crash) (next|tomorrow|soon)\b",
]

def scrub_output(text: str) -> str:
    cleaned = ADVICE_RE.sub("[research note: data shows]", text)
    if DISCLAIMER not in cleaned:
        cleaned += f"\n\n---\n{DISCLAIMER}"
    return cleaned

合规 Disclaimer

每条 final response 自动追加：

Disclaimer: This information is for research purposes only and does not constitute investment advice. Past performance is not indicative of future results.

对 institutional users（API key tier=B），可关闭 disclaimer。

Fact-check 二次确认

可选启用：用 Haiku 跑一次 self-check，如果发现 final response 中数字未在 trace 出现，标记 hallucination 并返回兜底回答。

9.5 Compliance 框架

---

第 10 章 部署与运维

10.1 部署拓扑

v1（小型部署）

┌────────────────────────────────────────────┐
│             Cloudflare WAF + DNS           │
└─────────────────────┬──────────────────────┘
                      │
┌─────────────────────┴──────────────────────┐
│  Single VM (16 vCPU / 32GB / Ubuntu 24.04) │
│  ┌──────────────────────────────────────┐  │
│  │ docker-compose stack:                │  │
│  │  - finance_agent (uvicorn)           │  │
│  │  - qdrant                            │  │
│  │  - elasticsearch                     │  │
│  │  - redis                             │  │
│  │  - postgres                          │  │
│  │  - prometheus + grafana              │  │
│  └──────────────────────────────────────┘  │
│                                            │
│  External: Anthropic / Voyage / Cohere /   │
│            Etherscan / Dune / FRED / Tavily│
└────────────────────────────────────────────┘

成本：

• VM：~$200/月
• LLM/embedding API：~$1500/月（取决于 traffic）
• 数据 API：~$500/月
• 总：~$2200/月

Beta（中等部署，1000+ MAU）

[Cloudflare] → [API Gateway (Kong)] → [3x app pods]
                                          │
                 ┌────────────────────────┼─────────┐
                 ▼                        ▼         ▼
           [Postgres HA]            [Qdrant cluster]  [Redis HA]
           [Elasticsearch x3]       [Langfuse cloud]

10.2 docker-compose.yml

version: "3.9"
services:
  qdrant:
    image: qdrant/qdrant:v1.13.0
    ports: ["6333:6333"]
    volumes: ["./data/qdrant:/qdrant/storage"]
    restart: unless-stopped

  redis:
    image: redis:7.4-alpine
    ports: ["6379:6379"]
    restart: unless-stopped

  elasticsearch:
    image: elasticsearch:8.16.0
    environment:
      - discovery.type=single-node
      - xpack.security.enabled=false
      - ES_JAVA_OPTS=-Xms2g -Xmx2g
    ports: ["9200:9200"]
    restart: unless-stopped

  postgres:
    image: postgres:16
    environment:
      POSTGRES_DB: finance_agent
      POSTGRES_USER: agent
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    ports: ["5432:5432"]
    volumes: ["./data/pg:/var/lib/postgresql/data"]
    restart: unless-stopped

  agent:
    build: .
    env_file: .env
    depends_on: [qdrant, redis, elasticsearch, postgres]
    ports: ["8000:8000"]
    command: uvicorn src.api.server:app --host 0.0.0.0 --port 8000 --workers 4

  prometheus:
    image: prom/prometheus:v3.0
    volumes: ["./ops/prometheus.yml:/etc/prometheus/prometheus.yml"]
    ports: ["9090:9090"]

  grafana:
    image: grafana/grafana:11.4
    ports: ["3000:3000"]
    volumes: ["./data/grafana:/var/lib/grafana"]

10.3 Dockerfile

FROM python:3.12-slim

WORKDIR /app

RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential gcc curl \
    && rm -rf /var/lib/apt/lists/*

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY src/ ./src/
COPY prompts/ ./prompts/
COPY config.yaml ./config.yaml

EXPOSE 8000

HEALTHCHECK --interval=30s --timeout=5s \
  CMD curl -f http://localhost:8000/healthz || exit 1

CMD ["uvicorn", "src.api.server:app", "--host", "0.0.0.0", "--port", "8000"]

10.4 监控

Prometheus metrics

from prometheus_client import Counter, Histogram

QUERY_COUNTER = Counter("agent_queries_total", "Total queries", ["intent"])
QUERY_LATENCY = Histogram("agent_query_seconds", "Query latency", buckets=[1,3,5,10,20,30,60,120])
QUERY_COST = Histogram("agent_query_cost_usd", "Cost per query", buckets=[0.01,0.05,0.1,0.25,0.5,1,2])
TOOL_ERRORS = Counter("agent_tool_errors_total", "Tool errors", ["tool"])

Grafana Dashboards

Dashboard panels：

• QPS（每分钟 query 数）
• Latency p50/p95/p99
• Cost / query distribution
• Tool error rate by tool
• Hallucination rate（来自 daily eval）
• Cache hit rate（Anthropic + tool cache）
• LLM model usage breakdown

告警规则

---

第 11 章 评估结果（v1）

以下数字基于内测 100 query 的估算（标注 estimated）。

11.1 整体性能

11.2 按 query 类型拆分

观察：multi-step research 是最弱环节（pass rate 50%），主要因为：

• max_iters=15 偶有触顶
• 跨多 sub-agent 协调时 conflict resolution 不够
• v1.1 计划：增加 reflection step + raise max_iters to 25

11.3 失败案例分析

随机抽 14 条失败 case：

修复优先级：

• P0：Hallucinated 数字 → 加强 fact-check 二次确认
• P0：Intent 路由错 → 增加 routing eval cases，prompt 修订
• P1：Dune timeout → 加 fallback（dune-client 改成 cached query）

---

第 12 章 经验教训

12.1 做对的事

1. 早早做 golden test：从 day 1 就有 30 条 cases，每次改 prompt 都跑一遍。avoid 了 5 次 prompt regression。

2. 多 agent 而不是单 agent：从一开始就拆，而不是先做单 agent 再拆。中间没有重写代价。

3. MCP 风格的工具抽象：每个工具是独立 dispatch，未来很容易剥离成独立 MCP server。

4. Anthropic prompt caching 用满：cost 降 ~40%。建议任何 production agent 都启用。

5. Voyage finance-2 over generic embedding：金融场景就用金融 fine-tuned model，差距明显。

6. Langfuse trace 一开始就接：debug 多 agent 系统的痛苦，没有 trace 几乎无解。

12.2 走过的弯路

1. CrewAI 试用 1 周：role-playing 模式简单但生产级 debug 难，最终切回 LangGraph，损失约 40 工时。

2. Naive RAG 上线 3 天：单纯 vector retrieval 召回率不行，"NVDA Q3 revenue" 查不到 NVDA 的 10-Q（因为查询词 "Q3" 在向量空间不显眼）。引入 BM25 + Cohere rerank 后 nDCG@10 从 0.71 → 0.91。

3. 没考虑 Dune query timeout：Dune 的复杂 SQL 可以跑 60-120s，初版 timeout 30s 直接失败一半。改成 120s + 异步 polling。

4. Compliance 用 Sonnet 省钱：v0 用 Sonnet 4.6 做合规判断，false positive 率 8%（误判 ~8% 正常地址为高风险）。换 Opus 4.7 后降到 1.5%，cost 翻倍但可接受。

5. 没做 cost cap：v0 没有 per-query cost cap，一次 bug 让 agent 死循环 30 分钟，烧了 $42。立刻加 $0.50 cap。

12.3 反直觉的发现

• 长上下文不一定贵：开启 Anthropic prompt caching 后，复用同一份 10-K 的成本 < RAG（因为 RAG 的多次小 LLM call 也要 cost）。
• 简单 query 用 Haiku 4.5 没显著省钱：因为 simple query 的 token 也少，Sonnet vs Haiku 绝对差额小（< $0.01/query）。Haiku 真正省钱的场景是 batch / 高频小任务。
• Cohere rerank 是性价比之王：从 0.84 → 0.91 nDCG@10，仅增加 ~300ms 延迟和 $0.001/call。

---

第 13 章 路线图

13.1 v1.1（+30 天）

• • Macro Agent + Tavily + 5 个新工具
• • Web UI（Next.js + shadcn/ui）
• • Streaming（SSE 推送 token）
• • Long-term watch（Celery beat 定时 polling）
• • Telegram bot
• • 100 条 golden test 全量
• • Anthropic prompt caching 全面优化

13.2 v1.2（+60 天）

• • Portfolio attribution（Brinson / Fama-French）
• • Visualization（matplotlib → Plotly 交互式）
• • Conversational follow-up（leverage session memory）
• • Reflection step（confidence < 0.6 时二次 plan）

13.3 v1.5（+90 天）

• • Multi-tenant + RBAC
• • Self-host LLM fallback（DeepSeek-V4 routine 路径，cost 降 50%）
• • LoRA fine-tune（Unsloth + Qwen 2.5 7B 做财报抽取专模）
• • SOC 2 Type 1 audit
• • 多语言（中文 prompt 全套）

13.4 v2.0（+180 天）

• • Subgraph 化（compliance trace_funds 独立 LangGraph）
• • MCP server 化（tools/ 拆出独立 server）
• • 端到端 fine-tune coordinator routing model
• • Onchain agent（不只读，能 execute trade）— 需要严格的安全审查

---

附录 A 完整 API 规范

A.1 REST endpoints

POST /v1/query

请求：

{
  "query": "Compare BUIDL and SHV over past week",
  "user_id": "u_abc123",
  "session_id": "s_xyz789",
  "tier": "B"
}

响应：

{
  "query": "...",
  "intent": ["crypto", "equity"],
  "plan": "...",
  "answer": "...",
  "citations": [
    {"tool": "get_token_info", "args": {"symbol_or_id": "buidl"}, "agent": "crypto"},
    ...
  ],
  "sub_results": [
    {"agent": "crypto", "answer": "...", "iterations": 3},
    {"agent": "equity", "answer": "...", "iterations": 2}
  ],
  "total_input_tokens": 18400,
  "total_output_tokens": 2150,
  "total_cost_usd": 0.094,
  "latency_seconds": 22.3,
  "trace_url": "https://cloud.langfuse.com/trace/..."
}

POST /v1/query/stream（SSE）

event: token
data: {"text": "## "}

event: token
data: {"text": "BUIDL"}

event: tool_call
data: {"tool": "get_token_info", "args": {...}}

event: tool_result
data: {"tool": "get_token_info", "result": {...}}

event: done
data: {"total_cost_usd": 0.094, ...}

GET /healthz

{"status": "ok", "version": "1.0.0"}

POST /v1/eval/run（admin）

启动 eval 任务，返回 task_id。

A.2 Auth

JWT bearer token，scope:

• query:read：可发起 query
• eval:run：可触发 eval（admin）
• disclaimer:disable：tier=B 用户可关 disclaimer

A.3 Rate limits

---

附录 B 关键 prompt 模板

B.1 Coordinator routing prompt

You are the Coordinator of a financial research multi-agent system.

Sub-agents available:
  - macro:      macro economy, rates, FX, central bank, inflation
  - equity:     individual stocks, earnings, valuation, fundamentals
  - crypto:     onchain data, DeFi, tokens, DAOs, RWA
  - compliance: sanctions (OFAC), KYC/AML risk, fraud

Output strict JSON:
{
  "intent": ["agent1", "agent2"],
  "plan": "one-sentence plan"
}

Rules:
- For cross-asset queries, invoke multiple agents (e.g. macro+crypto).
- Always include compliance if query mentions specific wallet addresses
  or token contracts.
- Output JSON ONLY. No prose.

Example:
Query: "Compare BUIDL onchain to traditional money market funds"
Output: {"intent":["crypto","equity"],"plan":"Pull BUIDL onchain data + SHV equity data, then compare yields and flows."}

B.2 Coordinator synthesizer prompt

You are the Coordinator in synthesizer mode.

Below are sub-agent results in JSON form. Tasks:
1. Combine into a single coherent answer that directly addresses user's query.
2. Cite each fact by (agent, tool) - e.g. "...per Coingecko (crypto agent)".
3. Flag conflicts between sub-agents and explain.
4. NEVER fabricate numbers - if a sub-agent didn't produce a number, say
   "data unavailable".
5. Be concise: 200-400 words by default. Bullets for comparisons.
6. Research framing only - never give investment advice.

B.3 Equity agent system prompt

You are an equity research analyst agent.

Tools available:
  - get_stock_price (Yahoo, ~5min freshness)
  - get_financials (SEC EDGAR, quarterly/annual)
  - parse_filing (RAG over 10-K/10-Q sections)
  - compute_pe_ev_ebitda (ratios)
  - vector_search (hybrid retrieval over corpus)

Workflow:
  1. Decompose user's question into 1-5 tool calls.
  2. After each tool result, decide: more tools? OR end turn with final
     structured answer.
  3. Final answer JSON: {findings, citations, data}.

Rules:
  - Only use facts from tool outputs. NEVER fabricate numbers.
  - If a tool returns error/empty, say so explicitly.
  - Max 8 tool calls per query.
  - Always include time/period for any number (e.g. "Q3 2026" not "recent").

B.4 Crypto agent system prompt

You are a crypto onchain research agent.

Tools available:
  - get_eth_balance, get_eth_txs (Etherscan)
  - query_dune (custom SQL, up to 10K rows)
  - get_token_info (Coingecko)
  - get_defi_tvl (DeFiLlama)

Workflow:
  1. Identify wallet address(es), token contract(s), protocol(s) from query.
  2. Pull onchain data + price/TVL data + relevant docs in parallel.
  3. Final answer JSON: {findings, citations, data}.

Rules:
  - All onchain data must include block number / timestamp.
  - For tokens, always include contract address + chain.
  - NEVER fabricate balances or TX hashes.

B.5 Compliance agent system prompt

You are a compliance / sanctions / fraud risk agent.

Tools available:
  - check_ofac_sdn (OFAC SDN list lookup)
  - trace_funds (2-hop upstream trace)
  - get_eth_txs

Workflow:
  1. For any wallet/contract:
     a) check_ofac_sdn directly
     b) trace_funds depth=2
     c) for each upstream node, check_ofac_sdn
     d) flag if any path passes through known mixers (Tornado Cash, Sinbad, Wasabi)
  2. Output risk_score 0-100 with reasoning.

Risk scoring guideline:
  - 0-20:  clean, no flags
  - 21-50: indirect link to flagged address (3+ hops)
  - 51-80: 2-hop link, OR mixer interaction
  - 81-100: directly sanctioned OR 1-hop link

NEVER make legal pronouncements. Output is risk research, not legal advice.

B.6 Macro agent system prompt

You are a macro economic research agent.

Tools:
  - get_macro_series (FRED time series)
  - get_news (Tavily)
  - get_stock_price (for indices like SPX, IEF, GLD)
  - compute_correlation

Workflow:
  1. Identify the time series / indices in query.
  2. Pull data with proper start/end dates.
  3. Run correlations or transformations as needed.
  4. Provide structured answer with timestamps.

Rules:
  - Always cite series_id (e.g. "DGS10" for 10Y treasury).
  - Always include date ranges in answer.
  - Use percentage points (pp) for rate spreads, not "%".

---

附录 C 工具 schema 索引

总月度数据成本估算：~$2500/月 中等使用量。

---

致谢

本文是过去 56 天连续学习与实战积累的产物。感谢：

• Anthropic 团队提供的 Claude Opus / Sonnet / Haiku 模型与 prompt caching、tool use 等工程能力
• Voyage AI / Cohere 在 retrieval 上的领先模型
• LangGraph 团队在 multi-agent 编排上的优秀框架
• Langfuse 在 LLM observability 上的开源贡献
• Etherscan / Dune / FRED / SEC EDGAR 的开放数据

---

文档版本

---

End of Document 总长度：约 1700 行 维护者：MomoFinance Architecture Team 相关文档：docs/daily/EXPERT-DAY177.md（设计） / docs/daily/EXPERT-DAY178.md（实现）