بناء الوكلاء على الواجهة البرمجية (API)
- تعريف ما هو الوكيل فعلًا: نموذج يعمل ضمن حلقة
- تطبيق اختبار اتخاذ القرار لاختيار استدعاء واحد مقابل سير عمل مقابل وكيل
- تصميم حلقة وكيل بحدّها الأدنى مع الضوابط الوقائية الصحيحة
- معرفة متى تلجأ إلى Claude Agent SDK بدلًا من البناء اليدوي
- اجعل الوكيل متينًا: حُدّه، وعالِج الأعطال، وقيّد الصلاحيات، وقيّمه
الوكيل هو نموذج يعمل ضمن حلقة: يسعى لتحقيق هدف عبر استدعاء الأدوات، ومراقبة النتائج، واتخاذ قرار الخطوة التالية حتى الانتهاء. قبل أن تبني وكيلًا، اختر أبسط شيء يؤدّي الغرض.
اختبار اتخاذ القرار (لا تُفرط في البناء)
ليست كل مهمة تحتاج إلى وكيل. اسلك هذه الشجرة أولًا — تتوقّف معظم المهام عند القمّة.
ثلاثة خيارات، الأبسط أولًا:
- استدعاء واحد — مطالبة واحدة تجيب عنه. معظم المهام. الأرخص والأكثر موثوقية.
- سير عمل — أنت تنسّق تسلسلًا ثابتًا من الاستدعاءات في الشيفرة (تدفّق تحكّم حتمي). استخدمه عندما تكون الخطوات معروفة.
- وكيل — النموذج يقرّر الخطوات ديناميكيًا. استخدمه فقط عندما يتعذّر فعلًا ترميز المسار بشكل ثابت.
لجأ إلى الوكيل عندما تكون القابلية للتكيّف هي الهدف — لا لأنه يبدو مبهرًا. سير العمل الذي تتحكّم به أسهل في الاختبار وتصحيح الأخطاء.
تصميم الحلقة
الوكيل المخصّص بحدّه الأدنى ما هو إلا أربعة أجزاء متحرّكة. ابنِها بهذا الترتيب:
- بيّن الهدف، والقيود، والأدوات المتاحة. هذا ما يستند إليه النموذج في تفكيره في كل دورة.
- أرسل الرسائل ← إذا كانت الاستجابة tool_use، شغّل الأداة، وأضف tool_result، وكرّر ← حتى الوصول إلى إجابة نهائية أو شرط توقّف.
- أضِف حدًّا أقصى للتكرارات، وميزانية للرموز/التكلفة، والتحقّق من مدخلات الأدوات قبل تشغيل أي شيء.
- لخّص أو قلّص مع نموّ السجلّ — الفكرة ذاتها التي تناولناها في إدارة السياق (/docs/claude-code/context-management).
تمنحك حزمة Claude Agent SDK هذه الحلقة — الأدوات، والصلاحيات، ومعالجة السياق — جاهزة بالكامل، حتى لا تبنيها يدويًا بنفسك.
قبل أن تكتب حلقتك الخاصة، اسأل ما إذا كانت Agent SDK تغطّيها بالفعل. فهي توفّر الحلقة، والصلاحيات، ومعالجة السياق حتى تتمكّن من التركيز على الأدوات والهدف.
اجعله متينًا
الحلقة التي تستطيع استدعاء الأدوات تستطيع أيضًا أن تسيء التصرّف. أربع عادات تُبقي الوكيل جديرًا بالثقة:
- حُدّ كل شيء: التكرارات، والوقت، والتكلفة. فالوكلاء قد يدخلون في حلقة لا تنتهي.
- عالِج أعطال الأدوات بسلاسة (أعِد الخطأ كنتيجة).
- أقل صلاحية ممكنة + تدخّل بشري للإجراءات الخطرة — راجع تأمين الوكلاء.
- قيّمه على حالات حقيقية قبل الوثوق به — راجع التقييمات ودليل تقييم وكيل الذكاء الاصطناعي الخاص بك المخصّص للتقييم على مستوى المسار ولبوابة CI.
- الوكيل هو نموذج يعمل ضمن حلقة يستدعي الأدوات سعيًا لتحقيق هدف — استخدمه فقط عندما يتعذّر ترميز المسار بشكل ثابت
- ترتيب القرار: استدعاء واحد ← سير عمل ← وكيل ← الوكلاء المُدارون؛ فضّل الأبسط الذي يؤدّي الغرض
- الحلقة بحدّها الأدنى = مطالبة النظام + حلقة tool_use/tool_result + ضوابط وقائية + إدارة السياق
- تمنحك Claude Agent SDK الحلقة، والأدوات، والصلاحيات، ومعالجة السياق جاهزة
- المتانة = تحديد التكرارات/الوقت/التكلفة، ومعالجة أعطال الأدوات، وأقل صلاحية ممكنة + تدخّل بشري، والتقييم قبل الوثوق