ابزارها و پیام‌های غنی

ابزارها کمک‌های سمت سروری هستند که دستیار فروش شما می‌تواند در میانه یک نوبت آنها را فراخوانی کند. بازدیدکننده چیزی تایپ می‌کند، هوش مصنوعی تصمیم می‌گیرد "برای این کار باید یک ابزار را فراخوانی کنم"، ابزار روی سرور اجرا می‌شود و نتیجه آن یا به پاسخ نهایی هوش مصنوعی بازخورد داده می‌شود یا مستقیماً به‌عنوان یک بلوک ساختاریافته (مثلاً دکمه "اتصال به کارشناس") در ویجت نمایش داده می‌شود.

ابزارها توسط قابلیت‌های عمودی دستیار فروش محافظت می‌شوند. هر ابزار اعلام می‌کند که به کدام قابلیت نیاز دارد. ثبت فقط ابزارهایی را در معرض دستیاران فروشی قرار می‌دهد که لیست قابلیت‌های آنها شامل آن نامک باشد. مدیران می‌توانند لیست را با vertical_overrides.enabled_tools بیشتر محدود کنند.

ابزارهای ارسال‌شده

ابزار	قابلیت مورد نیاز	فعالسازی خودکار در	کاربرد
escalate_to_human	ticket_escalation	هر عمودی (قابلیت در هر پیش‌تنظیم ارسال می‌شود)	یک دکمه "اتصال به کارشناس" نمایش می‌دهد (نوع بلوک escalation_button). کلیک، جریان جذب مشتری موجود را فعال می‌کند تا یک اپراتور بتواند مکالمه را تصاحب کند. آرگومان‌ها: reason.
lookup_order	order_status	فروشگاهی	نقطه پایانی REST ووکامرس فضای کاری را از طریق LookupOrderClient فراخوانی کرده و سفارشات اخیر بازدیدکننده (وضعیت + موارد + ردیابی) را دریافت می‌کند. زمان‌بندی سخت ۵ ثانیه. نیاز به خریدار واردشده (ادعای shopper.wp_user_id JWT) و یک منبع woocommerce_products متصل به دستیار فروش دارد — در صورت عدم وجود هر کدام، به‌خوبی از کار می‌افتد. آرگومان‌ها: limit (پیش‌فرض ۵، حداکثر ۱۰)، status اختیاری.
open_ticket	ticketing	مرکز راهنما (قابلیت به‌طور خودکار شامل می‌شود)	یک تیکت پشتیبانی بادوام از داخل مکالمه باز می‌کند — اختلافات صورتحساب، مشکلات حساب، گزارش‌های باگ. در جدول tickets متصل به مکالمه منبع ذخیره می‌شود. آرگومان‌ها: subject (≤ ۱۲۰ کاراکتر)، body، priority اختیاری (کم / معمولی / بالا / فوری).
send_kb_article	kb_article_card	مرکز راهنما	یک کارت حاوی لینک به یک مقاله پایگاه دانش منتشرشده نمایش می‌دهد. نامک را در برابر پاسخ‌های گزینشی فضای کاری جستجو می‌کند. بازدیدکننده یک کارت با عنوان + خلاصه + کلیک برای مشاهده می‌بیند. آرگومان‌ها: slug.

محافظت ابزار، اشتراک (الف) قابلیت‌های عمودی دستیار فروش، (ب) قابلیت مورد نیاز هر ابزار و (ج) لیست مجاز vertical_overrides.enabled_tools مدیر است. هر ابزاری که قابلیت مورد نیاز آن در مجموعه دستیار فروش نباشد، قبل از دیده شدن توسط هوش مصنوعی، به‌طور بی‌صدا حذف می‌شود.

نحوه حل فراخوانی ابزار در مسیر اصلی

برای هر نوبت بازدیدکننده در یک دستیار فروش با قابلیت ابزار، MessageStreamController یک حلقه کوچک حل ابزار را قبل از پاسخ نهایی پخش جریانی اجرا می‌کند:

1. آرایه tools به سبک OpenAI را از نتیجه forAgent($agent) ثبت می‌سازد.
2. llm->chatWithTools(messages, tools) را به‌صورت غیر پخش جریانی فراخوانی می‌کند. مدل یا tool_calls را برمی‌گرداند (می‌خواهد یک یا چند ابزار را فراخوانی کند) یا content را (آماده پاسخ است).
3. اگر tool_calls: یک رویداد SSE tool_call برای هر فراخوانی منتشر می‌کند، execute() ابزار را اجرا می‌کند، نتیجه ابزار را به‌عنوان یک پیام {role: 'tool'} به تاریخچه پیام اضافه می‌کند و حلقه می‌زند.
4. پس از اینکه مدل content را برگرداند (یا پس از ۳ مرحله، هر کدام زودتر اتفاق بیفتد)، به مسیر streamChat موجود باز می‌گردد. بازدیدکننده همچنان پخش جریانی توکن به توکن را برای پاسخ نهایی دریافت می‌کند، بنابراین TTFT حفظ می‌شود.
5. هر payload block که ابزارها تولید کرده‌اند (مثلاً escalation_button) به‌عنوان رویدادهای SSE block برای نمایش درون‌خطی توسط ویجت منتشر می‌شوند.

سازگاری سرویس‌دهنده

سرویس‌دهنده	فراخوانی ابزار	توضیحات
OpenAI (gpt-4o-mini، gpt-4o)	بومی	پشتیبانی کامل از آرایه tools OpenAI از طریق SDK.
OpenRouter	وابسته به مدل	مدل‌های با قابلیت ابزار (Claude 3.5، Llama 3.3 70B Hermes و غیره) از طریق همان سطح سازگار با OpenAI کار می‌کنند.
Cloudflare Workers AI	وابسته به مدل	Llama 3.3 70B Hermes و تعداد انگشت‌شماری از مدل‌های دیگر از فراخوانی تابع پشتیبانی می‌کنند. مدل‌های بدون پشتیبانی ابزار به‌خوبی از کار می‌افتند — آرایه ابزار را نادیده گرفته و مستقیماً محتوا را برمی‌گردانند، بنابراین حلقه به‌سادگی خارج می‌شود.

نمایش بلوک‌ها در ویجت

ویجت رویدادهای SSE block را در طول یک نوبت دریافت کرده و هر بلوک را به پیام دستیار فروش در حال انجام متصل می‌کند. ثبت نمایش‌دهنده در resources/widget/src/ui/blocks.tsx نوع block → کامپوننت Preact را نگاشت می‌کند. انواع بلوک ناشناس به‌طور بی‌صدا حذف می‌شوند (سازگاری رو به جلو برای سرورهای جدیدتر).

راهنمای canRender(capability, agent) ویجت اکنون true را برمی‌گرداند زمانی که:

1. بسته یک نمایش‌دهنده برای آن قابلیت ارائه می‌دهد، و
2. آرایه capabilities حل‌شده توسط سرور دستیار فروش انتخاب کرده باشد.

هر دو مورد نیاز هستند — ویجت هرگز قابلیتی را که سرور مجوز نداده است فعال نمی‌کند و هرگز سعی نمی‌کند بلوکی را که نمایش‌دهنده آن در بسته نیست، نمایش می‌دهد.

افزودن یک ابزار جدید

1. App\Services\Tools\Contracts\Tool را در app/Services/Tools/Tools/YourTool.php پیاده‌سازی کنید. یک name() منحصربه‌فرد انتخاب کنید، یک description() واضح بنویسید (هوش مصنوعی از آن برای تصمیم‌گیری در مورد زمان فراخوانی استفاده می‌کند)، نامک capability() مورد نیاز خود را اعلام کرده و schema() JSON را تعریف کنید.
2. ابزار را در ToolRegistry::__construct ثبت کنید.
3. اگر execute() ابزار شما یک payload block برمی‌گرداند، یک نمایش‌دهنده برای آن در ui/blocks.tsx ارسال کرده و نامک قابلیت مربوطه را به مجموعه RENDERABLE در capabilities.ts اضافه کنید.
4. یک تست واحد Pest برای ابزار و یک تست ویژگی برای جریان سرتاسری با استفاده از FakeOpenAi::pushToolCall اضافه کنید.

ملاحظات تأخیر

حلقه ابزار یک رفت و برگشت غیر پخش جریانی به ازای هر مرحله قبل از شروع پاسخ نهایی پخش جریانی اضافه می‌کند. برای یک نوبت "نیاز به یک ابزار" معمولی، این حدود ۲۰۰–۵۰۰ میلی‌ثانیه تأخیر قبل از دیدن اولین توکن توسط بازدیدکننده اضافه می‌کند. حالت ۹۹٪ (بدون استفاده از ابزار) بدون تغییر است زیرا ثبت برای دستیاران فروشی که قابلیت‌های آنها با هیچ ابزار ثبت‌شده‌ای مطابقت ندارد، یک لیست خالی ابزار برمی‌گرداند.

برای مدیریت تأخیر، توضیحات ابزار را به‌گونه‌ای بنویسید که هوش مصنوعی فقط زمانی که واقعاً به آن نیاز دارد، ابزار را فراخوانی کند. محدودیت مرحله (۳) یک شبکه ایمنی است — توضیحات ابزار به‌خوبی نوشته‌شده باید در ۱ مرحله همگرا شوند.