دليل المطوّر العربي إلى لانغ تشين ولانغ غراف: من الصفر إلى وكيل يعمل

لانغ تشين (LangChain) إطار عمل أعلى مستوى: يقدّم لك وكيلاً جاهزاً من نموذج لغوي وأدوات وحلقة تتكرّر حتى تنتهي المهمة. لانغ غراف (LangGraph) بيئة تشغيل منخفضة المستوى تُشغّل هذا الوكيل، وتحفظ حالته، وتتيح إيقافه في منتصف المسار بانتظار موافقة إنسان. الفرق في جملة واحدة: لانغ تشين تعطيك الوكيل، ولانغ غراف تعطيك التحكم في مساره — ولانغ تشين مبنية فوق لانغ غراف، لا العكس.

ولماذا يهمّك هذا الآن؟ لأن أغلب الشرح المنشور قبل أكتوبر 2025 لم يعد يعمل كما هو. الإصداران 1.0.0 نُشرا على PyPI في 17 أكتوبر 2025، ومعهما تغيّر اسم دالة البناء الأساسية: create_agent حلّت محل create_react_agent الموقوفة، وانتقلت السلاسل والمُسترجِعات القديمة إلى حزمة langchain-classic. أما الوثائق الرسمية نفسها فمكتوبة بالإنجليزية بلا ترجمة عربية — وهذا سبب وجود هذه السلسلة أصلاً.

المصطلحات التي ستراها في كل مقال من السلسلة:

• وكيل (agent): نموذج يستدعي أدوات في حلقة حتى تكتمل المهمة. ليس روبوت محادثة — روبوت المحادثة يردّ، والوكيل يقرّر وينفّذ.
• بنية تشغيل الوكيل (harness): كل ما يحيط بحلقة النموذج — الموجّه، والأدوات، والطبقات الوسيطة.
• إطار عمل (framework): لانغ تشين. طبقة التجريدات والتكاملات.
• بيئة التشغيل (runtime): لانغ غراف. طبقة الحفظ والتدفّق والتدخّل البشري.
• الحالة (state): لقطة البيانات المشتركة التي تقرأ منها كل عقدة وتكتب فيها.
• محادثة (thread): جلسة واحدة يستمر منها الوكيل، ومعرّفها في الكود thread_id.
• طبقة وسيطة (middleware): قطعة تُركّبها حول الحلقة لتضيف قدرة: تلخيص، أو إخفاء بيانات التعريف الشخصية، أو موافقة بشرية.

ما هو الوكيل؟ المعادلة الرسمية: الوكيل = نموذج + بنية تشغيل

الوكيل ليس دالة تعيد نصاً، بل نموذج لغوي يمرّ بحلقة: يُرسَل له طلب، فيقرّر إما أن يستدعي أداة أو يعطي جواباً نهائياً، وإن استدعى أداة نُفِّذت وعادت نتيجتها إلى المحادثة، فتكرّرت الحلقة. الوثائق الرسمية تختصر المعادلة كلّها في سطر واحد: الوكيل = نموذج + بنية تشغيل، والبنية هي كل ما يحيط بحلقة النموذج — الموجّه والأدوات وأي طبقة وسيطة تشكّل السلوك. بلغة langchain، الدالة التي تغلّف كل ذلك اسمها create_agent.

والفصل الذي يهمّك عملياً: النموذج وحده لا يعرف شيئاً عن قواعدك، ولا عن الـ API الذي تريد استدعاؤه. البنية هي التي تعطيه تلك المعرفة وتقرّر متى يستعملها. لهذا ينفع الوكيل في مهمة تتطلّب خطوات لا يمكن استنتاجها من النص، ويضيع في مهمة تتطلّب خطوة محسوبة واحدة فقط.

ما الفرق بين الإطار وبيئة التشغيل؟

إطار العمل طبقة تجريدات عالية، وبيئة التشغيل الطبقة التي تُشغّل ما بَنَاه تلك التجريدات وتضمن استمراره. والوثائق تحسم الأمر بجملة واحدة: أطر العمل أعلى مستوىً وتعمل على بيئات التشغيل، ولانغ تشين 1.0 مبنية فوق لانغ غراف. في الجدول التالي ثلاث طبقات من نفس العائلة:

الطبقة	ما تضيفه	متى تستعملها
بيئة التشغيل (لانغ غراف)	تنفيذ متين، بثّ، تدخّل بشري، حفظ الحالة	حين تريد تحكماً دقيقاً، وتشغيلاً طويلاً، ووكيلاً ذا حالة
إطار العمل (لانغ تشين)	تجريدات وتكاملات	حين تريد بناء وكيل بسرعة وتوحيد طريقة الفريق
بنية تشغيل جاهزة (الوكلاء العميقون / Deep Agents)	أدوات وموجّهات ووكيلون فرعيون جاهزة	حين تريد كل شيء ملفوفاً، لا حين تبني بنفسك

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

أما الوكلاء العميقون (Deep Agents) فهم طبقة ثالثة، وحزمة deepagents ما زالت قبل الإصدار 1.0 وقيد تطوير نشط، فلا بنينا شيئاً عليها في هذه السلسلة عن قصد.

لماذا نكتب عن الإصدار 1 تحديداً؟

لأن كل شرح جُيّر قبل أكتوبر 2025 يصف نظاماً لم يعد موجوداً. هذه أرقام الحزم كما هي اليوم:

الحزمة	متى نُشر 1.0.0	أحدث إصدار على PyPI	متطلبات Python
langchain	17 أكتوبر 2025	1.4.3 — 28 سبتمبر 2026	<4.0.0, >=3.10.0
langgraph	17 أكتوبر 2025	1.2.14 — 6 أكتوبر 2026	>=3.10

وأُعلن الإصداران رسمياً في 22 أكتوبر 2025. الفارق بين التاريخين ليس خطأً: الحزم نُشرت على PyPI أولاً، ثم جاء الإعلان.

والتزاماً موعوداً: إصدارا 1.0 مُصنَّفان دعماً طويل الأمد (LTS)، ويبقى الإصدار 1.0 في حالة نشطة حتى صدور الإصدار 2.0، ثم ينتقل إلى وضع الصيانة سنة كاملة على الأقل. أما الإصدارات القديمة (لانغ تشين 0.3 ولانغ غراف 0.4) فهي في وضع الصيانة حتى ديسمبر 2026. عملياً: ابدأ بالإصدار 1.0 ولا تقلق من كسر مفاجئ.

وتستحق الكلفة أن نقولها بصراحة: الحزمة لم تعد «مكتبة واحدة». ثبّت langchain-core وlangchain وlanggraph، وقد تحتاج حزمة رابعة لحزمة مزوّدك. هذه كلفة حقيقية. ويضاف إليها أن لانغ سميث (LangSmith) — منصة التتبّع والتقييم والنشر — منتج تجاري منفصل؛ مفيد، لكنه ليس شرطاً للبناء عليه، وهذه السلسلة لا تفترض وجوده أصلاً.

خريطة طريق السلسلة: ماذا تقرأ وماذا تبني بعد كل مقال

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

#	slug	العنوان	السؤال الذي يجيب عنه	ماذا تبني بعده
2	langchain-vs-langgraph	لانغ تشين أم لانغ غراف؟ كيف تختار الطبقة المناسبة لمشروعك	متى تكفيك لانغ تشين وحدها، ومتى تحتاج لانغ غراف تحت الغطاء	شجرة قرار تعرف بها أي حزمة تستورد قبل أول سطر تكتبه
3	langchain-standard-model-interface	الواجهة الموحّدة للنماذج: كيف يتحدّث كودك إلى أي مزوّد دون إعادة كتابة	كيف تبدّل المزوّد بتغيير صغير وتُبقي تطبيقك قابلاً للنقل	طبقة نموذج قابلة للتبديل، بحيث لا يهمّ أي مزوّد اشتركت به
4	langchain-tools-and-tool-calling	الأدوات واستدعاؤها: كيف يقرّر النموذج متى ينفّذ دالة	كيف تعرّف دوالّك للنموذج وتتحكّم في متى تُستدعى	مجموعة أدوات حقيقية متّصلة بواجهة برمجية وقاعدة بيانات، وتفهم عقدها مع النموذج
5	langchain-create-agent-and-middleware	create_agent وطبقة الوساطة: تبني وكيلاً قابلاً للتخصيص خطوة بخطوة	كيف تبدأ من أبسط وكيل وتضيف قدرات تدريجياً بلا إعادة كتابة	وكيل فيه تلخيص تلقائي، وحماية لبيانات التعريف الشخصية، وموافقة بشرية
6	langgraph-state-checkpoints-and-memory	الحالة ونقاط الحفظ: كيف تبني ذاكرة قصيرة المدى وذاكرة طويلة المدى	كيف يتذكّر الوكيل محادثتك بعد إغلاق البرنامج، وما الفرق بين نوعي الذاكرة	وكيل يحتفظ بمحاور بعد إغلاق العملية، ويكتب ذاكرة مستخدم في مخزن دائم
7	langgraph-workflows-and-interrupts	أنماط سير العمل في لانغ غراف: من الحواف الشرطية إلى المقاطعة التفاعلية	كيف تخلط خطوات محسوبة بخطوات يقرّرها النموذج، وتوقفه بانتظار إنسان	خط أنابيب فيه بوابة موافقة بشرية قبل كل إجراء حساس
8	build-your-first-langgraph-agent-end-to-end	ابنِ وكيلك الأول من الصفر إلى النهاية: مشروع كامل بلانغ تشين ولانغ غراف	كيف تجمع كل ما سبق في مشروع واحد يعمل، وتعرف أن كل سطر فيه لسبب	وكيل حجوزات يحفظ حالته ويطلب موافقتك قبل أي إجراء خطر

إن كان وقتك ضيقاً: اقرأ هذا المقال، ثم المقالة الثانية لتختار طبقة، ثم المقالة الخامسة، ثم اقفز إلى المشروع الكامل.

قبل أن تبدأ: متطلبات بيئة العمل

تحتاج Python 3.10 فأحدث، وثلاث حزم مفتوحة المصدر، ومفتاح واجهة برمجية لمزوّد واحد. لا شيء غير ذلك.

pip install -U langchain-core langchain
pip install -U langgraph
pip install -qU langchain "langchain[openai]"

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

وللتأكد مما رُكّب فعلاً:

import langchain_core
print(langchain_core.__version__)

ضع مفتاح المزوّد في متغيّر بيئة ولا تكتبه في المستودع. وقبل أن تنسخ أي مقال من السلسلة، انتبه أن أسماء النماذج تختلف بين صفحات الوثائق نفسها، فتحقّق من الاسم في صفحة المقال الذي تقرؤه.

أبسط وكيل ممكن: من دالة واحدة إلى وكيل يعمل

هذا كامل المثال من صفحة لانغ تشين، كما هو:

# pip install -qU langchain "langchain[openai]"
from langchain.agents import create_agent

def get_weather(city: str) -> str:
    """Get weather for a given city."""
    return f"It's always sunny in {city}!"

agent = create_agent(
    model="openai:gpt-5.5",
    tools=[get_weather],
    system_prompt="You are a helpful assistant",
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "What's the weather in San Francisco?"}]}
)
print(result["messages"][-1].content_blocks)

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

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

مصطلحات مختصرة

الإنجليزية	العربية	ما تعنيه هنا
agent	وكيل	النموذج وهو يستدعي أدوات في حلقة حتى تكتمل المهمة
harness	بنية تشغيل الوكيل	الموجّه والأدوات والوساطة حول الحلقة
agent loop	حلقة الوكيل	إرسال، قرار، تنفيذ، تكرار
middleware	طبقة وسيطة	خطّاف يضاف في الحلقة ليعمل في توقيت محدّد
system prompt	الموجّه النظامي	تعليمات الدور والسلوك
tool	أداة	دالة يقرّر النموذج استدعاءها
state	الحالة	لقطة البيانات المشتركة بين العقد
thread / thread_id	محادثة	جلسة مستمرة، ومعرّفها الدائم
checkpoint	نقطة حفظ	لقطة تُكتب عند حدود الخطوات الكبرى
store	مخزن	ذاكرة طويلة المدى خارج حالة الرسم
human-in-the-loop	تدخّل بشري في الحلقة	تعليق التنفيذ حتى يوافق إنسان
interrupt	تعليق تفاعلي (interrupt())	طلب موافقة يوقف الرسم

ما الذي لن تجده في هذه السلسلة

الشفافية قبل التطبيق:

• لا نشر ولا استضافة. كل ما هنا يعمل على جهازك أو على خادمك أنت.
• لا افتراض بأن لديك لانغ سميث. هي منصة تجارية، ونكتب الكود بحيث يعمل بلاها.
• لا بناء على الوكلاء العميقين. حزمتهم ما زالت في تطوير نشط، ولا نضع أساس سلسلة على أساس متحرّك.
• لا LCEL. ببناء السلسلة | الذي كان قلب لانغ تشين صار مساراً قديماً انتقل إلى langchain-classic؛ هذه السلسلة تبني على create_agent وعلى رسم الحالة.
• لا وعود بثبات لا يوفّره المشروع. حين نكتب عن حفظ الحالة والتعليق التفاعلي، نكتب عن الصيغ التي تعلّمها الوثائق — ومنها ما له كلفة حقيقية إن أخطأت، ونقولها عند موضعها.

اقرأ السلسلة بالترتيب

1. لانغ تشين أم لانغ غراف؟ كيف تختار الطبقة المناسبة لمشروعك
2. الواجهة الموحّدة للنماذج: كيف يتحدّث كودك إلى أي مزوّد دون إعادة كتابة
3. الأدوات واستدعاؤها: كيف يقرّر النموذج متى ينفّذ دالة
4. create_agent وطبقة الوساطة: تبني وكيلاً قابلاً للتخصيص خطوة بخطوة
5. الحالة ونقاط الحفظ: كيف تبني ذاكرة قصيرة المدى وذاكرة طويلة المدى
6. أنماط سير العمل في لانغ غراف: من الحواف الشرطية إلى المقاطعة التفاعلية
7. ابنِ وكيلك الأول من الصفر إلى النهاية: مشروع كامل بلانغ تشين ولانغ غراف

---

تحتاج وكيلاً يعمل لفريقك؟

نصمّم ونبني أنظمة وكلاء للشركات والأفراد فوق لانغ تشين (LangChain) ولانغ غراف (LangGraph) — من إثبات المفهوم في أسبوع إلى نظام إنتاجي يُشغَّل يومياً. ابدأ بطلبك من صفحة التواصل.