انتقل إلى المحتوى

AGENTO / AI Agent Runtime

الـ API عندك جاهزة؟حولها لـ Agent.

خلّي المستخدم يبحث ويختار وينفّذ طلبه بالمحادثة. AGENTO تحوّل طلبًا واحدًا إلى Flow عبر REST Endpoints تعتمد على بعضها، وتنقل النتائج بين الخطوات وتطلب التأكيد قبل تغيير البيانات.

npm install agento-runtime

Node.js 20.11+ · TypeScript · تعمل داخل الـ Backend

مثال تفاعليreturns.flow
المستخدم

بدي أرجع السماعات من آخر طلب إلي.

AGENTOneeds_selection

المنتج قابل للإرجاع. كيف تريد استرداد المبلغ؟

خطوات التنفيذ
  1. البحث عن طلب المستخدم
  2. تحديد المنتج الذي اشتراه
  3. التحقق من أهلية وخيارات الإرجاع
  4. 04انتظار طريقة الاستردادبانتظارك
  5. 05انتظار التأكيد
  6. 06إنشاء طلب الإرجاع
POST /returnsawaiting confirmation

مثال محلي للتوضيح. لا تُرسَل طلبات API فعلية.

الـ Endpoints عندك. نظام المصادقة عندك. وقواعد العمل عندك.

الإصدار الموثّق v1.1.0

01 / لماذا AGENTO؟

بنيت الـ API. تبقّى منطق تشغيل الـ Agent.

اختيار Tool خطوة واحدة. الربط الفعلي يحتاج مدخلات صحيحة، ومعرّفات حقيقية، وحالة للمحادثة، وطريقة لأخذ التأكيد قبل تغيير البيانات.

عرّف العملية مرة واحدة

حدّد مدخلات الأدوات وربط HTTP ومعالجة الاستجابة في YAML. أرسل كلام المستخدم إلى chat()؛ تختار AGENTO الأداة وتجهّز مدخلاتها.

افهم ملف Config

ابنِ Flows عبر عدة Endpoints

عرّف Dependencies متداخلة بين الأدوات. تنفّذ AGENTO الاستعلامات المطلوبة بالترتيب، وتنقل كل نتيجة للخطوة التالية، وتستكمل بعد اختيارات المستخدم.

شاهد معالجة Dependencies

راجع العملية قبل تغيير البيانات

فعّل التأكيد لعمليات الكتابة. يعرض تطبيقك العملية المجهّزة، وتبقى الصلاحيات وقواعد العمل مسؤولية الـ API.

افهم آلية التأكيد

02 / طريقة الربط

ابدأ بـ Endpoint واحدة.

عرّف العملية في YAML، واضبط نموذج اختيار الأدوات، ثم أرسل كلام المستخدم إلى chat(). تختار AGENTO الأداة، وتستخرج مدخلاتها، وتستدعي الـ API الموجودة عندك.

  1. 01

    عرّف الـ Tool

    احتفظ بطريقة HTTP والرابط والمصادقة وأسماء المعاملات التي تستخدمها الـ API عندك.

  2. 02

    اضبط نموذج اختيار الأدوات

    اختر نموذجًا يدعم الأدوات لدى مزوّدك، ومرّر مفتاحه من بيئة الخادم.

  3. 03

    أرسل رسالة المستخدم

    مرّر الرسالة ومعرّف الجلسة وToken المستخدم إلى chat(). اعرض النتائج وتعامل مع طلب المدخلات والاختيارات والتأكيدات في تطبيقك.

افهم لغة المستخدم. واضبط لغة الرد.

تستخدم الطلبات متعددة اللغات الأدوات نفسها. اضبط assistant.language على auto لمتابعة لغة المستخدم، أو على ar أو en لتوجيه الردود للغة محددة.

language: autoاتبع لغة المستخدم
language: arوجّه الردود للغة محددة
إعدادات اللغة والمساعد
اتبع دليل الربط
runtime.mjsESM / Node.js
import { AgentRuntime } from "agento-runtime";
 
// Create once when your backend starts.
const runtime = await AgentRuntime.create({
  configPath: "./config.yml",
  presentation: "raw",
});
 
// The user message to the agent.
const clientMessage = "Find my headphone order";
// AGENTO selects find-orders and extracts its inputs.
const result = await runtime.chat({
  sessionId: `user-${user.id}`,
  auth: {
    token: user.accessToken,
  },
  message: clientMessage,
});
 
console.log(result);

يأتي user من نظام المصادقة في الـ Backend عندك. تستخدم chat() نموذج Routing في config.yml لاختيار الأداة، وتفرض الـ API صلاحيات المستخدم.

03 / DEPENDENCY FLOWS

طلب واحد. Flow عبر عدة Endpoints.

طلب «أريد إرجاع السماعات» يحتاج أكثر من اسم المنتج. يجب أن تجد الـ API طلب المستخدم، وتحدد المنتج الذي اشتراه، وتعيد خيارات الإرجاع المسموحة. تربط AGENTO هذه الاستعلامات قبل تجهيز طلب الإرجاع.

كل Dependency ممكن تعتمد على غيرها

تعتمد خيارات الإرجاع على المنتج المشترى، ويعتمد تحديد المنتج على طلب المستخدم. تحسم AGENTO الاستعلام الأعمق أولًا، ثم تستكمل العملية التي تعتمد عليه.

نتيجة كل خطوة تصبح مدخلًا للتالية

يُمرَّر معرّف الطلب إلى استعلام المنتجات، ومعرّف المنتج إلى أهلية وخيارات الإرجاع، والخيار الذي يختاره المستخدم إلى الطلب النهائي.

توقّف للاختيار، ثم استكمل الـ Flow

اطلب الاختيار عندما تطابق النتائج عدة طلبات أو منتجات أو طرق إرجاع. استكمل بنتيجة الـ API المختارة، ثم خذ التأكيد قبل إنشاء طلب الإرجاع.

شاهد تعريف Dependency

مقطع داخل request-return. يعرّف المثال الكامل أيضًا اعتماد return-options على order-items، واعتماد order-items على find-orders، مع المصادقة وطلب HTTP وMapping لكل أداة.

# On the request-return tool:
depends_on:
  - tool: return-options
    arguments:
      query: $.query
    select:
      items_path: $.options
      id_path: $.id
      label_path: $.label
      id_sensitive: true
      facts:
        item: $.item_name
        method: $.label
    map:
      $.return_option_id: $.id
مثال على ترتيب التنفيذorders → items → return options → return request
  1. 01
    GET /ordersاستعلام قراءة

    ابحث عن طلب المستخدم

    ابحث في طلباته باستخدام Token المستخدم واسم المنتج.

    order_id يُمرَّر لاستعلام المنتجات
  2. 02
    GET /order-itemsاستعلام قراءة

    حدّد المنتج الذي اشتراه

    اجلب المنتجات التابعة لهذا الطلب.

    item_id يُمرَّر للتحقق من الإرجاع
  3. 03
    GET /return-optionsاستعلام قراءة

    اجلب خيارات الإرجاع المسموحة

    اسأل الـ API عن الطرق التي يؤهل لها هذا المنتج.

    الخيارات تُعرض للمستخدم
  4. 04
    needs_selectionاختيار

    اترك طريقة الاسترداد لاختياره

    استخدم الطريقة المختارة من استجابة الـ API.

    return_option_id يُمرَّر لطلب الإرجاع
  5. 05
    needs_confirmationتأكيد

    اعرض الطلب وانتظر التأكيد

    اعرض المنتج والطريقة المختارة قبل الإرسال.

    تأكيد صريح
  6. 06
    POST /returnsالكتابة النهائية

    أنشئ طلب الإرجاع

    تقبل الـ API الطلب أو ترفضه وفق سياسات المتجر.

    النتيجة من استجابة API

Endpoints وقيم للتوضيح. تُنفّذ Dependencies المخصصة للقراءة قبل عملية الكتابة النهائية.

04 / التحكم يبقى داخل تطبيقك

المستخدم يطلب. أنت تحدد ما يمكن تنفيذه.

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

اقرأ عن بنية المكتبة
  1. 01

    النموذج عندك

    يفهم المقصود ويقترح الـ Tool ومدخلاتها.

  2. 02

    AGENTO

    تتحقق من المدخلات، وتجلب Dependencies، وتنفّذ طلبات HTTP المحددة في Config.

  3. 03

    الـ API عندك

    تتحقق من هوية المستخدم وتفرض الصلاحيات وقواعد العمل.

تحتاج MCP؟ أعد استخدام الأدوات المجهّزة عبر MCP Adapter.

الربط مع MCP

قبل ما تبدأ

إجابات عملية.

هل أحتاج أعيد بناء الـ Backend؟

لا. تعمل AGENTO داخل تطبيقك وتستدعي REST Endpoints الموجودة عندك. تحدد مدخلاتها وطريقة بناء الطلب في config.yml.

هل أقدر أستدعي Tool مباشرة؟

نعم. invoke() واجهة مستقلة للعملية التي يعرف تطبيقك مسبقًا أي أداة تنفّذها. واجهة الـ Agent هي chat(): تستقبل رسالة المستخدم وتختار الأداة المضبوطة عبر نموذج Routing.

اقرأ Runtime API
هل يمكن لطلب واحد المرور بعدة Endpoints؟

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

افهم Dependency Flows
عندي ملف OpenAPI، هل أستفيد منه؟

يوجد دليل منفصل لتوليد AGENTO Config من OpenAPI. تحقق من توفر الميزة في إصدارك، وراجع YAML الناتجة، ثم حمّلها في Runtime المعتاد. المولّد ليس طبقة ضمن Runtime.

اقرأ دليل OpenAPI

ابنِ على الموجود عندك

ابدأ بطلب API حقيقي واحد.

اربطه. تحقق من النتيجة. ثم خلّي المستخدم يطلبه بكلامه.