Claude Agent SDK: وظيفته وكيفية تقييمه

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

بالنسبة للفرق التي تحتاج إلى إنجاز أعمالها القائمة على المصادر دون امتلاك بيئة تشغيل وكيل، يوفر Ottermind مسار مساحة العمل المُدارة: حيث يتم ربط الملفات وسياق البحث والقرارات والمخرجات أثناء مراجعة النتائج. يحل كل من SDK ومساحة العمل المُدارة مشكلات تشغيلية مختلفة.

البحث والإفصاح: يستند هذا الدليل إلى مستودع Claude Agent SDK وAnthropic - وثائق استخدام الأداة وAWS AgentCore Claude Agent SDK وثائق، الذي تمت مراجعته في 3 سبتمبر 2026. تتطور واجهات برمجة التطبيقات والقيود باستمرار؛ لذا يُرجى التحقق من الإصدار الحالي قبل التطبيق.

المكونات الأساسية

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

البدء بمهمة واحدة قابلة للعكس

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

عقد مهمة بسيط

Prompt

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

الجلسات والوكلاء الفرعيون

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

بنية عملية

احتفظ بمجموعة تطوير البرامج (SDK) ضمن حدود تطبيق بخمس مسؤوليات:

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

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

الجلسات، الاستئناف، والفشل

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

أمثلة على تصميم الأدوات

يُفضّل استخدام وظيفة مثل create_draft_task(title, owner, due_date) بدلاً من أداة سطر الأوامر العامة. تُمكّن هذه الوظيفة المُخصصة من فرض تنسيقات التاريخ، والمالكين المُصرّح لهم، ونطاق المشروع، وحالة المسودة فقط. يجب أن تُعيد أداة البحث عن الملفات مُعرّفات الملفات ومقتطفات منها، لا أن تكشف عن محرك الأقراص بالكامل دون تنبيه. يجب أن تستخدم أداة التصفح قائمة السماح وأن تتوقف قبل المصادقة أو الدفع.

التكاليف وزمن الاستجابة

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

مجموعة تطوير البرامج (SDK) مقابل مساحة عمل مُدارة

استخدم حزمة تطوير البرامج (SDK) عندما يحتاج فريقك إلى أدوات خاصة بالتطبيق، أو التحكم في النشر، أو بيئة تشغيل مخصصة، مع إمكانية إدارة الأمان والمراقبة والصيانة. تُعد مساحة العمل المُدارة نقطة انطلاق أفضل عندما يكون الشرط الأساسي هو ربط الملفات والأبحاث والقرارات والمخرجات للمراجعة البشرية. يتعلق الاختيار بمسؤولية التشغيل، وليس بأي تسمية تبدو أكثر استقلالية.

مثال: وكيل لتحويل الأبحاث إلى ملخصات.

تخيل فريقًا يحتاج إلى تقرير أسبوعي عن المنافسين. يتحقق معالج الطلبات من هوية المحلل ويختار المشروع المعتمد. يسترجع مُحمِّل السياق قائمة المصادر ويسجل تاريخ الاسترجاع. لا يمكن لجلسة الوكيل استدعاء سوى search_approved_sources وdraft_brief. ترفض طبقة السياسات طلبات عناوين URL العشوائية، أو المنشورات الخارجية، أو الملفات خارج المشروع. يتطلب مُهايئ النتائج أقسامًا للنتائج، والاستشهادات، ونقاط عدم اليقين، والأسئلة المفتوحة قبل عرض المسودة على المُراجع.

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

الترقيم والتحديثات

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

قائمة التحقق من جاهزية الإنتاج

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

حدود الأذونات والأمان.

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

تقييم سير العمل، وليس العرض التوضيحي.

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

الأسئلة الشائعة

هل Claude Agent SDK هو نفسه استخدام أداة Claude API؟

لا. استخدام الأداة هو نمط تفاعل مع النموذج. توفر SDK المزيد من اللبنات الأساسية على مستوى التطبيق لجلسات الوكيل وسير العمل، بينما يظل تطبيقك مسؤولاً عن السياسة والتخزين والأذونات والتقييم.

هل أحتاج إلى عدة وكلاء؟

عادةً لا يكون ذلك ممكنًا في البداية. يُسهل اختبار وتشغيل وكيل واحد بأدوات محدودة ونقاط تحقق واضحة.

هل يمكن لحزمة تطوير البرامج (SDK) تعديل الملفات أو تشغيل الأوامر بأمان؟

يمكن ربطها بمثل هذه الأدوات، لكن الأمان يعتمد على بيئة الاختبار المعزولة (Sandbox)، وقوائم السماح، والتحقق، والمراجعة، وتصميم التراجع. لا تتعامل أبدًا مع أي أمر مُنشأ على أنه مُعتمد مسبقًا.

للاطلاع على حدود النظام الأوسع، راجع بنية وكيل الذكاء الاصطناعي وأمن وكيل الذكاء الاصطناعي..