ToolReplay yordamida AI agentining vosita chaqiruvlarini tekshirish

ToolReplay nima qiladi

ToolReplay haqiqiy vositalarni ishga tushirmasdan, qayd etilgan AI-agent vosita chaqiruvlarini audit qiladi. U transkriptni tahlil qilib, uchta muammoni aniqlaydi: deterministik bo‘lmagan javoblar, ortiqcha chaqiruvlar va agent e’lon qilgan ruxsatlardan tashqaridagi chaqiruvlar. Shuningdek, transkriptni SHA-256 xeshlar zanjiriga muhrlashi va muhrlangan fayl tahrirlanmaganini tekshirishi mumkin.

ToolReplay jonli chaqiruvlarni amalga oshirish o‘rniga qayd etilgan javoblarni qayta ijro etgani sababli, auditlar xavfsiz, nojo‘ya ta’sirlarsiz, takrorlanuvchan bo‘ladi va asl vositalar mavjud bo‘lmaganida ham ishlaydi.

ToolReplay’ni o‘rnatish va ishga tushirish

ToolReplay uchun Python 3.11 yoki undan yangiroq versiya talab qilinadi va u uchinchi tomonning ish vaqtiga oid bog‘liqliklariga ega emas. U tarmoqqa ulanmaydi.

Manba kodi nusxasidan modulni bevosita ishga tushiring:

python -m toolreplay version

Konsol skriptini ham o‘rnatishingiz mumkin:

pip install .
toolreplay version

Har ikkala usul ham o‘rnatilgan versiyani, masalan, quyidagicha chiqaradi:

toolreplay 0.6.0

Transkript formatini tushunish

Transkript JSON Lines faylidir. Har bir bo‘sh bo‘lmagan qator bitta vosita chaqiruvini ifodalaydi va aynan to‘rtta maydonni o‘z ichiga olishi kerak:

• index: 0 dan boshlanib, aynan 1 ga oshib boradigan butun son.
• tool: chaqirilgan vosita nomi.
• args: vosita argumentlarini o‘z ichiga olgan obyekt.
• response: qayd etilgan vosita javobini o‘z ichiga olgan obyekt.

Yaroqli yozuv quyidagicha ko‘rinadi:

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

Ajratish ataylab qat’iy amalga oshiriladi. Noma’lum maydonlar, yetishmayotgan maydonlar, noto‘g‘ri obyekt turlari, butun son bo‘lmagan indekslar va tartibdan tashqari indekslar jiddiy xatoga olib keladi. Python bool turini int quyi turi deb hisoblasa ham, mantiqiy qiymatlar butun son sifatida qabul qilinmaydi.

ToolReplay chaqiruvlarni kanonik JSON yordamida taqqoslaydi: vosita nomi va argumentlar saralangan kalitlar hamda ortiqcha bo‘shliqlarsiz kodlanadi. Shu sababli, kalitlari turlicha tartiblangan argument obyektlari baribir bir xil chaqiruvni ifodalaydi. ToolReplay deterministiklikni tekshirayotganda javoblar uchun ham xuddi shu kanonik kodlashdan foydalanadi.

Qayta ijro auditini ishga tushirish

replay buyrug‘i transkriptni unda qayd etilgan javoblarning o‘zi bilan tekshiradi. Repozitoriyaga kiritilgan muammoli namunani sinab ko‘ring:

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

Buyruq deterministik, satrma-satr hisobot hosil qiladi:

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

Sarlavha yuqoridan pastga qarab o‘qiladi. calls: 6 oltita yaroqli yozuv ajratilganini bildiradi. divergence: index 5 deterministik qayta ishga tushirish qayd bilan birinchi marta mos kelmaydigan nuqtani ko‘rsatadi. findings: 2 keyingi topilmalar sonini bildiradi.

Topilmalar avval indeks, so‘ng tur bo‘yicha saralanadi, shuning uchun bir xil kiritma uchun takroriy auditlar baytma-bayt bir xil natija beradi.

Deterministik emaslik

ToolReplay har bir kanonik chaqiruv uchun birinchi javobni eslab qoladi. Agar keyinroq aynan bir xil chaqiruv boshqa qayd etilgan javob bilan uchrasa, u deterministik emaslik haqida xabar beradi. Namunada install uchun search chaqiruvi 3- va 5-indekslarda uchraydi, biroq javoblarda turli natijalar soni ko‘rsatilgan. 5-indeks farqlanish nuqtasiga aylanadi.

Bu agentlar uchun muhim, chunki birinchi javob asosida qabul qilingan qaror ikkinchi javob qaytarilganda o‘zgarishi mumkin. Topilma sessiya qayd ichida barqaror bo‘lmagan ma’lumotga bog‘liqligini ko‘rsatadi.

Ortiqcha chaqiruvlar

Takrorlangan chaqiruv faqat ikki chaqiruv orasida holatni o‘zgartirishi mumkin bo‘lgan qayd etilgan hodisa bo‘lmagan taqdirdagina ortiqcha hisoblanadi. Standart o‘zgartiruvchilar: write_file, delete_file, create_file, move_file va run_command. Bir xil chaqiruvlar orasidagi har qanday boshqa chaqiruv ham ehtiyotkorlik bilan ehtimoliy holat o‘zgarishi sifatida ko‘riladi.

Namunada read_file docs/intro.md faylini 1- va 2-indekslarda, orada holat o‘zgarishisiz o‘qiydi, shuning uchun 2-indeks belgilanadi. write_file chaqiruvidan keyingi o‘qish ortiqcha deb hisoblanmaydi.

Agent ruxsatlarini tekshirish

Agent uchun ruxsat deklaratsiyasi mavjud bo‘lsa, scope buyrug‘idan foydalaning:

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

Namuna quyidagilarni hosil qiladi:

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

Qayta ijro va qamrov ataylab alohida buyruqlardir. Qayta ijro sessiyani o‘ziga nisbatan baholaydi va faqat transkriptni talab qiladi. Qamrov esa har bir chaqiruvni alohida ruxsat fayli bilan taqqoslaydi.

Qamrov fayli agent nomi va ruxsat berilgan vositalarning aniq ro‘yxatini o‘z ichiga olgan bitta JSON obyektidir:

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

Vosita nomlari aynan va katta-kichik harflarga sezgir tarzda solishtiriladi. Yetishmayotgan maydonlar, noto‘g‘ri turlar yoki satr bo‘lmagan elementlar rad etiladi. Qamrov tekshiruvi nomga asoslanadi; u argumentlarni tekshirmaydi va ruxsat berilgan vosita ruxsat etilgan yo‘lga murojaat qiladimi-yo‘qmi, aniqlamaydi.

Transkriptni muhrlash

seal buyrug‘i transkriptni xeshlar zanjiriga ega JSONL fayliga aylantiradi:

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

Har bir muhrlangan havola prev va digest bilan birga asl yozuv maydonlarini ham o‘z ichiga oladi. Birinchi havolada oldingi dayjest sifatida 64 ta nol o‘n oltilik belgidan foydalaniladi. Har bir keyingi SHA-256 dayjesti oldingi dayjestni va joriy yozuvning kanonik baytlarini, jumladan uning indeksi, vositasi, argumentlari va javobini o‘z ichiga oladi.

Har bir havola oldingi havolaga bog‘liq bo‘lgani sababli, avvalgi yozuvni o‘zgartirish o‘sha yozuv dayjestini va undan keyingi barcha dayjestlarni o‘zgartiradi. Shu tariqa zanjir o‘zgartirishlarni ko‘rinadigan qiladi va birinchi buzilgan havola qayerda ekanini aniqlaydi.

Muhrlangan faylni tekshirish

Butun zanjirni quyidagi buyruq bilan tekshiring:

python -m toolreplay verify sealed.jsonl

O‘zgartirilmagan fayl quyidagini chiqaradi:

chain: intact

Agar qayd etilgan javob yoki zanjirdagi boshqa istalgan maydon o‘zgartirilsa, tekshiruv birinchi buzilgan havolani hamda kutilgan va topilgan dayjestlarni ko‘rsatadi:

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

Muhrlash muhrlangandan keyingi o‘zgartirishlarni, jumladan tartib, indekslar, vositalar, argumentlar va javoblardagi o‘zgarishlarni aniqlaydi. Bu raqamli imzo emas: faylni tahrirlash imkoniga ega har kim uni qayta muhrlashi ham mumkin. Kelib chiqishni tasdiqlash uchun yakuniy dayjestni ToolReplay’dan tashqarida boshqariladigan kalit bilan imzolash kerak bo‘ladi.

ToolReplay’dan CI’da foydalanish

ToolReplay chiqish kodlari uni build nazorat nuqtalarida ishlatishga mos qiladi:

• 0: audit toza yoki zanjir butun.
• 1: aniqlangan muammolar mavjud yoki zanjir buzilgan.
• 2: foydalanish xatosi yuz berdi, masalan, noto‘g‘ri formatdagi kiritma yoki fayl yo‘qligi.

Replay va scope tekshiruvlarini bevosita CI vazifasida ishga tushiring:

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

1 chiqish kodi vosita auditni yakunlaganini va hisobot berish kerak bo‘lgan holatni topganini anglatadi. 2 chiqish kodi auditni ishga tushirib bo‘lmaganini bildiradi, shuning uchun avtomatlashtirish noto‘g‘ri kiritmani haqiqiy aniqlangan muammodan farqlashi mumkin.

Qayta tiklanadigan taqqoslashlar uchun har bir ishga muhr qo‘ying va natijalarni farqlang:

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

Hisobotlarda vaqt tamg‘alari yoki tasodifiy qiymatlar bo‘lmagani uchun bir xil kiritmalar bir xil natija beradi. Birinchi farqli muhrlangan qator ikki ish qayerda bir xil natija berishdan to‘xtaganini ko‘rsatadi, o‘zgargan dayjest esa keyingi havolalar ushbu farqqa bog‘liqligini bildiradi.

Ilg‘or foydalanish va amaliy cheklovlar

• Transkriptlarni qo‘shishga qulay saqlang. JSON Lines ishlab chiqaruvchiga har bir chaqiruv uchun bittadan yozuv qo‘shish imkonini beradi va versiyalar nazoratida o‘zgarishlarni ko‘rib chiqishni osonlashtiradi.
• Qayd etilgan javoblarni saqlang. Replay haqiqiy vositalarni chaqirmaydi; u faqat transkriptda aks etgan muammolarni aniqlay oladi.
• Ortiqchalikka ehtiyotkorlik bilan yondashing. Standart mutatorlar ro‘yxati o‘zgarmas bo‘lib, ushbu ro‘yxatda bo‘lmagan maxsus o‘zgartiruvchi vositalar ortiqchalik tahlilida faqat o‘qish uchun deb qaraladi.
• Taqqoslash chegarasini unutmang. Deterministik emaslik faqat bir xil kanonik chaqiruv takrorlanganda aniqlanadi. Mazmunan bog‘liq javoblarga ega turli chaqiruvlar ekvivalentlik bo‘yicha baholanmaydi.
• Vakolatni nishonlashdan ajrating. Scope tekshiruvlari faqat vosita nomlarini tekshiradi. Ularga ruxsat berilgan vosita taqiqlangan resursda ishlatilganini aniqlay olmaydi.
• Muhrlashdan yaxlitlik uchun foydalaning, shaxsni tasdiqlash uchun emas. Zanjir fayl muhrlangandan keyin o‘zgargan-o‘zgarmaganini ko‘rsatadi, ammo zanjirni kim yaratganini isbotlamaydi.

Testlar to‘plamini ishga tushirish

Loyiha Python’ning standart kutubxonasidagi unittest freymvorkidan foydalanadi va uchinchi tomon test bog‘liqliklariga ega emas. Repozitoriy ildizidan quyidagini ishga tushiring:

python -m unittest discover -s tests

Testlar qat’iy transkript tahlilini, kanonik kodlashni, xesh-zanjir yaratish va buzib o‘zgartirishni aniqlashni, replay natijalarini, scope nazoratini, CLI xatti-harakatini va chiqish kodlarini qamrab oladi.

Xulosa

ToolReplay AI-agent seanslari uchun ixcham audit ish jarayonini taqdim etadi. Izchil bo‘lmagan yoki samarasiz xatti-harakatlarni topish uchun replaydan boshlang, e’lon qilingan vosita ruxsatlarini tekshirish uchun scopedan foydalaning, yozuvdan keyingi o‘zgarishlarni aniqlash uchun esa seal va verifyni ishlating. Uning qat’iy kiritma tekshiruvi va deterministik hisobotlari uni nosozliklarni tuzatish, ko‘rib chiqish, versiyalar nazorati va CI nazorati uchun amaliy vositaga aylantiradi.