عرّف العملية مرة واحدة
حدّد مدخلات الأدوات وربط HTTP ومعالجة الاستجابة في YAML. أرسل كلام المستخدم إلى chat()؛ تختار AGENTO الأداة وتجهّز مدخلاتها.
افهم ملف ConfigAGENTO / AI Agent Runtime
خلّي المستخدم يبحث ويختار وينفّذ طلبه بالمحادثة. AGENTO تحوّل طلبًا واحدًا إلى Flow عبر REST Endpoints تعتمد على بعضها، وتنقل النتائج بين الخطوات وتطلب التأكيد قبل تغيير البيانات.
npm install agento-runtimeNode.js 20.11+ · TypeScript · تعمل داخل الـ Backend
needs_selectionالمنتج قابل للإرجاع. كيف تريد استرداد المبلغ؟
POST /returnsawaiting confirmationمثال محلي للتوضيح. لا تُرسَل طلبات API فعلية.
الـ Endpoints عندك. نظام المصادقة عندك. وقواعد العمل عندك.
الإصدار الموثّق v1.1.001 / لماذا AGENTO؟
اختيار Tool خطوة واحدة. الربط الفعلي يحتاج مدخلات صحيحة، ومعرّفات حقيقية، وحالة للمحادثة، وطريقة لأخذ التأكيد قبل تغيير البيانات.
حدّد مدخلات الأدوات وربط HTTP ومعالجة الاستجابة في YAML. أرسل كلام المستخدم إلى chat()؛ تختار AGENTO الأداة وتجهّز مدخلاتها.
افهم ملف Configعرّف Dependencies متداخلة بين الأدوات. تنفّذ AGENTO الاستعلامات المطلوبة بالترتيب، وتنقل كل نتيجة للخطوة التالية، وتستكمل بعد اختيارات المستخدم.
شاهد معالجة Dependenciesفعّل التأكيد لعمليات الكتابة. يعرض تطبيقك العملية المجهّزة، وتبقى الصلاحيات وقواعد العمل مسؤولية الـ API.
افهم آلية التأكيد02 / طريقة الربط
عرّف العملية في YAML، واضبط نموذج اختيار الأدوات، ثم أرسل كلام المستخدم إلى chat(). تختار AGENTO الأداة، وتستخرج مدخلاتها، وتستدعي الـ API الموجودة عندك.
احتفظ بطريقة HTTP والرابط والمصادقة وأسماء المعاملات التي تستخدمها الـ API عندك.
اختر نموذجًا يدعم الأدوات لدى مزوّدك، ومرّر مفتاحه من بيئة الخادم.
مرّر الرسالة ومعرّف الجلسة وToken المستخدم إلى chat(). اعرض النتائج وتعامل مع طلب المدخلات والاختيارات والتأكيدات في تطبيقك.
تستخدم الطلبات متعددة اللغات الأدوات نفسها. اضبط assistant.language على auto لمتابعة لغة المستخدم، أو على ar أو en لتوجيه الردود للغة محددة.
language: autoاتبع لغة المستخدمlanguage: arوجّه الردود للغة محددةversion: "2"
assistant:
language: auto
models:
routing:
provider: openai
model: YOUR_TOOL_CAPABLE_MODEL
api_key: $ENV:OPENAI_API_KEY
tools:
- id: find-orders
tool:
description: Find the current user's orders by product name.
input_schema:
type: object
properties:
query: { type: string, minLength: 1 }
required: [query]
request:
method: GET
url: https://api.example.com/orders
auth: { type: session }
map:
query:
q: $.query
استبدل رابط المثال واسم النموذج، واضبط OPENAI_API_KEY في بيئة الـ Backend. يستخدم البحث Token مستخدم التطبيق.
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
طلب «أريد إرجاع السماعات» يحتاج أكثر من اسم المنتج. يجب أن تجد الـ API طلب المستخدم، وتحدد المنتج الذي اشتراه، وتعيد خيارات الإرجاع المسموحة. تربط AGENTO هذه الاستعلامات قبل تجهيز طلب الإرجاع.
تعتمد خيارات الإرجاع على المنتج المشترى، ويعتمد تحديد المنتج على طلب المستخدم. تحسم AGENTO الاستعلام الأعمق أولًا، ثم تستكمل العملية التي تعتمد عليه.
يُمرَّر معرّف الطلب إلى استعلام المنتجات، ومعرّف المنتج إلى أهلية وخيارات الإرجاع، والخيار الذي يختاره المستخدم إلى الطلب النهائي.
اطلب الاختيار عندما تطابق النتائج عدة طلبات أو منتجات أو طرق إرجاع. استكمل بنتيجة الـ API المختارة، ثم خذ التأكيد قبل إنشاء طلب الإرجاع.
مقطع داخل 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: $.idorders → items → return options → return requestGET /ordersاستعلام قراءةابحث في طلباته باستخدام Token المستخدم واسم المنتج.
order_id يُمرَّر لاستعلام المنتجاتGET /order-itemsاستعلام قراءةاجلب المنتجات التابعة لهذا الطلب.
item_id يُمرَّر للتحقق من الإرجاعGET /return-optionsاستعلام قراءةاسأل الـ API عن الطرق التي يؤهل لها هذا المنتج.
الخيارات تُعرض للمستخدمneeds_selectionاختياراستخدم الطريقة المختارة من استجابة الـ API.
return_option_id يُمرَّر لطلب الإرجاعneeds_confirmationتأكيداعرض المنتج والطريقة المختارة قبل الإرسال.
تأكيد صريحPOST /returnsالكتابة النهائيةتقبل الـ API الطلب أو ترفضه وفق سياسات المتجر.
النتيجة من استجابة APIEndpoints وقيم للتوضيح. تُنفّذ Dependencies المخصصة للقراءة قبل عملية الكتابة النهائية.
04 / التحكم يبقى داخل تطبيقك
يفهم النموذج الطلب. يحدد ملف Config العمليات المتاحة. وتقرر الـ API إن كان المستخدم يملك صلاحية تنفيذها.
اقرأ عن بنية المكتبةيفهم المقصود ويقترح الـ Tool ومدخلاتها.
تتحقق من المدخلات، وتجلب Dependencies، وتنفّذ طلبات HTTP المحددة في Config.
تتحقق من هوية المستخدم وتفرض الصلاحيات وقواعد العمل.
تحتاج MCP؟ أعد استخدام الأدوات المجهّزة عبر MCP Adapter.
الربط مع MCPقبل ما تبدأ
لا. تعمل AGENTO داخل تطبيقك وتستدعي REST Endpoints الموجودة عندك. تحدد مدخلاتها وطريقة بناء الطلب في config.yml.
نعم. invoke() واجهة مستقلة للعملية التي يعرف تطبيقك مسبقًا أي أداة تنفّذها. واجهة الـ Agent هي chat(): تستقبل رسالة المستخدم وتختار الأداة المضبوطة عبر نموذج Routing.
اقرأ Runtime APIنعم. تستطيع Tool تعريف Dependencies للقراءة، ويمكن لهذه الأدوات أن تعتمد على أدوات أخرى. تحسم AGENTO الخطوات بالترتيب، وتنقل النتائج إلى مدخلات العمليات الأم، وتتوقف للاختيار عند الحاجة، ثم تستكمل وصولًا للعملية النهائية بعد تأكيدها.
افهم Dependency Flowsيوجد دليل منفصل لتوليد AGENTO Config من OpenAPI. تحقق من توفر الميزة في إصدارك، وراجع YAML الناتجة، ثم حمّلها في Runtime المعتاد. المولّد ليس طبقة ضمن Runtime.
اقرأ دليل OpenAPIابنِ على الموجود عندك
اربطه. تحقق من النتيجة. ثم خلّي المستخدم يطلبه بكلامه.