ربط وكيل الذكاء الاصطناعي بأي API بدون كود

يربط منشئ API Action في Quickchat AI وكيل الذكاء الاصطناعي لديك بواجهة REST API من جملة واحدة بلغة إنجليزية بسيطة. تصف API الذي تريد استدعاءه، مثل “ابحث عن حالة تسليم طلب وأخبر العميل متى سيصل”، فيقرأ LLM مزود ببحث ويب وثائق API المباشرة ويجمع إجراءً كاملًا عاملًا، ويملأ الطريقة، وURL، والرؤوس، والمعلمات، والوصف الذي يخبر وكيلك متى يستخدمه. إنه يستشهد بالوثائق التي قرأها، وعندما لا يستطيع تأكيد endpoint حقيقي، فإنه يقول ذلك بدل التخمين.

يبني هذا الدليل إجراءين مباشرين من جملتين مكتوبتين، على حساب مجاني، ويثبت كليهما باستدعاءات حقيقية مسجلة في Inbox. وفي الطريق يشرح ما الذي يفعله استدعاء API فعليًا لوكيلك وما هو “function calling”، الآلية التي تعمل عليها هذه الميزة.

كل ما يلي بُني واختُبر على وكيل حقيقي. كل لقطة شاشة، وحقل منشأ، واستدعاء API من ذلك البناء، ويمكنك إعادة إنتاجها كلها.

النتيجة النهائية: يسأل مسافر عن عطلة نهاية الأسبوع، فيستدعي الوكيل API للطقس أثناء المحادثة ويجيب بأرقام مباشرة.

ما الذي ستبنيه

وكيل دعم لـ Wanderlark Tours، وهي شركة خيالية صغيرة لتنظيم رحلات مشي جبلية في جبال الألب لمجموعات صغيرة، يجيب من معرفته ويستدعي واجهتي API حقيقيتين أثناء المحادثة. يستغرق بناء الاثنين واختبارهما ومشاهدة الاستدعاءات المباشرة نحو خمس عشرة دقيقة:

1. بحث عن توقعات الطقس عبر Open-Meteo، مبني من جملة واحدة. لا يحتاج مفتاحًا، لذلك يمكنك إكماله بحساب Quickchat فقط.
2. صورة اليوم الفلكية من NASA عبر api.nasa.gov، لإضافة مشاهدة النجوم لدى Wanderlark. يحتاج هذا إلى مفتاح API، وهذا سبب وجوده هنا: يعلّم مسار العنصر النائب [[secret]]، حيث يبقى التفعيل محظورًا حتى تلصق مفتاحك.

ستكتب أيضًا جملة يرفض المنشئ بناءها عمدًا، لأن رؤية كيفية فشله جزء من معرفة متى تثق به.

ما تحتاج إليه:

• حساب Quickchat AI مجاني (سجّل هنا).
• لا كود، ولا خادم. للإجراء الثاني، مفتاح NASA API: تشغّل NASA مفتاحًا مشتركًا محدود المعدل DEMO_KEY للتجربة، وهو ما تستخدمه لقطات الشاشة، وتصدر مفاتيح شخصية فورًا في api.nasa.gov.

ماذا يعني أن يستدعي وكيل الذكاء الاصطناعي API؟

الوكيل القادر على استدعاء واجهات API يستطيع جلب أشياء أو تغييرها في أنظمة حقيقية أثناء المحادثة، ثم يجيب بالنتيجة. يستطيع chatbot وصف نشاطك؛ أما الوكيل الذي يستدعي واجهات API فيستطيع العمل داخله.

من جهة المستخدم النهائي، لا يتغير شيء سوى الإجابة. يسأل مسافر “كيف سيكون الطقس في إنترلاكن يوم السبت؟” ويرى مؤشر كتابة لبضع ثوان، ثم ردًا بدرجات حرارة فعلية. لا يرى أداة، أو طلبًا، أو حمولة JSON. تبدو الثانيتان بينهما هكذا:

يرى المسافر سؤالًا وإجابة. بينهما، اختار النموذج إجراءً، وملأ قيمه، وأرسلت Quickchat طلب HTTP حقيقيًا: 280 ms من نحو ثانيتين.

يمكنك حتى ضبط ما يراه الزائر أثناء ذلك التوقف. يمكن لكل إجراء حمل thinking message، وهي سطر قصير تعرضه أداة الموقع بدل “Thinking…” العامة أثناء تشغيل الاستدعاء. يضبط إجراء توقعات Wanderlark واحدًا، لذلك هذا ما يراه المسافر فعليًا أثناء هاتين الثانيتين:

عرض جهة المسافر أثناء الاستدعاء: يلمع سطر التفكير المخصص حيث سيظهر الرد. ستضبط هذا السطر في محرر الإجراء لاحقًا.

لا يخص أي من هذا الطقس وحده. أي نظام يعرّض HTTP API يمكن أن يكون في الطرف الآخر من إجراء: قاعدة بيانات طلباتك، أو نظام حجز، أو CRM، أو أداة تذاكر، أو منصة مراسلة. تجيب عمليات البحث عن الأسئلة ببيانات مباشرة؛ وتغيّر عمليات الكتابة شيئًا وتترك سجلًا.

كل مربع هو طلب HTTP موصوف واحد. يبني هذا الدليل عمليتي بحث منهما؛ وتغطي الأدلة المرتبطة في النهاية أنماط الكتابة.

كانت المشكلة تاريخيًا أن توصيل أحد هذه الأمور كان يعني قراءة وثائق API وملء الطلب يدويًا. هذا الجزء هو ما يزيله المنشئ.

كيف يعمل منشئ الإجراءات باللغة الإنجليزية البسيطة؟

تصف API في جملة واحدة، ويحوّل LLM مزود ببحث ويب مباشر تلك الجملة إلى إجراء كامل. يبحث في وثائق API أثناء الإنشاء، ويصيغ الطريقة، وURL، والرؤوس، ومعلمات الاستعلام، والوصف الذي يخبر وكيلك متى يستدعيه، ويعيد النتيجة مع روابط إلى صفحات الوثائق التي قرأها. يستغرق الإنشاء نحو نصف دقيقة، وتفتح النتيجة في مربع حوار عندما تصبح جاهزة.

لا يرسل المنشئ إلا ما أكده في الوثائق. أي شيء لم يستطع تأكيده يصبح عنصرًا نائبًا أو رفضًا، وليس تخمينًا أبدًا.

ثلاث خصائص تجعله آمنًا للاستخدام:

• لا يعمل شيء حتى تفعّله. يصل كل إجراء منشأ وهو متوقف، لتراجعه.
• المجهولات تصبح عناصر نائبة، لا تخمينات. القيم التي يجب أن يملأها النموذج لكل استدعاء (تاريخ، مدينة) تصبح فراغات {{param}}؛ والثوابت التي تعرفها أنت فقط (مفتاح API) تصبح فراغات [[secret]]، ويُحظر التفعيل حتى تستبدلها.
• يعرض عمله. تسرد النتيجة صفحات الوثائق التي قرأها، ولكل منها ملاحظة عما أكدته تلك الصفحة، لذلك تبدأ المراجعة من الدليل لا من الثقة:

استشهادات من إنشاء ثان للجملة نفسها الخاصة بالطقس المستخدمة لاحقًا في هذا الدليل: صفحة الوثائق إضافة إلى أقسام API فيها، وكل منها مع ما أكده المنشئ هناك.

الخطوة 1: إنشاء وكيل السفر

أنشئ الوكيل أولًا حتى يكون للإجراءات ما تنتمي إليه. بعد التسجيل، سمّ الوكيل (يستخدم هذا البناء Wanderlark) وأعطه مهمته في حقل AI Main Prompt ضمن Identity في لوحة التحكم:

أنت المساعد الخاص بـ Wanderlark Tours، وهي شركة رحلات مشي جبلية في جبال الألب لمجموعات صغيرة. تدير Wanderlark ثلاث رحلات موجهة: Interlaken Classic، وZermatt Highline، وDolomites Traverse، إضافة إلى إضافة مشاهدة النجوم Dark-Sky Nights. ساعد المسافرين على اختيار رحلة، وفهم التواريخ، والأسعار، ومستوى الصعوبة، وما يجب حزمه، وأجب عن أسئلة الحجز والإلغاء. كن ودودًا وعمليًا وموجزًا، واجعل الإجابات قصيرة.

أجب فقط مما تعرفه فعلًا عن Wanderlark. إذا لم تكن لديك معلومة، فقل إنك لا تملكها واعرض وصلهم بفريق Wanderlark بدل التخمين.

ثم أضف بضع حقائق ضمن Knowledge Base حتى يكون لديه ما يجيب منه. يستخدم العرض خمسة مقالات قصيرة (الرحلات والأسعار، وإضافة Dark-Sky Nights، والحجز والإلغاء، والتجهيز، ونقاط الالتقاء)؛ النص الكامل موجود في كتلة النسخ قرب النهاية. نمدد هذا prompt بسطرين خاصين بالإجراءات بعد وجود الإجراءات. إذا أردت شرحًا من الصفر للـ prompts والمعرفة، فإن مقال الوصفة الرئيسي المرتبط أدناه يشرح ذلك خطوة بخطوة.

الخطوة 2: وصف API في جملة واحدة

في الشريط الجانبي، افتح Actions & MCPs، وانقر Add Action، واختر API Action، وهو أول عنصر في القائمة.

توجد الإجراءات المخصصة ضمن Actions & MCPs. يفتح عنصر API Action مربع حوار الوصف.

يطلب منك مربع الحوار الذي يفتح وصف API الذي يجب أن يستدعيه هذا الإجراء، وتسمية endpoint أو ربط وثائقه. هذه هي الجملة الدقيقة لإجراء الطقس:

احصل على توقعات الطقس اليومية لمكان من Open-Meteo API (docs: https://open-meteo.com/en/docs) حتى عندما يسأل مسافر كيف سيكون الطقس في إحدى وجهاتنا، يستطيع الوكيل الإجابة بدرجات حرارة حقيقية واحتمالات مطر للأيام التي سأل عنها.

جملة واحدة: أي API، ورابط وثائق، ومتى يجب أن يستخدمه الوكيل، وما الذي يجب أن يفعله بالنتيجة.

تحمل تلك الجملة الأشياء الثلاثة التي يحتاجها الوصف الجيد:

1. API محدد، أو endpoint، أو URL وثائق. “The Open-Meteo API” مع رابط الوثائق يعطي المنشئ شيئًا حقيقيًا يقرأه. بدونه، تحصل على رفض بدل إجراء.
2. متى يجب أن يستخدمه الوكيل. “عندما يسأل مسافر كيف سيكون الطقس” ينتهي، تقريبًا حرفيًا، في الوصف الذي يشغل الإجراء لاحقًا.
3. ماذا يفعل بالنتيجة. “الإجابة بدرجات حرارة حقيقية واحتمالات مطر” تشكل طريقة استخدام الوكيل للاستجابة.

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

انقر Submit. يغلق مربع الحوار، ويخبرك إشعار بأن الإجراء قيد التحضير، وبعد نحو نصف دقيقة يفتح مربع حوار النتيجة من تلقاء نفسه:

المسار كله في الوقت الحقيقي، مع تقصير الانتظار: اكتب الوصف، أرسل، وراجع ما عاد.

ماذا يوجد داخل الإجراء المنشأ؟

مربع حوار النتيجة سطح مراجعة. على اليسار، بطاقة معاينة للإجراء الجديد، تمامًا كما سيظهر في صفحة Actions. على اليمين، Details: يشرح المنشئ ما بناه، والقيم التي يملؤها النموذج وقت التشغيل، وما افترضه عندما تركت جملتك شيئًا مفتوحًا. في الأسفل، Sources: الوثائق التي قرأها، كروابط.

يشرح المنشئ عمله حقلًا بحقل. عند التمرير في مربع الحوار، يسرد قسم Sources ما قرأه لهذا الإجراء: صفحة وثائق Open-Meteo ومواصفة OpenAPI للمشروع على GitHub، وكل منهما مع ملاحظة عما أكده.

بالنسبة إلى جملة الطقس، أنشأ المنشئ إجراءً اسمه get_open_meteo_daily_forecast (تبدو أسماء المنشئ كأن مهندسًا كتبها؛ يمكنك إعادة التسمية في المحرر). انقر Edit Action في المعاينة لترى كل حقل ملأه:

كل ما يحتويه إجراء مبني يدويًا، وقد مُلئ: الاسم، وجدول المعلمات ضمن “What to ask the user first”، وendpoint.

قراءته من الأعلى إلى الأسفل:

• API Action Name: ما يراه النموذج كاسم الأداة.
• What to ask the user first: جدول المعلمات. أعلن المنشئ سبع معلمات، لكل منها نوع ووصف: latitude، وlongitude، وtimezone، وstart_date، وend_date، إضافة إلى الوحدات الاختيارية. هذه هي قيم {{param}} التي يملؤها النموذج لكل استدعاء. لاحظ ما ليس هنا: لا توجد معلمة “city”. وصل المنشئ endpoint بالطريقة التي يعمل بها Open-Meteo فعليًا، عبر الإحداثيات، وترك الجغرافيا للنموذج. سنراه يملأ تلك الإحداثيات بشكل صحيح بعد قليل.
• API Endpoint: GET https://api.open-meteo.com/v1/forecast، مع توصيل معلمات الاستعلام. تبقى القيم الثابتة حرفية، مثل قائمة daily لمتغيرات التوقعات التي اختارها المنشئ؛ وتظهر القيم التي يملؤها النموذج كشرائح {{...}} ملونة.

تبقى الأجزاء الثابتة ثابتة؛ والشرائح الملونة هي الفراغات التي يملؤها النموذج. الشرائح هي وسيلة الواجهة نفسها لتوضيح مصدر كل شيء.

يشغّل التبويب الرابع في محرر endpoint، Test Response، الطلب الحقيقي قبل أن يقابل الإجراء أي زائر. تحصل كل معلمة على حقل “Your test value”؛ املأها بقيم معقولة، واضغط زر التشغيل (“Test the API”)، وتعود الاستجابة الفعلية مع رمز حالتها. يكشف مفتاح Show cURL، بعبارته، “طلب HTTP الدقيق الذي سيُشغل عندما يعمل AI Action هذا بهذه المعلمات”. هذا اختبار هذا البناء، بإحداثيات إنترلاكن مرة أخرى:

استجابة 200 حقيقية من Open-Meteo، مشغلة من داخل المحرر، مع الطلب المحلول مكتوبًا تحته. راجع، اختبر، ثم فعّل.

• API Action Description: الجملة التي تقرر متى يلجأ الوكيل إلى هذا الإجراء. كتبها المنشئ من عبارة “عندما يسأل مسافر”. هذا الحقل يقوم بأكبر قدر من العمل وقت التشغيل، وهو أول ما تضبطه إذا شغّل الوكيل الإجراء في لحظة خاطئة.
• Thinking message: السطر الذي يراه المسافر من الخط الزمني السابق. يصفه المحرر بأنه “محمل تفكير سيُعرض للمستخدم عند استدعاء هذا الإجراء”؛ يضبط إجراء توقعات Wanderlark قيمته إلى “Checking the live forecast for you…”.

وصل الإجراء متوقفًا. افتحه في المحرر وتعرض Quickchat شريطًا يقول إن الإجراء متوقف، مع زر Enable؛ أو اقلب المفتاح في بطاقته على صفحة Actions. وبما أنه لم يكن هناك شيء لملئه في هذا الإجراء، يتم تفعيله فورًا.

راجع أولًا، ثم شغّل. لا يستدعي أي شيء أي شيء حتى تفعل ذلك.

إذا كنت تفضل بناء هذا الإجراء نفسه يدويًا، حقلًا بحقل، وفهم كل خانة من المبادئ الأولى، فهذا هو الدليل الأساسي: ابنِ وكيل ذكاء اصطناعي مجانيًا يتخذ إجراءات. ينتج المنشئ والمحرر اليدوي النوع نفسه من الإجراءات؛ هذا المقال هو المسار المنشأ.

الخطوة 3: اختبره وشاهد الاستدعاء يحدث

اسأل الوكيل سؤالًا يجب أن يشغّل الإجراء. أُجريت النصوص هنا عبر مسار اختبار Quickchat وسُجلت في Inbox مثل أي محادثة؛ في حسابك، تمنحك لوحة AI Preview في الشريط الجانبي الحلقة نفسها في المتصفح.

رسالة الاختبار:

مرحبًا! سنقوم برحلة Interlaken Classic في عطلة نهاية الأسبوع القادمة. كيف سيكون الطقس في إنترلاكن يوم السبت 25 يوليو ويوم الأحد 26 يوليو؟

أجاب الوكيل بالتوقعات الحقيقية: نحو 27.7°C وشبه بلا أمطار يوم السبت، وأبرد مع احتمال هطول حتى 18 mm من المطر يوم الأحد، إضافة إلى نصائح تجهيز استمدها من معرفته.

الإيصال في Inbox. تحت رد الوكيل توجد علامة “1 action called”؛ وسّعها فتحصل على السجل الكامل لما حدث:

سجل الاستدعاء: get_open_meteo_daily_forecast، وHTTP 200 خلال 280 ms، وكل قيمة ملأها النموذج.

اقرأ المعلمات التي اختارها النموذج: latitude: 46.6863, longitude: 7.8632, timezone: Europe/Zurich, start_date: 2026-07-25, end_date: 2026-07-26. لم يكتب أحد الإحداثيات. قال المسافر “Interlaken”، وترجم النموذج ذلك إلى القيم التي يحتاجها API، بدقة كافية للوصول إلى البلدة. هذا نصف الحكم في النظام وهو يؤدي عمله؛ أما النصف الحتمي (URL، والطريقة، وقائمة متغيرات daily الثابتة) فقد خرج تمامًا كما روجع.

ما هو function calling في وكلاء الذكاء الاصطناعي؟

الإيصال أعلاه صورة للآلية التي تسميها الصناعة function calling: يختار نموذج لغوي، أثناء المحادثة، إصدار استدعاء منظم إلى أداة محددة مسبقًا بدل جملة، وتنفذه المنصة، ويستمر النموذج والنتيجة بين يديه.

Function calling في الاستدعاء الحقيقي لهذا الدليل. لا ينتج النموذج إلا القيم المنظمة؛ تمتلك المنصة الطلب؛ وAPI هو HTTP عادي.

تنتج عن المخطط عدة أمور:

• النموذج يقرر، والمنصة تنفذ. لا يرسل النموذج أبدًا بايتات إلى Open-Meteo. ينتج {"latitude": 46.6863, ...} وتدرج Quickchat تلك القيم في الطلب الذي راجعته. الأجزاء التي ثبتّها، URL، والطريقة، وأي سر، ليست من صلاحية النموذج لتغييرها.
• “Tool calling” هو الشيء نفسه. يصف الاسمان آلية واحدة؛ وtool calling هو المصطلح الأحدث والأعم. AI Action هو تعريف أداة: اسمه، ووصفه، وجدول معلماته هي بالضبط ما يقرأه النموذج عند تقرير ما إذا كان سيستدعيه وكيف. لهذا يهم حقل الوصف كثيرًا. من الناحية المفهومية، يصل التعريف كله الذي يراه النموذج إلى هذا:

name:        get_open_meteo_daily_forecast
description: استخدم هذا الإجراء عندما يسأل مسافر كيف سيكون الطقس في أيام قادمة محددة في وجهة...
parameters:  latitude (number, required), longitude (number, required), timezone (text, required), start_date (text, required), end_date (text, required), temperature_unit (text), precipitation_unit (text)

• جانب API عادي. لم يضف Open-Meteo دعمًا للذكاء الاصطناعي لهذا. أي endpoint يتحدث HTTP ويعيد JSON يمكن أن يكون أداة، وهذا سبب تعميم وصفة الجملة الواحدة على backend الخاص بك.

تدعم كل عائلات النماذج الكبرى هذه الآلية. ما يختلف بين المنصات هو من يكتب تعريفات الأدوات. في منصات المطورين وإجراءات GPT المخصصة، هذا عملك، يدويًا، في مخطط. المنشئ الذي استخدمته في الخطوة 2 هو function calling مع إزالة كتابة المخطط: أصبحت جملتك تعريف الأداة. للرؤية الهندسية لهذا المشهد، من بروتوكولات مثل MCP إلى endpoints مخصصة، راجع APIs لوكلاء الذكاء الاصطناعي: من MCP إلى endpoints مخصصة.

الخطوة 4: API يحتاج إلى مفتاح

تريد معظم واجهات API الحقيقية اعتمادًا. هنا يظهر نوع العنصر النائب الثاني في المنشئ، وتمنحنا إضافة مشاهدة النجوم لدى Wanderlark سببًا طبيعيًا: يحب ضيوف Dark-Sky Nights السؤال عن صورة اليوم الفلكية من NASA.

افتح Add Action، واختر API Action مرة أخرى، وصِفه، وهذه المرة أخبر المنشئ مسبقًا أنك ستقدم المفتاح:

اجلب صورة اليوم الفلكية من NASA من NASA APOD API (GET https://api.nasa.gov/planetary/apod) حتى يتمكن الضيوف المهتمون بإضافة Dark-Sky Nights من السؤال عن صورة الفلك المميزة لهذه الليلة وسماع عنوانها وما تعرضه. سأقدم مفتاح NASA API الخاص بي.

قول “سأقدم مفتاح API الخاص بي” يخبر المنشئ أن يترك فراغًا نظيفًا بدل التخمين في المصادقة.

بعد نصف دقيقة يفتح مربع حوار النتيجة، ويبدو مختلفًا بطريقة مهمة: لوحة كهرمانية بعنوان “Replace before activating”، تسرد شيئًا واحدًا بالضبط: [[nasa_api_key]]. تحمل بطاقة المعاينة شارة Incomplete حمراء، ومفتاح التفعيل فيها متوقف ويبقى متوقفًا.

وصل المنشئ الإجراء كله وترك فراغًا واحدًا لم يستطع ملأه: مفتاحك. حتى تستبدله، لا يمكن تشغيل الإجراء.

في صفحة Actions، يكون المفتاح معطلًا صراحة، مع تلميح يشرح السبب:

يُحظر التفعيل على مستوى المنصة بينما يبقى أي [[secret]]. لا يمكن لإجراء يحتوي عنصرًا نائبًا حيث يجب أن يكون المفتاح أن يفشل الساعة 3 صباحًا، لأنه لا يستطيع العمل.

لنوعي العناصر النائبة مالكان مختلفان:

URL واحد، والنوعان معًا: {{date}} هو فراغ النموذج، يُملأ لكل استدعاء من المحادثة؛ و[[nasa_api_key]] هو لك، تلصقه مرة واحدة.

الآن املأه. تصدر NASA مفاتيح شخصية فورًا (الاسم والبريد الإلكتروني في api.nasa.gov، ويصل المفتاح بالبريد)، وتوثق DEMO_KEY المشترك للتجربة، وهو ما يستخدمه هذا البناء:

1. في بطاقة الإجراء، انقر Edit Action، ثم افتح تبويب Query Params في قسم API Endpoint.
2. يحتوي صف api_key على شريحة [[nasa_api_key]] الكهرمانية. انقر داخل القيمة، واستبدلها بمفتاحك.
3. انقر Save changes.

العنصر النائب قيمة عادية قابلة للتحرير. استبدله واحفظ.

ثم لاحظ ما لم تكن مضطرًا إلى فعله: قلب المفتاح. عندما يجعل حفظ ما إجراء GET للقراءة فقط مكتملًا وصحيحًا لأول مرة، تفعّله Quickchat لك. الإجراءات التي تكتب (POST، PUT، PATCH، DELETE) لا تفعل هذا أبدًا؛ تنتظر تفعيلًا متعمدًا، وهذا هو الافتراضي الصحيح لأي شيء يغير البيانات.

الصق، احفظ، وتفعّل عملية بحث للقراءة فقط نفسها. تترك إجراءات الكتابة القرار النهائي لك دائمًا.

اختبره بالطريقة نفسها مثل التوقعات:

أضفنا إضافة Dark-Sky Nights إلى رحلة Zermatt Highline. ما موضوع صورة الفلك لهذه الليلة؟

جلب الوكيل صورة الليلة، “Shadow and Rainbow”، ولخص ما تعرضه.

والإيصال مرة أخرى، في Inbox:

HTTP 200 من api.nasa.gov. القيمة الوحيدة التي ملأها النموذج هي التاريخ، متروكة فارغة حتى تعود NASA افتراضيًا إلى اليوم. المفتاح غير موجود في هذا السجل: ليس معلمة، لذلك ليس للنموذج أبدًا أن يملأه أو يكشفه.

ماذا يحدث عندما لا يستطيع المنشئ العثور على API؟

لا ينتج المنشئ إجراءً دائمًا، وهذا مقصود. اكتب جملة تصف سلوكًا لكنها لا تسمي API:

دع وكيلي يساعد المسافرين على إعادة جدولة رحلتهم عندما يبدو الطقس سيئًا.

يبحث المنشئ، ولا يجد API واحدًا يستطيع اختياره لك بمسؤولية، ويعود بمربع حوار مختلف: “We need a bit more detail”. لا يُنشأ أي إجراء. تشرح لوحة Details بدقة ما ينقص (أي مزود طقس؟ أي نظام حجز؟) وتعرض إعادة الصياغة، وصولًا إلى جملة مثال فيها endpoint محدد.

رفض مع عدة إصلاح: ما كان غامضًا، ولماذا سيكون التخمين خطأ، ومثال للجملة التي ستعمل.

هناك نوع ثان من الرفض. صِف شيئًا تفعله Quickchat أصلاً بشكل مدمج:

حوّل المحادثة إلى مرشد بشري عندما يبدو المسافر محبطًا أو يطلب التحدث إلى شخص.

يتعرف المنشئ على أن هذا مجال ميزة مدمجة، وبدل تغليف API خارجي حول مشكلة محلولة، يوجهك إلى الميزة، مع زر Set up Human Handoff داخل مربع الحوار نفسه:

ليست كل قدرة يجب أن تكون إجراءً مخصصًا. التصعيد إلى إنسان مدمج، ويوجهك المنشئ إليه بدل تكراره.

الجمل والإعدادات الدقيقة للنسخ

كل ما استخدمه العرض، في مكان واحد. الجملتان اللتان أنشأتا الإجراءات:

احصل على توقعات الطقس اليومية لمكان من Open-Meteo API (docs: https://open-meteo.com/en/docs) حتى عندما يسأل مسافر كيف سيكون الطقس في إحدى وجهاتنا، يستطيع الوكيل الإجابة بدرجات حرارة حقيقية واحتمالات مطر للأيام التي سأل عنها.

اجلب صورة اليوم الفلكية من NASA من NASA APOD API (GET https://api.nasa.gov/planetary/apod) حتى يتمكن الضيوف المهتمون بإضافة Dark-Sky Nights من السؤال عن صورة الفلك المميزة لهذه الليلة وسماع عنوانها وما تعرضه. سأقدم مفتاح NASA API الخاص بي.

AI Main Prompt، بما في ذلك سطرا الإجراءين المضافان بعد وجود الإجراءات. تسمية الإجراءات ولحظات تشغيلها في prompt تجعل التشغيل أكثر موثوقية بوضوح، وأسماء الإجراءات التي يجب استخدامها هي الأسماء المنشأة التي رأيتها في المحرر:

أنت المساعد الخاص بـ Wanderlark Tours، وهي شركة رحلات مشي جبلية في جبال الألب لمجموعات صغيرة. تدير Wanderlark ثلاث رحلات موجهة: Interlaken Classic، وZermatt Highline، وDolomites Traverse، إضافة إلى إضافة مشاهدة النجوم Dark-Sky Nights. ساعد المسافرين على اختيار رحلة، وفهم التواريخ، والأسعار، ومستوى الصعوبة، وما يجب حزمه، وأجب عن أسئلة الحجز والإلغاء. كن ودودًا وعمليًا وموجزًا، واجعل الإجابات قصيرة.

عندما يسأل مسافر كيف سيكون الطقس في وجهة خلال الأيام القادمة، استدع get_open_meteo_daily_forecast وأجب بالأرقام الحقيقية للأيام التي سأل عنها. عندما يسأل ضيف عن صورة الفلك لهذه الليلة أو عما قد يراه في Dark-Sky Night، استدع get_tonights_nasa_apod وصف عنوان الصورة وما تعرضه.

أجب فقط مما تعرفه فعلًا عن Wanderlark. إذا لم تكن لديك معلومة، فقل إنك لا تملكها واعرض وصلهم بفريق Wanderlark بدل التخمين.

API Action Descriptions المنشأة، كما كتبها المنشئ (اضبط هذه، لا URL، عندما يحتاج سلوك التشغيل إلى عمل):

استخدم هذا الإجراء عندما يسأل مسافر كيف سيكون الطقس في أيام قادمة محددة في وجهة، وتحتاج إلى بيانات توقعات يومية حقيقية (درجات الحرارة العليا/الدنيا واحتمال المطر) من Open-Meteo API. يجب أن يستدعي المساعد هذا باستخدام خط عرض/خط طول الوجهة، ونطاق التاريخ، والوحدات المفضلة، ثم يستخدم استجابة JSON لوصف درجات الحرارة المتوقعة واحتمالات الهطول للأيام المطلوبة بلغة طبيعية.

استخدم هذا الإجراء عندما يسأل ضيف عن صورة اليوم الفلكية لهذه الليلة المرتبطة بإضافة Dark-Sky Nights، حتى تتمكن من جلب بيانات APOD الرسمية من NASA ووصف العنوان وما تعرضه الصورة. يستدعي الإجراء NASA APOD API للتاريخ المحدد (ويعود افتراضيًا إلى اليوم إذا لم يُقدَّم تاريخ) ويعيد JSON يتضمن URL الصورة أو الفيديو، والعنوان، والشرح، ونوع الوسائط، مما يجب على المساعد تلخيصه بأسلوب محادثة للضيف.

Thinking message المضبوطة على إجراء التوقعات (السطر الذي تعرضه الأداة أثناء تشغيل الاستدعاء):

Checking the live forecast for you...

مقالات Knowledge Base الخمسة، مختصرة إلى حقائقها:

الرحلات: Interlaken Classic، 3 أيام، سهلة إلى متوسطة، 890 يورو، الحد الأقصى 10 ضيوف، من مايو إلى أكتوبر. Zermatt Highline، 4 أيام، متوسطة إلى صعبة، 1,290 يورو، الحد الأقصى 8، من يونيو إلى سبتمبر. Dolomites Traverse، 5 أيام، صعبة، 1,590 يورو، الحد الأقصى 8، من أواخر يونيو إلى منتصف سبتمبر، من كوخ إلى كوخ. تشمل الأسعار المرشد، والإقامة، ووجبات الإفطار.

Dark-Sky Nights: إضافة مشاهدة نجوم على Zermatt Highline وDolomites Traverse، 120 يورو للشخص، جولة ليلية موجهة مع تلسكوب، مجدولة حول القمر الجديد؛ الجلسات التي تحجبها السحب تُنقل أو تُرد قيمتها.

الحجز: عربون 200 يورو، والرصيد مستحق قبل 30 يومًا من البداية. إلغاء مجاني حتى 30 يومًا؛ استرداد 50 بالمئة من 29 إلى 14 يومًا؛ خلال 14 يومًا لا يوجد استرداد لكن إعادة حجز مجانية واحدة خلال 12 شهرًا.

التجهيز: طبقات، سترة مقاومة للماء، أحذية مستخدمة ومريحة، حقيبة يومية 30 لترًا؛ العصي وcrampons متاحة؛ أمسيات باردة حتى في الصيف.

نقاط الالتقاء: محطة Interlaken Ost؛ محطة Zermatt (بلا سيارات، نقل من Taesch)؛ Cortina d'Ampezzo، نقل من مطار Venice بقيمة 45 يورو لكل اتجاه.

كيف أصف API حتى يفهمه المنشئ بشكل صحيح؟

ثلاث قواعد تغطي كل ما واجهه هذا البناء، ومربع حوار الفشل يعلّم الدرس نفسه من الجهة الأخرى:

النمط وراء كل نتيجة في هذا الدليل: API محدد يدخل، إجراء عامل يخرج؛ سلوك فقط يدخل، إرشاد يعود.

1. سمِّ API، أو endpoint، أو الصق URL وثائق. أنتجت “The Open-Meteo API (docs: …)” إجراءً صحيحًا مستندًا إلى مصدرين مستشهد بهما. أنتجت “إعادة جدولة رحلتهم عندما يبدو الطقس سيئًا” رفضًا، لأنها تسمي رغبة، لا API. يحتاج المنشئ إلى شيء محدد يمكنه قراءته، وهذه هي القاعدة التي تستند إليها القاعدتان الأخريان.
2. قل متى يجب أن يستخدمه الوكيل، وماذا يقول بعد ذلك. تصبح عبارة التشغيل لديك وصف الإجراء تقريبًا حرفيًا، والوصف هو ما يشغّل الإجراء وقت التشغيل. “عندما يسأل مسافر كيف سيكون الطقس” إشارة يستطيع النموذج التعرف عليها أثناء المحادثة.
3. قل كيف ستعمل الاعتمادات، إن وُجدت. جعلت عبارة “سأقدم مفتاح NASA API الخاص بي” المصادقة تُنمذج كـ [[secret]] نظيف. يميل المنشئ أيضًا إلى هذا بنفسه: يفضّل الاعتمادات الثابتة طويلة العمر مثل المفاتيح وwebhook URLs على رموز OAuth قصيرة العمر، لأن الإجراء يعمل كما هو في كل استدعاء، بدون آلية تحديث رموز.

وقاعدة غير لازمة: لا تحتاج إلى تحديد المعلمات، أو التنسيقات، أو حقول الاستجابة. قرأ المنشئ وثائق Open-Meteo واختار سبع معلمات، وافتراضات معقولة، ومتغيرات يومية صحيحة بدون أن يُطلب منه ذلك. راجع ما اختاره في المحرر بدل محاولة إملائه مسبقًا.

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

الإطلاق

لقد أنجز التفعيل ذلك بالفعل. تنتمي الإجراءات إلى الوكيل، لا إلى قناة، لذلك تعمل عمليتا البحث اللتان بنيتهما بالطريقة نفسها من أداة الموقع، وWhatsApp، وMessenger، وSlack، وTelegram، وDiscord، أو أي مكان آخر يُنشر فيه الوكيل، مع تسجيل كل استدعاء في Inbox. إذا كانت أداة الموقع هي القناة الرئيسية، يمكنك استخدام white-label للـ AI chatbot بدون تغيير الإجراء. وينطبق الأمر نفسه على ما لا يستطيع الإجابة عنه: عند سؤاله عن رحلات المشي بالأحذية الثلجية شتاءً، يقول Wanderlark إنه لا يدير أيًا منها، بدل الارتجال.

عندما يُسأل عن شيء خارج معرفته، يقول الوكيل ذلك بدل الارتجال. ينطبق ضبط النفس نفسه على استدعاءات API.

خطوتان طبيعيتان تاليتان بعد تشغيل إجراءاتك الأولى:

• اجعل التشغيل حتميًا حيث يهم ذلك. تحدد أوصاف الإجراءات متى يستدعي النموذج؛ بالنسبة إلى الإجراءات التي يجب أن تعمل فقط في شروط محددة، أضف شروط تشغيل من جانب الخادم والتقاطات ذاكرة: كيف تجعل إجراءات وكيل الذكاء الاصطناعي موثوقة.
• استخدم عمليات التكامل بنقرة واحدة للأدوات التي تمتلكها. تحتوي قائمة Add Action نفسها على الطرق الأخرى: HubSpot Action، وDiscord Action، وGoogle Sheets تأتي كمعارض جاهزة، وShopify MCP يربط كتالوج متجر، وMCP يربط أي خادم MCP بعيد، من كتالوج يضم أكثر من 240 أو URL ملصق، مع استيراد أدوات ذلك الخادم. تشرح الأدلة أدناه المعارض.

ثلاث طرق إلى المكان نفسه، وقاعدة عملية واحدة:

أدلة ذات صلة

• اربط وكيل الذكاء الاصطناعي لديك بـ HubSpot: جهات اتصال، وصفقات، وتذاكر تُكتب أثناء المحادثة، مع نمط أمان للكتابة فقط.
• حوّل وكيل الذكاء الاصطناعي لديك إلى خادم MCP: الشكل العكسي، حيث يستدعي ChatGPT وClaude وCursor وكيلك.
• ابنِ بوت Telegram بالذكاء الاصطناعي لإدارة مجموعتك: ستة إجراءات Bot API مبنية يدويًا مع بوابات إدارية.
• بوت إشراف Discord بالذكاء الاصطناعي: إجراءات إشراف مع أذونات وتفويض منفذين بشكل صحيح.
• بوت تذاكر Discord بالذكاء الاصطناعي: نصف الدعم من المعرض نفسه، يجيب من قاعدة معرفة ويفتح threads تذاكر خاصة.
• اربط وكيل الذكاء الاصطناعي بـ Google Sheets: تكامل التقارير بنقرة واحدة.

الأسئلة الشائعة

كيف أربط وكيل ذكاء اصطناعي بـ API بدون كتابة كود؟

في Quickchat AI، افتح Actions & MCPs، وانقر Add Action، واختر API Action، ثم صِف API في جملة واحدة بلغة إنجليزية بسيطة. يقرأ LLM مزود ببحث ويب مباشر وثائق API وينشئ الإجراء الكامل، بما في ذلك الطريقة، وURL، والمعلمات، والوصف. تراجعه، وتملأ أي قيم بديلة مثل مفتاح API، ثم تفعّله.

ما هو function calling في وكلاء الذكاء الاصطناعي؟

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

هل function calling هو نفسه tool calling؟

نعم. يشير function calling وtool calling إلى الآلية نفسها؛ وtool calling هو المصطلح الأحدث والأعم. AI Action هو إحدى هذه الأدوات: طلب HTTP موصوف يمكن للنموذج اختيار استدعائه أثناء محادثة.

كيف يعرف المنشئ شكل API؟

يشغّل بحث ويب مباشرًا في وثائق API أثناء الإنشاء، ويجمع الإجراء فقط مما استطاع تأكيده هناك. يعرض مربع حوار النتيجة المصادر التي قرأها، حتى تتمكن من فحصها قبل تفعيل الإجراء.

ما الفرق بين العناصر النائبة {{param}} و[[secret]]؟

قيمة {{param}} يملؤها النموذج من المحادثة في كل استدعاء، مثل تاريخ أو مدينة. قيمة [[secret]] ثابت تلصقه مرة واحدة قبل التفعيل، مثل مفتاح API. لا يختار النموذج الأسرار ولا يحررها، وهي ليست معلمات يمكنه ملؤها.

أين أضع مفتاح API، وهل يستطيع زائر استخراجه من الوكيل؟

تستبدل العنصر النائب [[secret]] داخل الإجراء، في المحرر، قبل التفعيل. يصبح المفتاح جزءًا من الطلب الثابت الذي ترسله Quickchat. ليس معلمة، لذلك لا يستطيع النموذج تغييره، ولا يظهر في سجل استدعاء الإجراء في المحادثة.

هل ينشئ المنشئ عمليات بحث GET فقط، أم يستطيع الوكيل كتابة البيانات أيضًا؟

كلاهما. ينشئ مسار الجملة الواحدة نفسه إجراءات POST وPUT وPATCH وDELETE. تفعّل إجراءات GET للقراءة فقط نفسها عندما تكون مكتملة وصحيحة؛ أما إجراءات الكتابة فتنتظر دائمًا أن تفعّلها عمدًا.

هل يمكنه الاتصال بواجهات API خاصة أو داخلية؟

نعم، ما دام endpoint قابلًا للوصول عبر HTTPS من جهة Quickchat. يستند المنشئ إلى الوثائق العامة، لذلك بالنسبة إلى API داخلي صِف endpoint صراحة في جملتك، أو أنشئ قالبًا قريبًا وعدّل URL والحقول في المحرر.

ماذا يحدث إذا وصفت سلوكًا بدل API محدد؟

يفشل المنشئ بشكل مغلق. بدل اختراع endpoint، يشرح ما ينقص ويعرض كيف تعيد الصياغة، عادة بذكر مزود أو endpoint أو URL وثائق محدد. إذا طابق طلبك ميزة مدمجة مثل Human Handoff، فإنه يوجهك إلى تلك الميزة بدل إنشاء إجراء مخصص.

ماذا يحدث إذا فشل استدعاء API أثناء محادثة؟

يرى الوكيل الخطأ ويخبر المستخدم بأنه لم يستطع إكمال البحث بدل اختراع إجابة. يسجل كل استدعاء في المحادثة داخل Inbox مع معلماته ورمز حالة HTTP، حتى تتمكن من رؤية ما أُرسل وما عاد بالضبط.

هل يستطيع ChatGPT أو Claude أو Gemini الاتصال بـ API بهذه الطريقة؟

تدعم نماذجهم كلها function calling، لكن توصيله عمل للمطورين: تكتب مخطط الدالة أو مواصفة OpenAPI بنفسك، كما في إجراءات GPT المخصصة. هنا تكتب جملة واحدة وينشأ الإجراء من وثائق API المباشرة، ثم يعمل على كل قنوات الوكيل. يمكنك أيضًا إتاحة وكيل Quickchat المكتمل إلى ChatGPT وClaude وCursor كخادم MCP.

من أي قنوات يستطيع الوكيل استدعاء API؟

من جميعها. تنتمي Actions إلى الوكيل، لا إلى قناة، لذلك يعمل الإجراء نفسه من أداة الموقع، وWhatsApp، وMessenger، وSlack، وTelegram، وDiscord، وأي مكان آخر يُنشر فيه وكيلك.

هل منشئ الإجراءات باللغة الإنجليزية البسيطة مجاني؟

نعم. إنشاء API Actions ومراجعتها وتفعيلها يعمل في الخطة المجانية، وكلا الإجراءين في هذا الدليل بُنيا على حساب مجاني. تضيف الخطط المدفوعة حدود استخدام أعلى ونماذج أكثر تقدمًا، وليس الوصول إلى المنشئ.

كيف يختار الوكيل بين إجراءات متعددة؟

يقرأ اسم كل إجراء ووصفه ويختار ما يطابق لحظة المحادثة. يحمل وكيل العرض إجراءين: سؤال الطقس يذهب إلى إجراء التوقعات، وسؤال الفلك يذهب إلى إجراء NASA، لأن أوصافهما تسمي تلك المشغلات. الأوصاف الواضحة والمتميزة هي ما يجعل الاختيار موثوقًا.

ما مقدار زمن التأخير الذي يضيفه استدعاء API إلى الرد؟

أقل مما قد تتوقع. عاد استدعاء التوقعات الحقيقي في هذا الدليل خلال 280 ms، داخل رد استغرق نحو ثانيتين من البداية إلى النهاية. يرى الزائر مؤشر تفكير قصيرًا، يمكنك استبداله برسالة تفكير مخصصة، ثم إجابة مبنية على بيانات مباشرة.

الخلاصة

تحولت جملتان مكتوبتان إلى API Actions مباشرين وموثقين ومراجعين: بحث طقس بلا مفتاح وبحث NASA بمفتاح، وكل منهما مثبت بـ HTTP 200 مسجل في Inbox بجانب القيم التي ملأها النموذج. القواعد التي تجعله موثوقًا تتسع في ثلاثة أسطر. سمِّ API حقيقيًا، فيؤسس المنشئ الإجراء في وثائقه ويستشهد بها. أي شيء تعرفه أنت فقط يصل كـ [[secret]] يحظر التفعيل حتى تملأه. أي شيء لا يستطيع المنشئ تأكيده يصبح شرحًا وإعادة صياغة مقترحة، وليس تخمينًا أبدًا.

للحصول على قائمة الحقول الكاملة لـ API Actions، وشروط التشغيل، ومعالجة الاستجابات، أبقِ وثائق AI Actions قريبة أثناء البناء.