Agent SDK: تضمين قدرات Claude Code داخل تطبيقاتك الخاصة
📚 دليل السلسلة: الدرس السابق 44 GitHub Actions علمك كيفية ربط Claude بأداة CI ليعمل تلقائياً في طلبات السحب وبناء الأكواد. هذا الدرس يتقدم خطوة أخرى — فبدلاً من مجرد ربطه ببيئة البناء، سنقوم بتضمين واستخدام قدرات Claude Code كحزمة برمجية (library) داخل تطبيقاتك وخدماتك الخاصة. ويوفر لك Agent SDK القناة الرسمية لـ "استدعاء وبرمجة وكيل Claude برمجياً".
يا رفاق، سنتحدث اليوم عن أداة تحولك من "مستخدم للأدوات" إلى "صانع للأدوات".
في الدروس الأربعين السابقة، كنت بمثابة مستخدم لـ Claude Code — تفتح الطرفية وتكتب claude لتتحدث معه وتراقب تعديلاته للأكواد. وهذا هو "الوجه الخارجي" للأداة. ولكن هناك "وجه داخلي" لم نلمسه بعد: حيث يمكن لسيناريوهاتك البرمجية استدعاء المحرك الأساسي للأداة — بما يحتويه من دورة عمل لقراءة الملفات وتشغيل الأوامر والتفكير المنظم — وتشغيله برمجياً.
وهذا هو Agent SDK (حزمة تطوير برمجيات الوكيل، وهي مجموعة مكتبات تمكنك من استدعاء نواة Claude Code برمجياً في لغات Python أو TypeScript). وبالمصطلحات البسيطة، يقوم بتحويل "Claude Code" من أداة سطر أوامر إلى دالة برمجية داخل كودك. وتكتب بضعة سطور برمجية لتشغل داخل تطبيقك وكيلاً ذكياً يستطيع قراءة الكود وتعديل الملفات والبحث في الويب تلقائياً.
وتظهر قيمة هذه الأداة بوضوح عندما تفكر في بناء "بوت مراجعة طلبات السحب التلقائي". فإذا حاولت كتابة الكود البرمجي بالاعتماد على واجهة API الأساسية مباشرة، فستضطر لكتابة الكثير من السطور البرمجية لمجرد "تمكين النموذج من قراءة ملف" — مثل قراءة محتوى الملف وضمه للطلب، والاستجابة لطلب النموذج "أريد قراءة الملف X"، ثم تشغيل القراءة الفعلية، وإعادة إرسال المحتوى للنموذج... لتغرق في تفاصيل كثيرة. وبفضل Agent SDK، تختفي كل هذه السطور البرمجية الروتينية، وبثلاثة أسطر برمجية يستطيع Claude قراءة الملف وإصلاح الخطأ بنفسه. سنمهد لك هذا المسار اليوم.
بعد قراءة هذا الدرس، ستحصل على:
- شرح مبسط لـ Agent SDK، وما الأجزاء التي يتيح لك استخلاصها واستخدامها من Claude Code
- الفارق بينه وبين أداة CLI التي تستخدمها يومياً — نفس المحرك الأساسي مع مدخلين مختلفين
- الفارق الجوهري بينه وبين "واجهة API الأساسية" (وعدم فهم هذا الفارق يجعلك تعيد كتابة أكواد جاهزة بالفعل)
- كيفية الاختيار بين نسختي TypeScript و Python، وأوامر التثبيت والمتطلبات المسبقة لكل منهما
- تطبيق عملي مع خطوات تشغيل ونتائج متوقعة لإنشاء وكيل مصغر: يكتشف خطأ برمجياً ويصلحه بنفسه
- هل يناسبك هذا المسار حالياً ويجب عليك تعلمه أم لا
01 افهم أولاً: ما الذي يستخلصه Agent SDK من Claude Code ليعطيك إياه
الخلاصة أولاً: يقوم Agent SDK بتحويل المحرك الأساسي لـ Claude Code إلى حزمة برمجية، لتستدعي برمجياً (بلغة Python أو TypeScript) وكيلاً برمجياً يملك نفس قدرات أداة CLI المعتادة.
تذكر "دورة عمل الوكيل" المشروحة في الدرس 03 — حيث يسير عمل Claude في حلقة "فكر ← اعمل ← راقب" تكرارية: يفكر في الخطوة التالية، يستدعي الأداة المناسبة (قراءة ملف، تشغيل أمر)، ويراقب المخرجات لتحديد الخطوة التالية. وعند استخدامك لأداة CLI عبر أمر claude في الطرفية، فإنك تستفيد من هذه الدورة مع مجموعة أدوات مدمجة (Read و Edit و Bash وغيرها، راجع الدرس 03 بالتفصيل).
المعلومة الحاسمة: أن دورة العمل والأسلحة البرمجية هذه ليست حكراً على أداة CLI، بل يمكن لكودك استدعاؤها مباشرة. وتوضح الوثائق الرسمية ذلك صراحة:
يوفر لك Agent SDK نفس الأدوات ودورة عمل الوكيل وإدارة السياق التي يوفرها Claude Code، لتستخدمها برمجياً في Python و TypeScript.
تشبيه: إحضار آلة القهوة التلقائية من المقهى إلى مطبخ منزلك. تذهب يومياً للمقهى لطلب القهوة (وهذا يماثل استخدام CLI)، وتسير الأمور بسلاسة. ولكن فكرت يوماً في تقديم نفس القهوة في مطعمك الصغير — ولن ترسل زبائنك للمقهى بالتأكيد. فتقوم بإحضار نفس آلة القهوة لمطعمك: لتعمل بنفس محرك طحن الحبوب والاستخلاص والتبخير، ولكنها مستقرة داخل نظام عملك وتتحكم برمجياً في موعد تحضير الكوب ولمن وبجانب أي وجبة. ويعتبر Agent SDK بمثابة هذه "الآلة المنقولة" — نفس المحرك الأساسي يعمل داخل كودك الخاص.
وما هي العناصر التي يستخلصها ويوفرها لك؟ تذكر الوثائق الرسمية قائمة الميزات المدمجة، ولا ينقصها شيء مما توفره أداة CLI:
- الأدوات المدمجة: أدوات Read و Write و Edit و Bash و Glob و Grep و WebSearch جاهزة للاستخدام مباشرة، دون أن تحتاج لكتابة أكواد لتشغيلها بنفسك
- دورة عمل الوكيل: نظام التفكير والتنفيذ والمراقبة يديره SDK بالنيابة عنك
- إدارة السياق: يتذكر الملفات التي قرأها وتاريخ المحادثة تلقائياً
- وتتوفر أيضاً قدرات التمديد مثل الخطافات (Hooks)، والوكلاء الفرعيين، و MCP، وإدارة الأذونات، واستعادة الجلسة — فكل ميزات CLI متاحة برمجياً في SDK
وفي أي السيناريوهات العملية ستحتاج إليه؟ إليك ثلاثة أفكار شائعة:
- "أريد بناء بوت لتطبيق Slack، وبمجرد إرسال سجل أخطاء (error log) فيه، يذهب للبث البرمجي للمستودع ويحدد الخلل ويقترح الإصلاح" — يتطلب هذا تضمين الوكيل داخل خدمة Slack الخاصة بك
- "أريد تشغيل مهمة دورية تفحص المستودع ليلاً للبحث عن وسوم TODO وكتابة تقرير بها" - يتطلب هذا استدعاء الوكيل برمجياً واستقبال مخرجاته وحفظها
- "أريد إضافة ميزة 'المساعد الذكي' داخل تطبيقي ليتعامل مع ملفات المستخدمين مباشرة" — وهذا يتطلب استخدام SDK حتماً
وتعتبر هذه المهام الثلاث صعبة التنفيذ باستخدام CLI — لأن CLI مصمم للتفاعل البشري المباشر في الطرفية؛ بينما تناسب هذه المهام طبيعة عمل SDK المعتمدة على "التشغيل والتلقي الآلي".
💡 خلاصة القول في جملة واحدة: يحول Agent SDK محرك Claude Code (الأدوات + دورة عمل الوكيل + إدارة السياق) إلى حزمة برمجية، لتستدعي برمجياً وكيلاً بنفس قدرات CLI وتضمنه داخل تطبيقاتك وخدماتك الخاصة.
02 الفارق الجوهري بين CLI و SDK: محرك واحد بمدخلين
هذه نقطة يسهل الخلط فيها، وسنوضحها تماماً: يعتمد Agent SDK وأداة CLI التي تكتبها في الطرفية على نفس المحرك البرمجي في الخلفية، ويكمن الفارق في "المدخل" فقط — مدخل بشري عبر الطرفية، ومدخل برمجى عبر كودك.
وتعبر العبارة الرسمية عن ذلك بدقة:
نفس القدرات، بواجهات مختلفة.
تشبيه: آلة القهوة نفسها تعمل كآلة مقهى يدوية مقابل آلة بيع ذاتي تفاعلية. المحرك الأساسي وآلية التحضير واحدة. ففي المقهى، يتعامل معها بائع ويعدل الإعدادات ويسألك عن رغباتك — وهذا يماثل CLI المناسب للتفاعل البشري الفوري. وفي آلة البيع الذاتي، تضع النقود وتضغط الزر لتعمل الآلة وتخرج الكوب تلقائياً دون تدخل بشري — وهذا يماثل SDK المناسب للأتمتة والتشغيل التلقائي. المحرك لم يتغير، وتغير من يضغط على زر التشغيل فقط.
وتوفر الوثائق الرسمية جدولاً يوضح موعد اختيار كل منهما:
| سيناريو الاستخدام | الخيار الأفضل |
|---|---|
| التطوير التفاعلي البشري (تكتب الكود وتعدل بالتزامن) | CLI |
| المهمة الفردية السريعة (تطلب منه القيام بأمر لمرة واحدة) | CLI |
| بيئات البناء المستمر CI/CD (أتمتة خطوط البناء) | SDK |
| بناء تطبيقات مخصصة (تضمينه كمنتج لعملائك) | SDK |
| الأتمتة الكاملة للإنتاج (تشغيل تلقائي دون مراقبة بشرية) | SDK |
والقاعدة الذهبية للاختيار هي: اسأل نفسك "هل سأقف بنفسي لمراقبة العمل والتفاعل الفوري، أم سيعمل الكود بشكل تلقائي وآلي". مراقبة وتفاعل فوري ← CLI؛ تشغيل تلقائي وتلقي نتائج ← SDK.
وتذكر الوثائق الرسمية معلومة تطمئنك لعدم ضياع مهاراتك بين الجانبين:
تستخدم الكثير من فرق التطوير الأداتين معاً: أداة CLI للتطوير اليومي البشري، وحزمة SDK لأتمتة الإنتاج. وتسير تدفقات العمل بينهما بسلاسة وتوافق تام.
وهذا صحيح وعملي جداً. فكثير من المطورين يتبعون هذا الأسلوب: نهاراً يكتب الكود ويستعين بـ claude في الطرفية للمساعدة (CLI)؛ وعند تكرار نفس الخطوات اليدوية للمرة الخامسة والشعور بالملل، يكتب كوداً برمجياً باستخدام SDK لتشغيلها تلقائياً. فمفاهيم "التوجيه (prompt)" و "الأدوات المتاحة" و "الأذونات" متطابقة تماماً بين الجانبين — والخبرة التي تكتسبها في CLI تنتقل معك لـ SDK بالكامل.
ولذلك لا تنظر إليهما كأداتين متعارضتين. بل تذكر: أداة CLI هي مدخلك للتفاعل البشري، وحزمة SDK هي مدخلك للأتمتة البرمجية، والمحرك خلفهما واحد وهو Claude Code. ويوضح الرسم البياني هذه العلاقة:
ويعني هذا الرسم: وجود مدخلين مختلفين في الأعلى — البشري عبر CLI والبرمجي عبر SDK؛ ليلتقيا عند محرك Claude Code الموحد ويقوما بنفس الأعمال البرمجية في النهاية. وهذا هو معنى "المحرك الموحد بالمدخلين".
💡 خلاصة القول في جملة واحدة: يعتمد CLI و SDK على محرك موحد بمدخلين — للتفاعل البشري نستخدم CLI، وللأتمتة والتشغيل الآلي نستخدم SDK؛ وتتكامل الأداتان معاً وتنتقل خبراتك بينهما بالكامل.
03 احذر الخلط: Agent SDK يختلف تماماً عن "واجهة API العامة"، والفارق هو "إدارة دورة الأدوات"
يعتبر هذا التفصيل هو الأهم والأكثر قيمة في هذا الدرس. وعدم فهمه قد يجعلك تظن أنك تستخدم SDK بينما أنت تعيد كتابة منطق معقد ومبني بالفعل.
قد تكون سمعت بـ "واجهة API لشركة Anthropic" أو "Client SDK" (وهي المكتبة البرمجية المخصصة للاتصال المباشر بنماذج الذكاء الاصطناعي). وبالرغم من تشابه الأسماء وقدرتهما على تشغيل Claude، إلا أن طبيعة عملهما مختلفة تماماً. ويتلخص الفارق في جملة واحدة:
يعطيك Client SDK (الواجهة العامة) نموذجاً يجيب على الأسئلة، وتكتب أنت كود تشغيل الأدوات؛ بينما يعطيك Agent SDK وكيلاً ذكياً يقوم بالعمل وتشغيل الأدوات بالنيابة عنك تلقائياً.
وتوضح الوثائق الرسمية هذا الفارق بوضوح:
توفر لك Anthropic Client SDK وصولاً مباشراً لواجهة API: حيث ترسل التوجيه وتقوم بكتابة كود تشغيل الأدوات بنفسك. بينما توفر لك Agent SDK نسخة من Claude تملك قدرة مدمجة لتشغيل الأدوات بنفسها.
تشبيه: شراء حبوب بن خضراء وتحضيرها بنفسك مقابل شراء آلة قهوة تلقائية بالكامل. استخدام Client SDK يشبه شراء حبوب البن الخضراء — وهي حبوب ممتازة (النموذج قوي جداً)، ولكن للحصول على كوب قهوة، يجب عليك تحميصها وطحنها وتسخين الماء والاستخلاص وتبخير الحليب بنفسك وكتابة أكواد لكل خطوة. بينما استخدام Agent SDK يشبه شراء آلة تلقائية بالكامل — تضغط على زر "Americano" لتقوم بالطحن والاستخلاص داخلياً وتقديم الكوب جاهزاً لك. الحبوب المستخدمة واحدة (النموذج واحد)، والفارق يكمن في "من يقوم بالخطوات الروتينية الوسيطة".
ويظهر الفارق البرمجي بوضوح في الأكواد. انظر للمقارنة التالية بلغة Python لتشعر بفارق الأكواد المطلوبة:
# Client SDK: يجب عليك كتابة كود تشغيل الأدوات بنفسك وتكرار الحلقة
response = client.messages.create(...)
while response.stop_reason == "tool_use":
result = your_tool_executor(response.tool_use) # تقوم بكتابة كود تشغيل الأداة يدوياً
response = client.messages.create(tool_result=result, **params) # وتعيد النتيجة للنموذج
# Agent SDK: يتولى Claude تشغيل الأدوات بنفسه دون تدخلك
async for message in query(prompt="Fix the bug in auth.py"):
print(message)هل لاحظت الفارق؟ الحلقة التكرارية while في Client SDK — المتمثلة في "إخبارك من النموذج بالرغبة في أداة ← تشغيل الكود البرمجي للأداة بنفسك ← إرسال النتيجة للنموذج ← تفكير النموذج بالخطوة التالية" — هي الأعمال الروتينية المعقدة المذكورة في البداية. فالنموذج يخبرك برغبته في قراءة ملف auth.py كـ "رسالة شفهية"، بينما عملية القراءة الفعلية للملف وتمرير محتوياته يجب أن تكتب كودها البرمجي بنفسك. ويجب عليك إدارة هذه الدورة البرمجية بالكامل.
أما Agent SDK فيقوم بدمج هذه الحلقة التكرارية بالكامل داخل دالة query(). فتقول له ببساطة "أصلح الخطأ في auth.py"، ليتولى هو تحديد الملف المطلوب وقراءته وتعديله والتحقق من صحته بنفسه وبشكل آلي، وتتلقى أنت سجل العمليات النهائي فقط.
وهذا هو السر وراء الفخ المذكور في البداية. فعند محاولة بناء بوت لمراجعة طلبات السحب، يقع المطور في فخ كتابة حلقة while لتشغيل الأدوات يدوياً — وإدارة قراءة الملفات وتشغيل أوامر git يدوياً هي عملية معقدة وعرضة للأخطاء البرمجية. وبمجرد التعرف على Agent SDK، تكتشف إمكانية حذف مئات السطور البرمجية الروتينية والاستعانة بدالة query() مباشرة. تذكر هذه المقارنة جيداً:
| وجه المقارنة | Client SDK (واجهة API العامة) | Agent SDK |
|---|---|---|
| ما تحصل عليه | نموذج ذكاء اصطناعي يجيب على الأسئلة | وكيل برمجى ذكي يقوم بالعمل البرمجي |
| من يقوم بتشغيل الأدوات | تكتب كود التشغيل بنفسك | يقوم Claude بالتشغيل تلقائياً |
إدارة حلقة الأدوات while | تكتبها وتديرها بنفسك | يديرها SDK بالنيابة عنك |
| الأدوات المدمجة (ملفات، أوامر) | غير متوفرة، وتكتب أكوادها بنفسك | مدمجة وجاهزة للاستخدام |
| السيناريو الأنسب | تخصيص دقيق جداً لا يتطلب لمس الملفات | وكيل ذكي يتفاعل ويعدل الأكواد والملفات |
قاعدة الاختيار: إذا كنت تريد "وكيلاً يستطيع قراءة وتعديل الملفات وتشغيل الأوامر بالنيابة عنك" — فاختر Agent SDK فوراً وتجنب كتابة حلقات while يدوياً. ولا تفكر في Client SDK إلا إذا كنت تريد نموذجاً للمحادثة الشفهية البحتة دون حاجة للمس الملفات أو تشغيل الأوامر وتفضل التحكم الكامل في كل خطوة.
💡 خلاصة القول in جملة واحدة: يختلف Agent SDK تماماً عن واجهة API العامة (Client SDK) — فالواجهة العامة تعطيك نموذجاً وتطالبك بكتابة حلقات تشغيل الأدوات بنفسك؛ بينما يعطيك Agent SDK وكيلاً يتولى تشغيل الأدوات وإدارة دورة العمل تلقائياً. وللحصول على وكيل يقوم بالأعمال البرمجية الفعلية، استخدم Agent SDK ووفر على نفسك كتابة الأكواد الروتينية.
04 لغتان للبرمجة: TypeScript و Python، التثبيت والشروط المسبقة
يوفر Agent SDK نسختين رسميتين للتطوير بحسب لغتك المفضلة: TypeScript و Python. والقدرات البرمجية متطابقة تماماً بينهما، وتوفر الوثائق الرسمية أمثلة متزامنة للغتين معاً، فلا تحتار في السؤال عن "أيهما أكثر ميزات" — بل اختر اللغة التي تعتمد عليها في مشروعك وفريقك حالياً.
وقاعدة الاختيار بسيطة: استخدم نسخة SDK المتوافقة مع لغة مشروعك الحالية. إذا كانت خلفيتك تطوير Node أو واجهات أمامية — استخدم TypeScript؛ وإذا كنت تعمل في علوم البيانات أو الأتمتة البرمجية أو أنظمة الذكاء الاصطناعي — استخدم Python. كلا الخيارين ممتاز وتحدد لغة مشروعك الاختيار المناسب.
الأوامر والمتطلبات المسبقة للتثبيت
تختلف أوامر التثبيت والبيئة المطلوبة للغتين، وسأوضحها في جدول المقارنة التالي (بناءً على الوثائق الرسمية):
| TypeScript | Python | |
|---|---|---|
| أمر التثبيت | npm install @anthropic-ai/claude-agent-sdk | pip install claude-agent-sdk |
| البيئة المطلوبة | Node.js الإصدار 18+ | Python الإصدار 3.10+ |
| هل يتطلب تثبيت Claude Code مسبقاً؟ | لا يتطلب (يأتي مدمجاً في الحزمة) | انظر التوضيح أدناه |
توفر نسخة TypeScript ميزة مريحة نبهت عليها الوثائق الرسمية:
تضم حزمة TypeScript SDK نسخة مدمجة من ملف Claude Code الثنائي (binary) كاعتمادية اختيارية متوافقة مع بيئتك، لذا لن تحتاج لتثبيت Claude Code بشكل منفصل على جهازك.
وهذا يعني أن حزمة TS SDK تعمل فور تثبيتها دون متطلبات إضافية.
بينما تواجه نسخة Python شرطاً برمجياً يتعلق بالإصدار — حيث تتطلب Python الإصدار 3.10 أو أعلى. وإذا ظهر لك خطأ من أداة pip مثل No matching distribution found for claude-agent-sdk فغالباً ما يكون السبب هو استخدام نسخة Python قديمة على جهازك. وتأكد من النسخة عبر تشغيل:
أنظمة macOS / Linux:
python3 --versionنظام Windows:
py --versionوإذا كان الإصدار أقل من 3.10 فقم بالترقية أولاً. ففي بعض أجهزة Mac القديمة، تكون النسخة المدمجة للنظام هي 3.9، ويظهر الخطأ السابق فوراً، وتُحل المشكلة بالترقية للنسخة 3.11 وتثبيت الحزمة بسلاسة.
تهيئة مفتاح API
في كلتا النسختين، يتطلب تشغيل الكود توفير مفتاح API لشركة Anthropic (وهو بمثابة الهوية والمصادقة للوصول للنماذج). وتنصح الوثائق الرسمية بإنشاء ملف .env في مجلد مشروعك وحفظ المفتاح داخله:
ANTHROPIC_API_KEY=your-api-keyتجلب المفتاح من منصة Claude (platform.claude.com)؛ وتذكر عدم رفع هذا الملف أبداً لـ git — وأضفه لملف
.gitignoreمباشرة. وقد شرحنا تفاصيل تهيئة وحماية هذا المفتاح في الدرس 04.
وإليك تنبيه هام يتعلق بالرسوم المالية، وضعته الوثائق الرسمية في مربع تنبيه في البداية، وسأنقله لك حرفياً لتوخي الحذر:
بدءاً من 15 يونيو 2026، سيتم احتساب استهلاك استخدام Agent SDK وأمر
claude -pتحت خطط الاشتراك من رصيد شهري مستقل مخصص لـ Agent SDK، ويتم احتسابه بشكل منفصل عن رصيد المحادثات التفاعلية المعتادة.
بالمصطلحات البسيطة: يتم الفصل بين رصيد المحادثات التفاعلية المعتادة (الذي تستخدمه للدردشة في الطرفية) ورصيد استخدام Agent SDK بدءاً من هذا التاريخ. فلا تظن أن امتلاكك اشتراكاً يمنحك استخداماً مفتوحاً لـ SDK دون قيود — بل يخضع SDK لرصيد واحتساب مستقل. وتأكد من تفاصيل الرسوم في الوثائق الرسمية.
💡 خلاصة القول في جملة واحدة: نسختا SDK متطابقتان في القدرات وتختار بحسب لغة مشروعك — وتثبت نسخة TS عبر
npm install @anthropic-ai/claude-agent-sdk(تتطلب Node 18+ وتضم الملف الثنائي تلقائياً)، وتثبت نسخة Python عبرpip install claude-agent-sdk(تتطلب Python 3.10+)؛ وتتطلب كلتاهما توفير مفتاحANTHROPIC_API_KEYفي ملف.env، وتخضع لميزانية مالية مستقلة عن رصيد المحادثات.
05 استعراض كود برمجي بسيط: دالة query() هي المدخل الأساسي
الحديث النظري لا يكفي، وقراءة كود برمجي حقيقي توضح الصورة تماماً. والمدخل الأساسي لـ Agent SDK هو دالة query(). وفهم هذه الدالة يفتح لك أبواب استخدام الأداة بالكامل.
سنقوم بتفكيك الكود البرمجي الأصغر الموضح في الوثائق الرسمية بلغة Python أولاً:
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
# دورة عمل الوكيل: يكتب الأكواد ويعرض النتائج برمجياً بالتزامن
async for message in query(
prompt="Find and fix the bug in auth.py",
options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]),
):
print(message) # يقرأ Claude الملف ويحدد الخلل ويصلحه تلقائياً
asyncio.run(main())وتسير نسخة TypeScript بنفس المنطق والخطوات تماماً:
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Find and fix the bug in auth.ts",
options: { allowedTools: ["Read", "Edit", "Bash"] }
})) {
console.log(message); // يقرأ Claude الملف ويحدد الخلل ويصلحه تلقائياً
}بمنتهى البساطة. وسنفصل في ثلاثة عناصر أساسية يتكون منها هذا الكود (بناءً على التوضيح الرسمي):
أولاً query() — المدخل الأساسي لدورة عمل الوكيل. وتعيد هذه الدالة "مكرراً متزامناً (async iterator)"، وتستخدم حلقة async for (أو for await في TS) لاستقبال تدفق الرسائل والمخرجات التي ينتجها Claude أثناء عمله بالتزامن: تفكيره، وتسمية الأداة التي يستدعيها حالياً، ومخرجات الأداة، والنتيجة النهائية للمهمة.
ثانياً prompt — المهمة المطلوبة منه. وتماثل تماماً الجملة التي توجهها له في الطرفية. وهنا طلبنا منه "البحث عن الخطأ البرمجي في ملف auth.py وإصلاحه". وسيتولى Claude تحديد الأدوات والخطوات المطلوبة لإنجاز ذلك.
ثالثاً options — إعدادات وقيود الوكيل. ويبرز حقل allowed_tools (أو allowedTools في TS) كأهم إعداد، لتحديد الأدوات المسموح للوكيل باستخدامها. وهنا حددنا أدوات Read و Edit و Bash لتعني "نسمح لك بقراءة وتعديل الملفات وتشغيل أوامر الطرفية".
وانتبه لحلقة التكرار async for — فهي تستمر في العمل والدوران حتى ينتهي Claude من إنجاز المهمة بالكامل أو يتوقف بسبب خطأ. ومع كل دورة يخرج سطر سجل جديد، ويتولى SDK في الخلفية إدارة تشغيل الأدوات وتحديث السياق ومعالجة الأخطاء الروتينية، وتكتفي أنت باستقبال سجل العمليات وعرضه. وتوضح الوثائق الرسمية ذلك:
يتولى SDK تفاصيل الإدارة البرمجية (تشغيل الأدوات، إدارة السياق، وإعادة المحاولة)، وما عليك سوى استقبال تدفق البيانات وعرضه.
وهذا هو الفارق المريح مقارنة بواجهة API الأساسية — فليس هناك وجود لـ حلقة التكرار المعقدة while لتشغيل الأدوات، بل تم دمجها بالكامل داخل دالة query().
ونؤكد على قاعدة تحديد الصلاحيات عبر تحديد الأدوات المتاحة (توافقاً مع الدرس 20). فنوعية الأدوات التي تسمح بها في حقل allowed_tools تحدد بدقة نطاق الصلاحيات البرمجية الممنوحة للوكيل. وتوضح اللوحة الرسمية ذلك بوضوح:
| الأدوات المسموح بها | ما يستطيع الوكيل فعله |
|---|---|
Read و Glob و Grep | القراءة والتحليل فقط (لا يستطيع التعديل) |
Read و Edit و Glob | القراءة والتعديل البرمجي للأكواد |
Read و Edit و Bash و Glob و Grep | الأتمتة الكاملة (يقرأ ويعدل ويشغل الأوامر) |
فإذا كنت تريد بناء وكيل آمن يقتصر عمله على "القراءة والتحليل دون تعديل" — فاكتفِ بالسماح بأدوات Read و Glob و Grep فقط. ويعتبر هذا المنع أقوى وأضمن من المنع في أداة CLI — فلعدم توفير أداة Edit للوكيل، لن يتمكن برمجياً من تعديل الملفات حتى لو أراد ذلك.
ولمطوري لغة Python: بالإضافة لدالة
query()المخصصة للمهمة الفردية، توفر الحزمة كلاسClaudeSDKClient— وهو غلاف برمجى يحافظ على جلسة العمل (session) مستمرة عبر الطلبات المتعددة تلقائياً دون حاجة لتمرير معاملات استعادة الجلسة يدوياً. وهو مناسب لبناء واجهات محادثة أو بيئات REPL تفاعلية؛ وتكفي دالةquery()للمهام والأتمتة الفردية، فابدأ بها وافهمها جيداً.
💡 خلاصة القول في جملة واحدة: المدخل الأساسي لـ Agent SDK هو دالة
query()— وتمرر لهاprompt(المهمة) وحقلoptions(الذي يحدد الأدوات المسموح بها في حقلallowed_tools)، وتستقبل مخرجاتها عبر تدفق رسائل متزامن؛ وتم دمج وإخفاء حلقة تشغيل الأدواتwhileالمعقدة داخل دالةquery()بالكامل.
06 العمل: بناء وتشغيل وكيل يكتشف الخطأ ويصلحه بنفسه في 5 دقائق
الكلام بدون تطبيق يبقي الأمور غامضة. سنقوم الآن بتطبيق عملي كامل لإنشاء وكيل مصغر — نكتب كوداً برمجياً يحتوي على أخطاء منطقية خفية، وندع الوكيل يكتشفها ويصلحها بنفسه بشكل آلي. العملية محلية بالكامل ولا تتطلب مستودعات خارجية، فاتبع الخطوات البرمجية التالية بلغة Python (وتسير نسخة TS بنفس الخطوات مع تعديل الأوامر الموضحة):
المتطلبات المسبقة: تثبيت Node.js 18+ أو Python 3.10+، وتوفير مفتاح API لشركة Anthropic. تتطلب الخطوات تواصل خوادم التشغيل وشركة Anthropic، فاستخدم شبكة تدعم الوصول للمواقع المحجوبة عند تعطل الاتصال.
الخطوة الأولى: إنشاء مجلد المشروع والدخول إليه
mkdir my-agent
cd my-agentالخطوة الثانية: تثبيت SDK وتهيئة مفتاح الأمان
لغة Python (باستخدام بيئة افتراضية venv):
python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdkولمطوري TypeScript استخدم الأمر:
npm install @anthropic-ai/claude-agent-sdk.
ثم أنشئ ملف .env في مجلد my-agent وضَع مفتاحك فيه:
ANTHROPIC_API_KEY=your-api-keyالمتوقع: ينتهي تثبيت حزمة SDK بنجاح وظهور سطر مثل Successfully installed claude-agent-sdk-.... رؤية نجاح التثبيت يعني جاهزية SDK للعمل. وإذا واجهت خطأ No matching distribution found فتأكد من تحديث نسخة Python لتكون 3.10 أو أعلى (راجع القسم 04).
الخطوة الثالثة: إنشاء ملف يحتوي على أخطاء برمجية خفية
أنشئ ملفاً باسم utils.py في مجلد my-agent وضَع الأكواد التالية فيه (وهي أكواد برمجية تحتوي على خطأين منطقيين يسببان انهيار البرنامج):
def calculate_average(numbers):
total = 0
for num in numbers:
total += num
return total / len(numbers)
def get_user_name(user):
return user["name"].upper()والخطأ الأول: تمرير قائمة فارغة لدالة calculate_average([]) يسبب انهيار البرنامج بسبب القسمة على صفر؛ والخطأ الثاني: تمرير قيمة فارغة لدالة get_user_name(None) يسبب خطأ TypeError.
الخطوة الرابعة: كتابة كود تشغيل الوكيل
أنشئ ملفاً باسم agent.py وضَع الأكواد التالية فيه (وهي الأكواد البرمجية الرسمية لتشغيل الوكيل مع إضافة تعليقات توضيحية):
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage
async def main():
# دورة عمل الوكيل: يستقبل سجل المخرجات بالتزامن ويطبع التفاصيل
async for message in query(
prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Edit", "Glob"], # السماح بهذه الأدوات للعمل
permission_mode="acceptEdits", # الموافقة التلقائية على تعديل الملفات
),
):
# تصفية طباعة الرسائل البشرية المفهومة
if isinstance(message, AssistantMessage):
for block in message.content:
if hasattr(block, "text"):
print(block.text) # تفكير ومنطق Claude
elif hasattr(block, "name"):
print(f"Tool: {block.name}") # الأداة التي يستدعيها حالياً
elif isinstance(message, ResultMessage):
print(f"Done: {message.subtype}") # النتيجة النهائية للمهمة
asyncio.run(main())وقد أضفنا خياراً جديداً لم نذكره في القسم 05: وهو permission_mode="acceptEdits" — وتعني الموافقة التلقائية على تعديل الملفات، ليقوم الوكيل بتعديل الملفات البرمجية دون أن يتوقف في كل مرة ويطلب موافقتك اليدوية (وهو مناسب للسيناريوهات البرمجية الموثوقة). وتوفر الوثائق الرسمية خيارات متعددة للأذونات:
| وضع الأذونات | طبيعة سلوكه | السيناريو الأنسب |
|---|---|---|
acceptEdits | يوافق تلقائياً على تعديلات الملفات والأوامر البسيطة، ويطلب تأكيدك للعمليات الأخرى | سيناريوهات التطوير الموثوقة (وهو المستخدم في تجربتنا حالياً) |
bypassPermissions | يوافق تلقائياً على تشغيل كل الأدوات دون تنبيه أو طلب تأكيد | بيئات البناء المستمر الآمنة والمعزولة تماماً |
default | يطلب موافقة صريحة عبر استدعاء دالة موافقة (callback) تحددها بنفسك | لتخصيص مسار إعطاء الأذونات البرمجية |
dontAsk | يرفض تشغيل أي أداة تتطلب إذناً تلقائياً ودون إزعاجك | السيناريوهات البرمجية المقفلة لبيئات CI |
plan | يسمح بأدوات القراءة والتحليل فقط، ويمنع تعديل الملفات | لبناء خطط عمل وتحليل كود المستودع دون تعديله |
الخطوة الخامسة: تشغيل الكود البرمجي
python agent.pyولمطوري TypeScript تشغيل الأمر:
npx tsx agent.ts.
المتوقع: تظهر في الطرفية سجلات متتالية توضح منطق وتفكير Claude (مثل الحاجة لقراءة ملف utils.py أولاً)، ثم تظهر سطور استدعاء الأدوات مثل Tool: Read و Tool: Edit لتنتهي السجلات بعبارة Done: success. رؤية عبارة Done: success تعني انتهاء مهمة الوكيل بنجاح.
الخطوة السادسة: مراجعة ملف utils.py لرؤية التعديلات
افتح ملف utils.py مجدداً. المتوقع: قام الوكيل بإضافة أكواد حماية وفحص — مثل التحقق من كون القائمة فارغة في دالة calculate_average وإرجاع قيمة صفر (أو إخراج خطأ واضح)، والتحقق من سلامة متغير user ووجود حقل name قبل تحويل الحروف في دالة get_user_name.
وهذا هو السر الكامن وراء Agent SDK، وتلخصه عبارة الوثائق الرسمية:
يكمن تميز Agent SDK في قيام Claude بتشغيل وتنفيذ الأدوات بنفسه، دون الحاجة لكتابة كود تشغيلها بنفسك.
فطوال عملية تشغيل الوكيل، قام بشكل آلي ومستقل: بقراءة ملف utils.py وفهمه ← وتحليل الأخطاء وال边界 المتوقعة ← وتعديل الملف البرمجي وإضافة أكواد الحماية. دون أن تكتب سطراً واحداً من منطق العمل البرمجي، وتولى هو كل شيء.
بإتمام هذه الخطوات الست، تكون قد مررت بالمسار الكامل لـ SDK "تثبيت الحزمة ← تهيئة المفتاح ← صياغة دالة query() ← تحديد الأدوات والأذونات ← استقبال تدفق السجلات ← التحقق من النتائج" بنفسك. وتعتبر هذه الخطوات هي الأساس لبناء أي وكيل أتمتة برمجى مستقبلاً — وما عليك سوى تعديل التوجيه prompt وتعديل الأدوات المسموح بها في حقل allowed_tools وربط أدوات MCP أو الأذونات بحسب متطلبات مشروعك.
وتقترح الوثائق الرسمية تجربة توجيهات أخرى لرؤية مرونة الكود البرمجي في التعامل مع المتطلبات: مثل مطالبته بـ
"Add type hints to all functions in utils.py"(لإضافة تلميحات الأنواع)، أو مطالبته بـ"Write unit tests for utils.py, run them, and fix any failures"(لكتابة اختبارات وحدة وتشغيلها وإصلاح الفاشل منها — ويتطلب هذا السماح بأداةBashفي حقل الأدوات لتشغيل الاختبارات).
💡 خلاصة القول في جملة واحدة: تتلخص تجربة تشغيل الوكيل في ست خطوات — إنشاء المجلد ← تثبيت SDK وتهيئة مفتاح الأمان ← إنشاء ملف يحتوي على أخطاء ← كتابة كود استدعاء
query()← تشغيل الكود ← التحقق من تعديل وإصلاح الأخطاء تلقائياً؛ وتجربتك للخطوات بنفسك يزيل أي غموض حول طريقة عمل SDK.
07 لمن تصلح هذه الأداة: هل تحتاجه في عملك حالياً
في النهاية، دعنا نوضح حقيقة هامة: لا يعتبر Agent SDK أداة يجب على كل مطور تعلمها فوراً، ولكنه الأداة التي لا غنى عنها لكل من يفكر في بناء أتمتة برمجية ذكية. ونوضح الحالات لتحدد مسارك وتتجنب تشتيت جهودك.
متى لا تحتاج إليه تماماً؟ إذا كان هدفك هو الاستعانة بـ Claude لمساعدتك في كتابة الكود وإصلاح الأخطاء في طرفيتك المحلية أثناء عملك اليومي البشري — فاكتفِ باستخدام أداة CLI وتجنب تعقيد SDK. فـ SDK مخصص للاتصال البرمجي وكتابة الأكواد، وإذا لم تكن تملك هذا المتطلب، فسيعطيك تعقيداً غير مبرر في التعامل مع البيئات البرمجية ولغات الأتمتة وصيغ الاتصال المتزامن (async).
ومتى يجب عليك التوجه لتعلمه واستخدامه؟ إذا كنت تملك أحد هذه المتطلبات الثلاثة، فابدأ بتعلمه فوراً:
| المتطلب الذي تفكر فيه | هل تتوجه لـ SDK؟ |
|---|---|
| "أريد مساعداً ذكياً يساعدني في كتابة وتصحيح الأكواد في الطرفية" | ❌ لا، استخدم CLI فهو الأنسب والمصمم للتفاعل البشري |
| "تكرر هذا العمل اليدوي عدة مرات، وأريد أتمتته برمجياً ليعمل تلقائياً" | ✅ نعم، اكتب سيناريو برمجي باستخدام SDK ليعمل بالنيابة عنك |
| "أريد إضافة ميزة الذكاء الاصطناعي التي تعدل الملفات وتبني الأكواد لمنتجي الخاص" | ✅ نعم، يعتبر SDK هو الخيار الوحيد والمناسب لبناء هذه القدرات |
| "أريد بناء بوت محادثة أو مهمة دورية تفحص وتعدل الأكواد تلقائياً" | ✅ نعم، فتشغيل هذه المهام عبر CLI صعب وتعتبر حزمة SDK هي الحل |
وتوفر الوثائق الرسمية مساراً للتدرج والتوسع، نذكره لتتضح لك خريطة المستقبل:
يبدأ المطورون عادة باستخدام Agent SDK محلياً لبناء النماذج البرمجية وتجربتها، ثم ينتقلون لاستخدام Managed Agents في بيئات الإنتاج الفعلية.
وهنا يظهر مصطلح جديد وهو Managed Agents (الوكلاء المدارون) — وبالمصطلحات البسيطة، هي خدمة توفرها شركة Anthropic لإدارة وتشغيل الوكلاء والبيئات المعزولة (sandboxes) بالنيابة عنك عبر واجهة REST API، ليرسل تطبيقك الطلبات ويتلقى النتائج، دون أن تتحمل عناء إدارة الخوادم أو حفظ جلسات العمل. بينما يعمل Agent SDK داخل تطبيقك وجهازك الخاص ويدير دورة التكرار محلياً. ونلخص الفوارق البرمجية والعملية بينهما بناءً على اللوحة الرسمية:
| وجه المقارنة | Agent SDK | Managed Agents |
|---|---|---|
| بيئة التشغيل | داخل تطبيقك وخوادمك الخاصة | خوادم مدارة ومدارة بالكامل من شركة Anthropic |
| واجهة الاستخدام | مكتبة برمجية بلغة Python / TypeScript | واجهة طلبات REST API |
| الملفات التي يعدلها | الملفات الحقيقية لجهازك أو خادمك | بيئة معزولة (sandbox) مخصصة لكل جلسة محادثة |
| الأنسب لـ | التجارب المحلية، والوكلاء الذين يتعاملون مع ملفات جهازك مباشرة | بيئات الإنتاج، وتجنب عناء إدارة وصيانة الخوادم والبيئات المعزولة |
ولذلك يسير التدرج الطبيعي للمطور كالتالي: تبدأ باستخدام Agent SDK محلياً لتجربة وبناء فكرتك (تماماً كما فعلنا في القسم 06)، وعند رغبتك في نقل الفكرة للإنتاج وخدمة زبائن كثر وتجنب إدارة البنية التحتية، تتوجه لاستخدام Managed Agents. ويعتبر Agent SDK هو بوابتك الأولى للتعلم والتجربة، وتعتبر Managed Agents هي خطوتك التالية للتوسع — والتركيز على فهم وإتقان خطوة Agent SDK حالياً كافٍ وممتاز.
وعند تحويلك لبعض المهام الروتينية لسيناريوهات برمجية باستخدام SDK — مثل فحص وتحديث الاعتماديات منتهية الصلاحية لمستودعاتك أسبوعياً وتوليد تقرير منظم بها. ورؤيتك للتقرير وهو يولد تلقائياً مع استيقاظك صباحاً بفضل الأتمتة الدورية، يعطيك شعوراً بالقدرة على "صناعة أدوات تعمل بالنيابة عنك" لا توفره لك أداة CLI التفاعلية. فإذا كنت تواجه مهاماً مكررة تود التخلص منها — فهذا هو موعد الانتقال لـ SDK.
💡 خلاصة القول في جملة واحدة: إذا كان هدفك هو التفاعل الشخصي مع Claude في الطرفية فاستخدم CLI وتجنب SDK؛ وإذا كان هدفك أتمتة عملية مكررة برمجياً أو تضمين ميزات الذكاء الاصطناعي في تطبيقك فاستخدم SDK؛ ويسير التدرج بـ "البدء بـ Agent SDK محلياً ثم الانتقال لـ Managed Agents للإنتاج"، وركز على الخطوة الأولى حالياً.
08 خلاصة
كشفنا في هذا الدرس الغطاء البرمجي عن "الوجه الداخلي" لـ Claude Code — وهو إمكانية استدعاء وتضمين محركه الأساسي كحزمة برمجية داخل كودك الخاص، وهو ما توفره حزمة Agent SDK.
ونلخص النقاط الأساسية التي شرحناها في الدرس:
| ما تريد فهمه | الإجابة والحل | النقاط الرئيسية |
|---|---|---|
| ما هو Agent SDK | محرك Claude Code كحزمة برمجية | يضم دورة عمل الوكيل والأدوات وإدارة السياق للتطوير البرمجي |
| علاقته بـ CLI | محرك موحد بمدخلين | للتفاعل الشخصي نستخدم CLI، وللأتمتة البرمجية نستخدم SDK، والخبرة مشتركة |
| فارقه عن واجهة API | من يدير دورة تشغيل الأدوات | في واجهة API المعتادة تكتب حلقة while لتشغيل الأدوات بنفسك، ويتولاها SDK هنا تلقائياً |
| نسختا التطوير | لغتان متطابقتان في القدرات | نسخة TS (تتطلب Node 18+) ونسخة Python (تتطلب Python 3.10+) |
| دالة المدخل الأساسي | دالة query() | تمرر لها prompt والإعدادات، وتستقبل تدفق سجل العمليات بالتزامن |
| موعد استخدامه | هل تملكه أتمتة أو منتج برمجى؟ | تجنبه عند الاكتفاء بالتطوير الشخصي، واستخدمه للأتمتة وبناء التطبيقات المخصصة |
يجب أن تكون قادراً الآن على: شرح كيفية استخلاص واستخدام محرك Claude Code برمجياً عبر Agent SDK، وتوضيح الفوارق بينه وبين CLI وبينه وبين واجهة API الأساسية لشركة Anthropic، واختيار وتثبيت نسخة اللغة المتوافقة مع مشروعك (TS أو Python)، وفهم وتعديل الأكواد البرمجية لدالة query() وتحديد الأدوات والأذونات الممنوحة للوكيل، وبناء وتشغيل وكيل محلي يكتشف ويصلح الأخطاء البرمجية بنفسك. والأهم من ذلك، تحديد ما إذا كان مشروعك يحتاج للتوجه لـ SDK حالياً أم لا. وبفهمك لهذه المبادئ، يتحول Claude Code من أداة سطر أوامر تستخدمها إلى مجموعة قدرات برمجية تطوعها لبناء وتطوير تطبيقاتك الخاصة.
بهذا المفهوم، يتسع نطاق استخدامك لـ Claude Code من مجرد كونه "أداة مساعدة" إلى كونه "مكوناً أساسياً" تبني به منتجاتك البرمجية المبتكرة.
الدرس القادم 46 "إعدادات التطوير" — لقد تعلمنا كيفية برمجة الوكيل باستخدام SDK، ولكن للانتقال للتطوير الفعلي، لا تكفي دالة query() وحدها: فكيف نحمي مفاتيح API في بيئات التطوير المختلفة، وكيف نفصل بين إعدادات البيئة المحلية وبيئة الإنتاج، وكيف نهيئ المتغيرات البيئية عند استخدام بوابات اتصال ونماذج خارجية... هذه "الترتيبات الأساسية اللازمة قبل بدء التطوير" سنقوم بفرزها وتوضيحها في الدرس القادم. فكر في الأمر: كود الوكيل يعمل بنجاح على جهازك الشخصي، ولكنه يفشل في الاتصال بالنموذج بمجرد رفعه للخادم، وغالباً ما يكمن السبب في أخطاء تهيئة المتغيرات والإعدادات — وسنساعدك في تجنب هذه العوائق مسبقاً.