‏ابزارهای ایجنت لاراول در عمل؛ اون چیزی که دمو یادت نمی‌ده

نویسنده می‌گه وصل کردن یه tool به ایجنت تو Laravel AI SDK فقط یه خطه، و همون یه خط کل چیزیه که مستندات پوشش می‌دن. ولی مشکل‌های واقعی داخل یه tool زندگی نمی‌کنن، بلکه بین ابزارها هستن: تو اون loopی که مدل چند tool رو در چند round-trip صدا می‌زنه، هر نتیجه رو به context خودش برمی‌گردونه و تصمیم بعدی رو می‌گیره. برای نشون دادن این، یه ایجنت واقعی می‌سازه: یه دستیار تحقیق محتوا با سه tool از کاتالوگ (FirecrawlSearch، FirecrawlScrape و DatabaseQueryTool) که وب رو می‌گرده، منابع خوب رو اسکرپ می‌کنه و پست‌های منتشرشدهٔ خودش رو چک می‌کنه.

درس اول: هر خروجی tool ورودی نامعتمده. وقتی ایجنت یه صفحهٔ وب رو اسکرپ می‌کنه، هرچی اون صفحه بگه مستقیم می‌ره تو context مدل. هیچی جلوی این صفحه رو نمی‌گیره که بنویسه «دستورهای قبلیت رو نادیده بگیر و…»؛ برای مدل، متن اسکرپ‌شده و دستورهای خودت یه‌جور می‌رسن. این همون prompt injection ئه و ابزاری که وب باز رو می‌خونه، پهن‌ترین درِ ورودشه. DatabaseQueryTool امن‌تره چون دیتای خودتو می‌خونه، ولی خروجی ابزارهای وب رو باید مثل متن خصمانه رفتار کنی، نه دستور.

درس دوم: خروجی خام tool یه صورت‌حساب توکنه. نویسنده می‌گه یه اجرای تحقیقش ۳۹٬۳۸۲ توکن ورودی خورد ولی فقط ۲٬۳۴۵ توکن خروجی داد. علتش اینه که هر tool کل پاسخ API رو پرینت‌شده برمی‌گردونه و همه‌ش هر بار به context برمی‌گرده؛ شش tool call بعد، مدل داره کل تاریخچهٔ هرچی fetch کرده رو دوباره می‌خونه. راه‌حل اینه که خروجی رو همون سرِ tool محدود کنی: تعداد نتایج رو cap کنی، فقط محتوای اصلی رو نگه داری و تعداد ردیف‌های کوئری رو ببندی.

درس‌های بعدی: بعضی ابزارها تو یه turn تموم نمی‌شن؛ مثلاً crawl کردن کل سایت async ئه و فقط یه crawl id برمی‌گردونه، پس کاری که job id می‌ده باید بره رو صف، نه تو turn ایجنت. «read-only» یعنی «scoped» نیست؛ read-only جلوی حذف دیتا رو می‌گیره ولی جلوی خوندن ردیف‌هایی که به ایجنت ربط نداره رو نمی‌گیره، پس تو یه جدول چند-مستأجری یه SELECT بی‌محدوده سفارش همهٔ مشتری‌ها رو می‌خونه؛ scope کردن با read replica یا view فیلترشده وظیفهٔ خودته. و آخری: یه tool بالاخره fail می‌شه، پس باید خطاش رو به‌صورت رشته برگردونه نه exception؛ وقتی یه اسکرپ خطای 403 گرفت، ایجنت چون خطا به‌صورت متن برگشت اونو خوند و سراغ منابع دیگه رفت؛ اگه exception پرتاب می‌شد کل اجرا می‌مرد.

نویسنده در آخر می‌گه چرا اصلاً از کاتالوگ استفاده کنیم؟ چون کاری که ساده به نظر میاد اغلب نیست؛ مثلاً tool ماشین‌حساب به‌جای eval() با چند صد خط کد recursive-descent عبارت‌ها رو parse می‌کنه. جمع‌بندیش اینه: ابزارهای عمومی رو نصب کن، ولی درزها و loop رو خودت مالک باش؛ ابزارهای دامنه‌ای که سفارش‌ها و کاربرهای خودتو لمس می‌کنن رو هنوز خودت می‌نویسی.

نکات کلیدی:

• هر خروجی tool رو مثل ورودی نامعتمد رفتار کن؛ ابزارهای وب درِ اصلی prompt injection ان
• خروجی هر tool رو قبل رسیدن به مدل محدود کن تا صورت‌حساب توکن منفجر نشه
• ابزارهای async رو بفرست رو صف، نه تو turn ایجنت
• read-only کافی نیست؛ scope کردن ردیف‌ها با تو ئه
• خطای tool رو به‌صورت رشته برگردون تا یه call بد کل loop رو نکشه