Finance Agent

자연어 주식 질문을 커스텀 MCP 서버(yfinance 퀀트 도구)와 뉴스 도구 사이에서 라우팅하는 LangGraph 에이전트로, 직접 만든 평가 세트로 검증했습니다.

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 — "both" 쿼리에 대해 quant + news 출력을 하나의 일관된 답변으로 조정합니다.

"both" 쿼리의 경우 quant와 news가 동시에 실행되며, LangGraph는 synthesize를 실행하기 전에 둘 다 완료될 때까지 대기합니다.

Related MCP server: Yahoo Finance MCP Server

MCP 서버 — 퀀트 도구

각각 단일 질문 형태에 맞춰진 5개의 도구:

도구 설명에는 명시적 부정 사례("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, 그리고 적대적(adversarial). 적대적 사례에는 키워드 함정(quant 질문을 감싼 뉴스 언어)과 거짓 전제 쿼리(설명 전에 검증해야 하는 가격 움직임에 대한 주장)가 포함됩니다.

결과: 15/18 → 18/18 — 두 개의 취약한 티커 문자열 단언을 수정하고 라우터 프롬프트에 거짓 전제 분류 규칙을 추가한 후 달성했습니다.

주요 설계 결정

1. 라우팅 로직으로서의 도구 설명. 모든 도구 설명은 무엇을 처리하지 않는지 명시적으로 밝힙니다. 부정 사례가 없으면 매개변수 형태가 겹치는 도구(예: get_stock_price와 get_price_history_stats는 둘 다 티커 + 날짜 유사 매개변수를 받음)는 LLM 라우터에게 모호합니다.

2. 뉴스는 두 번째 MCP 서버가 아닌 일반 LangGraph 도구로. 처음 직관은 "두 번째 MCP 서버 = 재사용 가능한 빌딩 블록"이었습니다. 여기에 대해 질문을 던졌습니다: 무엇을 위해 재사용 가능한가? 구체적인 두 번째 소비자가 존재하지 않았습니다. 두 번째 MCP 서버는 실행하고 관리할 두 번째 하위 프로세스를 의미합니다. 일반 @tool은 단일 프로세스 내 함수입니다. 프로세스 경계 오버헤드에 상응하는 이점이 없었습니다.

3. 라우터는 의도를 분류하고, 에이전트가 도구를 선택합니다. 라우터는 3방향 분류만 수행합니다. 어떤 quant 도구를 호출할지 선택하지 않습니다. LLM 도구 선택(쿼리를 5개 도구 설명 중 하나에 매칭)은 유연하고 비결정적인 작업으로, 라우터 프롬프트에 중복해서 넣지 않고 quant ReAct 루프 내부에 속합니다.

4. 합성은 연결이 아니라 조정이어야 합니다. 합성 프롬프트는 모델에게 quant 데이터와 뉴스 맥락을 하나의 일관된 답변으로 연결하도록 명시적으로 지시합니다. "둘을 따로 나열하지 말고 연결하세요." 이것이 없으면 "both" 경로는 실제 답변이 아니라 두 단락을 겹쳐 놓은 결과를 만듭니다.