ربط LangChain API بوكيل يقرأ بيانات Narwhal

استخدم LangChain مع Narwhal لطرح أسئلة بلغة طبيعية عن الإجازات الرسمية ومواعيد الإصدار والبيانات الاقتصادية والسلع وأسعار الصرف وأسواق التنبؤ. اربط وكيلك بـ Narwhal عبر MCP بمفتاح API الخاص بك، وحمّل الأدوات للقراءة فقط، ودع الوكيل يختار الأداة لكل سؤال.

ما الذي ستعدّه

يربط LangChain وكيلك بأدوات MCP للقراءة فقط في Narwhal، وستحصل على سكربت Python يطرح سؤالًا عن كل مجال من مجالات البيانات. يستخدم الاتصال langchain-mcp-adapters لتحميل الأدوات وcreate_react_agent من langgraph.prebuilt لبناء الوكيل. لدى Narwhal حساب واحد ومفتاح API واحد عبر واجهات البيانات، ويشترك REST وMCP في هذا المفتاح. يتصل السكربت بـ https://api.narwhalapi.com/mcp مع ترويسة Authorization: Bearer YOUR_KEY. والأوامر أسئلة عادية، ويختار الوكيل الأداة التي يستدعيها.

اضبط مفتاح API الخاص بك

  1. أنشئ مفتاحًا مجانيًا أنشئ مفتاحك المجاني من narwhalapi.com/signup. استخدم مفتاح Narwhal هذا لاتصال MCP في السكربت؛ ويعمل المفتاح نفسه أيضًا مع REST API.
  2. احفظ المفتاح في بيئة التشغيل احتفظ بمفتاحك في متغير بيئة اسمه NARWHAL_API_KEY. استبدل YOUR_KEY بمفتاحك قبل إدخال الأمر، ثم شغّل السكربت من تلك البيئة. يقرأ اتصال Python هذا المتغير لتكوين ترويسة Bearer.
    احفظ مفتاح Narwhal
    export NARWHAL_API_KEY="YOUR_KEY"

اسحب البيانات بالكود

يستخدم اتصال MCP النقل streamable_http. يحتفظ MultiServerMCPClient بعنوان الخادم وترويسة التفويض، وتزوّد 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 المجاور لكل مثال نقطة نهاية البيانات المقابلة وحقل الاستجابة الذي تعيده.

شغّله وفق جدول

شغّل python agent.py من cron أو من جدولة تطبيقك، مع إتاحة NARWHAL_API_KEY للسكربت. يتبع السكربت المجدول حلقة الأوامر نفسها كما في التشغيل اليدوي. اضبط الأسئلة في PROMPTS على ما تريد أن يطرحه الوكيل عند بدء السكربت.

يخصم كل استدعاء أداة ناجح استدعاءً واحدًا من رصيد مفتاحك. تبدأ الجدولة السكربت فقط، ويختار الوكيل الأدوات استجابةً للأسئلة الموجودة فيه. وإذا أردت تقييد الأدوات التي يستخدمها الوكيل المجدول، فصفِّ قائمة الأدوات قبل تمريرها إلى create_react_agent.

الإجازات الرسمية مع LangChain

اسأل هل 25 ديسمبر 2026 إجازة رسمية في الولايات المتحدة. أداة الإجازات هي 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

اسأل متى يصدر CPI الأمريكي في نوفمبر 2026. أداة مواعيد الإصدار هي 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 والتضخم والناتج المحلي الإجمالي والعوائد. في استجابة 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. مرّر القائمة المصفّاة وسيطَ الأدوات إلى create_react_agent ليملك الوكيل الأدوات التي اخترتها.

نُشر في .

الخطوات التالية