لنفترض أن لديك API للبحث عن الخدمات، وتريد أن يكتب المستخدم «ابحث عن خدمات صبغة الشعر» بدل ملء نموذج بحث. يربط AGENTO بين الواجهتين: يفهم الـ AI Model طلب المستخدم، ثم يتحقق الـ Runtime من القيم وينفّذ عملية HTTP التي تسمح بها إعدادات الـ Config.
المكتبة تعمل داخل خادم تطبيقك. لا تستبدل API الموجودة لديك، ولا تجعل الـ AI Model مسؤولًا عن بناء أي عنوان يريده أو تقرير صلاحيات المستخدم.
ماذا تضيف المكتبة إلى تطبيق يعمل أصلًا؟
عندما تستدعي API مباشرةً، يحدد كودك العملية والقيم التي سترسلها. مع AGENTO تستطيع وصف العمليات المتاحة مرة واحدة في config.yml، ثم السماح للـ AI Model باختيار المناسب منها واستخراج مدخلاته من كلام المستخدم.
كل عملية متاحة تسمّى Tool. قد تستدعي Tool البحث Endpoint واحدة، بينما تحتاج Tool الحجز إلى جلب المواعيد المتاحة أولًا. الـ Tool هي تعريف لعملية، وليست AI Model جديدًا أو بالضرورة خدمة مستقلة.
الـ Runtime هو كائن AgentRuntime الذي ينشئه خادمك. يحتفظ بالـ Config وحالة المحادثة، ويتحقق من الـ Input، ويدير Selection وConfirmation، وينفّذ HTTP. وعند إضافة chat()، يتولى الـ AI Model فهم اللغة.
يبقى تطبيقك مسؤولًا عن تسجيل الدخول، وتحديد الـ Session التي تخص المستخدم، وعرض النتائج والأسئلة. وتبقى API مسؤولة عن صلاحية الوصول وقواعد العمل وحفظ التغييرات.
تتبّع طلب بحث واحدًا
يكتب المستخدم «ابحث عن صبغة الشعر». يختار الـ AI Model الـ Tool المسماة search-services ويضع عبارة البحث في query. يتحقق الـ Runtime من أن القيمة نص صالح.
ينقل الـ Mapping المكتوب بصيغة q: $.query هذه القيمة إلى Query Parameter باسم q في الـ API. يتلقى تطبيقك الـ Response، ويمكنه عرض البيانات مباشرة أو طلب صياغتها بلغة طبيعية.
كل جزء يحل مشكلة مختلفة. وصف الـ Tool يساعد على اختيار العملية. وinput_schema يحدد قيم Input المقبولة. وrequest.map يحدد كيف تتحول الـ Input إلى HTTP. لذلك لا يكفي وصف ممتاز إذا كان اسم الحقل المرسَل إلى API خاطئًا.
ابدأ بـ invoke() وحدد الـ Tool والـ Input بنفسك. بعد نجاحها، استخدم chat() ليحدد الـ AI Model هذه القيم من رسالة المستخدم. تبقى عملية HTTP المحددة في الـ Config كما هي.
اتبع هذا المسار للمرة الأولى
- ثبّت المكتبة في مشروع الخادم.
- اربط Endpoint فعلية. جهّز
api-context.md، واكتب أول إعداد، ثم قارنه بطلب يعمل لديك. - افهم بنية
config.yml. اعرف ما يخص الـ Tool وما يخص التشغيل كله، ومتى تضيف كل قسم. - عرّف الـ Input، ثم اربطها بطلب HTTP، ثم اضبط الـ Response.
- أضف AI Model للمحادثة، وافهم اختيار الـ Tools، ثم تعامل مع نتائج التشغيل في واجهتك.
بعد هذه الخطوات يكون لديك تكامل قراءة مفهوم من كلام المستخدم حتى Response API. لا يلزم قراءة إعدادات التخزين المخصص وMCP قبل الوصول إليه.
متى تحتاج إلى أكثر من Tool؟
إذا قال المستخدم «احجز غدًا»، فهو يحدد التاريخ، لكنه لا يعرف الـ ID الداخلي للموعد المتاح. تجلب Dependency هذا الـ ID من الـ API، وتطلب من المستخدم اختيار موعد إذا وجدت عدة مواعيد.
بعد معرفة الموعد، يبقى الحجز عملية تغيّر البيانات. لذلك نجهّز معاينة وConfirmation قبل إرسال POST. ثم يجمع مثال الحجز هاتين الخطوتين في تجربة مستقلة لاختبار السلوك. هذا المثال تمرين إضافي، وليس شرطًا لربط API لديك.
أما عرض فئات ثم فتح منتجات الفئة المختارة، فستجده في Navigation بين الـ Tools.
استخدم بقية الفصول عند حاجتك إليها
عند ربط المكتبة بخادمك، راجع دوال Runtime وAuth والـ Sessions. عند تجهيز الإطلاق، انتقل إلى التعامل مع أعطال HTTP والمراقبة والاستعداد لـ Production.
إذا فشلت تجربة، ابدأ بـتشخيص المشكلة، ثم استخدم مرجع الأخطاء للرمز الذي حصلت عليه. بقية الفصول مراجع ترجع إليها؛ ليست واجبات يجب إنهاؤها بالترتيب.
المصطلحات التي ستتكرر
API contract هو وصف الـ Request والـ Response والـ Auth والقيود الخاصة بالـ Endpoint. تستمده من توثيق نظامك وطلباته الفعلية.
Schema تحدد شكل البيانات المقبول. تصف input_schema الـ Input الذي تقبله الـ Tool، وتُستخدم output_schema للتحقق من الـ Response.
Mapping يربط مصدر قيمة بوجهتها. لا يشغّل JavaScript داخل YAML، ولا يمرّر تلقائيًا كل ما أنتجه الـ AI Model.
Dependency هي Tool توفر بيانات تحتاجها Tool أخرى. المقصود هنا علاقة بين Tools، وليس حزم npm التي يعتمد عليها المشروع.
Session تحفظ حالة المحادثة والخطوات المعلّقة. الـ ID الخاص بها لا يثبت هوية المستخدم؛ خادمك هو المسؤول عن ربطها بصاحبها.
تصف هذه الصفحات الحزمة العامة agento-runtime@1.0.0. رقم إصدار الحزمة منفصل عن إصدار صيغة الـ Config التي تبقى version: "2". راجع التثبيت قبل تشغيل الأوامر.