مهارة الذكاء الاصطناعي: إجراء طلبات HTTP

أهلية الخطة: متاحة في خطط Advanced وEnterprise وبعض خطط Legacy المنتقاة. الاختبار متاح لجميع المستخدمين، لكن النشر يتطلب خطة مؤهلة.

يتيح الإجراء Make HTTP requests لوكيل الذكاء الاصطناعي استدعاء APIs خارجية أثناء المحادثة. يتيح ذلك لوكيل الذكاء الاصطناعي استرداد بيانات لحظية أو تشغيل إجراءات في أنظمة خارجية بناءً على طلب جهة الاتصال. على سبيل المثال، يمكنه التحقق من حالة الطلب أو استرجاع معلومات الحساب أو إنشاء سجلات في نظام آخر. في هذا المقال، ستتعلم كيفية تكوين مهارة طلب HTTP واختبارها مع وكيل الذكاء الاصطناعي.

وكيل الذكاء الاصطناعي:

1. يقوم بتحليل رسالة جهة الاتصال لتحديد ما إذا كانت تطابق النية المحددة في تعليمات الإجراء الخاصة بك.

2. يجمع أي معلومات مطلوبة.

3. يرسل طلب HTTP.

4. يفسر استجابة API.

5. يرد بشكل طبيعي على جهة الاتصال.

أضف إجراء طلب HTTP

إذا لم تتم إضافة Make HTTP requests إلى وكيل الذكاء الاصطناعي بعد، انقر + Add skill واخترها. ثم اختر + Add action لتكوين أول طلب HTTP. يمكنك إضافة ما يصل إلى 10 إجراءات بهذه الطريقة، كلٌ يستدعي نقطة نهاية مختلفة أو يتعامل مع سيناريو مختلف.

حدد متى يجب تشغيل الإجراء

أعطِ اسمًا وصفيًا للإجراء في حقل Action name .

في حقل When and how should this action be performed? الحقل، صف:

• متى يجب أن يستخدم وكيل الذكاء الاصطناعي هذا الإجراء

• ما الذي يسترده أو يرسله

• أي شروط أو نتائج يجب التعامل معها

مثال:

استخدم هذا الإجراء لاسترجاع حالة طلب جهة الاتصال عندما يسأل عن طلبه. إذا أعاد API خطأ 404، أخبر جهة الاتصال أنه لم يتم العثور على الطلب.

يستخدم وكيل الذكاء الاصطناعي هذا الوصف ليحدد متى يطلق الطلب.

معلومات قد يحتاج إليها وكيل الذكاء الاصطناعي (اختياري)

حدد المدخلات المطلوبة في هذا القسم قبل استدعاء API الخاص بك.

هذه المتغيرات الديناميكية المنظمة التي يجب على الوكيل جمعها. يتم تشغيل الطلب فقط بعد توفر جميع المدخلات المطلوبة.

إذا كانت القيمة:

• مذكورة بالفعل في المحادثة → يستخدمها الوكيل.

• مفقودة → يطلب الوكيلها من جهة الاتصال.

يمكن استخدام المتغيرات التي تم إنشاؤها هنا في تكوين API. متغيرات جهة الاتصال (مثل $contact.email) متاحة تلقائيًا ولا تحتاج إلى إضافتها.

إعدادات الحقل

تكوين الطلب

حدد كيفية استدعاء وكيل الذكاء الاصطناعي لـ API الخاص بك.

يمكنك تكوين:

• طريقة

• URL

• معلمات الاستعلام

• العناوين

• جسم JSON (لـ POST وPUT وPATCH)

الإشارة إلى المتغيرات

يمكنك إدراج المتغيرات في URL أو المعلمات أو العناوين أو الجسم باستخدام $.

هناك نوعان:

• متغيرات جهة الاتصال — حقول جهة الاتصال الموجودة

  • $contact.email

• متغيرات وكيل الذكاء الاصطناعي — الحقول المعرّفة تحت المعلومات التي قد يحتاجها وكيل الذكاء الاصطناعي

  • $agent.order_id

يتم استبدال المتغيرات بقيم حقيقية عند تنفيذ الطلب. إذا كان متغير وكيل الذكاء الاصطناعي المطلوب مفقودًا، سيطلبه الوكيل قبل تشغيل استدعاء API.

كيفية تعامل الوكيل مع استجابات API

مثال على جسم الطلب:

{
  "order_id": "$agent.order_id",
  "email": "$contact.email"
}

يفسر وكيل الذكاء الاصطناعي تلقائيًا استجابة JSON من API ويولّد ردًا طبيعيًا.

مثال لاستجابة API:

{
  "status": "shipped",
  "eta": "2025-12-12"
}

رد الوكيل: "أخبار سارة! تم شحن طلبك ومن المتوقع أن يصل في 12 ديسمبر 2025."

إرسال الصور أو الملفات من استجابة API

إذا تضمنت استجابة API رابط صورة أو ملف صالحًا (مثل مخطط طابق أو فاتورة أو صورة منتج)، يمكن لوكيل الذكاء الاصطناعي إرساله كمرفق مُصوَّر — نفس الآلية المستخدمة لروابط مصدر المعرفة وروابط الإرشادات. انظر إرسال الملفات والصور كمرفقات.

هذا يتطلب تعليمًا صريحًا يجيز ذلك، على سبيل المثال:

أرسل الصورة/الملف كمرفق كلما كان هناك رابط صورة/ملف صالح في استجابة API.

بدون هذه التعليمات، سيستخدم وكيل الذكاء الاصطناعي الرابط فقط في رده النصي — ولن يرسله كمرفق.

الاختبار

يمكنك اختبار إجراء طلب HTTP في لوحة اختبار وكيل الذكاء الاصطناعي قبل النشر.

كيفية إجراء الاختبار

1. ابدأ محادثة اختبارية تتطابق مع شروط الإجراء الخاص بك.

   

2. عندما يتم اكتشاف النية وتكون المدخلات المطلوبة متاحة، ينفّذ وكيل الذكاء الاصطناعي طلب HTTP.

3. يظهر حدث تنفيذ في لوحة الاختبار:

   

   1. {AI Agent name} نفّذ {Action name}

   2. تُعرض الاستجابات 2xx على أنها ناجحة

   3. يُعرض كل رموز الحالة الأخرى على أنها فشل

4. انقر على الحدث لعرض:

   1. علامة التبويب Response (الافتراضي) — جسم الاستجابة الكامل لـ API

   2. علامة التبويب Request — حمولة طلب cURL الكاملة

   3. خيار النسخ للتصحيح

5. بعد تلقي استجابة API، يولّد وكيل الذكاء الاصطناعي ردًا بناءً على البيانات المسترجعة.

ملاحظات هامة

• تظهر أحداث التنفيذ فقط في لوحة اختبار وكيل الذكاء الاصطناعي. لا تظهر في Inbox أو نشاط جهة الاتصال.

• إذا كانت المدخلات المطلوبة مفقودة، سيطلب وكيل الذكاء الاصطناعي منها قبل تشغيل الطلب.

أفضل الممارسات

• كن دقيقًا في وصف الإجراء الخاص بك. التعليمات الغامضة تؤدي إلى تفعيل غير دقيق.

• حدد المدخلات المطلوبة بوضوح. إذا كان على الوكيل أن يطلب شيئًا، اجعل ذلك واضحًا.

• عالج حالات الخطأ في تعليماتك.

• اختبر دائمًا قبل النشر.

• تجنّب تكرار المنطق الذي تتم معالجته بالفعل بواسطة سير العمل ما لم يكن ذلك مقصودًا.

القيود

• حد أقصى 10 إجراءات طلب HTTP لكل وكيل ذكاء اصطناعي.

• الحد الأقصى لكل إجراء:

  • 20 حقلًا لإدخال البيانات

  • 50 معلمة

  • 50 عناوين

• ينتظر وكيل الذكاء الاصطناعي ما يصل إلى 15 ثانية لاستجابة API. إذا استغرقت نقطة النهاية الخاصة بك وقتًا أطول، يفشل الطلب.

• يحدد وكيل الذكاء الاصطناعي متى يستدعي API بناءً على الوصف المكتوب الخاص بك. قد تتسبب التعليمات المكتوبة بشكل ضعيف في تشغيل غير متوقع.

• معالجة استجابة API تلقائية. لا يمكنك تعيين حقول الاستجابة يدويًا — فالوكيل يفسّر JSON سياقيًا.

• تظهر أحداث تنفيذ طلب HTTP فقط في لوحة Test AI Agent وليس في نشاط جهة الاتصال.

• يمكن لوكلاء الذكاء الاصطناعي الصوتي تفعيل إجراء Make HTTP requests. مع ذلك، لا تُعاد استجابة API إلى وكيل الذكاء الاصطناعي الصوتي لتوليد الرد، مما يعني أن المحادثات الصوتية لا يمكنها الاستجابة ديناميكيًا بناءً على نتيجة API.

• إذا قام وكيل الذكاء الاصطناعي بتحديث مجال جهة الاتصال واستخدم ذلك المجال أيضًا في هذا الإجراء ضمن نفس الدور، فإن الطلب يرسل القيمة القديمة (أو فارغة إذا لم تُحدد من قبل) في كل مرة. يحدث هذا بغض النظر عن أي إجراء يتم تنفيذه أولًا. إذا كنت مهتمًا، صوّت لِـطلب الميزة.