راهنمای محصول

۱. نمای کلی پلتفرم

هر ایجنت با متن پایگاه دانش (RAG) و در صورت نیاز با ابزار SQL زنده پاسخ می‌دهد. شما یک API با توکن bearer صدا می‌زنید. پلن مشخص می‌کند چه فیچرها و محدودیت‌هایی دارید.

۲. فراخوانی API ایجنت

درخواست POST به /api/agent/ask بفرستید همراه Authorization: Bearer {agent_token}.

نمونه ساده

curl -X POST http://localhost:8000/api/agent/ask \
  -H 'Authorization: Bearer YOUR_AGENT_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"message":"سهمیه‌ام چقدره؟"}'

پارامترهای مهم

• message — الزامی. متن سوال کاربر.
• user_id — اختیاری. شناسه کاربر نهایی برای کوئری‌های SQL (همچنین ?user=123 یا فیلد user در body).
• session — اختیاری. شناسه مکالمه. با یک مقدار ثابت، حافظه بین گفتگوها حفظ می‌شود.

۳. ابزارهای SQL (دیتای زنده)

ابزار SQL یعنی کوئری‌های نام‌گذاری‌شده که روی ایجنت تعریف می‌شوند. وقتی سوال به داده زنده نیاز داشته باشد مدل آن‌ها را صدا می‌زند. هر ابزار کدی مثل %users% دارد که در پرامپت استفاده می‌شود.

مراحل راه‌اندازی

1. اتصال MySQL را روی ایجنت تنظیم کنید (هاست، دیتابیس، کاربر، رمز).
2. یک یا چند ابزار SQL با کد یکتا، کوئری و توضیح بسازید.
3. کد ابزار را در پرامپت سیستم بنویسید تا مدل بداند کی صدا بزند.
4. SQL Tools / MySQL را در تنظیمات ایجنت روشن کنید (و پلن هم اجازه‌اش را بدهد).

نمونه ابزار

code: %orders%

SELECT id, status, total_amount, created_at
FROM orders
WHERE user_id = :user_id
ORDER BY created_at DESC
LIMIT 5

تو دستیار پشتیبانی فروشگاه آنلاین «دیجی‌مارت» هستی. برای وضعیت سفارش کاربر از %orders% استفاده کن. برای اطلاعات حساب از %customers% استفاده کن. قیمت و موجودی را فقط از پایگاه دانش بگو — حدس نزن.

ارسال پارامتر برای ابزار از URL/بدنه

شناسه کاربر نهایی را بفرستید تا placeholderهایی مثل :user_id درست پر شوند.

POST /api/agent/ask?user=42
Authorization: Bearer TOKEN
{"message":"سفارش ۱۲۳۴۵ من الان کجاست؟"}

۴. اتصال دیتابیس

اتصال MySQL ایجنت فقط برای ابزارهای SQL است. ذخیره‌سازی وکتور/RAG روی PostgreSQL مشترک پلتفرم انجام می‌شود.

فیلدهای معمول: host، port، database، username، password و در صورت نیاز SSL.

تا جای ممکن کاربر دیتابیس را فقط‌خواندنی بگذارید.

۵. سشن‌های اختصاصی / حافظه

اگر حافظه روی ایجنت (و پلن) فعال باشد، رفت‌وبرگشت‌های اخیر ذخیره و دوباره به مدل داده می‌شود.

{"message":"قبلا چی پرسیدم؟","session":"web-user-42-checkout"}

کلید session چگونه کار می‌کند

پارامتر session را در درخواست بفرستید. برای هر چت کاربر نهایی یک کلید جداگانه بگذارید. اگر نفرستید، API خودش یک fingerprint می‌سازد.

{"message":"قبلا چی پرسیدم؟","session":"web-user-42-checkout"}

chat_memory_turns مشخص می‌کند چند رفت‌وبرگشت اخیر ارسال شود. مقدار ۰ عملاً تاریخچه را خاموش می‌کند.

۶. نوشتن پرامپت خوب

نقش، قوانین، زبان پاسخ، و زمان صدا زدن ابزار SQL را در پرامپت سیستم بنویسید. کوتاه بودن پاسخ و اختیاری بودن ابزار را واضح بگویید.

نمونه خوب

تو دستیار پشتیبانی فروشگاه آنلاین «دیجی‌مارت» هستی.
همیشه کوتاه و به زبان کاربر جواب بده.
برای وضعیت سفارش از %orders% استفاده کن.
برای اطلاعات حساب کاربر از %customers% استفاده کن.
قوانین مرجوعی و گارانتی را از پایگاه دانش بخوان.
شماره سفارش یا مبلغ را بدون tool نساز.

نمونه ضعیف

تو دستیار مفیدی هستی. به سوالات جواب بده.

• کد ابزارها را واضح بگذارید: %orders%، %customers%، %inventory%.
• دقیقا بگویید هر ابزار کی لازم است (سفارش زنده vs FAQ در PDF).
• ساخت وضعیت سفارش یا قیمت بدون tool را ممنوع کنید.
• سبک پاسخ را ثابت نگه دارید (کوتاه / بولت / رسمی).

۷. پایگاه‌های دانش

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

پلن تعداد پایگاه دانش، حجم فایل، و سقف سوال ماهانه را محدود می‌کند.

۸. پلن‌ها و محدودیت‌ها

پلن‌ها فیچرهایی مثل ابزار SQL، تنظیمات اختصاصی ایجنت، حافظه مکالمه، اولویت امبدینگ و پشتیبانی را کنترل می‌کنند. محدودیت‌ها شامل تعداد ایجنت، KB، فضای MB و سوال ماهانه است.