LangChain 금융 데이터에 Narwhal API 사용하기

설정할 내용

LangChain은 에이전트를 Narwhal의 읽기 전용 MCP 도구에 연결하며, 결과물은 데이터 영역마다 질문하는 Python 스크립트입니다. 연결에는 도구를 불러오는 langchain-mcp-adapters와 에이전트를 만드는 langgraph.prebuilt의 create_react_agent를 씁니다. Narwhal은 데이터 API 전반에 하나의 계정과 하나의 API 키를 쓰고, REST와 MCP가 그 키를 공유합니다. 스크립트는 Authorization: Bearer YOUR_KEY 헤더로 https://api.narwhalapi.com/mcp에 연결합니다. 프롬프트는 평범한 질문이며, 어떤 도구를 호출할지는 에이전트가 고릅니다.

API 키 설정

1. 무료 키 만들기 narwhalapi.com/signup에서 무료 키를 만드세요. 스크립트의 MCP 연결에 이 Narwhal 키를 쓰며, 같은 키를 REST API에도 쓸 수 있습니다.
2. 환경 변수에 키 저장하기 키를 NARWHAL_API_KEY라는 환경 변수에 보관하세요. 명령을 입력하기 전에 YOUR_KEY를 본인의 키로 바꾸고, 그 환경에서 스크립트를 시작하세요. Python 연결 코드는 이 변수를 읽어 Bearer 헤더를 만듭니다.
   Narwhal 키 보관하기

   export NARWHAL_API_KEY="YOUR_KEY"

코드로 데이터 가져오기

MCP 연결은 전송 방식으로 streamable_http를 씁니다. MultiServerMCPClient가 서버 URL과 인증 헤더를 보관하고, get_tools()가 읽기 전용 도구를 에이전트에 제공합니다. 스크립트에서는 질문 텍스트와 연결 설정이 분리되어 있어서, URL은 클라이언트 설정에 두고 각 사용자 메시지는 PROMPTS에서 가져옵니다. 질문에 엔드포인트나 도구 이름을 넣지 않아도 영역에 대해 물어볼 수 있습니다.

1. 패키지 설치하기 MCP 어댑터, LangGraph, 스크립트가 쓰는 모델 통합을 설치하세요. 어댑터는 MultiServerMCPClient를 제공하고, LangGraph는 Narwhal 도구를 호출하는 사전 구성된 에이전트를 제공합니다.
   에이전트 패키지 설치하기

   pip install langchain-mcp-adapters langgraph langchain-anthropic

2. 에이전트 스크립트 저장하기 다음 코드를 agent.py로 저장하세요. await client.get_tools()로 도구를 불러오고, 에이전트를 만든 뒤 PROMPTS의 각 질문을 사용자 메시지로 보냅니다. 출력되는 각 답변은 에이전트가 반환한 마지막 메시지의 내용입니다.

import asyncio, os
from langchain_mcp_adapters.client import MultiServerMCPClient
from langgraph.prebuilt import create_react_agent

PROMPTS = {
    "holidays": "Is 25 December 2026 a public holiday in the United States?",
    "release dates": "When is the US CPI release in November 2026?",
    "economics": "What is the latest US CPI index and its month-on-month change?",
    "commodities": "What is the Brent spot price in dollars a barrel?",
    "FX": "What are the USD/EUR and USD/IDR rates?",
    "predictions": "What are the Fed rate odds for its next meeting?",
}

async def main():
    client = MultiServerMCPClient({
        "narwhal": {
            "transport": "streamable_http",
            "url": "https://api.narwhalapi.com/mcp",
            "headers": {"Authorization": f"Bearer {os.environ['NARWHAL_API_KEY']}"},
        }
    })
    tools = await client.get_tools()
    agent = create_react_agent("anthropic:claude-sonnet-5-5", tools)
    for area, question in PROMPTS.items():
        result = await agent.ainvoke({"messages": [("user", question)]})
        print(area, "->", result["messages"][-1].content)

asyncio.run(main())

1. 에이전트 시작하기 Narwhal 키가 있는 환경에서 저장한 파일을 실행하세요. 다른 질문을 하려면 해당 프롬프트 텍스트를 바꾸면 됩니다. 에이전트가 도구를 고를 수 있도록 프롬프트는 자연어 질문으로 유지하세요.
   저장한 스크립트 실행하기

   python agent.py

영역별 예시는 전체 스크립트와 같은 agent와 PROMPTS를 씁니다. 에이전트를 만든 뒤 main() 안에 예시를 넣으면 해당 영역의 질문을 하고 답변을 출력합니다. 각 예시 옆의 REST URL은 대응하는 데이터 엔드포인트와 그것이 반환하는 응답 필드를 보여 줍니다.

일정에 맞춰 실행하기

cron이나 앱의 스케줄러에서 python agent.py를 실행하고, 스크립트에서 NARWHAL_API_KEY를 사용할 수 있게 하세요. 예약 실행되는 스크립트도 수동으로 실행할 때와 같은 프롬프트 루프를 따릅니다. 스크립트가 시작될 때 에이전트가 물어봐야 할 질문을 PROMPTS에 설정하세요.

도구 호출이 성공할 때마다 키의 크레딧에서 호출 1회가 차감됩니다. 스케줄은 스크립트를 시작할 뿐이고, 어떤 도구를 쓸지는 스크립트 안의 질문에 따라 에이전트가 고릅니다. 예약된 에이전트가 쓸 수 있는 도구를 제한하려면 create_react_agent에 넘기기 전에 도구 목록을 걸러 내세요.

LangChain으로 공휴일 조회하기

2026년 12월 25일이 미국 공휴일인지 물어보세요. 공휴일 도구는 calendars_list_holidays입니다. 대응하는 REST 데이터는 https://api.narwhalapi.com/v1/calendars/holidays/USA/2026이며 holidays를 반환하고, 각 항목에 date와 name이 있습니다. 예시는 PROMPTS의 공휴일 질문을 에이전트에 보냅니다.

result = await agent.ainvoke({
    "messages": [("user", PROMPTS["holidays"])]
})
print(result["messages"][-1].content)

LangChain으로 발표일 조회하기

2026년 11월 미국 CPI 발표가 언제인지 물어보세요. 발표일 도구는 economics_list_releases입니다. 대응하는 REST URL은 https://api.narwhalapi.com/v1/economics/calendar?countries=USA&start_date=2026-11-01&end_date=2026-11-30&limit=100입니다. releases를 읽으면 at, period, topic, status가 있는 항목을 얻습니다. 이 질문은 경제 캘린더에 있는 발표일을 묻는 것입니다.

result = await agent.ainvoke({
    "messages": [("user", PROMPTS["release dates"])]
})
print(result["messages"][-1].content)

LangChain으로 경제 데이터 조회하기

경제 데이터 프롬프트로 미국 CPI 지수와 전월 대비 변동을 물어보세요. CPI 도구는 economics_get_cpi입니다. 대응하는 REST URL https://api.narwhalapi.com/v1/economics/USA/cpi/observations?start=2025-09는 observations를 반환하며, 각 항목에 period와 value가 있습니다. 에이전트는 질문을 받고 답할 도구를 고릅니다. Narwhal 경제 데이터에는 CPI, 인플레이션, GDP, 수익률이 포함됩니다. CPI 응답에서 period는 관측 기간을, value는 관측값을 나타냅니다. 이 프롬프트는 에이전트에게 지수와 전월 대비 변동을 묻습니다.

result = await agent.ainvoke({
    "messages": [("user", PROMPTS["economics"])]
})
print(result["messages"][-1].content)

LangChain으로 원자재 조회하기

Brent 현물 가격을 배럴당 달러로 물어보세요. 현물 가격 도구는 commodities_get_spot_price입니다. 대응하는 REST URL은 https://api.narwhalapi.com/v1/commodities/spot/BRENT/USD이며, 응답에 price 필드가 있습니다. 원자재 현물 코드에는 예를 들어 XAU, XAG, XPT, XPD, XCU, BRENT, WTI가 있습니다.

result = await agent.ainvoke({
    "messages": [("user", PROMPTS["commodities"])]
})
print(result["messages"][-1].content)

LangChain으로 환율 조회하기

환율 프롬프트로 USD/EUR과 USD/IDR 환율을 물어보세요. 환율 도구는 fx_get_rates입니다. 대응하는 REST URL https://api.narwhalapi.com/v1/fx/rates/USD?currencies=EUR,IDR는 rates를 반환하며, 각 항목에 currency와 rate가 있습니다. 두 통화쌍은 에이전트에 보내는 같은 질문 안에 들어 있습니다.

result = await agent.ainvoke({
    "messages": [("user", PROMPTS["FX"])]
})
print(result["messages"][-1].content)

LangChain으로 예측 시장 조회하기

예측 시장 프롬프트로 Fed 금리 확률을 물어보세요. 정책 경로 도구는 predictions_get_policy_path입니다. 대응하는 REST URL은 https://api.narwhalapi.com/v1/predictions/policy-paths/federal-reserve입니다. meetings 항목에는 resolves_at, p_cut, p_hold, p_hike가 있어, 회의의 결과 확정 시각과 인하, 동결, 인상 확률을 나타냅니다. 확정 시각으로 그 확률이 어느 회의의 것인지 알 수 있습니다. 예제 질문은 금리 확률을 묻고, 에이전트는 그 질문을 사용자 메시지로 받습니다.

result = await agent.ainvoke({
    "messages": [("user", PROMPTS["predictions"])]
})
print(result["messages"][-1].content)

도구 호출도 요청으로 계산되나요?

네. 요청 사용량은 에이전트가 하는 도구 호출에 따라 정해집니다. PROMPTS에 질문 목록을 넣는다고 해서 에이전트가 그 질문에 어떤 도구를 고를지가 정해지는 것은 아닙니다. 스크립트를 예약 실행할 때는 그 도구 호출분도 감안하세요.

도구를 제한하려면 어떻게 하나요?

get_tools()가 반환한 목록을 이름으로 걸러 낸 뒤 에이전트에 넘기세요. 이름에는 economics_get_cpi, economics_list_releases, calendars_list_holidays, commodities_get_spot_price, fx_get_rates, predictions_get_policy_path가 있습니다. 걸러 낸 목록을 create_react_agent의 tools 인수로 넘기면 에이전트는 선택한 도구만 갖게 됩니다.