ما هو لانججراف؟ دليل بناء وكلاء الذكاء الاصطناعي ذوي الحالة

تبدأ معظم أكواد الوكلاء بسيطة ثم تنهار تحت وطأة محاولاتها المتكررة. تقوم بتوصيل نموذج لغة كبير (LLM)، وتزويده ببعض الأدوات، وفي اللحظة التي يحتاج فيها سير العمل إلى التكرار أو التفرع أو التوقف لتدخل بشري، ينهار السكريبت ذو الخط المستقيم. LangGraph هو الإطار المصمم خصيصًا لهذه الفوضى: فهو يصمم الوكيل كـ "رسم بياني" (Graph) ذي حالة مشتركة، لذا تصبح الحلقات والفروع بنية من الدرجة الأولى بدلاً من عبارات if المتشابكة. يشرح هذا الدليل ماهية LangGraph، والمشكلة التي يحلها، وأين يأتي دور اختبار الـ API عندما يستدعي وكيلك خدمات حقيقية.

ما هو LangGraph

LangGraph هو إطار عمل تشغيلي ومنصة تشغيل منخفضة المستوى لبناء وكلاء طويلين الأمد وذوي حالة. تم بناؤه بواسطة LangChain Inc، الفريق الذي يقف وراء LangChain، ولكنه مكتبة منفصلة لها تركيزها الخاص. يمكنك تثبيتها بمفردها باستخدام pip install -U langgraph، ويمكنك استخدامها بدون باقي منظومة LangChain.

الفكرة الأساسية صغيرة. أنت تصف وكيلك كـ "رسم بياني" (graph). تقوم العقد بالعمل (استدعاء نموذج، تشغيل أداة، تحويل البيانات). تحدد الحواف ما الذي يتم تشغيله بعد ذلك. يتدفق كائن حالة مشتركة عبر كل عقدة، ويمكن لكل عقدة قراءته والكتابة إليه. نظرًا لأن الحواف يمكن أن تشير إلى الخلف، يمكن أن يتكرر الرسم البياني. هذا هو الجزء الذي لا تستطيع السلسلة العادية القيام به بشكل جيد.

إذا كنت قد استخدمت التجريد الأقدم Chain من LangChain، فإن الفرق هو شكل تدفق التحكم. السلسلة هي خط أنابيب: الخطوة الأولى، الخطوة الثانية، الخطوة الثالثة، انتهى. الرسم البياني يسمح للعقدة بفحص الحالة الحالية، ثم القفز إلى فرع مختلف، أو العودة للتكرار، أو التفرع إلى عدة عقد تعمل بالتوازي وتدمج نتائجها. يحتاج الوكلاء الحقيقيون إلى ذلك، لأن "الاستدلال، التصرف، الملاحظة، الاستدلال مرة أخرى" هي حلقة وليست خطًا.

المشكلة التي يحلها LangGraph

تعتبر سير العمل للوكلاء دورية بطبيعتها. يقوم الوكيل باستدعاء أداة، وينظر إلى النتيجة، ويقرر ما إذا كان قد انتهى، وإذا لم يكن كذلك، يحاول مرة أخرى. يصبح نمذجة ذلك باستخدام الشروط المتداخلة غير قابلة للقراءة بسرعة، ويزداد الأمر سوءًا بمجرد إضافة الأشياء التي يحتاجها الوكلاء الإنتاجيون فعليًا:

• الحلقات ذات شرط التوقف. استمر في استدعاء الأدوات حتى تكتمل المهمة، دون الدوران إلى الأبد.
• التفرع بناءً على الحالة. التوجيه إلى عقدة مختلفة اعتمادًا على ما أعاده النموذج.
• الثبات. النجاة من الأعطال أو المهلة أو إعادة التشغيل واستئناف العمل من آخر نقطة صحيحة.
• التدخل البشري (Human-in-the-loop). التوقف، والسماح لشخص بفحص أو تعديل الحالة، ثم المتابعة.
• التدفق (Streaming). إصدار الرموز والخطوات الوسيطة فور حدوثها، وليس فقط في النهاية.

يحول LangGraph كل واحدة من هذه إلى قدرة مدمجة بدلاً من شيء تقوم بتطويره يدويًا. تحصل على آلة حالات ذات تنفيذ دائم، بحيث يمكن للوكيل أن يعمل لدقائق أو ساعات ويستأنف من حيث توقف.

المفاهيم الأساسية: الرسم البياني، الحالة، العقد، الحواف

أربعة أساسيات تحمل معظم إطار العمل. إليك كيف تتناسب مع بعضها البعض.

الحالة (State) هي كائن مُصنَّف مشترك عبر التشغيل بأكمله. تحدد شكله باستخدام مخطط (schema)، وغالبًا ما يكون TypedDict، ويقوم LangGraph بدمج تحديثات كل عقدة فيه. نقطة الانطلاق الشائعة هي MessagesState، وهو مخطط مُعد مسبقًا يحتوي على قائمة جارية من رسائل الدردشة.

العقد (Nodes) هي دوال. تأخذ كل واحدة منها الحالة الحالية وتُرجع تحديثًا جزئيًا. يمكنك تسجيلها باستخدام add_node().

الحواف (Edges) تربط العقد. تتجه الحافة العادية باستخدام add_edge() دائمًا من A إلى B. تقوم الحافة الشرطية باستخدام add_conditional_edges() بتشغيل دالة توجيه تقرأ الحالة وتُرجع اسم العقدة التالية، وهذا هو كيفية التعبير عن "إذا طلب النموذج أداة، اذهب لتشغيلها؛ وإلا انتهِ".

START و END هما علامتا تحديد خاصتان لبداية ونهاية التنفيذ.

هنا شكل رسم بياني بسيط. إنه مستوى pseudo-code، ولكن أسماء الـ API حقيقية.

from langgraph.graph import StateGraph, START, END, MessagesState

def call_model(state: MessagesState):
    response = model.invoke(state["messages"])
    return {"messages": [response]}

def should_continue(state: MessagesState) -> str:
    last = state["messages"][-1]
    return "tools" if last.tool_calls else END

builder = StateGraph(MessagesState)
builder.add_node("model", call_model)
builder.add_node("tools", tool_node)
builder.add_edge(START, "model")
builder.add_conditional_edges("model", should_continue)
builder.add_edge("tools", "model")   # loop back

graph = builder.compile()

السطر add_edge("tools", "model") هو الدورة. بعد تشغيل الأدوات، يعود التحكم إلى النموذج، الذي يمكنه استدعاء المزيد من الأدوات أو التوقف. هذه الحلقة هي السبب الأساسي لوجود LangGraph.

الثبات والتدخل البشري

قم بتجميع رسم بياني مع "مدقق نقاط التوقف" (checkpointer) وسيقوم بحفظ لقطة من الحالة بعد كل خطوة. قم بتمرير thread_id في التكوين، وسيقوم LangGraph باستعادة آخر نقطة تفتيش لهذا الخيط في الاستدعاء التالي. لا تتغير العقد الخاصة بك؛ يتعامل وقت التشغيل مع عملية الحفظ والاستعادة.

from langgraph.checkpoint.memory import InMemorySaver

graph = builder.compile(checkpointer=InMemorySaver())
config = {"configurable": {"thread_id": "user-42"}}
graph.invoke({"messages": [user_message]}, config)

InMemorySaver جيد للتطوير. لشيء يستمر بعد إعادة التشغيل، يتوفر في LangGraph أدوات حفظ مدعومة بقواعد بيانات (SQLite لخادم واحد، Postgres للتوسع متعدد المثيلات). ولأن الحالة دائمة، فإنك تحصل أيضًا على التدخل البشري (human-in-the-loop) بشكل شبه مجاني. يمكنك مقاطعة الرسم البياني عند نقطة مختارة، وعرض الحالة الحالية لشخص لفحصها أو تعديلها، ثم استئناف العمل من تلك النقطة المحددة. تعتمد بوابات الموافقة، والتصحيحات اليدوية، وخطوات "هل أنت متأكد؟" جميعها على هذا.

التدفق (Streaming) يكمل الصورة. يمكن لـ LangGraph تدفق رموز النموذج وتحديثات على مستوى العقدة مع تقدم التشغيل، بحيث يمكن لواجهة المستخدم أن تُظهر الوكيل وهو يفكر بدلاً من التحديق في مؤشر تحميل.

كيف يرتبط LangGraph بـ LangChain

هذا يربك الناس، لذا دعنا نكن مباشرين. LangChain هو مجموعة الأدوات الأوسع: أغلفة النماذج، قوالب الأوامر، المسترجعات، محملات المستندات، والتكاملات مع مئات المزودين. LangGraph هو طبقة التنسيق التي تقع تحت أجزاء الوكيل في مجموعة الأدوات هذه.

لست بحاجة إلى LangChain لاستخدام LangGraph. يمكنك تعريف حالتك وعقدك وحوافك، واستدعاء أي عميل نموذج تريده داخل عقدة. العديد من الفرق تجمع بين الاثنين، لأن تجريدات نموذج وأدوات LangChain مريحة، ومساعد create_react_agent المدمج في LangGraph (في langgraph.prebuilt) يمنحك وكيلًا عاملاً لاستدعاء الأدوات في بضعة أسطر عندما لا تحتاج إلى رسم بياني مخصص.

ملاحظة للمستخدمين الحاليين: لقد كانت نسخة LangGraph v1.0 (المستقرة منذ أواخر عام 2025) تعمل على نقل مساعد الوكيل المدمج نحو langchain.agents.create_agent، لذا تحقق من نسختك المثبتة والمرجع الرسمي لمسار الاستيراد الدقيق قبل نسخ المقتطفات القديمة. بناء وكلاء مخصصين من الصفر هو مهارة مفيدة هنا أيضًا؛ راجع دليلنا حول بناء وكيل ذكاء اصطناعي مخصص للحصول على الصورة الأوسع.

منصة واستوديو LangGraph

المكتبة مفتوحة المصدر هي الأساس، ولكن هناك منتجان إضافيان مهمان بمجرد أن تبدأ في النشر.

LangGraph Studio هو بيئة تطوير متكاملة (IDE) بصرية للوكلاء. يقوم بعرض الرسم البياني الخاص بك، ويسمح لك بتشغيله، ويعرض الحالة في كل عقدة حتى تتمكن من مشاهدة التنفيذ خطوة بخطوة عبر العقد والحواف. لأي شيء يحتوي على دورات وتوجيه شرطي، فإن رؤية المسار الذي سلكه الوكيل بالفعل أفضل من قراءة سطور السجل.

LangGraph Platform هو الجانب المدار للنشر: نقاط نهاية API لوكلائك، استمرارية مدمجة للتشغيل طويل الأمد، وخيارات استضافة تتراوح من الاستضافة الذاتية إلى الإدارة الكاملة في السحابة. لا تحتاجها لاستخدام المكتبة؛ إنها موجودة عندما تريد بنية تحتية للوكلاء في الإنتاج بدلاً من تشغيلها بنفسك.

متى تستخدم LangGraph

استخدم LangGraph عندما يكون لوكيلك تدفق تحكم حقيقي. مؤشرات جيدة:

• العمل هو حلقة، وليس تسلسلًا (استدعاء الأدوات، التحقق، التكرار).
• تحتاج إلى التفرع بناءً على ما قرره النموذج.
• يمكن أن يكون التشغيل طويلًا، وتريد أن ينجو من الانهيار ويستأنف.
• يجب على الإنسان الموافقة على شيء ما أو تعديله أثناء التشغيل.
• أنت تنسق عدة جهات فاعلة أو وكلاء فرعيين يشاركون الحالة.

تجاهله عندما تقوم مكالمة نموذج واحدة أو سلسلة خطية قصيرة بالمهمة. الرسم البياني هو عبء إضافي لا تحتاجه لتلخيص "هذا النص". احفظ البنية لسير العمل التي تتفرع وتتكرر بالفعل.

أين يتناسب اختبار ومحاكاة واجهة برمجة التطبيقات (API)

هذا هو الجزء الذي يضر بالفرق في مرحلة التطوير. لا يكون وكيل LangGraph موثوقًا إلا بقدر موثوقية واجهات برمجة التطبيقات التي يستدعيها، ويستدعي الكثير منها: نقطة نهاية LLM، بالإضافة إلى كل واجهة برمجة تطبيقات للأدوات (البحث، CRM، الواجهة الخلفية الخاصة بك). LangGraph تنسق هذه الاستدعاءات؛ ولا تختبرها. هذه مهمة منفصلة، وهنا يأتي دور Apidog.

تظهر مشكلتان بسرعة. أولاً، ضرب واجهات برمجة التطبيقات الحية في كل تشغيل اختبار يستهلك الرموز ويتسبب في تجاوز حدود المعدل. يمكنك محاكاة واجهة برمجة التطبيقات التي يعتمد عليها الوكيل بحيث تعيد نقطة نهاية الأداة استجابة حتمية وفورية بينما تقوم بالتكرار على منطق الرسم البياني. قم بمحاكاة نقطة نهاية LLM بنفس الطريقة وتتوقف عن الدفع مقابل الرموز لمجرد اختبار التوجيه.

ثانيًا، تفترض العقد الخاصة بك شكل استجابة. إذا قامت واجهة برمجة تطبيقات أداة ما بتغيير اسم حقل بهدوء، فإن حافتك الشرطية تقرأ شيئًا خاطئًا ويتكرر الوكيل أو يتعطل. يؤدي تثبيت هذه العقود باستخدام تأكيدات API إلى اكتشاف الانحراف قبل أن يصل إلى الرسم البياني الخاص بك. ولأن الوكلاء يتعاملون مع المفاتيح عبر مراحل التطوير والإنتاج، فإن إدارتها في البيئات يحافظ على الأسرار بعيدًا عن كود العقدة الخاص بك. إذا كنت تريد سير عمل الوكيل الكامل، فإن مجموعة اختبار Apidog لوكلاء الذكاء الاصطناعي تشرح ذلك من البداية إلى النهاية. لتوضيح الأمر، لا يقوم أي من هذا بتنسيق الوكيل؛ يقوم Apidog باختبار ومحاكاة واجهات برمجة التطبيقات التي تعتمد عليها.

الأسئلة المتداولة

هل LangGraph بديل لـ LangChain؟ لا. LangGraph هو وقت تشغيل التنسيق؛ LangChain هي مجموعة أوسع من المكونات والتكاملات. إنهما مكتبتان منفصلتان من نفس الفريق، ويمكنك تشغيل LangGraph بدون LangChain أو استخدامهما معًا. يتعامل LangGraph مع تدفق التحكم الدوري ذي الحالة الذي تعاني منه السلاسل العادية.

هل أحتاج إلى معرفة LangChain للبدء بـ LangGraph؟ لا. يمكنك تعريف StateGraph، وإضافة العقد والحواف، واستدعاء أي عميل نموذج داخل عقدة. أغلفة نماذج LangChain مريحة، ولكنها اختيارية. ابدأ بالأساسيات الأولية للرسم البياني وأضف الباقي فقط عندما تحتاج إليه.

كيف يتذكر LangGraph الأشياء بين الاستدعاءات؟ من خلال نقاط التفتيش (checkpointers). قم بتجميع الرسم البياني الخاص بك باستخدام نقطة تفتيش ومرر thread_id، وسيحفظ LangGraph لقطة للحالة بعد كل خطوة، ثم يستعيدها في الاستدعاء التالي لذلك الخيط. هكذا تحصل على ذاكرة المحادثة واستعادة الأعطال دون تغيير منطق العقدة الخاص بك.

كيف أقوم باختبار واجهات برمجة التطبيقات التي يستدعيها وكيلى؟ اختبرها وقم بمحاكاتها بشكل منفصل عن الرسم البياني. قم بمحاكاة نقاط نهاية LLM والأداة لتكون التشغيلات سريعة ومجانية أثناء التطوير، وتأكد من أشكال الاستجابة حتى لا يتسبب حقل متغير في كسر عقدة. يغطي دليلنا حول اختبار ChatGPT API المصادقة، والتدفق، واستدعاءات الأدوات، وهي الأسطح الدقيقة التي يعتمد عليها الوكيل.

الخلاصة

يمنحك LangGraph البنية المفقودة للوكلاء الذين يتكررون ويتفرعون ويستمرون ويتوقفون لتدخل بشري. قم بنمذجة سير العمل كرسم بياني ذي حالة مشتركة، واعتمد على نقاط التفتيش للذاكرة والاستعادة، واستخدم Studio والمنصة عندما تكون مستعدًا لتصحيح الأخطاء والنشر. يتعامل الإطار مع التنسيق. لا تزال واجهات برمجة التطبيقات التي يستدعيها وكيلك بحاجة إلى شبكة أمان خاصة بها، لذا قم بمحاكاتها واختبارها في Apidog للحفاظ على تكاليف التطوير منخفضة وعقود أدواتك صادقة. قم بتنزيل Apidog لمحاكاة نقطة نهاية والتأكد من استجاباتها قبل أن يستدعيها وكيلك بشكل حقيقي.