الوحدة 2 — الوكلاء والأدوار والأهداف

قرّرنا في الوحدة 1 أنّ فريقًا من أربعة وكلاء يستحقّ العمل على وثيقة المنتَج. الوحدة الحاليّة تُنشئ هؤلاء الوكلاء واحدًا واحدًا. الفئة Agent في CrewAI بسيطة في الظاهر، لكنّ كلّ حقل فيها يؤثّر فعلًا على السلوك: تعليمة كلمة واحدة زيادة قد تُغيّر مسار الفريق كلّه.

الحقول الثلاثة التي تصنع وكيلًا

كلّ Agent في CrewAI يبدأ بثلاثة حقول إلزاميّة، تُتَرجَم داخليًّا إلى تعليمة نظام يقرأها النموذج قبل أن يبدأ العمل:

• role: الدور الوظيفيّ في جملة قصيرة، من نوع «محرّر تقنيّ للوثائق البرمجيّة». يُستعمل في السجلّات ويُقدَّم في تعليمة النظام.
• goal: الهدف الملموس لهذا الوكيل داخل الفريق، من نوع «إنتاج وثيقة عشر صفحات بأسلوب رسميّ متماسك تصف الوظائف المُستخرَجة من المواصفات». هدف واضح يمنع النموذج من الابتعاد.
• backstory: القصّة الخلفيّة التي تُلوّن الأسلوب، مثل «تعمل منذ عشر سنوات على وثائق واجهات برمجيّة عامّة لشركات SaaS». تُوجّه اللهجة والمفردات دون أن تُقيّد.

الفئة تقبل حقولًا اختياريّة نستعملها كثيرًا: llm لاختيار النموذج، tools لقائمة الأدوات، verbose=True لتفعيل السجلّ التفصيليّ، allow_delegation=True للسماح بالتفويض (الوحدة 6)، max_iter لسقف الحلقة الداخليّة.

اختيار النموذج بحسب الدور

خطأ شائع: استعمال gpt-4o لكلّ الوكلاء «لأنّه الأقوى». الحقيقة أنّ كلّ وكيل يحتاج نموذجًا يناسب مهمّته:

• المحلِّل والمراجِع: يقرؤون كثيرًا ويُنتجون قليلًا. نموذج قوي في الاستيعاب مثل gpt-4o أو claude-3.5-sonnet مُبرَّر.
• المحرِّر: يُنتج نصًّا طويلًا. النموذج نفسه، لكن مع درجة حرارة أعلى (temperature=0.5) لتنويع الأسلوب.
• المسؤول: يُدير التفاعل ويُوزّع. نموذج أخفّ يكفي، مثل gpt-4o-mini، لأنّ قراراته قصيرة.

هذا التوزيع خفّض فاتورة تجربة داخليّة من 4 دولارات إلى 1.3 دولار لكلّ وثيقة، بلا تغيير في الجودة المُقاسة.

from crewai import Agent
from langchain_openai import ChatOpenAI

llm_lourd = ChatOpenAI(model="gpt-4o", temperature=0)
llm_ecrit = ChatOpenAI(model="gpt-4o", temperature=0.5)
llm_leger = ChatOpenAI(model="gpt-4o-mini", temperature=0)

الوكلاء الأربعة للخيط الأحمر

نُعرّف الآن وكلاء فريقنا. الملاحظة الأهمّ: كلّ دور يُذكَر في جملة، وكلّ هدف يذكر معيار نجاح قابلًا للقياس.

analyste = Agent(
    role="محلّل مواصفات منتَج",
    goal="استخراج قائمة كاملة من الوظائف والفئات المستهدفة من ملفّ المواصفات",
    backstory="مهندس منتَج بخبرة عشر سنوات في تحليل مواصفات SaaS",
    llm=llm_lourd,
    verbose=True,
)

redacteur = Agent(
    role="محرّر تقنيّ",
    goal="كتابة وثيقة عشر صفحات بأسلوب رسميّ يغطّي كلّ الوظائف المُستخرَجة",
    backstory="محرّر توثيقات لواجهات برمجيّة عامّة منذ عام 2015",
    llm=llm_ecrit,
    verbose=True,
)

relecteur = Agent(
    role="مراجِع تقنيّ",
    goal="التحقّق من التماسك اللغويّ والدقّة التقنيّة، وإصدار قائمة تصحيحات محدّدة",
    backstory="مراجِع لغويّ يعمل مع فرق توثيق منذ سبع سنوات",
    llm=llm_lourd,
    verbose=True,
)

responsable = Agent(
    role="مسؤول التحرير",
    goal="ضمان أنّ المخرَج النهائيّ يحترم قيود العدد الأقصى من الصفحات ومعايير الجودة",
    backstory="مدير توثيق يوازن بين آراء المحرّر والمراجِع",
    llm=llm_leger,
    allow_delegation=True,
    verbose=True,
)

الإسهاب: صديق التطوير عدوّ الإنتاج

verbose=True يُظهر في السجلّ كلّ تفكير وكيل قبل أن يفعل، وكلّ نداء نموذج، وكلّ نتيجة أداة. هذا لا غنى عنه أثناء التطوير: يُظهر لماذا اختار الوكيل هذه الأداة، وكيف قرأ نتيجتها، وأين تعثّر.

في الإنتاج، ينتج آلاف الأسطر لكلّ تنفيذ، ويُبطّئ التنفيذ، ويُظهر أحيانًا أسرارًا. القاعدة: verbose=True أثناء التطوير، وإخراج مُهيكَل عبر callbacks في الإنتاج (الوحدة 9).

الفخّ: هدف يعني «كلّ شيء»

«الهدف: إنتاج وثيقة جيّدة» بلا معايير قابلة للقياس يعني أنّ النموذج لن يعرف متى ينتهي. سيُطيل ويُطيل، أو يُنتج فقرة ويعتبر المهمّة منتهية. الأهداف الجيّدة تحتوي على قيد كمّيّ («عشر صفحات»، «قائمة كاملة»، «قائمة تصحيحات محدّدة») ومعيار كيفيّ («بأسلوب رسميّ»، «قابلة للقياس»).

قاعدة قرار

اقرأ هدف الوكيل بصوت عالٍ. إن لم تستطع تصوّر مخرَج ملموس بعد جملة واحدة، أعِد الصياغة.

قاعدة عمليّة قبل الانتقال إلى المهامّ

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

الخلاصة

• كلّ Agent يُعرَّف بثلاثة حقول: الدور، والهدف، والقصّة الخلفيّة؛ وحقول اختياريّة تُغيّر السلوك عمليًّا.
• اختَر نموذجًا بحسب المهمّة: نموذج قوي للاستيعاب والمراجعة، ونموذج خفيف للتنسيق.
• verbose=True لا غنى عنه في التطوير، وممنوع في الإنتاج بلا فلترة.
• الهدف يجب أن يحمل قيدًا كمّيًّا ومعيار جودة، وإلاّ فلن يعرف الوكيل متى ينتهي.