Custom Tools

حالات الاستخدام

الإعداد

الحقول

• الاسم — معرّف للدالة (أحرف، أرقام، شرطات سفلية)، مثل get_order_status. يرى الذكاء الاصطناعي هذا الاسم.
• الوصف — الحقل الأهم. يُخبر الذكاء الاصطناعي متى يستدعي الأداة. كن صريحًا: “استدعِ هذا كلما ذكر العميل رقم طلب. لا تطلب التحقق.”
• عنوان URL لنقطة النهاية — عنوان URL العام بـ HTTPS الذي ستستدعيه Asyntai.
• طريقة HTTP — GET (للقراءة فقط، مُوصى بها) أو POST (يمكنها تغيير البيانات — انظر قسم الأمان أدناه).
• المعاملات — المدخلات التي يستخرجها الذكاء الاصطناعي من المحادثة ويرسلها. لكل منها اسم ونوع ووصف وعلامة إلزامية. بالنسبة إلى GET تُرسل كمعاملات لسلسلة الاستعلام؛ وبالنسبة إلى POST كجسم JSON.
• ترويسة المصادقة (اختيارية) — اسم ترويسة + قيمة تُرسل في كل استدعاء، مثل X-API-Key. استخدم هذا إذا كانت نقطة النهاية الخاصة بك تتطلب مفتاحًا.

مثال تطبيقي: البحث عن حالة الطلب

لنفترض أن متجرك يكشف نقطة النهاية هذه:

GET https://yourstore.com/api/order-status?order_number=10294

…والتي تعيد JSON مثل:

{
  "found": true,
  "status": "Accepted, preparing for shipment",
  "carrier": "DHL",
  "customer_message": "Your order has been accepted and is being prepared for shipment."
}

ستُعدّ أداة على النحو التالي:

• الاسم: get_order_status
• الوصف: “ابحث عن حالة طلب العميل. استدعِ هذا فورًا كلما قدّم العميل رقم طلب — لا تطلب تحققًا إضافيًا. استخدم customer_message المُعاد في ردك.”
• عنوان URL لنقطة النهاية: https://yourstore.com/api/order-status
• الطريقة: GET
• المعامل: order_number (string، مطلوب) — “رقم طلب العميل، عادةً 8 أرقام أو أكثر.”

عندما يكتب العميل “كيف حال طلبي #10294؟”، يستدعي الذكاء الاصطناعي get_order_status(order_number=10294)، وتطلب Asyntai عنوان URL الخاص بك بـ ?order_number=10294، ويجيب الذكاء الاصطناعي باستخدام الاستجابة.

ما تستقبله نقطة النهاية الخاصة بك وما ينبغي أن تعيده

• الطلب: طلب GET بمعاملاتك في سلسلة الاستعلام، أو طلب POST بجسم JSON. تُضمَّن أي ترويسة مصادقة قمت بتكوينها.
• الاستجابة: أعِد JSON (المفضّل) أو نصًا عاديًا. تمرر Asyntai الجسم إلى الذكاء الاصطناعي. الحقل الذي يمكن للذكاء الاصطناعي اقتباسه مباشرة — مثل customer_message — يعمل بشكل جيد.
• غير موجود / أخطاء: أعِد حمولة واضحة (على سبيل المثال كائن JSON يحتوي على found: false و customer_message) كي يتمكن الذكاء الاصطناعي من الرد بصدق بدلًا من التخمين.

اختبار أداتك

تحتوي كل أداة على لوحة مدمجة اختبر هذه الأداة في صفحة التكوين، حتى تتمكن من التحقق من أنها تعمل قبل أن يستخدمها أي عميل — ودون إرسال رسالة عبر الروبوت.

1. أدخل قيمًا تجريبية لمعاملات الأداة (مثل رقم طلب حقيقي).
2. انقر على تشغيل الاختبار. تستدعي Asyntai نقطة النهاية الخاصة بك تمامًا كما يفعل الذكاء الاصطناعي — نفس سلسلة الاستعلام أو جسم JSON، ونفس ترويسة المصادقة، ونفس مهلة الـ 5 ثوانٍ وفحوصات السلامة.
3. سترى النتيجة على الفور: شارة نجاح/فشل، وحالة HTTP، ووقت الاستجابة، وعنوان URL الدقيق الذي استدعيناه، والاستجابة الخام لنقطة النهاية الخاصة بك (منسّقة بشكل مقروء إذا كانت JSON).

يعمل هذا على التعديلات غير المحفوظة أيضًا، لذا يمكنك تعديل عنوان URL أو المعاملات أو ترويسة المصادقة وإعادة الاختبار حتى تعيد ما تتوقعه.

الأمان — اقرأ هذا

• فضّل GET / القراءة فقط. عمليات البحث (حالة الطلب، المخزون، التتبع) آمنة للكشف عنها. ولهذا السبب يُعد GET الخيار الافتراضي.
• POST يتطلب إقرارًا. نظرًا لأن POST يمكنه تغيير البيانات، لا يمكن حفظ أداة POST إلا بعد تحديد مربع اختيار يؤكد أنك المسؤول الوحيد عن تأمين الطلبات وتفويضها على نقطة النهاية الخاصة بك. لا تربط أبدًا عمليات الاسترداد أو الإلغاء أو تغيير كلمات المرور أو نقل الأموال ما لم تتحقق نقطة النهاية الخاصة بك من الطلب بشكل مستقل.
• احترس من التعداد. إذا كان مفتاح البحث قابلاً للتخمين (مثل أرقام الطلبات المتسلسلة)، فاطلب عاملًا ثانيًا — مثل رقم الطلب و البريد الإلكتروني المرتبط بالطلب، وتحقق من تطابقهما — حتى لا يتمكن الزائر من قراءة بيانات عملاء آخرين بتجربة الأرقام.
• لا تثق أبدًا بوسائط الذكاء الاصطناعي. تحقق من صحة كل طلب وفوّضه من جانب الخادم كما لو كان قادمًا من مهاجم مجهول — لأنه قد يكون كذلك فعليًا.

التحقق من الاستدعاءات الحية

بمجرد أن تصبح أداتك حية، يُسجَّل كل استدعاء حقيقي من محادثة. ولكل استدعاء نسجّل اسم الأداة، والوسائط التي أرسلها الذكاء الاصطناعي، وعنوان URL الدقيق الذي طلبناه، وحالة HTTP، والاستجابة، والمدة. يتيح لك هذا تأكيد أن أداة قد أُطلقت في محادثة حقيقية ورؤية ما أعادته نقطة النهاية الخاصة بك، دون التنقيب في سجلات خادمك. (لوحة اختبر هذه الأداة أعلاه مخصصة للتحقق من الإعداد بنفسك؛ أما هذا السجل فيلتقط ما يحدث أثناء محادثات العملاء الفعلية.)

الحدود & الضمانات

• حتى 10 أدوات لكل موقع ويب.
• مهلة 5 ثوانٍ لكل استدعاء؛ والاستجابات محدودة بحد أقصى 10 KB.
• يجب أن تكون نقاط النهاية عناوين URL عامة من نوع http(s). والعناوين الخاصة وعناوين الاسترجاع (loopback) وعناوين الشبكة الداخلية محظورة.
• متاح في خطتي Standard وPro.
• الفوترة: كل استدعاء لأداة يُحتسب كرسالة إضافية في باقتك. الرد العادي يستخدم رسالة واحدة؛ أما الرد الذي يستدعي فيه الذكاء الاصطناعي أداة فيستخدم رسالتين (الرد بالإضافة إلى استدعاء الأداة)، لأن استدعاء الأداة يتطلب طلبًا إضافيًا من الذكاء الاصطناعي.
• إذا فشل استدعاء أداة (مهلة، أو خطأ، أو حظر)، يتم إخبار الذكاء الاصطناعي ويجيب بسلاسة — ولن يتسبب في تعطُّل المحادثة.