الوحدة 10 — مشروع: وكيل بحث وثائقيّ مضبوط

نجمع في هذه الوحدة كلّ ما بنيناه: أدوات، حلقة، ذاكرتان، تخطيط، تحقّق، ضوابط، وقابليّة مراقبة. الغاية ليست وكيلًا لامعًا في العرض، بل وكيلًا يعمل في يوم عمل عاديّ لفريق منتَج، وتُقاس جودته بـ 30 سؤالًا مرجعيّة.

البنية العامّة

خمس طبقات:

طبقة الأدوات (بايثون): recherche_web, lire_page, base_interne, noter_fait, verifier_fait.
طبقة الذاكرة: مخزن متّجهيّ (Chroma) لذاكرة طويلة، وقائمة رسائل مع تلخيص تدريجيّ لذاكرة العمل.
طبقة الوكيل: مخطِّط (gpt-4o) + منفِّذ (gpt-4o-mini) + متحقِّق (gpt-4o)، مع حلقة ReAct داخل كلّ خطوة تنفيذ.
طبقة الضوابط: حدّ تكرار 12، ميزانيّة 20 ألف/4 آلاف رمز، صلاحيّات مصنَّفة، بيئة معزولة لـlire_page.
طبقة قابليّة المراقبة: أثر JSON، تنبيهات، لوحة أسبوعيّة.

        [مستخدم]
           │
           ▼
      [مصنّف السؤال]  ─── بسيط ──▶  [سلسلة موجَّهة]
           │
        معقّد
           ▼
       [مخطِّط] ── خطّة ──▶ [منفِّذ (ReAct)] ── أدوات ──▶ [تنفيذ]
                                     │
                                     ▼
                              [متحقِّق (نموذج + أداة)]
                                     │
                              مقبول │ يحتاج تصحيح
                                     ▼
                                [مذكّرة]

البناء التدريجيّ

قاعدة عمليّة: لا تبدأ بالوكيل الكامل. ابنِ إلى الأعلى:

اليوم 1: الأدوات وحدها، مع اختبارات وحدة. recherche_web تعمل، lire_page تُقتطع، base_interne تُصنِّف الحالات.
اليوم 2: حلقة ReAct بسيطة (الوحدة 2)، بلا تخطيط، بلا تحقّق، بحدّ تكرار 6.
اليوم 3: التلخيص التدريجيّ (الوحدة 4) للتشغيلات التي تتجاوز خمس خطوات.
اليوم 4: طبقة التخطيط للأسئلة المُصنَّفة معقّدة (الوحدة 5).
اليوم 5: التحقّق الثلاثيّ (الوحدة 6): بأداة، بنموذج، بتصحيح موجَّه.
اليوم 6: الضوابط الأربع (الوحدة 7)، وبيئة قراءة معزولة.
اليوم 7: قابليّة المراقبة (الوحدة 9)، ولوحة، وتنبيهات.

كلّ يوم يُنتج نسخة قابلة للتشغيل. لا تنتقل حتّى تكون النسخة السابقة مستقرّة.

جدول التقييم: 30 سؤالًا مرجعيّة

بلا جدول، كلّ تعديل مقامرة. نُنشئ جدولًا يحوي 30 سؤالًا متنوّعة:

10 أسئلة حالية: تتطلّب recherche_web (تواريخ، إصدارات، أخبار).
10 أسئلة داخليّة: تتطلّب base_interne (سياسات، وثائق فريق).
10 أسئلة مركَّبة: تتطلّب مزجًا (سياسة داخليّة + إصدار خارجيّ + تحقّق تناقض).

لكلّ سؤال، جواب مرجعيّ ومصادر متوقّعة، بمصادقة بشريّة. نُشغّل الوكيل شهريًّا على الجدول، ونقيس:

مؤشّر	القيمة الحاليّة	الحدّ الأدنى المقبول
معدّل النجاح	87 ٪	80 ٪
متوسّط الكلفة	0.11 $	< 0.20 $
متوسّط الزمن	14 ث	< 25 ث
تجاوز الميزانيّة	3 ٪	< 10 ٪
حقن التعليمات المُكتَشف	2 حالة	كلّها ملتقَطة

انحدار في المؤشّر الأوّل تحت 80 ٪ يمنع النشر.

معالجة أخطاء الأدوات

كلّ أداة تُغلَّف بمحاولة صريحة، لا تسمح باستثناء غير معالج بالوصول إلى النموذج:

def executer_avec_gestion(nom, args):
    try:
        return fonctions[nom](**args)
    except TimeoutError:
        return {"statut": "erreur", "raison": "المهلة انقضت، أعِد المحاولة بعد قليل"}
    except ConnectionError:
        return {"statut": "erreur", "raison": "الاتّصال مقطوع، خدمة خارجيّة معطَّلة"}
    except ValidationError as e:
        return {"statut": "erreur", "raison": f"وسائط غير صالحة: {e}"}
    except Exception as e:
        journal.error("خطأ غير متوقَّع في %s: %s", nom, e)
        return {"statut": "erreur", "raison": "خطأ غير متوقَّع، توقّف مؤقّت"}

النموذج يقرأ statut وraison، ويقرّر: إعادة المحاولة، بديل، أو اعتذار للمستخدم. لا stack trace يمرّ إليه؛ رسالة إنسانيّة قصيرة تكفي.

تقرير الحوادث الأسبوعيّ

كلّ أسبوع، تلقائيًّا:

عدد التشغيلات، معدّل النجاح، كلفة الأسبوع.
ثلاث حالات فاشلة عشوائيّة، بأثرها كاملة، للمراجعة.
كلّ الحالات التي بلغت حدّ التكرار أو الميزانيّة (لا اختيار عشوائيّ هنا).
كلّ حالة أنماط حقن مكتشَفة في ملاحظات الأدوات.
تحديثات مقترَحة لكتالوج الأعطال.

هذا التقرير يقرأه فرد واحد في الفريق لمدّة نصف ساعة. مصدر الجودة الحقيقيّ في الإنتاج.

شروط الانتقال إلى الإنتاج

قبل أن يُخدم مستخدمًا حقيقيًّا، الوكيل يجتاز:

تقييم مصادَق: 30 سؤالًا بنسبة نجاح ≥ 80 ٪.
اختبار حمل: 20 استفسارًا متوازيًا بلا انهيار.
سيناريو خطأ مُفتعَل: أداة معطَّلة، مزوّد نموذج ينفد رصيده، مفتاح منقض الصلاحيّة.
مسح أمنيّ: قائمة الأدوات مُراجَعة، الأذونات محدَّدة، بيئة lire_page معزولة.
مسؤول محدَّد: شخص واحد يستلم التنبيهات، ويقرأ التقرير الأسبوعيّ.

انتقال بلا هذه القائمة يُنتج «وكيلًا نموذجيًّا» يعمل في التطوير ويفشل في الإنتاج.

اقتصاديّات الوكيل

قياس عمليّ على وكيل البحث بعد شهر إنتاج:

340 استفسارًا شهريًّا.
38 دولارًا كلفة نموذج، منها 61 ٪ على المنفِّذ، 24 ٪ على المتحقِّق، 15 ٪ على المخطِّط.
4 دولارات كلفة استضافة (قاعدة، مخزن متّجهيّ، تسجيل).
42 دولارًا شهريًّا كلّه.

الأثر البشريّ: 340 مذكّرة، إن كتبها إنسان بمعدّل 20 دقيقة، 113 ساعة عمل شهريًّا. أوفَر بكلّ المقاييس. لكنّ العدد لا يُبرِّر الوكيل وحده؛ الجودة أوّلًا: مذكّرة بأخطاء تُوقف قرارًا وتكلّف أكثر من ألف مذكّرة.

الفخّ: الوكيل الذي «سيتحسّن غدًا»

وكيل يُشغَّل بمعدّل نجاح 72 ٪ بحجّة «سنُحسِّنه بعد التسليم» يبقى على 72 ٪ بعد سنة. الأولويّة تنتقل، الفريق يتغيّر، الجدول التقييميّ يُهمَل. قاعدة: لا تسلّم وكيلًا تحت 80 ٪. من الأفضل تأخير التسليم أسبوعَين على إطلاق منتج لا يُوثَق به.

اجتماع مراجعة أسبوعيّة نصف ساعة

هذا هو ما يُبقي الوكيل حيًّا. عشر آثار عشوائيّة، الحالات الفاشلة، شكاوى المستخدمين. تحديث الكتالوج. تحديث الجدول التقييميّ إذا لزم. بلا هذا الاجتماع، الوكيل يتعفّن هادئًا حتّى ينفجر.

الخلاصة

بناء تدريجيّ بسبع مراحل، كلّ مرحلة قابلة للتشغيل؛ لا تنتقل حتّى تستقرّ السابقة.
جدول 30 سؤالًا مرجعيّة يقيس معدّل النجاح، الكلفة، الزمن، ونسب التجاوز؛ ينحدر → لا ينشر.
شروط الإنتاج خمس: تقييم مصادَق، اختبار حمل، سيناريو خطأ، مسح أمنيّ، مسؤول محدَّد.
الاقتصاديّات تُبرِّر الوكيل حين الجودة تحرس؛ 72 ٪ نجاح ليست بداية للتحسين، بل توقّف عن التسليم.

البنية العامّة​

البناء التدريجيّ​

جدول التقييم: 30 سؤالًا مرجعيّة​

معالجة أخطاء الأدوات​

تقرير الحوادث الأسبوعيّ​

شروط الانتقال إلى الإنتاج​

اقتصاديّات الوكيل​

الفخّ: الوكيل الذي «سيتحسّن غدًا»​

الخلاصة​