Claude Agent SDK أم LangGraph: أيهما تختار لبناء الوكلاء؟

يتوقف الاختيار بين Claude Agent SDK وLangGraph على سؤال واحد: هل يقرر النموذج ما يحدث لاحقًا، أم يقرره كودك؟ يمنح Claude Agent SDK تطبيقك حلقة الوكيل نفسها التي تعمل داخل Claude Code، فيختار Claude أدواته وخطواته بنفسه. أما LangGraph فيقدّم لك آلة حالة. أنت ترسم العقد والحواف، ويؤدي النموذج العمل عند كل محطة. كلاهما يبني وكلاء ذكاء اصطناعي قادرين، لكنهما يختلفان في من يمسك عجلة القيادة.

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

الجواب المختصر

إذا كان وكيلك في الغالب "امنح نموذجًا قادرًا أدوات جيدة ودعه يعمل"، فابدأ باستخدام Claude Agent SDK. وإذا كان وكيلك سير عمل له مراحل ثابتة وفروع وإعادات محاولة ونقاط تدقيق، فابدأ بـLangGraph. يتلاشى معظم الالتباس بمجرد أن تصنّف مشروعك في أحد هذين الشكلين.

إليك المقارنة الجانبية قبل التفاصيل:

💡 قاعدة عملية: عُدّ الخطوات التي يمكنك كتابتها مسبقًا. إذا كان بإمكانك سردها على ورقة صغيرة، فارسم رسمًا بيانيًا. وإذا كانت الإجابة الصادقة هي "يتوقف الأمر على ما يجده الوكيل"، فاستخدم الحلقة.

ما هو كل إطار عمل

نظرة سريعة على Claude Agent SDK

أطلقت Anthropic هذه الأداة أولًا باسم Claude Code SDK، ثم أعادت تسميتها لاحقًا إلى Claude Agent SDK، لأن الناس كانوا يستخدمونها لأغراض أبعد بكثير من البرمجة. تثبّت claude-agent-sdk لبيئة Python أو @anthropic-ai/claude-agent-sdk لبيئة TypeScript، ثم تستدعي query() مع أمر نصي وبعض الخيارات، وتتلقى الرسائل تدفقًا أثناء عمل الوكيل.

وتحت السطح يعمل الإطار نفسه الذي يشغّل Claude Code. يرسل السياق إلى Claude، ويشغّل الأدوات التي يطلبها، ويعيد النتائج إليه، ويكرر ذلك حتى يقرر Claude أن المهمة انتهت. وما تحصل عليه دون أن تكتبه بنفسك:

• الأدوات المدمجة: Read، Write، Edit، Bash، Glob، Grep، WebSearch، و WebFetch
• إدارة السياق: يضغط الإطار الأدوار الأقدم عندما تمتلئ نافذة السياق
• الوكلاء الفرعيون: مساعدون متخصصون لديهم أوامرهم النصية وقوائم أدواتهم الخاصة
• الخطافات (hooks): يعمل الكود الخاص بك قبل استدعاء أداة أو بعده
• دعم MCP: وصّل خوادم Model Context Protocol لقواعد البيانات والمتصفحات وواجهات API الداخلية
• الصلاحيات: أوضاع وقواعد تحدد استدعاءات الأدوات التي تحتاج إلى موافقة
• تعليمات المشروع: ملفات CLAUDE.md والمهارات المحمّلة من نظام الملفات

نظرة سريعة على LangGraph

يأتي LangGraph من فريق LangChain، وقد صُمم للوكلاء طويلي التشغيل وذوي الحالة. بلغ إصداره 1.0 في أواخر عام 2025. تعرّف مخطط حالة، وتكتب العقد كدوال عادية، وتصل بينها بحواف ثابتة أو شرطية، ثم تجمّع النتيجة في رسم بياني قابل للتشغيل.

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

حلقة الوكيل مقابل الرسم البياني الصريح

من يختار الخطوة التالية

هذا هو مفترق الطرق الحقيقي. في SDK يختار Claude الحركة التالية في كل دورة: قراءة ملف آخر، أو تشغيل أمر، أو البحث في الويب، أو التوقف. في LangGraph تختار الحواف، ولا يقرر النموذج إلا داخل العقدة التي أُعطيها.

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

المهمة نفسها في الاثنين

لنأخذ مهمة بسيطة: تدقيق وحدة المصادقة والإبلاغ عن أخطر الدوال. إليك الحل باستخدام Claude Agent SDK:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    options = ClaudeAgentOptions(
        allowed_tools=["Read", "Grep", "Glob"],
        system_prompt="You review code for security risks.",
    )
    async for message in query(
        prompt="Audit the auth module and list the three riskiest functions.",
        options=options,
    ):
        print(message)

asyncio.run(main())

نسخ الأمر النصي

هذا هو البرنامج كله. يقرر Claude أي الملفات يفتح، وبأي ترتيب، ومتى يكون قد رأى ما يكفي.

الآن المهمة نفسها في LangGraph، مع خطوة مراجعة مضمونة. الدالتان run_audit وpasses_checks عنصرا نيابة عن كودك الخاص:

from typing import TypedDict
from langgraph.graph import StateGraph, START, END

class State(TypedDict):
    question: str
    report: str
    approved: bool

def audit(state: State) -> dict:
    return {"report": run_audit(state["question"])}

def review(state: State) -> dict:
    return {"approved": passes_checks(state["report"])}

def route(state: State) -> str:
    return "done" if state["approved"] else "retry"

builder = StateGraph(State)
builder.add_node("audit", audit)
builder.add_node("review", review)
builder.add_edge(START, "audit")
builder.add_edge("audit", "review")
builder.add_conditional_edges("review", route, {"done": END, "retry": "audit"})
graph = builder.compile()

نسخ الأمر النصي

هنا أنت من كتب العملية: تُراجع كل تقرير، ويُعاد توجيه أي تقرير يفشل في المراجعة دائمًا. النموذج لا يستطيع أن يتجاوز المراجعة أبدًا. الثمن هو أعمال الربط والتجهيز: كود أكثر، وقرارات أكثر، ورسم بياني يجب صيانته.

إعدادات الأنظمة متعددة الوكلاء

يتعامل SDK مع تفويض المهام عبر الوكلاء الفرعيين. تعرّف كل مساعد بوصف وأمر نصي وقائمة أدوات مقيّدة، ويسلّمهم الوكيل الرئيسي العمل. يعمل كل وكيل فرعي في سياقه الخاص، وهذا يُبقي نافذة الوكيل الأب نظيفة. الإعداد سريع، وقرارات التفويض تبقى مع Claude.

يمثل LangGraph الفكرة نفسها بالرسوم البيانية الفرعية أو بعقدة مشرف توجّه العمل إلى عقد العمال. التسليمات صريحة، والحالة المشتركة مُعرّفة النوع، ويمكنك اختبار كل عامل على حدة. عندما يجب أن يتعاون خمسة وكلاء بترتيب ثابت، تؤتي هذه الصراحة ثمارها. وعندما يكون الوكلاء متخصصين غير مقيدين، قد تبدو وكأنها أعمال ورقية.

الأدوات والحالة والذاكرة

الأدوات المدمجة مقابل العقد المخصصة

يأتي SDK بصندوق أدوات كامل، ولهذا يشعرك بالإنتاجية منذ اليوم الأول. وكيل يستطيع قراءة مستودع وتحرير الملفات وتشغيل الاختبارات يعمل فور أن تمرر allowed_tools. تنضم الأدوات المخصصة عبر خوادم MCP داخل العملية أو أي خادم MCP خارجي. تقييد الصندوق لا يقل أهمية عن ملئه: Bash قوية، فامنحها فقط للوكلاء الذين يحتاجونها.

يبدأ LangGraph بطاولة عمل فارغة. الأدوات دوال تربطها بنموذج داخل عقدة، وتنفّذ عقدة أدوات جاهزة الاستدعاءات. هذا يعني إعدادًا أكثر وحرية أكبر: يمكن للأداة أن تكون أي شيء تستطيع Python أو JavaScript استدعاءه، وأنت تقرر ما الذي يُسمح لكل عقدة بلمسه.

الجلسات مقابل نقاط الحفظ

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

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

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

الموافقة البشرية والتحكم

الوكلاء الذين يلمسون الأموال أو بيانات الإنتاج أو بريد العملاء يحتاجون إلى شخص في الحلقة. يدعم الأداتان ذلك، لكن في أماكن مختلفة.

الأذونات والخطافات

يحمي SDK الإجراءات. تتدرج أوضاع الأذونات من السؤال قبل كل شيء، إلى القبول التلقائي لتعديلات الملفات، وصولًا إلى وضع تخطيط للقراءة فقط. يمكنك السماح بالأدوات أو منعها بالاسم، وتزويدها بدالة استدعاء تعتمد كل استدعاء، وإرفاق خطافات تعمل قبل تنفيذ الأداة ويمكنها أن تمنعها أو تعيد كتابتها. الخطاف الذي يرفض أي أمر صدفة يحتوي على rm -rf هو دالة قصيرة.

المقاطعات والاستئناف

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

أيهما أفضل؟ إذا كنت تقلق بشأن ما الذي يُسمح للوكيل بفعله، فأذونات SDK مناسبة. وإذا كنت تقلق بشأن متى يجب أن يوافق شخص في عملية تجارية، فمقاطعات LangGraph مناسبة.

اختيار النموذج وواقع الإنتاج

الارتباط بنموذج واحد

يشغّل Claude Agent SDK نماذج Claude. يمكنك الوصول إليها عبر API من Anthropic، أو عبر مزودي خدمات السحابة مثل Amazon Bedrock و Google Vertex AI، لكن لا يمكنك استبدال مزود آخر. وإذا كان Claude خيارك على أي حال، فهذه ميزة، لأن الإطار مضبوط على طريقة استخدام Claude للأدوات.

LangGraph محايد. يمكنك تشغيل عقدة على نموذج سريع ورخيص للتوجيه، وأخرى على نموذج استدلال قوي، وتبديل أيٍّ منهما بتغيير في الإعدادات. قبل أن تلتزم، شغّل أمر الوكيل نفسه على عدة نماذج في PicassoIA: Claude Sonnet 5 لتوازن البرمجة واستخدام الأدوات، وClaude Opus 4.7 للاستدلال الأصعب، وClaude Fable 5 لمهام البرمجة المعقدة، وGPT 5.6 Sol، وGemini 3.1 Pro، وKimi K2.6، وهو مُصمم لبناء الوكلاء. إذا فاز مزود واحد بوضوح في مهمتك، فسؤال الارتباط يجيب عن نفسه.

المراقبة والنشر

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

وكلاء LangGraph خدمات عادية. تتتبع LangSmith كل عقدة، واستوديو مرئي يتيح لك التنقل عبر الحالة خطوة بخطوة، ويوجد خيار نشر مُستضاف للرسوم البيانية طويلة التشغيل. التنفيذ المستمر عبر نقاط الحفظ يعني أن إعادة النشر أو التعطل لا يمحو عملية تشغيل جارية.

التكلفة والزمن الكامن

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

أيهما تختار

اختر Claude Agent SDK عندما

• يعمل الوكيل على الملفات أو الكود أو الصدفة، وتتطابق الأدوات المدمجة مع المهمة بالفعل
• لا يمكن التنبؤ بالمسار عبر المهمة مسبقًا
• أنت ملتزم بنموذج Claude وتريد سلوكه في استخدام الأدوات داخل منتجك
• تريد نموذجًا أوليًا يعمل خلال ظهيرة، لا خلال أسبوع
• قصة الأمان لديك تدور حول الإجراءات المسموح بها، لا حول المراحل التي تُنفَّذ

اختر LangGraph عندما

• للعملية مراحل مرتبة وفروع وإعادات محاولة يجب أن تحدث في كل مرة
• تحتاج إلى الجمع بين نماذج من عدة مزودين أو تبديلها بحرية
• يجب أن تتوقف عمليات التشغيل لأيام ثم تستأنف من حيث توقفت تمامًا
• يريد المدققون الحالة عند كل خطوة
• تملك فرق متعددة وكلاء مختلفين يجب أن يسلّم بعضهم العمل لبعض

شغّلهما معًا

ليسا متنافيين. يستخدم نمط شائع LangGraph كسير عمل خارجي، مع عقدة واحدة تستدعي Claude Agent SDK للجزء المفتوح، مثل "أصلح الاختبارات الفاشلة". يتولى الرسم البياني التوجيه والموافقة وإعادات المحاولة، ويتولى SDK الجزء الفوضوي في المنتصف.

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

دورك أنت: أنشئ مع Picasso IA

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

جرّب أمر وكيلك الأولي مع Claude Sonnet 5 على PicassoIA:

1. افتح صفحة Claude Sonnet 5.
2. الصق مسودة موجه النظام لديك ومهمة واقعية واحدة.
3. اطلب من النموذج أن يسرد بالترتيب الأدوات التي سيستدعيها ولماذا.
4. شغّل النص نفسه عبر Claude Opus 4.7 أو Gemini 3.1 Pro وقارن الخطط.
5. احتفظ بالخطة التي تطابق الخطوات التي كنت سترسمها في رسم بياني. هذا يخبرك أي إطار يناسبك.

ثم أنشئ شيئًا يرافقه. صِف مشهدًا، مثل فريق برمجيات أمام لوحة بيضاء في ضوء صباحي ناعم، مُصوَّر بفيلم 35mm، وولّده خلال ثوانٍ. تصفح كل النماذج المتاحة على picassoia.com/en/all-models، وجرّب ثلاثة أو أربعة أوامر، وانظر إلى أي مدى تقودك جملة واحدة. يستحق وكيلك القادم إطلاقًا جميلًا.