الوحدة 7 · الدرس 3 · 16 دقيقة قراءة
LangGraph: الوكيل كرسم بياني للحالة
LangGraph: Agents as State Graphs
المقدمة
يعامل LangGraph الوكيل كرسم بياني: عُقد تقرأ حالة مشتركة وتحدّثها، وحواف تحدد المسار. في هذا الدرس نبني رسمًا صغيرًا يعمل دون مفتاح API، ونفهم لماذا يسهّل الرسم الصريح الاختبار والاستئناف والموافقة البشرية.
أهداف التعلم
- شرح مفهوم رسم الحالة والعقد والحواف في LangGraph
- بناء رسم بسيط باستخدام StateGraph وMessagesState وSTART وEND
- فهم كيف تعيد العقدة تحديثًا للحالة لا حالة كاملة
- مقارنة رسم الحالة بالحلقة المفتوحة مع التسليم
LangGraph: التنظيم منخفض المستوى
يصف التوثيق الرسمي LangGraph بأنه إطار تنظيم (Orchestration) منخفض المستوى لبناء وكلاء طويلي التشغيل يحتفظون بالحالة (Stateful)، ويركّز على أربع قدرات: التنفيذ المتين (Durable Execution) الذي يسمح باستئناف التشغيل بعد انقطاع، والبث (Streaming)، والإنسان في الحلقة (Human-in-the-Loop)، والاستمرارية والذاكرة (Persistence). ومن المهم أنه لا يتطلب استخدام LangChain، وإن كان يتكامل معه. يُثبَّت بالأمر pip install -U langgraph، وآخر إصدار على PyPI هو 1.2.22 (بحسب التوثيق الرسمي، مراجعة 18 نوفمبر 2026).
الفكرة الأساسية: بدل أن يقرر النموذج وحده ما يحدث بعد كل خطوة كما في الحلقة المفتوحة، ترسم أنت رسمًا بيانيًا للحالة (State Graph): عُقد (Nodes) هي دوال تقرأ الحالة وتعيد تحديثًا لها، وحواف (Edges) تحدد الانتقال من عقدة إلى أخرى.
المكونات الخمسة التي تحتاجها للبداية
StateGraph: باني الرسم، ويأخذ نوع الحالة.MessagesState: حالة جاهزة تحتوي على مفتاحmessages، وتُضاف الرسائل الجديدة إلى القائمة بدل استبدالها.add_node(name, fn): يضيف عقدة. الدالة تستقبل الحالة وتعيد قاموسًا بالتحديث.add_edge(a, b): يضيف حافة. الثابتانSTARTوENDيمثلان بداية الرسم ونهايته.compile()ثمinvoke(...): تحويل الباني إلى رسم قابل للتشغيل ثم تشغيله على حالة ابتدائية.
مثال عملي يعمل دون مفتاح API
السيناريو: مكتب دعم في كلية يستقبل رسائل الطلاب. نريد عقدة تصنّف الرسالة، ثم عقدة تكتب الرد. لتوضيح البنية دون أي نموذج لغوي، العقد هنا دوال بايثون عادية تعتمد على قواعد بسيطة:
# langgraph 1.2.22 — مراجعة 18 نوفمبر 2026
# يتطلب: pip install -U langgraph (لا يحتاج هذا المثال إلى مفتاح API لأن العقد لا تستدعي نموذجًا)
from langgraph.graph import StateGraph, MessagesState, START, END
def classify(state: MessagesState):
text = state["messages"][-1].content
label = "مالي" if "رسوم" in text or "فاتورة" in text else "أكاديمي"
return {"messages": [{"role": "assistant", "content": "التصنيف: " + label}]}
def respond(state: MessagesState):
label = state["messages"][-1].content
reply = "سنحوّلك إلى الشؤون المالية" if "مالي" in label else "سنحوّلك إلى المرشد الأكاديمي"
return {"messages": [{"role": "assistant", "content": reply}]}
builder = StateGraph(MessagesState)
builder.add_node("classify", classify)
builder.add_node("respond", respond)
builder.add_edge(START, "classify")
builder.add_edge("classify", "respond")
builder.add_edge("respond", END)
graph = builder.compile()
result = graph.invoke({"messages": [{"role": "user", "content": "لدي سؤال عن رسوم الفصل"}]})
for m in result["messages"]:
print(type(m).__name__, ":", m.content)عند التشغيل ستظهر ثلاث رسائل: رسالة المستخدم، ثم التصنيف، ثم الرد. لاحظ أن كل عقدة أعادت تحديثًا يحتوي على رسالة جديدة فقط، وأن MessagesState أضافها إلى القائمة. ولاحظ أن القواميس التي كتبناها تحوّلت إلى كائنات رسائل (مثل HumanMessage وAIMessage)، لذلك نقرأ النص عبر .content.
لماذا الرسم الصريح مفيد؟
- قابلية التنبؤ: المسار مكتوب في الكود، فلا يستطيع النموذج تخطي خطوة التحقق أو الموافقة.
- قابلية الاختبار: كل عقدة دالة مستقلة يمكن اختبارها وحدها.
- الاستئناف: لأن الحالة مركزية وصريحة، يمكن للإطار حفظها بعد كل خطوة (الاستمرارية) واستئناف التشغيل من آخر نقطة، وهو أساس التنفيذ المتين ونقاط الموافقة البشرية التي سندرسها في وحدة الوكلاء المستقلين.
- الدورات المقصودة: يمكن رسم حافة تعود إلى عقدة سابقة لبناء حلقة «فكّر ثم نفّذ ثم راجع»، مع شرط خروج واضح.
مقارنة سريعة بالحلقة والتسليم
| السؤال | حلقة مع تسليم (Agents SDK) | رسم حالة (LangGraph) |
|---|---|---|
| من يحدد الخطوة التالية؟ | النموذج غالبًا | الحواف التي ترسمها، مع قرارات النموذج داخل العقد |
| شكل الحالة | سجل المحادثة | حالة مُعرّفة تتشاركها العقد |
| أفضل استخدام | محادثات متعددة المتخصصين | مسارات عمل طويلة ومضبوطة وقابلة للاستئناف |
الملخص
LangGraph إطار تنظيم منخفض المستوى للوكلاء طويلي التشغيل، يركّز على التنفيذ المتين والبث والإنسان في الحلقة والاستمرارية، ولا يتطلب LangChain. تبني الرسم بـ StateGraph وتضيف العقد والحواف بين START وEND ثم تستدعي compile وinvoke. العقد تعيد تحديثات للحالة، وMessagesState يضيف الرسائل الجديدة إلى القائمة. الرسم الصريح يجعل المسار قابلًا للتنبؤ والاختبار والاستئناف.
المصطلحات
| المصطلح | English | التعريف |
|---|---|---|
| عقدة | Node | دالة تقرأ الحالة وتعيد تحديثًا لها |
| حافة | Edge | انتقال محدد من عقدة إلى أخرى |
| حالة الرسائل | MessagesState | حالة جاهزة بمفتاح messages تُضاف إليه الرسائل الجديدة |
| التنفيذ المتين | Durable Execution | القدرة على استئناف التشغيل بعد انقطاع من آخر حالة محفوظة |
| التجميع | compile | تحويل الباني إلى رسم قابل للتشغيل |
أسئلة المراجعة
- ما دور START وEND في رسم LangGraph؟
- لماذا تعيد العقدة قاموس تحديث بدل الحالة كاملة؟
- كيف يساعد الرسم الصريح على وضع نقطة موافقة بشرية لا يمكن تخطيها؟
- ما الخطر في رسم دورة دون شرط خروج؟
المراجع
- LangGraph overview docs.langchain.com روجع في 2026-11-18
- langgraph on PyPI pypi.org روجع في 2026-11-18
