اربط API لديك

إذا كانت API لديك موثقة بصيغة OpenAPI، يمكنك استخدام مولّد OpenAPI مسارًا بديلًا لتجهيز Config عندما يحتويه الإصدار المثبّت. راجع الناتج قبل متابعة تكامل Runtime.

لديك API تعمل بالفعل، وتريد أن يستطيع مساعد استخدام إحدى عملياتها. هذه البداية تأخذك من طلب تعرف أنه يعمل إلى Tool ينفّذها AGENTO، مع فهم دور كل جزء في config.yml. لن تحتاج إلى إنشاء خادم تجريبي أو تغيير backend.

ما الذي ستخرج به؟ ملف api-context.md يصف API ويمكن نقله إلى أي AI Model، وملف config.yml لـ Tool واحدة، وطلب حقيقي يمكنك مقارنة نتيجته باستدعاء API المباشر.

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

١. اختر عملية تعرف كيف تستدعيها

اختر Endpoint للقراءة لا تغيّر البيانات، مثل البحث عن خدمات أو عرض منتجات. جرّبها بعميل HTTP الذي تستخدمه عادةً، مثل curl أو Postman، واحتفظ بالطلب الناجح وعينة استجابته بعد إزالة البيانات الحساسة.

لا تبدأ بعملية حجز أو دفع أو حذف. لهذه العمليات خطوة Confirmation سنشرحها بعد أن تتضح العلاقة بين الـ Input وطلب HTTP.

دوّن أربع معلومات من API لديك: method، والعنوان الكامل، والحقول المطلوبة ومكانها، وطريقة Auth.

لا تغيّر أسماء حقول API لتطابق المثال في هذا الدليل.

سنشرح Mapping بمثال Endpoint بحث يقبل GET /services?q=hair. المسار واسم q مجرد مثال للتفسير؛ العنوان YOUR_API_HOST يجب استبداله بعنوانك، وقد تكون عمليتك /products?search=phone أو Endpoint مختلفًا تمامًا

٢. حوّل توثيق API إلى ملف يمكن إعادة استخدامه

إذا كنت تعرف متطلبات الـ API، اكتبها بنفسك وانتقل إلى الخطوة التالية. وللاستعانة بـ AI Model، زوّده بملف OpenAPI أو توثيق الـ Endpoints أو تعريفات الـ Routes، مع أمثلة Request وResponse بعد إزالة البيانات الحساسة.

افتح prompt تحليل API، وأرسله مع المصادر إلى الـ AI Model الذي تستخدمه. سيطلب منه إنتاج api-context.md؛ لن يطلب منه تخمين config.yml من اسم المشروع.

الملف الناتج يجب أن يجيب عن هذه الأسئلة:

• ما العملية التي سنربطها أولًا، وما فائدتها للمستخدم؟
• ما الحقول التي يستقبلها الطلب، وأيها مطلوب؟ هل تأتي في path أم query أم body؟
• من يملك كل قيمة؟ هل يقولها المستخدم، أم يوفرها خادمك، أم تعيدها Endpoint أخرى؟
• هل تحتاج العملية إلى Bearer Token للمستخدم أم API key للخدمة؟
• ما شكل الـ Response والأخطاء الموثقة؟ وما المعلومات التي ما زالت ناقصة؟

راجع الملف قبل استخدامه. إذا وصف الـ AI Model حقلًا بأنه مطلوب، ابحث عن دليل ذلك في توثيق الـ API. وإذا لم يعرف اسم حقل، اتركه UNKNOWN بدل استخدام تخمينات. رؤية id في التقرير لا تكفي للقول إنه دائمًا موجود أو إنه الـ ID المناسب لعملية أخرى.

يمكنك البدء أيضًا من قالب api-context.md إذا أردت كتابته يدويًا.

احفظ الملف مع مشروعك بعد إزالة البيانات الحساسة. لاحقًا تستطيع إعطاءه لنموذج مختلف بدل إعادة شرح API من البداية. AGENTO نفسه لا يقرأ هذا الملف؛ إنه وثيقة للمطوّر ولمساعدته في إعداد YAML.

٣. أنشئ Tool واحدة، ثم افهم ما كتبته

يمكنك كتابة الإعداد بنفسك باستخدام الشرح أدناه، أو إعطاء الـ AI Model api-context.md مع prompt إنشاء الإعداد ومرجع AGENTO القابل للإرفاق. يجمع المرجع شرح الـ Input والـ Mapping وAuth وبقية الإعدادات الأساسية؛ لا يحتاج الـ AI Model إلى معرفة محتوى محادثة سابقة.

اطلب ملفًا كاملًا لـ Tool واحدة. لا تبدأ بتحويل جميع Endpoints دفعة واحدة؛ إذا فشل الطلب، نريد أن يكون مصدر الخطأ محددًا.

لنفترض أن Endpoint فعلًا يطابق مثال البحث العام دون مصادقة. يصبح الملف التالي نقطة البداية. غيّر العنوان، والمسار، والحقول، وAuth لتطابق Endpoint قبل تشغيله:

version: "2"

assistant:
  name: Agento #Your agent's name
  language: auto
  timezone: UTC
  system_prompt: |
     Help users find and book appointments using the available tools.
      Do not invent availability or claim a booking before it completes.


models:
  routing:
    provider: openai
    model: gpt-5.6-luna
    api_key: $ENV:OPENAI_API_KEY
    temperature: 0

tools:
  - id: search-services
    tool:
      description: Search available services by the user's search phrase.
      input_schema:
        type: object
        properties:
          query:
            type: string
            minLength: 1
        required: [query]
    request:
      method: GET
      url: https://YOUR_API_HOST/services
      auth:
        type: none
      map:
        query:
          q: $.query

اقرأ الملف من الخارج إلى الداخل. version: "2" يحدد صيغة إعداد AGENTO، وليس إصدار API لديك. تحت tools قائمة؛ كل عنصر فيها يصف عملية متاحة للمساعد. أضفنا عنصرًا واحدًا وسمّيناه search-services.

قيمة id هي الاسم الداخلي الذي تختاره للـ Tool. سنستخدمه عند استدعاء invoke()، ويجب أن يكون فريدًا. لا يشترط أن يكون نفس اسم route في backend.

داخل tool نضع ما تحتاج المكتبة إلى معرفته عن العملية ومدخلاتها. يشرح description متى تصلح الـ Tool؛ يستفيد منه الـ AI Model عندما نضيف المحادثة. لكنه لا ينشئ طلب HTTP ولا يحدد اسم query parameter.

تحدد input_schema أن الـ Tool تقبل كائنًا يحتوي الحقل query كنص مطلوب وغير فارغ. اخترنا query اسمًا للـ Input داخل AGENTO، بينما تستخدم الـ API الاسم q. يربط request.map بين الاسمين.

داخل request نحدد التنفيذ الفعلي. method وurl يأتيان من Endpoint API. وauth.type: none صحيح فقط إذا كانت العملية لا تحتاج لمصادقة. تغيير الوصف في tool لا يغيّر هذا العنوان أو طريقة الطلب.

ربط Input الـ Tool بالـ API

يستخدم request.map.query لربط Input الـ Tool بالـ query parameters التي يستقبلها الـ API.

q: $.query

تعني:

• q هو اسم الـ parameter في الـ API.
• $.query هي القيمة المأخوذة من Input الـ Tool.

فإذا كانت الـ Input:

{ "query": "hair" }

سيتم إرسال:

GET /services?q=hair

ببساطة: اليسار هو اسم الحقل في الـ API، واليمين هو مصدر قيمته من Input الـ Tool.

لم نضف output_schema أو سياسة Retry. يتضمن ملف المثال إعدادًا اختياريًا للـ AI Model من أجل chat()؛ لا يحتاج invoke() مع presentation: "raw" إلى AI Model. إذا أبقيت قسم models في الملف، فوفّر مفتاحه المطلوب عند إنشاء الـ Runtime. هدف التجربة الأولى هو التأكد من طلب HTTP الفعلي. بعد نجاحه، سنضبط التحقق من الـ Response وفق شكل الـ Response الذي تحققت منه.

٤. اضبط Auth

يتم تحديد نوع Auth لكل Tool داخل request.auth.

إذا كانت الـ Endpoint عامة:

auth:
  type: none

فلا تحتاج إلى Access Token للمستخدم.

إذا كانت الـ Endpoint تعمل بصلاحيات المستخدم الحالي:

auth:
  type: session

في هذه الحالة، لا يتم تخزين الـ Access Token داخل config.yml. تطبيقك يمرّر Token المستخدم الحالي وقت تنفيذ الطلب:

{
  sessionId: `user:${user.id}`,
  auth: {
    token: user.accessToken,
  }
}

هذان الحقلان لهما وظيفتان مختلفتان:

sessionId   → يحدد جلسة المستخدم داخل AGENTO
auth.token  → يصادق المستخدم مع الـ API لديك

القيم user.id وuser.accessToken تأتي من تطبيقك ونظام Auth لديك. AGENTO لا يسجل دخول المستخدم ولا ينشئ Access Token.

مثلًا، في تطبيق ويب قد تحصل على المستخدم الحالي من الطلب:

const user = req.user;

ثم تمرر بياناته إلى AGENTO:

const request = {
  sessionId: `user:${user.id}`,
  auth: {
    token: user.accessToken,
  },
};

استخدم sessionId ثابتًا للمحادثة نفسها عندما تريد الحفاظ على سياق الـ Session.

صيغة user:${user.id} في المقاطع التوضيحية أدناه وأعلاه تحتاج إلى التكييف مع التطبيق: لا يقبل التنفيذ المرجعي المحرف : في Session ID. استخدم ID يديره الخادم ويتوافق مع الصيغة المقبولة، واربطه بالمستخدم الذي جرى التحقق من هويته.

إذا كانت الـ Tool المختارة تستخدم:

auth:
  type: none

فلا تحتاج إلى تمرير auth.token.

مفاتيح الخدمة الثابتة

بعض الـ APIs تستخدم مفتاحًا ثابتًا يخص التطبيق نفسه، وليس مستخدمًا محددًا.

في هذه الحالة استخدم:

auth:
  type: api-key
  env: $ENV:SERVICE_KEY
  header: X-API-Key

في مثال مفتاح الخدمة أعلاه، استخدم اسم Environment Variable وحده في env؛ بادئة $ENV: الظاهرة فيه تخص إعداد مفتاح الـ AI Model، ولا تطابق إعداد مفتاح الخدمة في التنفيذ المرجعي.

SERVICE_KEY هو اسم Environment Variable الذي يحتوي مفتاح الخدمة؛ يقرأه request.auth.env دون بادئة $ENV:. أما مفتاح الـ AI Model فيستخدم صيغة مثل $ENV:OPENAI_API_KEY. يقرأ AGENTO القيم من بيئة العملية، ولا يحمّل ملف .env تلقائيًا؛ حمّله بآلية تطبيقك كما يشرح دليل التثبيت.

الفرق باختصار:

session   → بيانات مصادقة ديناميكية للمستخدم الحالي
api-key   → بيانات مصادقة ثابتة للتطبيق أو الخدمة
none      → بدون مصادقة

٥. أرسل رسالة إلى AGENTO

أنشئ الـ Runtime مرة واحدة عند تشغيل تطبيقك:

import { AgentRuntime } from "agento-runtime";

const runtime = await AgentRuntime.create({
  configPath: "./config.yml",
  presentation: "raw",
});

بعدها أعد استخدام نفس الـ Runtime مع الطلبات القادمة بدل إنشاء واحد جديد لكل رسالة.

دع AGENTO يختار الـ Tool

عند إعداد AI Provider، استخدم chat() في الاستخدام الطبيعي للـ Agent:

const result = await runtime.chat({
  sessionId: `user:${user.id}`,
  auth: {
    token: user.accessToken,
  },
  message: "ابحث عن خدمات الشعر",
});

ترسل رسالة المستخدم بدل تحديد الـ Tool وarguments بنفسك. وتستمر في تمرير sessionId وبيانات Auth المطلوبة كما في المثال.

بعدها يتولى AGENTO الباقي:

رسالة المستخدم
      ↓
فهم الطلب
      ↓
اختيار الأداة
      ↓
جمع المدخلات
      ↓
تنفيذ طلب الـ API

لا تحتاج إلى تحديد search-services بنفسك.

إذا كانت الـ Tool التي اختارها AGENTO تستخدم:

auth:
  type: session

فسيستخدم auth.token الممرر مع الطلب عند الاتصال بالـ API.

أما إذا كانت الـ Tool عامة، فيمكن أن يكون الاستدعاء أبسط:

const result = await runtime.chat({
  sessionId: `user:${user.id}`,
  message: "ابحث عن خدمات الشعر",
});

تشغيل Tool مباشرة

أحيانًا يكون تطبيقك يعرف مسبقًا أي Tool يريد تشغيلها. في هذه الحالة استخدم invoke():

const result = await runtime.invoke({
  sessionId: `user:${user.id}`,
  auth: {
    token: user.accessToken,
  },
  tool: "search-services",
  arguments: {
    query: "hair",
  },
});

invoke() يتجاوز مرحلة اختيار الـ Tool بالـ AI ويشغل الـ Tool التي حددتها مباشرة.

٦. اقرأ النتيجة بدل افتراض النجاح

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

إذا كانت needs_input، فهناك مدخل مطلوب لم تقدمه. افحص missing، ثم قدّم قيمة الـ Input المطلوبة في الاستدعاء التالي. جرّب حذف query لترى هذا السلوك؛ لا ينبغي إرسال طلب بحث ناقص.

إذا كانت error، اقرأ error.code وerror.message. غياب مدخل مطلوب يختلف عن وجود مدخل من النوع الخطأ. مثلًا، { "query": 15 } يخالف Schema النصية. أما AUTH_REJECTED فيعني مراجعة Auth، وليس إعادة تسمية الـ Input.

إذا لم تصل إلى النتيجة أصلًا وفشل create()، فالمشكلة في تحميل الإعداد أو التحقق منه، مثل عنوان غير صحيح أو Environment Variable مفقود. راجع أول رسالة خطأ قبل تعديل عدة خيارات معًا.

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

٧. حدّد الخطوة التالية حسب ما نجح

تنتهي هذه البداية عندما ترسل الـ Tool الطلب المتوقع إلى API لديك، وتفهم مصدر كل قيمة، وتستطيع تفسير نجاحه أو فشله. لا تحتاج إلى ربط النظام كله كي تصل إلى هذه النقطة.

انتقل إلى فهم config.yml لتعرف كيف توسّع الإعداد دون نسخ خيارات لا تحتاجها. ثم اقرأ الـ Input وMapping والـ Response. بعد نجاح الطلب المباشر، أضف الـ AI Model ليحوّل كلام المستخدم إلى استدعاء للـ Tool نفسها.