دير أوديت لاستدعاءات الأدوات ديال وكيل الذكاء الاصطناعي بـ ToolReplay

شنو كيدير ToolReplay

ToolReplay كيدير تدقيق لاستدعاءات الأدوات ديال وكلاء الذكاء الاصطناعي المسجّلة، بلا ما يشغّل الأدوات الحقيقية. كيفحص السجل باش يحدّد ثلاثة ديال المشاكل: الردود اللي ماشي حتمية، الاستدعاءات المكرّرة، والاستدعاءات اللي خارج الصلاحيات المصرّح بها ديال الوكيل. ويقدر حتى يختم السجل فـ سلسلة ديال التجزئات SHA-256 ويتحقق باللي الملف المختوم ما تبدّلش.

حيت ToolReplay كيعيد تشغيل الردود المسجّلة بلا ما يدير استدعاءات مباشرة، فالتدقيقات آمنة، وما كتخلّيش آثار جانبية، وقابلة لإعادة الإنتاج، وكتخدم حتى ملي الأدوات الأصلية ما تكونش متاحة.

ثبّت وشغّل ToolReplay

ToolReplay كيحتاج Python 3.11 ولا أحدث وما عندوش حتى اعتماديات ديال التشغيل من جهات خارجية. وما كيدخلش للشبكة.

من نسخة مصدرية محلية، شغّل الموديول مباشرة:

python -m toolreplay version

وتقدر حتى تثبّت السكريبت ديال سطر الأوامر:

pip install .
toolreplay version

الطريقتين كيطبعو النسخة المثبّتة، بحال:

toolreplay 0.6.0

فهم صيغة السجل

السجل هو ملف JSON Lines. كل سطر ماشي فارغ كيمثّل استدعاء واحد لأداة، ولازم يكون فيه بالضبط أربعة ديال الحقول:

• index: عدد صحيح كيبدا من 0 وكيتزاد بالضبط بواحد.
• tool: سميّة الأداة اللي تعيّطات.
• args: كائن فيه الوسائط ديال الأداة.
• response: كائن فيه الرد المسجّل ديال الأداة.

السجل الصحيح كيبان هكا:

{"index": 4, "tool": "write_file", "args": {"path": "docs/intro.md", "text": "edited"}, "response": {"ok": true}}

التحليل صارم عن قصد. الحقول المجهولة، والحقول الناقصة، وأنواع الكائنات غير الصالحة، والفهارس اللي ماشي أعداد صحيحة، والفهارس اللي ما جاياش بالترتيب كيسببو خطأ حاسم. القيم المنطقية ما كتقبلش كأعداد صحيحة، رغم أن Python كيتعامل مع bool على أنه فئة فرعية من int.

ToolReplay كيقارن الاستدعاءات باستعمال JSON قانوني: سميّة الأداة والوسائط كيتشفّرو بالمفاتيح المرتّبة وبلا مسافات زايدة. وبالتالي، كائنات الوسائط اللي ترتيب المفاتيح ديالها مختلف كتمثّل نفس الاستدعاء. والردود كتستعمل نفس الترميز القانوني ملي ToolReplay كيتحقق من الحتمية.

دير تدقيق لإعادة التشغيل

الأمر replay كيفحص السجل مقابل الردود المسجّلة ديالو. جرّب العيّنة اللي فيها مشاكل والموجودة فالمستودع:

python -m toolreplay replay samples/session-dirty.jsonl

الأمر كيعطي تقرير حتمي، سطر بسطر:

calls: 6
divergence: index 5
findings: 2
index 2: redundant-call: tool 'read_file' repeats the identical call at index 1 with no state change between them
index 5: non-determinism: tool 'search' returned a different response than the identical call at index 3

الرأس كيتقرا من الفوق للتحت. calls: 6 كتعني أنه تحلّلو ستة ديال السجلات الصحيحة. divergence: index 5 كحدّد أول نقطة فين إعادة تشغيل حتمية غادي تختلف على التسجيل. findings: 2 كتحسب النتائج اللي جاية من بعد.

النتائج كترتّب حسب الفهرس ومن بعد حسب النوع، وبهذا التدقيقات المتكرّرة لنفس المُدخل كتعطي مخرجات مطابقة للبايت.

غياب الحتمية

ToolReplay كيتذكّر أول رد لكل استدعاء قانوني. إلا كان نفس الاستدعاء من بعد عندو رد مسجّل مختلف، كيسجّل غياب الحتمية. فالعينة، استدعاء search ديال install كيبان فالفهرسين 3 و5، ولكن الردود كتعطي عدد نتائج مختلف. وكيولي الفهرس 5 هو نقطة الاختلاف.

هاد الشي مهم بالنسبة للوكلاء، حيت قرار مبني على الجواب الأول يقدر يتبدّل إلا رجع الجواب الثاني. والنتيجة كتشير باللي الجلسة معتمدة على معلومات ماشي مستقرة داخل التسجيل.

الاستدعاءات المكرّرة

الاستدعاء المكرّر كيكون زايد غير إلا ما كان حتى حدث مسجّل بين الاستدعاءين يقدر يبدّل الحالة. الأدوات الافتراضية اللي كتبدّل الحالة هي write_file وdelete_file وcreate_file وmove_file وrun_command. وأي استدعاء مختلف بين استدعاءين متطابقين كيتعتبر حتى هو، بحذر، تغيير محتمل فالحالة.

فالعينة، read_file كيقرا docs/intro.md فالفهرسين 1 و2 بلا أي تغيير فالحالة بيناتهم، وبهذا كيتعلّم الفهرس 2. أما قراءة لاحقة من بعد استدعاء write_file فما غاديش تعتبر مكرّرة.

تحقّق من صلاحيات الوكيل

استعمل scope ملي تكون عندك وثيقة الصلاحيات ديال الوكيل:

python -m toolreplay scope samples/session-dirty.jsonl samples/scope.json

العينة كتعطي:

calls: 6
findings: 1
index 4: permission-overreach: tool 'write_file' is not in the declared scope for agent 'docs-reader'

إعادة التشغيل وفحص الصلاحيات أمران منفصلان عن قصد. إعادة التشغيل كتقيّم الجلسة مقابل راسها وكتحتاج غير للسجل. وفحص الصلاحيات كيقارن كل استدعاء مع ملف صلاحيات منفصل.

ملف الصلاحيات هو كائن JSON واحد فيه سميّة الوكيل ولائحة دقيقة ديال الأدوات المسموح بها:

{"agent": "docs-reader", "allowed_tools": ["read_file", "list_dir", "search"]}

سميات الأدوات كيتطابقو حرفياً وبحساسية لحالة الأحرف. الحقول الناقصة، والأنواع غير الصحيحة، والعناصر اللي ماشي نصوص كيرفضو. فحص الصلاحيات كيعتمد على السمية؛ ما كيفحصش الوسائط وما كيحدّدش واش الأداة المسموح بها كتستهدف مساراً مسموحاً.

ختم السجل

الأمر seal كيحوّل السجل لملف JSONL مربوط بسلسلة ديال التجزئات:

python -m toolreplay seal samples/session-dirty.jsonl > sealed.jsonl

كل رابط مختوم كيحتوي على الحقول الأصلية ديال السجل، وزايد عليهم prev وdigest. الرابط اللول كيستعمل 64 حرف سداسي عشري صفري كـ digest سابق. كل digest لاحق ديال SHA-256 كيشمل الـ digest السابق والبايتات القانونية ديال السجل الحالي، بما فيها الفهرس، والأداة، والوسائط، والجواب.

حيت كل رابط كيعتمد على الرابط اللي قبل منو، فتغيير سجل سابق كيبدل digest ديالو وجميع الـ digests اللي من بعدو. بهاد الشكل، السلسلة كتبرز التعديلات وكتحدد فين كاين أول رابط مكسور.

تحقّق من ملف مختوم

تحقّق من سلسلة سليمة بهاد الأمر:

python -m toolreplay verify sealed.jsonl

إلى كان الملف ما تبدلش، كيظهر:

chain: intact

إلى تبدل جواب مسجل ولا أي حقل آخر داخل السلسلة، فالتحقق كيبيّن أول رابط مكسور والـ digests المتوقع والموجود:

chain: broken
first broken link: index 3
expected: 34d19a9dfb112baa07afa37994ddcbbebe2973674385f3942340653d08d205bd
found: 40aadf3b8156217f0b5b1d95010b6b79f82a26ccf5e780aed0f5f311f865028a

الختم كيكتاشف التعديلات من بعد الختم، بما فيها التغييرات فترتيب السجلات، والفهارس، والأدوات، والوسائط، والأجوبة. ولكن ماشي توقيع رقمي: أي واحد يقدر يعدل الملف يقدر حتى يعاود يختمو. باش نثبتو المصدر، خاص توقيع الـ digest النهائي بمفتاح متدبّر خارج ToolReplay.

استعمل ToolReplay فـ CI

رموز الخروج ديال ToolReplay كاتخليه مناسب لبوابات البناء:

• 0: التدقيق نقي ولا السلسلة سليمة.
• 1: كاينين ملاحظات ولا السلسلة مكسورة.
• 2: وقع خطأ فالاستخدام، بحال إدخال غير صالح ولا ملف ناقص.

شغّل إعادة التشغيل وفحوصات النطاق مباشرة فـ مهمة CI:

python -m toolreplay replay session.jsonl
python -m toolreplay scope session.jsonl scope.json

رمز الخروج 1 كيعني باللي الأداة كملات التدقيق ولقات شي حاجة خاصها التبليغ. رمز الخروج 2 كيعني باللي التدقيق ما قدرش يخدم، وبهذا تقدر الأتمتة تفرّق بين إدخال غير صالح ونتيجة فعلية فالتدقيق.

باش تدير مقارنات قابلة لإعادة الإنتاج، ختم كل تشغيل وقارن النتائج:

python -m toolreplay seal run-a.jsonl > run-a.sealed.jsonl
python -m toolreplay seal run-b.jsonl > run-b.sealed.jsonl
git --no-pager diff --no-index run-a.sealed.jsonl run-b.sealed.jsonl

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

الاستعمال المتقدم والحدود العملية

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

شغّل مجموعة الاختبارات

المشروع كيستعمل إطار unittest القياسي ديال Python، وما عندوش حتى اعتماد اختباري من طرف ثالث. من جذر المستودع، شغّل:

python -m unittest discover -s tests

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

الخلاصة

ToolReplay كيوفر مسار تدقيق مركز لجلسات الوكلاء ديال الذكاء الاصطناعي. بَدا بـ replay باش تلقى السلوك غير المتناسق ولا اللي كيضيع الموارد، واستعمل scope باش تراجع الصلاحيات المصرّح بها للأدوات، واستعمل seal مع verify باش تكتاشف التغييرات من بعد التسجيل. التحقق الصارم من المدخلات والتقارير الحتمية ديالو كيخليوه عملي للتصحيح، والمراجعة، والتحكم فالإصدارات، وفرض القواعد فـ CI.