LangChain agent API：使用 Narwhal API

藉由 LangChain 和 Narwhal，你可以用自然語言詢問國定假日、發布日期、經濟數據、大宗商品、外匯和預測市場方面的問題。用 API 金鑰透過 MCP 把代理連接到 Narwhal，載入唯讀工具，由代理為每個問題選擇工具。

你將完成的設定

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 中的每個問題作為使用者訊息傳送。印出的每個答案，都是代理回傳的最後一則訊息的內容。
載入 Narwhal 工具，每個領域各問一個問題
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 中。

每次成功的工具呼叫會消耗該金鑰額度中的一次呼叫。排程只負責啟動腳本，用哪些工具由代理根據腳本中的問題來選擇。如果想限制排程代理可用的工具，請在把工具清單傳給 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 查詢預測市場

用預測市場的提示詞詢問聯準會利率的機率。政策路徑工具是 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。把過濾後的清單作為 tools 引數傳給 create_react_agent，代理就只擁有你選定的工具。

發布於 。

後續步驟