ایجنتهای هوش مصنوعی
ایجنت یک آدرس API با کلید خودش است که به سؤال جواب میدهد — فقط از روی دستورالعمل و دانستههایی که خودتان به آن میدهید، و اگر بخواهید از روی جدولهای پروژهتان. پاسخگوی سؤالهای تکراری مشتری، دستهبندی پیامها یا بیرون کشیدن فیلد از یک متن آزاد، همه با یک درخواست HTTP از اپ، سایت یا سرور خودتان.
ایجنت پروژه لازم ندارد. آن را از تب «هوش مصنوعی (AI)» در نوار بالای پنل میسازید، ویرایش میکنید، خاموش و روشن میکنید و حذف میکنید. هزینه را به تومان از همان کیف پول حسابتان میپردازید.
ایجنتها محصولی جدا از بکاند پروژهاند. API پروژهها همچنان با موتور قطعی فیکارو اجرا میشود؛ تنها جایی که جواب را یک مدل هوش مصنوعی مینویسد، همین ایجنتها هستند.
ساختن ایجنت
در تب «هوش مصنوعی (AI)» دکمهٔ «ایجنت جدید» را بزنید. میتوانید از صفر شروع کنید یا از یکی از هفت قالب آماده، که دستورالعمل، شکل خروجی و نمونهٔ دانستههایش از قبل پر شده است:
- پاسخگوی FAQ
- پشتیبان فروشگاه
- دستهبند تیکت و پیام
- فیلتر نظر
- استخراج فیلد
- توضیح پاسخ سؤال آزمون
- نوشتن توضیح محصول
هر چیزی که قالب پر کرده بعداً قابل تغییر است. پیش از استفادهٔ واقعی، در صفحهٔ میز آزمایش همان ایجنت با آن گفتوگو کنید، همانطور که کاربر اپ شما میکند: هر پرسش بعدی گفتوگوی قبلی را هم با خودش میبرد. هر پرسش آزمایشی یک جواب واقعی است و هزینهاش زیر همان جواب به تومان نوشته میشود.
وارد کردن PDF و لینک
دانستهها را لازم نیست دستی تایپ کنید. اگر فهرست قیمت، پرسشهای متداول، کاتالوگ یا قوانینتان را در یک فایل یا روی سایتتان دارید، در صفحهٔ دانستهها دکمهٔ «وارد کردن از فایل یا لینک» را بزنید:
- فایل PDF یا عکس (PNG، JPG یا WebP؛ مثلاً اسکن یک برگه یا اسکرینشات یک جدول). متنش با تشخیص متن خوانده میشود. پیش از شروع، شمار صفحهها و هزینهٔ برآوردی را میبینید و تأیید میکنید.
- لینک یک صفحهٔ وب. متن اصلی صفحه (بدون منو و پاورقی) بیرون کشیده میشود. این کار رایگان است. لینکی که به یک PDF میرسد، مثل فایل PDF وارد میشود.
بازبینی پیش از ذخیره
متنی که بیرون میآید هیچوقت خودکار ذخیره نمیشود. اول آن را در یک جعبهٔ قابل ویرایش میبینید. پیش از ذخیره بخوانیدش: تشخیص متن گاهی یک عدد یا حرف را اشتباه میخواند (مثلاً «۳ روز» را «۲ روز»)، و ایجنت دقیقاً همان چیزی را جواب میدهد که ذخیره کردهاید. هر چیزی را که لازم نیست هم همانجا پاک کنید.
با «ذخیره در دانستهها»، متن به یک یا چند «متن» عادی تبدیل میشود (هر کدام حداکثر ۳۰۰۰ نویسه، بریده روی مرز پاراگراف) و درست مثل بقیهٔ دانستهها به ایجنت داده میشود. اگر متن در سقف دانستههای پلن جا نشود، چیزی ذخیره نمیشود و دو راه دارید: ذخیرهٔ بخشی که جا میشود (از اول متن، تا جایی که جا دارد) یا ارتقای پلن ایجنت.
اگر بعد از یک لینک متن خیلی کمی برگشت، احتمالاً صفحه با جاوااسکریپت ساخته میشود و متنش در خود صفحه نیست. متن را از مرورگر کپی کنید و دستی بچسبانید، یا از صفحه PDF بگیرید و آن را وارد کنید.
سقفها
| سقف | مقدار | اگر رد شود |
|---|---|---|
| حجم فایل | ۲۰ مگابایت | پذیرفته نمیشود؛ فایل را کوچکتر یا چند تکه کنید |
| صفحههای PDF | ۳۰ صفحه | پذیرفته نمیشود؛ PDF را چند تکه کنید |
| حجم صفحهٔ وب | ۵ مگابایت | پذیرفته نمیشود |
| وارد کردن در ساعت | ۲۰ بار برای هر حساب | کمی بعد دوباره امتحان کنید |
| تشخیص متن همزمان | یکی برای هر حساب | صبر کنید تا قبلی تمام شود |
| متن هر کار | ۵۰۰٬۰۰۰ نویسه | بقیه بریده میشود |
| ماندن متن پیش از ذخیره | ۲۴ ساعت | متن پاک میشود و باید دوباره وارد کنید |
هزینه
تشخیص متن برای هر صفحه هزینه دارد: حدود ۵۰۰ تومان برای هر صفحه (در صفحهٔ قیمتها هم آمده است)، یعنی هزینهٔ واقعی همان تشخیص، تبدیلشده به تومان مثل هزینهٔ پرسشها. برآورد دقیقش را پیش از تأیید به تومان میبینید و هزینهٔ واقعی بعد از تمام شدن کار کم میشود. بخشی که از موجودی نقدی برود، با برچسب «تشخیص متن» و نام فایل در صورتحساب کیف پول میآید؛ صورتحساب فقط پول خود شما را نشان میدهد، پس بخشی که اعتبار هدیهی هوش مصنوعی پرداخته در آن نیست.
- این هزینه مثل هزینهٔ پرسشها اول از اعتبار هدیهی هوش مصنوعی و بعد از موجودی نقدی کیف پول کم میشود؛ پس با اعتبار هدیهی هوش مصنوعیِ حساب تازه میتوانید یک فایل را پیش از شارژ کیف پول امتحان کنید. اعتبار هدیهٔ ثبتنام آن را نمیپردازد.
- اگر تشخیص متن ناموفق باشد یا نیمهکاره بماند، چیزی کم نمیشود.
- لینک صفحهٔ وب و ذخیرهٔ متن رایگاناند.
حریم خصوصی
فایل شما فقط برای تشخیص متن نگه داشته میشود. نسخهٔ فیکارو بلافاصله بعد از فرستادن برای تشخیص متن پاک میشود (فایلی که تأیید نشود، بعد از یک ساعت)، و نسخهای که پردازشگر تشخیص متن دریافت میکند حداکثر ۷ روز نزد او میماند. فیکارو خود فایل را هیچجا ذخیره یا دوباره منتشر نمیکند؛ فقط متنی را نگه میدارد که خودتان ذخیره میکنید. پس مدارکی که نباید از دستتان بیرون برود، مثلاً قرارداد یا مدارک شخصی مشتریها، را وارد نکنید.
متن واردشده یک دانستهٔ عادی است و همان محدودیت prompt injection را دارد: هر چیزی که در آن باشد ممکن است با یک پرسش زیرکانه از ایجنت بیرون کشیده شود. اگر سندی که وارد میکنید دستورهایی خطاب به «هوش مصنوعی» داشته باشد، ایجنت آنها را مثل بقیهٔ متن میخواند؛ پیش از ذخیره پاکشان کنید.
صدا زدن ایجنت
POST https://api.fikaro.ir/ai/v1/bots/{botId}/ask
کلید را در سرآیند Authorization بفرستید و بدنه را JSON:
input— متن پرسش، الزامی. تا ۴۰۰۰ نویسه.data— اختیاری، فقط یک شیء JSON. ورودی ساختاریافته، مثل مشخصات محصول برای قالب «نوشتن توضیح محصول». تا ۱۶ کیلوبایت.history— اختیاری، پیامهای قبلی همین گفتوگو تا ایجنت پرسش دنبالهدار را بفهمد. جزئیاتش در گفتوگوی چندنوبتی.
شناسهٔ ایجنت و کلیدش در صفحهٔ «کلید و API» همان ایجنت است. دستور آماده با کلید کامل هم همانجا با «کپی دستور» کپی میشود.
ترمینال (curl)
curl -X POST "https://api.fikaro.ir/ai/v1/bots/{botId}/ask" \
-H "Authorization: Bearer apck_bot_..." \
-H "Content-Type: application/json" \
-d '{"input": "ساعت کاری پشتیبانی چیه؟"}'
این نمونه برای ترمینال لینوکس و مک است. در ویندوز دستور یکخطیِ «کپی دستور» پنل
را بردارید و در PowerShell بهجای curl بنویسید curl.exe، یا از نمونهٔ
جاوااسکریپت استفاده کنید.
جاوااسکریپت (fetch)
const res = await fetch("https://api.fikaro.ir/ai/v1/bots/{botId}/ask", {
method: "POST",
headers: {
Authorization: "Bearer apck_bot_...",
"Content-Type": "application/json",
},
body: JSON.stringify({ input: "ساعت کاری پشتیبانی چیه؟" }),
});
const body = await res.json();
if (!res.ok) {
// body.code پایدار است؛ body.detail توضیح فارسی است
throw new Error(`${body.code}: ${body.detail}`);
}
const { answered, answer, output } = body;
پاسخ
{
"answered": true,
"answer": "پشتیبانی شنبه تا پنجشنبه، ۹ صبح تا ۶ عصر جواب میدهد.",
"output": null,
"sources": [],
"requestId": "0199d3a2-7c41-7b8e-9f3a-2d6e1c0b4a17",
"handoff": false,
"knowledgeIds": ["0199d1f0-2b7a-7c11-8e4d-5a9b3c2d1e0f"],
"pendingAction": null
}
answered— همیشهtrueیاfalse. وقتیfalseاست یعنی ایجنت جواب را در دانستهها و جدولهایش پیدا نکرد، یا جواب دادن را رد کرد. در این حالتanswerهمیشه یک متن ناخالی است که میگوید چرا.answer— متن جواب برای ایجنت متنی.output— برای ایجنت شکلدار. اگر برای ایجنت شکل خروجی تعریف کرده باشید (یک برچسب از فهرست بسته، یا شیئی با فیلدهای مشخص)، نتیجه درoutputمیآید وanswerبرابرnullاست. اگر ایجنت شکلدار جواب را نداند،outputبرابرnullاست وanswerتوضیح میدهد. برای ایجنت متنیoutputهمیشهnullاست.sources— همیشه آرایه است. وقتی جواب از ردیفهای جدول آمده، هر عنصرش شیئی با دو فیلدtable(نام جدول) وid(شناسهٔ ردیف) است: کدام ردیفها پشت جواباند، بدون هیچ مقدار ستونی.requestId— شناسهٔ همین پرسش. همان شناسهای است که ردیف گزارش سؤالها با آن ثبت میشود.handoff— همیشهtrueیاfalse. وقتیtrueاست، اپ شما بهتر است گفتوگو را به یک آدم بسپارد: برایanswered: falsetrueاست (جز پیامی که بررسی محتوای ویجت یا بله ردش کرده، و کار نوشتنیای که انجام نشد)، و برای ایجنت شکلداری که برچسبش در صفحهٔ «ارجاع به انسان» علامت خورده (مثلاً «شکایت») همtrueاست، حتی وقتی جواب داده. مدل این را تعیین نمیکند. بیشتر: ارجاع به انسان.knowledgeIds— همیشه آرایه است، هیچوقتnull. شناسهٔ دانستههایی از همین ایجنت که جواب از آنها آمده (حداکثر پنج، بدون تکرار). شناسه همانidدانسته در پنل است. برایanswered: falseهمیشه[]است.sourcesجداست و فقط ردیفهای جدول را میگوید.pendingAction— همیشه هست:null، یا وقتی ایجنت میخواهد تابعی را اجرا کند که برایش «پیش از انجام از کاربر تأیید بگیر» را روشن کردهاید، شیء{fn, summary, token, expiresAt}. در این حالت هنوز هیچ چیز ثبت نشده است؛ کاربر باید تأیید کند. بیشتر: نوشتن و تأیید.
اپی که این فیلدها را نمیشناسد چیزی را از دست نمیدهد: هیچ فیلد قبلی عوض نشده است.
هزینهٔ هر پرسش در پاسخ API نمیآید؛ فقط در پنل دیده میشود.
از کد فانکشن (ctx.ai.ask)
کد یک فانکشن پروژه هم میتواند از ایجنتهای همین حساب بپرسد، بی کلید ایجنت و بی درخواست HTTP؛ مثلاً هر تیکت تازه را با ایجنت دستهبند برچسب بزند:
const r = ctx.ai.ask("<شناسهٔ ایجنت>", ctx.input.body, { data: { title: ctx.input.title } });
جواب همان بدنهٔ بالاست (pendingAction همیشه null)، هزینه و سقفها همان پرسش از
API است و از کیف پول شما کم میشود، و هر اجرای فانکشن حداکثر ۲ بار میپرسد. فقط
ایجنتهای حسابی که صاحب همان پروژه است جواب میدهند. فانکشنی که «عمومی» است به هر
صداکننده اجازه میدهد از کیف پول شما خرج کند؛ سقف ماهانهٔ ایجنت را بگذارید. خطاها و جزئیات در راهنمای
فانکشنها، بخش «ایجنت (ctx.ai.ask)».
گفتوگوی چندنوبتی
ایجنت با فیلد history گفتوگو را دنبال میکند. اپ شما پیامهای قبلی همان
گفتوگو را همراه پرسش تازه میفرستد و ایجنت پرسشی مثل «سایز ۴۳ چی؟» را در ادامهٔ
«کفش مشکی سایز ۴۲ دارید؟» میفهمد.
historyآرایهای از پیامهاست، قدیمی به جدید. هر پیام دقیقاً دو فیلد دارد:roleکه"user"(کاربر اپ شما) یا"agent"(جواب قبلی ایجنت) است، وtextکه متنی ناخالی است. فیلد دیگری پذیرفته نمیشود.- حداکثر ۶ پیام و روی هم ۸۰۰۰ نویسه. اپ شما معمولاً فقط چند پیام آخر را میفرستد؛ پیامهای قدیمیتر را خودتان کنار بگذارید.
- نبودن
history،nullیا آرایهٔ خالی یعنی پرسش تکنوبتی، مثل همیشه. - برای ایجنت شکلدار،
textنوبتagentهمانoutputقبلی است: اگر رشته است خودش (مثلاً"مالی")، وگرنه بهصورت JSON متنی (مثلاً"{\"city\":\"تهران\"}"). برای ایجنت متنی، همانanswer. historyفقط متن است وdataپرسشهای قبلی را با خود نمیبرد. اگر پرسش دنبالهدار به همان داده نیاز دارد (مثلاً «کوتاهترش کن» برای توضیح یک محصول)،dataرا همراه پرسش تازه دوباره بفرستید.historyبد (آرایه نیست، نقش یا متن نامعتبر، فیلد اضافه، یا بیش از سقف) با400 invalid_historyرد میشود، پیش از هر هزینهای.
history ورودی غیرقابلاعتماد است، مثل input. آن را اپ صداکننده میفرستد،
پس کاربر نهایی میتواند نوبت agent جعلی هم بسازد. آن را مثل خود پرسش، متن
کاربر حساب کنید و تصمیمی در اپتان را به «جواب قبلی ایجنت» در آن گره نزنید.
گفتوگو را اپ شما نگه میدارد، نه فیکارو. فیکارو هیچ نشستی برای کاربران شما
نمیسازد؛ history هر پرسش فقط کنار همان پرسش در گزارش سؤالها ثبت میشود تا
ببینید جواب از کجا آمده، و با همان مدت نگهداری گزارش پاک میشود.
هزینه: متن history جزو ورودی مدل است، پس گفتوگوی بلندتر پرسش گرانتری
است. موجودی پیش از جواب برای بدترین حالت با history رزرو میشود.
curl -X POST "https://api.fikaro.ir/ai/v1/bots/{botId}/ask" \
-H "Authorization: Bearer apck_bot_..." \
-H "Content-Type: application/json" \
-d '{
"input": "سایز ۴۳ چی؟",
"history": [
{"role": "user", "text": "کفش مشکی سایز ۴۲ دارید؟"},
{"role": "agent", "text": "بله، دو مدل موجود است."}
]
}'
// پیامهای این گفتوگو را خود اپ نگه میدارد.
const history = [];
// آخرین پیامها، در هر دو سقف سرور: ۶ پیام و روی هم ۸۰۰۰ نویسه.
function recent(turns, maxTurns = 6, maxChars = 8000) {
const out = [];
let chars = 0;
for (let i = turns.length - 1; i >= 0 && out.length < maxTurns; i--) {
const n = [...turns[i].text].length;
if (chars + n > maxChars) break;
chars += n;
out.unshift(turns[i]);
}
return out;
}
async function ask(input) {
const res = await fetch("https://api.fikaro.ir/ai/v1/bots/{botId}/ask", {
method: "POST",
headers: {
Authorization: "Bearer apck_bot_...",
"Content-Type": "application/json",
},
body: JSON.stringify({ input, history: recent(history) }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.code}: ${body.detail}`);
const out = body.output;
const reply = out == null ? body.answer : typeof out === "string" ? out : JSON.stringify(out);
history.push({ role: "user", text: input }, { role: "agent", text: reply });
return body;
}
await ask("کفش مشکی سایز ۴۲ دارید؟");
await ask("سایز ۴۳ چی؟"); // ایجنت میداند منظور همان کفش مشکی است
پاسخ همان شکل همیشگی است؛ history چیزی به پاسخ اضافه نمیکند.
اگر ایجنت را از متنی به شکلدار (یا برعکس) تغییر دهید، شکل پاسخ برای همهٔ اپهایی که صدایش میزنند هم عوض میشود. پنل پیش از ذخیره هشدار میدهد.
خطاها
خطاها قالب Problem Details (RFC 7807) دارند با detail فارسی؛ همان قالبی
که API پروژهها دارد. در کدتان به code و وضعیت تکیه کنید، نه متن
detail — کد پایدار است و متن ممکن است بهتر شود.
| کد | وضعیت | کی پیش میآید | هزینه |
|---|---|---|---|
| invalid_json | 400 | بدنه JSON معتبر نیست | ندارد |
| input_required | 400 | input نیامده یا خالی است | ندارد |
| input_too_long | 400 | input از سقف طول بلندتر است | ندارد |
| invalid_data | 400 | data شیء نیست یا از سقف حجم بزرگتر است | ندارد |
| invalid_history | 400 | history آرایه نیست، نقش یا متن نامعتبر دارد، یا از سقف ۶ پیام یا ۸۰۰۰ نویسه بیشتر است | ندارد |
| invalid_confirm_token | 400 | تأیید: توکن دستکاری شده، مال ایجنت، کانال یا نشست دیگری است، یا قبلاً یک بار به کار رفته | ندارد |
| invalid_bot_key | 401 | کلید نیامده، اشتباه است، عوض شده، یا کلید پروژه است | ندارد |
| cash_required | 402 | پول هست، ولی فقط اعتبار هدیه که هزینهٔ پرسش را نمیدهد | ندارد |
| insufficient_funds | 402 | پول قابلخرج کافی نیست؛ یا ایجنت به خاطر نپرداختن هزینهٔ ساعتی خاموش شده | ندارد |
| monthly_cap_reached | 402 | سقف ماهانهای که برای ایجنت گذاشتهاید پر شده | ندارد |
| bot_paused | 403 | صاحب ایجنت آن را خاموش کرده | ندارد |
| bot_not_found | 404 | ایجنت وجود ندارد یا حذف شده | ندارد |
| route_not_found | 404 | مسیر اشتباه زیر /ai/v1/ | ندارد |
| method_not_allowed | 405 | روشی غیر از POST روی مسیر ask | ندارد |
| confirm_token_expired | 410 | تأیید: پنج دقیقهٔ عمر توکن گذشته است | ندارد |
| rate_limit_exceeded | 429 | از سقف نرخ یا همزمانی ایجنت یا حساب گذشتهاید؛ همراه Retry-After | ندارد |
| internal_error | 500 | خطای داخلی | ندارد |
| output_invalid | 502 | مدل جواب خالی، بریده یا نامعتبر داد | دارد |
| ai_unavailable | 503 | سرویس هوش مصنوعی در دسترس نیست یا ظرفیت پر است | ندارد |
| invalid_widget_session | 400 | ویجت: session نیامده یا ۱۶ تا ۶۴ نویسه از [A-Za-z0-9_-] نیست | ندارد |
| invalid_feedback | 400 | ویجت: بازخورد requestId ندارد یا rating آن up، down یا null نیست | ندارد |
| invalid_widget_key | 401 | ویجت: کلید ویجت نیامده، اشتباه است یا عوض شده؛ یا کلید خود ایجنت روی مسیر ویجت آمده | ندارد |
| widget_disabled | 403 | ویجت: ویجت این ایجنت خاموش است | ندارد |
| widget_origin_not_allowed | 403 | ویجت: صفحه در فهرست دامنههای مجاز نیست، یا درخواست Origin و Referer ندارد | ندارد |
| log_entry_not_found | 404 | ویجت: پاسخی از ویجت همین ایجنت با این requestId نیست | ندارد |
cash_required و insufficient_funds یعنی «کیف پول را شارژ کنید و دوباره
بفرستید». ایجنتی هم که به خاطر تمام شدن موجودی خاموش شده، با شارژ کیف پول
خودبهخود روشن میشود. ولی monthly_cap_reached با شارژ برطرف نمیشود: سقف
ماهانهٔ ایجنت را در پنل بالا ببرید یا تا ماه بعد صبر کنید.
requestId در بدنهٔ خطا
خطاهایی که بعد از پذیرفتن پرسش رخ میدهند — کمبود پول، سقف ماهانه، 500،
502 و 503 — در بدنه فیلد requestId هم دارند. ردهای پیش از آن (400،
401، 403، 404، 405، 429، و 402 ایجنتی که به خاطر تمام شدن موجودی
خاموش شده) این فیلد را ندارند و ردیفی هم در گزارش نمیسازند. وقتی خطایی
requestId ندارد، پرسش به گزارش نرسیده است.
requestId را همراه هر خطا در لاگ اپ خودتان بنویسید. با آن، همان پرسش را
در گزارش سؤالهای پنل پیدا میکنید و میبینید دقیقاً چه پرسیده شد و چه شد.
دوباره فرستادن
- ۴۲۹: همیشه سرآیند
Retry-Afterدارد، به ثانیه. همانقدر صبر کنید و بعد دوباره بفرستید. سقف نرخ هر ایجنت را پلنش تعیین میکند (جدول «پلنها» در پایین)، ولی همهٔ ایجنتهای یک حساب با هم سقف ۵ درخواست در ثانیه دارند، و هر حساب همزمان فقط ۲ پرسش در جریان دارد — این دو عدد مال حساباند، نه پلن. پس نرخ واقعی یک ایجنت کمترِ این دو است: نرخ پلنش، یا سقف حساب منهای آنچه ایجنتهای دیگرتان در همان ثانیه مصرف کردهاند. وقتی پول یا جای سقف ماهانه هست ولی پرسشهای در جریان نگهش داشتهاند هم ۴۲۹ میگیرید، نه ۴۰۲؛ چند لحظه بعد آزاد میشود. - ۵۰۳: وقتی ظرفیت پر است
Retry-Afterدارد؛ همان را رعایت کنید. اگر نداشت، با فاصلهٔ رو به افزایش (چند ثانیه، بعد بیشتر) دوباره امتحان کنید. - ۵۰۲: میشود دوباره فرستاد، ولی این تلاش هزینه داشته و تلاش بعدی هم دارد.
- ۵۰۰: یک بار دیگر بفرستید؛ اگر تکرار شد،
requestIdرا (اگر دارد) به پشتیبانی بدهید. - ۴۰۰، ۴۰۱، ۴۰۲، ۴۰۳، ۴۰۴ و ۴۰۵: دوباره فرستادن بیتغییر فایده ندارد؛ اول علتش را درست کنید.
هزینه
ایجنت دو جور هزینه دارد و هر دو به تومان است:
- هزینهٔ ساعتی. هر ایجنت روشن به اندازهٔ پلنش ساعتی خرج دارد (جدول «پلنها» در پایین)، اول از اعتبار هدیه و بعد از موجودی نقدی. ایجنت خاموش هیچ هزینهای ندارد. ساختن یا روشن کردن ایجنت دستکم موجودی یک ساعت (هدیهی ثبتنام یا نقد؛ اعتبار هدیهی هوش مصنوعی هزینهٔ ساعتی را نمیدهد) را لازم دارد، و اگر موجودی هزینهٔ ساعتی را نپوشاند، ایجنت خاموش میشود تا شارژ کنید.
- هزینهٔ هر پرسش. به هزینهٔ واقعی مدل برای همان پرسش بستگی دارد و بعد از
تبدیل نرخ ارز و ضریب سرویس، به تومان حساب میشود. پرسشی که به جدول میرسد دو
بار مدل را صدا میزند — یک بار برای نوشتن query و یک بار برای نوشتن جواب — و
هر دو هزینه دارند. جوابی که مدل رد کرده (
answered: false) هم هزینه دارد.
هزینهٔ هر پرسش اول از اعتبار هدیهی هوش مصنوعی (۵۰۰۰ تومان برای حساب تازه، مشترک با دستیار ساخت بکاند) کم میشود و بعد از موجودی نقدی کیف پول. اعتبار هدیه هیچوقت هزینهٔ پرسش را نمیدهد. پرسشی که پولش نیست، پیش از هر خرجی با ۴۰۲ رد میشود.
هزینهٔ هر پرسش را در میز آزمایش و در گزارش سؤالها میبینید.
پلنها
هر ایجنت روی یکی از پلههای همان نردبان قهوهٔ پروژهها است. پلن هزینهٔ ساعتی و سقفهای ایجنت را تعیین میکند؛ هزینهٔ هر پرسش در همهٔ پلنها همان هزینهٔ واقعی جواب است و هیچ پلنی جواب رایگان یا از پیش خریدهشده ندارد.
| سقف | اسپرسو | کاپوچینو | ماکیاتو | موکا | آفوگاتو |
|---|---|---|---|---|---|
| هزینهی ساعتی | |||||
| ≈ ماهانه، همیشه روشن | |||||
| سقف دانستهها | |||||
| جدول متصل | |||||
| درخواست در ثانیه | |||||
| نگهداری گزارش پرسشها | |||||
| مدل |
- ساختن: در مرحلهٔ «پلن» ایجنت جدید انتخاب میکنید؛ اسپرسو از پیش انتخاب شده است.
- عوض کردن: در صفحهٔ «سقف و هزینه» ایجنت، فوری. ساعت جاری هم با نرخ پلن تازه حساب میشود. ارتقای ایجنتی که روشن است موجودی یک ساعت پلن تازه را لازم دارد.
- تنزل: اگر دانستهها یا جدولهای متصل ایجنت از سقف پلن پایینتر بیشتر باشد،
تغییر با
409 plan_downgrade_blockedرد میشود و پیام میگوید چه چیزی و چقدر را اول حذف کنید. چیزی بیصدا کوتاه نمیشود. فقط گزارش پرسشها از این قاعده جداست: اگر نگهداری گزارش در پلن تازه کوتاهتر باشد، پرسشهای قدیمیتر از آن در اجرای روزانهٔ بعدی پاک میشوند. - سرعت: «درخواست در ثانیه» سقف خود ایجنت است. همهٔ ایجنتهای یک حساب با هم هم سقفی دارند، پس سرعت واقعی یک ایجنت کمترِ نرخ پلنش و سهمش از سقف حساب است.
- مدل: ردیف «مدل» نام مدلهایی است که ایجنت آن پلن میتواند با آنها جواب بدهد؛ اولی پیشفرض پلن است. اگر پلنی چند مدل دارد، در صفحهٔ «مدل» ایجنت یکی را انتخاب میکنید (بخش مدل ایجنت).
مدل ایجنت
هر پلن یک مدل پیشفرض دارد و ممکن است چند مدل دیگر هم برای انتخاب داشته باشد. در صفحهٔ «مدل» ایجنت (گروه «ساخت» در منوی ایجنت) یکی را انتخاب کنید؛ از پرسش بعدی، هم API و هم میز آزمایش با همان مدل جواب میدهند.
- هزینهٔ هر پرسش به مدل بستگی دارد. مدل قویتر معمولاً هر جواب را گرانتر میکند، و موجودی پیش از جواب با قیمت همان مدل رزرو میشود. پیش از تغییر مدل، چند پرسش را در میز آزمایش بفرستید و هزینهٔ زیر هر جواب را مقایسه کنید.
- اگر مدل انتخابی شما از پلن برداشته شود، ایجنت بیوقفه با مدل پیشفرض پلن جواب میدهد و API هیچ خطایی برنمیگرداند؛ صفحهٔ «مدل» این را به شما میگوید.
- با تغییر پلن، اگر پلن تازه مدل انتخابی شما را نداشته باشد، ایجنت روی مدل پیشفرض پلن تازه میرود.
- مدلی که در پلن ایجنت نیست انتخاب نمیشود (
400 model_not_in_planدر API پنل). - ایجنتی که تابع دارد مدلی با حافظهٔ (پنجرهٔ) بزرگتر لازم دارد؛ بخش پنجرهٔ مدل برای توابع را ببینید.
کلید ایجنت و امنیت
کلید ایجنت (apck_bot_…) یک راز خرجکننده است: هر کس آن را داشته باشد
میتواند از کیف پول شما سؤال بپرسد. گذاشتن کلید در کد فرانت سایت یا اپ یعنی
همین — هر بازدیدکنندهای میتواند آن را ببیند.
مسیر ایجنت CORS باز دارد تا صدا زدنش از فرانت سایت ممکن باشد. اگر کلید را در فرانت گذاشتید:
سقف ماهانه را حتماً تنظیم کنید (صفحهٔ «سقف و هزینه» در منوی ایجنت). وقتی سقف
پر شود، ایجنت تا آخر ماه با monthly_cap_reached رد میکند و چیزی بیشتر خرج
نمیشود.
- سقف ماهانه به ماه میلادی و به وقت تهران حساب میشود و همهٔ پرسشهای ایجنت را میشمارد، از هر جیبی که پرداخت شده باشند. بدون سقف، هزینه تا ته کیف پول ادامه دارد.
- اگر کلید لو رفت، در صفحهٔ «کلید و API» دکمهٔ «عوض کردن کلید» را بزنید. کلید قبلی همان لحظه از کار میافتد و هر درخواستی با آن ۴۰۱ میگیرد.
- کلید هر ایجنت فقط به همان ایجنت دسترسی میدهد. کلید پروژه برای ایجنت کار نمیکند.
- اگر میخواهید ایجنت روی سایتتان با بازدیدکننده گفتوگو کند، بهجای گذاشتن این کلید در صفحه از ویجت سایت استفاده کنید.
ویجت سایت
ویجت سایت ایجنت را به شکل یک دکمهٔ گفتوگو در گوشهٔ سایت خودتان میگذارد. بازدیدکننده
روی دکمه میزند، میپرسد و جواب ایجنت را همانجا میبیند. برای نصبش کد نوشتن لازم
نیست: یک خط را در صفحه میگذارید. کلید خود ایجنت (apck_bot_…) هم هیچوقت در صفحه
دیده نمیشود.
نصب
در منوی ایجنت، صفحهٔ ویجت سایت را باز کنید:
- دامنهٔ سایتتان را به فهرست دامنههای مجاز اضافه کنید.
- ویجت را روشن کنید، ظاهرش را تنظیم کنید و ذخیره کنید. پیشنمایش کنار فرم همان لحظه عوض میشود.
- خطی را که همانجا با «کپی snippet» کپی میشود، پیش از
</body>در صفحههای سایت بگذارید:
<script src="https://api.fikaro.ir/ai/widget/v1.js" data-agent="{botId}" data-key="apck_wgt_..." async></script>
همین. وردپرس، سایتساز یا HTML دستنویس فرقی نمیکند. هر جا بشود یک تگ script
گذاشت، ویجت کار میکند. تغییر ظاهر هم بعد از ذخیره، با بار بعدی صفحه روی سایت دیده
میشود و لازم نیست snippet را عوض کنید.
دامنههای مجاز
ویجت فقط روی دامنههایی ساخته میشود که در فهرست هستند. اگر کسی snippet شما را روی سایت دیگری بگذارد، ویجتی آنجا ساخته نمیشود.
- هر ورودی یک نام دامنه است، مثل
shop.example.com. نشانی کامل هم پذیرفته میشود و فقط دامنهاش نگه داشته میشود. *.example.comهمهٔ زیردامنهها را میپذیرد، در هر عمقی، ولی خودexample.comرا نه. اگر هر دو را میخواهید، هر دو را بنویسید.- ورودی بدون پورت هر پورتی را میپذیرد، و ورودی با پورت فقط همان پورت را.
localhostو127.0.0.1فقط وقتی پذیرفته میشوند که خودتان اضافهشان کنید؛ مثلاًlocalhost:5500برای آزمایش روی رایانهٔ خودتان. IP دیگری پذیرفته نمیشود.- حداکثر ۲۰ ورودی. ویجت تا دستکم یک دامنه نداشته باشد روشن نمیشود.
این فهرست جلوی گذاشتن ویجت روی سایت دیگران را میگیرد، نه جلوی هر درخواستی را. کلید ویجت عمومی است و کسی که بخواهد میتواند با ابزاری مثل curl و سرآیند جعلی درخواست بفرستد. چیزی که خرج را محدود نگه میدارد، سقف نرخ ویجت برای هر IP و هر گفتوگو، سقفهای خود ایجنت و حساب، و سقف ماهانه است. پس برای ایجنتی که ویجت دارد، سقف ماهانه بگذارید.
آنچه بازدیدکننده میبیند
- یک دکمهٔ گرد در پایین راست یا چپ صفحه، به رنگ تأکیدی که انتخاب کردهاید. روی موبایل، پنل گفتوگو کل صفحه را میگیرد.
- عنوان، نشان، پیام خوشآمد و متن راهنمای کادر پیام را خودتان تعیین میکنید.
- گفتوگو تا وقتی آن برگهٔ مرورگر باز است میماند، حتی اگر صفحه عوض شود. پیامهای قبلی، مثل گفتوگوی چندنوبتی، همراه هر پرسش فرستاده میشوند. فیکارو چیزی از گفتوگو را در سرور نگه نمیدارد، جز ردیف معمول گزارش سؤالها.
- اگر ایجنت شکل خروجی داشته باشد، برچسب بهصورت متن ساده و شیء به شکل خطهای «نام: مقدار» نشان داده میشود.
- اگر ایجنت خاموش باشد، سقف ماهانه پر شده باشد یا موجودی کافی نباشد، بازدیدکننده فقط پیام «الان امکان پاسخ نیست» را میبیند. حرفی از پول و کیف پول به او زده نمیشود.
- وقتی جوابی
handoffدارد و در صفحهٔ «ارجاع به انسان» راه تماس گذاشتهاید، زیر جواب پیام شما و دکمهٔ «گفتوگو با پشتیبان انسانی» میآید که به تلفن، ایمیل، بله یا پیوند شما میرود. بدون راه تماس، چیزی اضافه نمیشود. - وقتی ایجنت میخواهد تابعی را اجرا کند که تأیید میخواهد، زیر جواب کارتی با خلاصهٔ کار و دو دکمهٔ «تأیید» و «لغو» میآید. «تأیید» کار را انجام میدهد و نتیجه پیام بعدی ایجنت است؛ «لغو» کارت را میبندد و چیزی به سرور نمیفرستد. بعد از پنج دقیقه کارت «مهلت تأیید تمام شد» میگوید. کارتی که تصمیمش گرفته شده یا مهلتش گذشته، بعد از بارگذاری دوبارهٔ صفحه هم دکمه ندارد.
- ویجت داخل Shadow DOM ساخته میشود. یعنی CSS سایت شما ظاهرش را به هم نمیریزد و CSS ویجت هم به سایت شما نشت نمیکند.
هزینه
هر پرسش از راه ویجت دقیقاً یک پرسش API است: همان هزینه، همان سقف نرخ ایجنت و حساب، و همان سقف ماهانه. ویجت هزینهٔ ماهانهٔ جدایی ندارد.
پیش از اینکه پیام بازدیدکننده به مدل برسد، یک بررسی پیام نامناسب را جدا میکند. این بررسی امروز رایگان است. پیامی که رد شود جواب مؤدبانهٔ ثابتی میگیرد و به مدل نمیرسد، پس هزینهٔ پاسخ مدل هم برایش گرفته نمیشود. در گزارش سؤالها با برچسب «پیام نامناسب» دیده میشود و جزو «بیجواب»ها نیست.
بازخورد بازدیدکننده
زیر هر جواب دو دکمه هست: مفید بود و مفید نبود. بازخورد در صفحهٔ گزارش سؤالها، کنار همان پرسش دیده میشود. پرسشهای ویجت در گزارش برچسب منبع «ویجت» دارند.
مسیرهای ویجت
اسکریپت ویجت خودش این چهار مسیر را صدا میزند و معمولاً لازم نیست شما صدایشان بزنید.
کلید ویجت (Authorization: Bearer apck_wgt_…) فقط روی همین چهار مسیر کار میکند:
روی مسیر ask جواب 401 invalid_bot_key میگیرد، و کلید خود ایجنت هم روی این
مسیرها 401 invalid_widget_key میگیرد.
GET /ai/v1/bots/{botId}/widget— ظاهر ویجت و سقفهایی که پیامها به آن بریده میشوند.POST /ai/v1/bots/{botId}/widget/ask— همان بدنهٔaskبهعلاوهٔsession(۱۶ تا ۶۴ نویسه از[A-Za-z0-9_-]). پاسخ همان پاسخaskاست.POST /ai/v1/bots/{botId}/widget/feedback—{"requestId": "…", "rating": "up" | "down" | null}، با پاسخ204.POST /ai/v1/bots/{botId}/widget/confirm—{"token": "…", "session": "…"}: تأیید کاری که پاسخ قبلی درpendingActionآورده. توکن فقط از همانsessionپذیرفته میشود که پرسش را فرستاده بود. پاسخ همان پاسخaskاست. بیشتر: نوشتن و تأیید.
اتصال به بازوی بله
ایجنت میتواند به پیامهای بازوی خودتان در پیامرسان بله جواب بدهد. بازو مال خودتان میماند؛ فیکارو فقط پیامهایی را که به آن میرسد با ایجنت جواب میدهد. کد نوشتن لازم نیست.
ساختن بازو
- در اپ بله به @botfather پیام بدهید و «شروع» را بزنید.
- یک بازوی تازه بسازید: یک نام و یک نام کاربری که به
botختم شود. - botfather یک توکن میدهد؛ چیزی شبیه
1234567890:AbC…. آن را کپی کنید.
اتصال
در منوی ایجنت، صفحهٔ بازوی بله را باز کنید، توکن را بگذارید و «اتصال» را بزنید.
فیکارو توکن را با خود بله میسنجد، آن را رمزنگاریشده نگه میدارد و به بله میگوید
پیامهای بازو را به ایجنت بفرستد. توکن بعد از ذخیره دیگر در پنل یا هیچ پاسخی دیده
نمیشود؛ پنل بازو را با @نامکاربری و چهار رقم آخر شناسهاش نشان میدهد.
- آزمایش اتصال بررسی میکند توکن هنوز کار میکند و بله پیامها را به ایجنت میفرستد. اگر نفرستد، اتصال را خودش دوباره ثبت میکند؛ مگر اینکه همان بازو حالا به ایجنت دیگری از شما وصل باشد. یک بازو هر بار فقط به یک ایجنت پیام میفرستد، پس آزمایش آن را از ایجنت دیگر پس نمیگیرد.
- اتصال با توکن تازه برای وقتی است که توکن را در botfather عوض کردهاید یا بازوی دیگری میخواهید.
رفتار بازو
- هر پیام متنی جواب میگیرد، بهصورت پاسخ به همان پیام. تا جواب آماده شود، کاربر «در حال نوشتن…» را میبیند. جواب بلند در چند پیام پشت هم فرستاده میشود.
- عکس، صدا، فایل و استیکر جواب نمیگیرند؛ کاربر پیامی میگیرد که فقط متن جواب داده میشود.
/startپیام خوشآمد را میگیرد: متنی که خودتان در صفحهٔ بازوی بله مینویسید، یا پیشفرض «سلام! سؤالتان را بنویسید.». این پیام پرسش حساب نمیشود و هزینه ندارد.- گروهها پیشفرض خاموشاند. اگر «پاسخ در گروهها» را روشن کنید، بازو در گروه
فقط به پیامی جواب میدهد که
@نامکاربریبازو را داشته باشد یا به پیام خود بازو جواب داده باشد. بقیهٔ گفتوگوی گروه را نادیده میگیرد، تا پول شما صرف گفتوگوی دیگران نشود. کانالها هیچوقت جواب نمیگیرند. - اگر ایجنت خاموش باشد، سقف ماهانه پر شده باشد یا موجودی کافی نباشد، کاربر بله فقط پیام «الان امکان پاسخ نیست؛ لطفاً کمی بعد دوباره بپرسید.» را میگیرد، حداکثر یک بار در ده دقیقه برای هر گفتوگو. حرفی از پول و کیف پول به او زده نمیشود.
- پیامهای بله هم مثل ویجت، پیش از مدل از بررسی پیام نامناسب رد میشوند.
- وقتی جوابی
handoffدارد و راه تماس گذاشتهاید، آخر همان پیام یک بند جدا میآید: پیام شما و زیرش شماره، ایمیل،@شناسهیا پیوند. این بند در حافظهٔ گفتوگو نگه داشته نمیشود. - تابعی که اجازهٔ نوشتن دارد فقط در چت خصوصی اجرا میشود؛ در گروه اجرا نمیشود. اگر تأیید میخواهد، بازو خلاصهٔ کار را با دو دکمهٔ «تأیید» و «لغو» میفرستد. کاربر میتواند دکمه را بزند یا در جواب بنویسد «تأیید» یا «لغو». فقط همان کاربر در همان چت میتواند تأیید کند، و بعد از تصمیم دکمهها برداشته میشوند.
هزینه
هر پیام متنی دقیقاً یک پرسش API است: همان هزینه، همان سقف نرخ ایجنت و حساب، و همان سقف ماهانه. اتصال بله هزینهٔ ماهانهٔ جدایی ندارد. پرسشهای بله در گزارش سؤالها با برچسب منبع «بله» دیده میشوند.
سقفها
| سقف | مقدار | اگر رد شود |
|---|---|---|
| پیام هر گفتوگو | ۱۰ در دقیقه | پرسیده نمیشود؛ کاربر «پیامها زیاد شد؛ لطفاً کمی صبر کنید.» را میگیرد |
| پیام هر بازو | ۶۰ در دقیقه | همان پیام |
| طول هر پیام | ۴۰۰۰ نویسه | بیشتر از آن بریده میشود و پرسش رد نمیشود |
| سقفهای ایجنت و حساب | همان سقفهای API | همان پیام «پیامها زیاد شد» |
حافظهٔ گفتوگو
برای اینکه ایجنت پرسش «و جمعه؟» را بعد از «ساعت کاری؟» بفهمد، ۶ پیام آخر هر
گفتوگو در ۲۴ ساعت گذشته همراه پرسش فرستاده میشود، مثل
گفتوگوی چندنوبتی. فقط پرسشهایی که جواب گرفتهاند به حافظه
میروند؛ پیام نامناسب، خطا و /start نه.
این حافظه بعد از ۲۴ ساعت پاک میشود و در هیچ پنل یا API نشان داده نمیشود، حتی به شما. قطع اتصال، وصل کردن بازوی دیگر و حذف ایجنت هم آن را پاک میکنند. ردیف معمول گزارش سؤالها مثل هر پرسش دیگری میماند.
قطع اتصال
«قطع اتصال» در صفحهٔ بازوی بله، اتصال پیامها را برمیدارد و توکن و حافظهٔ گفتوگوها را پاک میکند. خود بازو در بله میماند و میتوانید بعداً دوباره وصلش کنید. حذف ایجنت هم اتصال بلهاش را قطع میکند.
ارجاع به انسان
ایجنت همهچیز را نمیداند و بعضی گفتوگوها باید به یک آدم برسند. صفحهٔ «ارجاع به انسان» در بخش «اتصال» سه چیز را تعیین میکند. این یک راه تماس است، نه گفتوگوی زنده: کاربر خودش با شما تماس میگیرد.
کی ارجاع میشود
- همیشه وقتی ایجنت جواب را نمیداند. هر
answered: false، از جمله وقتی ایجنت از جواب دادن سر باز میزند و خطای تابع یا جدول،handoff: trueدارد. دو استثناhandoff: falseدارند: پیامی که بررسی محتوای ویجت یا بله ردش کرده، تا راه تماس شما زیر پیام نامناسب نیاید؛ و کار نوشتنیای که انجام نشد (رد شد، به سقف نوشتن خورد، یا پس از تأیید انجام نشد)، چون کاربر کاری خواسته بود، نه جوابی که ایجنت نداشت. برای این دو هشدار فوری هم فرستاده نمیشود. - برچسبهای ارجاع. برای ایجنت شکلدار، برچسبهایی را از همان شکل خروجی علامت بزنید (حداکثر ۳۰). جوابی که برچسبش یکی از اینهاست ارجاع میشود؛ برای ایجنت شیئی، کافی است یکی از فیلدهای گزینهای همان برچسب را داشته باشد. اگر برچسبی را بعداً از شکل خروجی بردارید، دیگر ارجاع نمیدهد و در صفحه هم دیده نمیشود.
راه تماس
یکی از اینها، با یک پیام کوتاه (حداکثر ۳۰۰ نویسه؛ خالی بماند، «برای ادامهٔ گفتوگو با پشتیبان انسانی در تماس باشید.»):
- تلفن — ۷ تا ۱۵ رقم، با
+یا بدون آن. رقم فارسی هم پذیرفته میشود. - بله — شناسهٔ بله، مثل
@shop_support. ویجت آن را بهhttps://ble.ir/shop_supportمیبرد. - ایمیل — یک نشانی ایمیل.
- پیوند — فقط نشانیای که با
https://شروع میشود.
راه تماس فقط در ویجت سایت و بازوی بله نشان داده
میشود. پاسخ /ask هیچوقت آن را ندارد؛ اپ شما خودش میداند با handoff چه کند.
تنظیم نادرست با 400 invalid_handoff_settings رد میشود و چیزی ذخیره نمیشود.
خبر به شما
- خلاصهٔ روزانه. هر روز از ساعت ۹ صبح به وقت تهران، برای هر ایجنتی که دیروز سؤال بیجواب داشته، یک اعلان در زنگولهٔ پنل میآید: تعداد، تا سه نمونه سؤال، و پیوند به فیلتر «بیجواب» گزارش سؤالها. سؤالهای میز آزمایش، پیامهای ردشده، نوشتنهایی که انجام نشدند و سؤالهایی که به دانستهها اضافه شدهاند شمرده نمیشوند. روزی که سؤال بیجوابی نبوده، اعلانی هم نیست.
- هشدار فوری. اگر روشنش کنید، وقتی پاسخی از API، ویجت یا بله ارجاع شد خبرتان میکنیم؛ برای هر ایجنت حداکثر یک بار در ساعت. میز آزمایش هشدار نمیدهد.
هر دو در زنگوله میآیند، و اگر حسابتان ایمیل دارد، به ایمیلتان هم. پیامکی فرستاده نمیشود. هر دو را در تنظیمات اعلانها، زیر «ایجنتها»، خاموش کنید.
یک محدودیت صادقانه: prompt injection
جلوگیری کامل از prompt injection ممکن نیست. هر چیزی که در دستورالعمل، دانستهها یا جدولهای وصلشدهٔ ایجنت باشد، ممکن است با یک پرسش زیرکانه از ایجنت بیرون کشیده شود — حتی اگر در دستورالعمل گفته باشید آن را نگوید.
پس چیز محرمانه در آنها نگذارید: کلید، رمز، اطلاعات تماس یا هر چیزی که نباید به دست کاربران اپ برسد.
همین دربارهی توابع هم صادق است. پرسنده میتواند با یک پرسش زیرکانه
ایجنت را وادار کند یکی از توابع متصل را با آرگومانهایی صدا بزند که شما انتظارش
را نداشتید — آرگومانهایی معتبر، ولی ناخواسته. تضمین فیکارو این است که ایجنت
هیچ کاری بیش از کد خود تابع نمیکند: فقط توابعی را صدا میزند که خودتان وصل
کردهاید، فقط با پارامترهایی که خودتان اعلام کردهاید، هرگز جدول یا ستونی را خودش
انتخاب نمیکند، و ctx.http.post و هر درخواست ctx.http به API خود فیکارو را رد
میکند. نوشتن در دیتابیس فقط برای تابعی ممکن است که خودتان «اجازهٔ نوشتن» را برایش
روشن کردهاید، و آن هم فقط در پروژهٔ خود همان تابع.
پس با تابع نوشتنی صادق باشیم: هر کسی که با ایجنت حرف میزند میتواند آن را به صدا
زدن تابع نوشتنی با مقدارهای معتبر وادارد. با کلید عمومی ویجت این یعنی هر
بازدیدکنندهٔ سایت شما. حالت تأیید جلوی کاری را میگیرد که کاربر نخواسته، ولی جلوی
کاربری را که خودش میخواهد چیز بیربطی ثبت کند نمیگیرد. سقفهای نوشتن تعداد را
محدود میکنند، نه محتوا را. پس اعتبارسنجی خود تابع آخرین دروازه است: هر مقدار را
بررسی کنید، با ctx.reject رد کنید، و سرآیند idempotency-key را که شکلش
<requestId>:<fn> است رعایت کنید تا یک کار دو بار ثبت نشود.
ctx.http.get به سرویسهای بیرونی باز میماند و هر کاری که کد خود تابع با آن بکند به
عهدهی شماست. تابعی وصل نکنید که خروجیاش نباید به هر پرسندهای برسد، و اگر تابع
دادهٔ یک کاربر را برمیگرداند، خودش بررسی کند که پرسنده حق دیدنش را دارد.
وصل کردن جدول
در صفحهٔ «جدولها» میتوانید ایجنت را به جدولهای پروژههای خودتان وصل کنید تا مثلاً به «کفش مشکی سایز ۴۲ زیر ۲ میلیون دارید؟» از روی جدول محصول جواب بدهد.
-
از راه جدول وصلشده، ایجنت فقط میخواند و هرگز نمینویسد. ایجنت هیچ ردیفی را مستقیم نمیسازد، ویرایش یا حذف نمیکند. تنها راه نوشتن، تابعی است که خودتان برایش اجازهٔ نوشتن دادهاید.
-
کل جدول وصل میشود، با یک استثنا: این ستونها هرگز به ایجنت داده نمیشوند — نه در جواب، نه در فیلتر، مرتبسازی یا جستوجو:
- ستونهای مخفی
- ستونهایی که خواندنشان فقط برای ادمین است
- ستونهای ایمیل و تلفن
- ستونهای محاسباتی
- ستونهای json و فایل
جدول
userاصلاً قابل اتصال نیست. -
ایجنت فقط به جدولهای پروژههای خود شما دسترسی دارد، و پروژه باید فعال باشد. تعداد جدولهای متصل هر ایجنت را پلنش تعیین میکند.
-
برای هر پرسش، مدل حداکثر دو query فقطخواندنی به زبان query فیکارو مینویسد و هر query حداکثر ۲۰ ردیف برمیگرداند. جواب فقط از روی همین ردیفها نوشته میشود؛ اگر ردیفی پیدا نشود، ایجنت صریح میگوید پیدا نشد.
-
queryهای هر پرسش در میز آزمایش و گزارش سؤالها دیده میشوند.
اگر پروژه یا جدول حذف شود یا ستونهایش عوض شوند، اتصال در پنل «نیازمند بازبینی» نشان داده میشود و ایجنت تا آن موقع از آن جدول استفاده نمیکند.
توابع
در صفحهٔ «توابع» میتوانید تا ۳ تابع endpoint از پروژههای فعال خودتان را به
ایجنت وصل کنید تا مثلاً به «سفارش ۱۲۳۴ کجاست؟» از روی جواب تابع order_status
جواب بدهد. منطق را خودتان در تابع نوشتهاید؛ ایجنت فقط تصمیم میگیرد کی و با چه
آرگومانی صدایش بزند.
برای هر تابع اینها را مینویسید:
- توضیح (حداکثر ۵۰۰ نویسه): تابع چه میکند و ایجنت کی صدایش بزند. ایجنت فقط از روی همین جمله تصمیم میگیرد.
- پارامترها (حداکثر ۵): نام لاتین (مثل
order_id)، نوع (متن، عدد، بله/خیر یا گزینهای با ۱ تا ۲۰ گزینه)، الزامی یا نه، و یک توضیح کوتاه. پارامترها از کد خوانده نمیشوند؛ همانهایی که اینجا اعلام کنید، تنها چیزی است که ایجنت میتواند بفرستد.
وقتی ایجنت تابع را صدا میزند:
- پیشفرض فقط برای خواندن اجرا میشود. هر
create،updateیاdelete— باctx.dbیاctx.db.admin— رد میشود و تابع خطا میدهد.ctx.db.listوctx.db.getکار میکنند. اگر برای تابع «اجازهٔ نوشتن» را روشن کنید، نوشتن در دیتابیس پروژهٔ خود تابع ممکن میشود؛ بخش نوشتن و تأیید. ctx.http.postهمیشه رد میشود، با اجازهٔ نوشتن یا بی آن.- به API خود فیکارو نمیرسد. هر درخواست
ctx.http— با هر متدی، حتی GET — بهapi.fikaro.ir، به دامنهٔ اختصاصی هر پروژه، یا به هر آدرس دیگری که به فیکارو برسد رد میشود و تابع خطا میدهد؛ وگرنه یک GET ممکن بود به تابع دیگری از پروژههایتان برسد که چیزی مینویسد. ctx.http.getبه سرویسهای بیرونی کار میکند. فیکارو نمیداند آن سرویس چه میکند؛ اگر چنین درخواستی چیزی را عوض میکند، مسئولیتش با کد تابع است.- تابع مثل فراخوانی با کلید API پروژه اجرا میشود:
ctx.authبرابر"key"است وctx.userخالی است، چون پرسندهٔ ایجنت کاربر پروژه نیست. ctx.input(همانctx.request.body) فقط آرگومانهایی است که ایجنت نوشته و سرور با اعلام شما مقایسه کرده؛ متن پرسش و گفتوگوی قبلی به تابع نمیرود. هر اجرا سرآیندidempotency-keyهم دارد، به شکل<requestId>:<fn>.- secretهای پروژه مثل همیشه در
ctx.secretsهستند و هیچجا ثبت نمیشوند. ctx.aiدر این اجرا رد میشود. تابعی که ایجنت صدا میزند نمیتواند خودش ایجنت صدا بزند (خطایai_not_allowed)، تا یک پرسش زنجیرهای از پرسشهای پولی نشود.- محدودیتهای همیشگی تابع سر جایش است: ۱۰ ثانیه و ۲۵ عملیات دیتابیس. هر اجرا یکی از درخواستهای ماهانهٔ همان پروژه شمرده میشود.
- جواب تابع (چه با
ctx.respond، چه باctx.reject) بهعنوان داده به ایجنت داده میشود، نه دستور، و ایجنت فقط از روی آن جواب مینویسد. پاسخ ۴۰۴ مثل «سفارش پیدا نشد» هم داده است و ایجنت آن را میگوید. - در هر پرسش حداکثر یک تابع صدا زده میشود (کنار حداکثر دو query جدول). اگر تابع
خطا بدهد، وقت تمام شود یا سهمیهٔ پروژه پر باشد، جواب
answered: falseبا یک جملهٔ ثابت است و جزئیات خطا فقط در گزارشها میآید.
| کجا ببینید | چه چیزی |
|---|---|
| میز آزمایش | «order_status صدا زده شد»، آرگومانها و خلاصهٔ خروجی تابع؛ برای تابع نوشتنی «ثبت کرد» یا «در انتظار تأیید» |
| گزارش سؤالها | همان، برای هر پرسش از API، ویجت، بله، کد فانکشن یا میز آزمایش |
| گزارش اجرای تابع در پروژه | یک ردیف fn_invocation برای هر اجرا، با شناسهٔ ایجنت و requestId |
خروجی تابع در پاسخ عمومی /ask نمیآید، در sources هم نه. تنها فیلدی که توابع به
پاسخ اضافه کردهاند pendingAction است، برای تابع نوشتنیای که تأیید میخواهد.
اگر تابع حذف یا غیرفعال شود، نامش عوض شود یا پروژهاش فعال نباشد، اتصال در پنل «نیازمند بازبینی» نشان داده میشود و ایجنت تا آن موقع آن را صدا نمیزند.
دو الگوی آماده
- وضعیت سفارش از یک فروشگاه بیرونی. تابع با
ctx.http.getو یک کلید فقطخواندنی ازctx.secretsسفارش را از REST API فروشگاه میخواند، موبایلی را که پرسنده داده با موبایل سفارش مقایسه میکند و فقط چند فیلد بیخطر مثل وضعیت و اقلام را برمیگرداند. برای موبایل اشتباه و سفارش ناموجود یک جواب بدهید تا حدس زدن شمارهها چیزی لو ندهد. کد کامل برای ووکامرس در پیگیری سفارش ووکامرس با هوش مصنوعی آمده است. - ساعتهای خالی نوبت. در پروژهای از قالب رزرو و نوبتدهی،
تابع با
ctx.db.listبازههای کاری و نوبتهای یک روز را میخواند و فقط ساعتهای آزاد و آدرس فرم رزرو را برمیگرداند. جدولbookingرا مستقیم به ایجنت وصل نکنید: یادداشت مراجع در آن است و جدول وصلشده برای هر پرسندهای خواندنی است. این تابع فقط میخواند و ایجنت با آن نوبت ثبت نمیکند؛ مراجع را به فرم رزرو خودتان بفرستد. اگر میخواهید خود ایجنت نوبت ثبت کند، تابع ثبت نوبتی بنویسید و با اجازهٔ نوشتن و تأیید وصلش کنید.
نوشتن و تأیید
در صفحهٔ «توابع»، هر تابع وصلشده دو کلید دارد که هر دو پیشفرض خاموشاند:
- اجازهٔ نوشتن. تابع با
ctx.dbوctx.db.adminدر دیتابیس پروژهٔ خودش ردیف میسازد، ویرایش یا حذف میکند. جای دیگری نمینویسد:ctx.http.postو هر درخواست به API فیکارو همچنان بستهاند، و ساختن یا حذف کاربر جدولuserرد میشود (برای ثبتنام کاربر، از auth پروژه استفاده کنید). مدل هیچوقت جدول یا ستون انتخاب نمیکند؛ فقط پارامترهایی را میفرستد که خودتان اعلام کردهاید. - پیش از انجام از کاربر تأیید بگیر. فقط با اجازهٔ نوشتن روشن میشود. تابع اجرا نمیشود تا کاربر خلاصهٔ کار را ببیند و تأیید کند. روشن ماندنش را توصیه میکنیم.
در هر پرسش حداکثر یک کار نوشتنی انجام میشود، و سرور هر کار را برای هر requestId
فقط یک بار ثبت میکند. سرآیند idempotency-key با شکل <requestId>:<fn> در اجرای
مستقیم و در اجرای بعد از تأیید یکسان است؛ تابع نوشتنی شما هم بهتر است آن را رعایت
کند. ایجنتی که تابع نوشتنی دارد، در توضیح آن تابع به مدل یادآوری میکند که فقط وقتی
کاربر صریحاً خواست و مقدارها را خودش نوشت صدایش بزند.
بدون تأیید، تابع همان لحظه اجرا میشود و ایجنت از روی جواب تابع پاسخ مینویسد.
با تأیید، تابع اجرا نمیشود و مدل دوباره صدا زده نمیشود. پاسخ این شکل را دارد:
{
"answered": true,
"answer": "برای انجام این کار تأیید شما لازم است: ثبت لید — نام: علی، شمارهی تماس: ۰۹۱۲۱۲۳۴۵۶۷",
"output": null,
"sources": [],
"requestId": "0199d3a2-7c41-7b8e-9f3a-2d6e1c0b4a17",
"handoff": false,
"knowledgeIds": [],
"pendingAction": {
"fn": "capture_lead",
"summary": "ثبت لید — نام: علی، شمارهی تماس: ۰۹۱۲۱۲۳۴۵۶۷",
"token": "eyJ…",
"expiresAt": "2026-10-13T10:05:00Z"
}
}
summaryرا سرور از آرگومانها میسازد، نه مدل: نام نمایشی تابع و برای هر آرگومان «توضیح پارامتر: مقدار» (هر مقدار حداکثر ۸۰ نویسه). پس متنی که کسی در پرسش جاسازی کرده نمیتواند کار دیگری را جای این کار جلوه دهد. خلاصه مقدار خام را نشان میدهد؛ یکدست کردن مقدار کار خود تابع است.tokenیکبارمصرف است، پنج دقیقه عمر دارد، و فقط برای همین ایجنت و همان کانال کار میکند: توکن API روی API، توکن ویجت فقط با همانsession، توکن میز آزمایش فقط در پنل. آرگومانها با توکن فرستاده نمیشوند؛ سرور خودش آنها را نگه داشته است.- خلاصه را به کاربر نشان دهید. اگر تأیید کرد، توکن را بفرستید:
curl -X POST "https://api.fikaro.ir/ai/v1/bots/{botId}/confirm" \
-H "Authorization: Bearer apck_bot_..." \
-H "Content-Type: application/json" \
-d '{"token": "eyJ…"}'
پاسخ همان شکل پاسخ ask است، با requestId تازه و pendingAction: null:
- انجام شد:
answered: trueوanswerبرابر «انجام شد.» بهعلاوهٔmessageجواب تابع، اگر تابع یکmessageمتنی برگرداند (حداکثر ۳۰۰ نویسه). - تابع رد کرد (
ctx.reject):answered: false،handoff: falseو «انجام نشد: » بهعلاوهٔ دلیلی که تابع داد (حداکثر ۲۰۰ نویسه). این تنها جایی است که متن رد تابع به پرسنده میرسد، چون همان اعتبارسنجی خود شماست. - خطای دیگر (خطای تابع، وقت تمام شد، یا اجازهٔ نوشتن در این فاصله برداشته شد):
answered: false،handoff: falseو یک جملهٔ ثابت، بی جزئیات خطا.
نوشتنی که انجام نشد، چه در ask و چه در confirm، هیچوقت handoff: true ندارد:
ویجت و بله زیرش راه تماس نمیگذارند و هشدار فوری فرستاده نمیشود.
هزینهٔ تأیید حداقل هزینهٔ یک پرسش است، چون مدلی صدا زده نمیشود، و وقتی توکن
مصرف شد همیشه گرفته میشود. 400 invalid_confirm_token و 410 confirm_token_expired
رایگاناند. 402 و 429 مثل ask است، و در این حالت توکن هنوز معتبر است؛ بعداً
دوباره بفرستید.
لغو مسیری ندارد: کاربری که تأیید نکند، توکن پنج دقیقه بعد خودش باطل میشود و چیزی ثبت نمیشود.
میز آزمایش و ویجت این کارت را خودشان نشان میدهند، و بازوی بله دکمههای «تأیید» و «لغو» را میفرستد. در گزارش سؤالها، پرسشی که منتظر تأیید ماند نشان «در انتظار تأیید» دارد و تأیید آن ردیف جدای خودش را با نشان «ثبت کرد» میسازد.
سقفهای نوشتن
کانالهای عمومی را هر کسی میتواند صدا بزند، پس نوشتن سقف جدا دارد. هر اجرای مستقیم یا صدور توکن یک بار شمرده میشود.
| کانال | سقف نوشتن |
|---|---|
| ویجت | ۳ در ساعت برای هر نشست، و ۱۰ در ساعت برای هر IP |
| API (کلید `apck_bot_`) | ۳۰۰ در ساعت برای هر ایجنت، از هر IP |
| بازوی بله | ۳ در ساعت برای هر گفتوگو؛ فقط در چت خصوصی، در گروه هرگز |
سقف API برای هر ایجنت است، نه هر IP، چون کلید ایجنت را بکاند شما صدا میزند و همهٔ کاربرانتان از همان یک IP میآیند. اگر برای هر کاربر خودتان سقف جدا میخواهید، آن را در بکاند خودتان بگذارید.
رسیدن به سقف یعنی تابع اجرا نمیشود و پاسخ answered: false و handoff: false با جملهٔ «الان امکان ثبت
نیست؛ کمی بعد دوباره امتحان کنید.» است. در گزارش سؤالها این فراخوانی «سقف ثبت پر
بود» نشان داده میشود.
ثبت لید
رایجترین کار نوشتنی یک ایجنت پشتیبانی این است که نام و شمارهٔ کسی را که میخواهد با او تماس بگیرید ثبت کند. دکمهٔ ثبت لید در صفحهٔ «توابع» این را بیکدنویسی میسازد:
- یک پروژهٔ فعال خودتان را انتخاب کنید.
- جدول را انتخاب کنید: یکی از جدولهای پروژه، یا «جدول تازهٔ leads» که با سه ستون
ساخته میشود:
name(متن، الزامی)،phone(تلفن، الزامی، یکتا) وnote(متن). - برای جدول موجود، بگویید نام، شماره و یادداشت در کدام ستون بروند. نام و یادداشت
ستون متنی میخواهند، شماره ستون تلفن یا متنی؛ سه ستون باید جدا باشند، یادداشت
اختیاری است، و هر ستون الزامی جدول که مقدار پیشفرض ندارد باید یکی از این سه باشد.
جدول
user، جدولهای سیستمی و ستونهای سیستمی و محاسباتی انتخاب نمیشوند. - «پیش از انجام از کاربر تأیید بگیر» پیشفرض روشن است.
فیکارو یک تابع endpoint فعال به نام capture_lead در پروژه میسازد (اگر این نام گرفته
باشد، capture_lead_2 و…) و آن را با اجازهٔ نوشتن به ایجنت وصل میکند. این تابع یکی
از سهمیهٔ توابع پروژه است، هر اجرایش یکی از درخواستهای ماهانهٔ پروژه، و جزو سقف
۳ تابع ایجنت. کد تابع ثابت است و کاری جز این نمیکند:
- رقم فارسی و عربی را لاتین میکند، فاصله و خط تیره را برمیدارد و شمارهٔ ایرانی را
یکدست میکند (
09…میشود+989…). - نام خالی یا بلندتر از ۱۰۰ نویسه، شمارهٔ نامعتبر و یادداشت بلندتر از ۵۰۰ نویسه را با
ctx.rejectرد میکند؛ کاربر «انجام نشد: …» با همان دلیل را میبیند. - یک ردیف میسازد و میگوید «شمارهٔ شما ثبت شد؛ بهزودی تماس میگیریم.». اگر ستون
شماره یکتا باشد و شماره قبلاً ثبت شده باشد، ردیف دوم نمیسازد و ردیف قبلی را هم
دست نمیزند، ولی همان جواب را میدهد (همان
201و همان پیام). ویجت و API را هر کسی میتواند صدا بزند؛ اگر جواب فرق داشت، هر بازدیدکننده میتوانست بفهمد شمارهای در جدول شما هست یا نه.
نگاشت نادرست با 400 invalid_lead_recipe و یک توضیح فارسی رد میشود و اتصالی ساخته
نمیشود. اگر جدول یا تابع ساخته شده باشد و گام بعدی شکست بخورد، همانها در پروژه
میمانند و پیام خطا نامشان را میبرد. لید فقط وقتی ثبت میشود که خود کاربر شماره داده
و ایجنت تابع را صدا زده است. ارجاع به انسان لید ثبت نمیکند: رویداد
ارجاع هیچ دادهٔ تماسی ندارد، و ثبت متن پرسش بدون رضایت کاربر یعنی ذخیرهٔ دادهٔ شخصی.
پنجرهٔ مدل برای توابع
ایجنتی که دستکم یک تابع وصل دارد، در هر پرسش چیزهای بیشتری برای مدل میفرستد (توضیح و پارامترهای توابع و خروجی تابع)، پس مدلی با پنجرهٔ بزرگتر لازم دارد. ایجنت بدون تابع هیچ تغییری نمیبیند و همهٔ مدلهای پلنش را دارد.
- وصل کردن تابع به ایجنتی که مدلش برای این کار کوچک است رد میشود
(
400 model_too_small_for_functions)؛ اول در صفحهٔ «مدل» یک مدل بزرگتر انتخاب کنید. - انتخاب مدل کوچک برای ایجنتی که تابع دارد، و تغییر پلن وقتی ایجنت در پلن تازه با مدلی کوچک جواب میدهد، با همین خطا رد میشوند و چیزی عوض نمیشود.
- API هرگز به این دلیل خطا نمیدهد. اگر سقفها یا مدلهای پلن بعداً طوری عوض شوند که مدل ایجنت برای توابع کوچک شود، پرسش با مدل پیشفرض پلن جواب میگیرد؛ اگر آن هم کوچک باشد، ایجنت آن پرسش را بدون توابع، فقط از دانستهها و جدولها جواب میدهد.
گزارش سؤالها
هر پرسش، از API، ویجت، بله، کد یک فانکشن (ctx.ai.ask) یا میز آزمایش، یک ردیف در
صفحهٔ «گزارش سؤالها» میسازد و منبعش کنار ردیف نوشته شده («فانکشن» برای ctx.ai.ask):
پرسش، جواب، هزینه، queryهای اجراشده، history همراه پرسش (اگر بود) و اینکه جواب
داده شد یا نه.
- گزارشها به اندازهٔ پلن ایجنت نگه داشته میشوند (جدول «پلنها») و بعد پاک میشوند. همین مدت زیر صفحهٔ گزارش هم نوشته شده است.
- کلید، سرآیندها و IP صداکننده ثبت نمیشوند. ولی متن پرسش،
dataوhistoryثبت میشوند — پس دادهٔ شخصی کاربر نهایی را در آنها نفرستید مگر واقعاً لازم باشد. - کنار هر سؤال بیجواب دکمهٔ «افزودن به دانستهها» هست. جواب را همانجا مینویسید و دفعهٔ بعد ایجنت همان سؤال را جواب میدهد.
- نوشتنی که انجام نشد بیجواب حساب نمیشود، چون کمبود دانستهها نیست: «ثبت نشد» (تابع یا کانال نوشتن را رد کرد، یا اجازهاش وسط پرسش برداشته شد)، «سقف ثبت پر بود» و «پس از تأیید انجام نشد». جزئیات ردیف جوابی را که کاربر دید نشان میدهد.
- ردیفی که ارجاع شده نشان «ارجاع شد» دارد، و جزئیات هر جواب میگوید از کدام دانستهها آمده.
SDK
@fikaro/client هنوز ایجنتها را پوشش نمیدهد. صدا زدن ایجنت یک درخواست fetch
ساده است — همان نمونهٔ بالا در بخش «صدا زدن ایجنت».
بیشتر بخوانید
- کار با API — قالب خطا در API پروژهها
- دستیار هوش مصنوعی — ساخت بکاند با هوش مصنوعی، که اعتبار آزمایشیاش با ایجنتها مشترک است