أنشئ Config من OpenAPI

استخدم وصف OpenAPI الموجود لديك لإنشاء إعداد أولي لـ AGENTO. يقرأ المولّد ملف JSON أو YAML محليًا، ويحوّل العمليات المدعومة إلى Tools، ثم يتحقق من الإعداد الناتج. راجع الملف قبل تشغيله على API لديك.

التوليد خطوة لتجهيز الإعدادات. لا يستدعي API أو AI Model. يحمّل AgentRuntime ملف Config الذي راجعته، ولا يحتاج إلى OpenAPI أثناء التشغيل.

تحقق من توفر الميزة

يوثق هذا الدليل المولّد الموجود في PR تنفيذ OpenAPI. تحتاج إلى إصدار من agento-runtime يحتوي أمر agento-openapi ومدخل agento-runtime/openapi. الميزة ليست ضمن إصدار 1.0.0 الذي توثقه بقية صفحات الموقع.

بعد تثبيت إصدار يحتوي المولّد، تحقق من وجود الأمر في المشروع:

npm install agento-runtime
npx --no-install agento-openapi --help

إذا لم يتوفر الأمر، راجع npm ls agento-runtime وملاحظات الإصدار. إعادة تثبيت 1.0.0 لا تضيف الميزة. يمنع --no-install محاولة تنزيل حزمة أخرى تحمل اسم الأمر.

جهّز ملف المصدر

استخدم openapi.json أو openapi.yaml محليًا يصف API الفعلية. الإصدارات المدعومة هي OpenAPI 3.0.x و3.1.x. لا يُقبل Swagger 2.0 أو OpenAPI 3.2.

إذا لم يكن مشروع Express أو Next.js يحتوي وصف OpenAPI، ابدأ بدليل تجهيز ملف OpenAPI. يمكنك الاستعانة بالـ Routes والـ Schemas وأمثلة API بعد إزالة الأسرار لتجهيز الوصف. مولّد AGENTO لا يفحص كود التطبيق لإنشائه.

يصف ملف openapi.yaml القابل للتنزيل التالي عملية قراءة عامة. النطاق api.example.com للتوضيح. استبدل العنوان والمتطلبات بما يطابق API لديك قبل تنفيذ أي طلب.

openapi: 3.0.3
info:
  title: Services API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /services/{id}:
    get:
      operationId: getService
      summary: Get a service
      description: Return the details of an existing service by its identifier.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
        - name: locale
          in: query
          schema:
            type: string
            enum: [en, ar]
      responses:
        '200':
          description: Service details

ضع operationId فريدًا لكل عملية؛ يستخدمه AGENTO معرّفًا للـ Tool. إذا غاب، يشتق المولّد معرّفًا من الطريقة والمسار. يفشل التحويل عند تعارض الأسماء أو عدم صلاحيتها. يجب أن تبدأ معرّفات Tools وأسماء المدخلات المرتبطة بحرف إنجليزي أو underscore، وأن تتكون من حروف إنجليزية أو أرقام أو underscores أو hyphens، وبطول لا يتجاوز 64 حرفًا. تُرفض أسماء المدخلات المتعلقة ببيانات الاعتماد أو prototype.

ولّد مسودة منفصلة

شغّل CLI من مجلد المشروع:

npx --no-install agento-openapi openapi.yaml --output config.generated.yml

يمكن أن يكون المصدر openapi.json أيضًا. الخيار --output مطلوب. يجب أن يكون مجلد الإخراج موجودًا وأن يكون اسم الملف جديدًا. يرفض المولّد الكتابة فوق Config سبق أن راجعته.

ينتج الأمر config.generated.yml للمثال السابق. افحصه، ثم احفظ النسخة التي راجعتها باسم config.yml. القيمة version: "2" تخص صيغة إعداد AGENTO، وهي مستقلة عن إصدار OpenAPI وإصدار حزمة npm.

تُكتب التحذيرات والأخطاء إلى stderr. تتضمن النتيجة الناجحة REVIEW_REQUIRED؛ وهو تذكير بالمراجعة، وليس فشلًا في التحويل. يعيد الأمر exit code يساوي 1 عند فشل القراءة أو parsing أو التحويل أو التحقق أو الكتابة. لا تنتج أخطاء التحويل Config جزئيًا.

حدد عنوان الخادم

عنوان الخادم هو عنوان الـ Backend API لديك، مع بادئة مشتركة مثل /v1 أو /api إن وُجدت. هذا هو العنوان الذي سيستدعيه AGENTO بعد مراجعة Config الناتجة وتشغيلها. وهو مستقل عن عنوان موقع توثيق AGENTO وعنوان مزوّد AI Model.

إذا كان Endpoint موجودًا على https://api.example.com/v1/services/42، فقسّم العنوان إلى عنوان خادم ومسار عملية:

يبقى {id} في Config؛ ويملؤه Runtime من ربط Path الذي راجعته عند استدعاء Tool. لا تكرر البادئة في الجزأين: خادم ينتهي بـ /v1 مع مسار /v1/services/{id} ينتج /v1/v1/services/{id}.

عرّف عنوان Backend في المصدر داخل servers. الجزء التالي يوضّح إعداد الخادم فقط؛ أبقِ العمليات الموجودة في ملف OpenAPI الكامل:

servers:
  - url: https://api.example.com/v1

لتوليد مسودة لبيئة أخرى دون تعديل المصدر، استخدم --base-url:

npx --no-install agento-openapi openapi.yaml --output config.staging.yml --base-url https://staging.example.com/v1

يكتب الأمر https://staging.example.com/v1/services/{id} في الطلب الناتج. يتجاوز الخيار جميع تعريفات الخوادم، بما فيها التعريفات الخاصة بعمليات منفردة. إذا كانت العمليات موزعة على Backends مختلفة، فتحقق من كل عنوان ناتج قبل استخدام تجاوز عام. الخيار المقابل في JavaScript هو generateConfig(source, { baseUrl: "https://staging.example.com/v1" }).

دون التجاوز، يختار المولّد خادمًا لكل عملية على حدة: أولًا servers على مستوى العملية، ثم المسار، ثم جذر الملف. إذا عُرّف مستوى صراحةً بقائمة servers: []، فلن يرجع إلى المستوى الأعلى. يجب أن تحتوي القائمة المستخدمة خادمًا واحدًا فقط؛ لا يختار المولّد أول خادم تلقائيًا عند وجود عدة خوادم.

استخدم عنوان HTTP(S) مطلقًا دون بيانات اعتماد مضمنة أو Query parameters أو Fragment أو متغيرات لم تُحل. استخدم HTTPS في Production. لا يرسل المولّد طلب شبكة، ولا يثبت إمكانية الوصول إلى العنوان أو تطابق المسارات مع API. راجع قيم request.url الناتجة واختبر Config المراجعة على البيئة المطلوبة.

يُحفظ العنوان في YAML وقت التوليد. تعديل خادم OpenAPI لاحقًا لا يغيّر Config موجودة أو Runtime قيد التشغيل. ولّد ملفًا مرشحًا منفصلًا، وقارنه بـ Config التي راجعتها، ثم انشر التغييرات المراجعة وفق خطوات تحديث وصف API دون فقد إعداداتك المراجعة.

راجع Tools الناتجة

في المثال السابق، يحتوي الطلب الناتج الجزء التالي:

request:
  method: GET
  url: https://api.example.com/v1/services/{id}
  auth:
    type: none
  map:
    path:
      id: $.path.id
    query:
      locale: $.query.locale
    headers: {}
    body: {}

هذا جزء من الإعداد، وليس Config كاملًا. يحتوي الملف القابل للتنزيل أيضًا Input Schema وسياسة السلوك.

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

لا يستنتج المولّد إعدادات Models أو Dependencies أو Selection وNavigation أو Routing hints أو Output Schemas. أضفها عبر خيارات Config والاستجابات وربط خطوات العمل. لا تُنسخ Response Schema الموجودة في OpenAPI إلى response.output_schema.

تعطي HTTP method سياسة أولية لأثر العملية، ولا تثبت سلوك API. راجع أي GET تغيّر حالة التطبيق. تتطلب عمليات الكتابة الناتجة تأكيدًا، لكن preview تكون فارغة أولًا؛ أضف معلومات مفهومة للمستخدم عبر إعدادات التأكيد.

شغّل Config بعد المراجعة

احفظ مثال run.mjs بجانب config.yml الذي راجعته:

import { AgentRuntime } from "agento-runtime";

const id = process.argv[2];
if (!id) throw new Error("Usage: node run.mjs <existing-service-id>");

const runtime = await AgentRuntime.create({
  configPath: "./config.yml",
  presentation: "raw",
});
try {
  const result = await runtime.invoke({
    sessionId: "openapi-example",
    tool: "getService",
    arguments: { path: { id }, query: { locale: "en" } },
  });
  console.log(JSON.stringify(result, null, 2));
  if (result.status !== "completed") process.exitCode = 1;
} finally {
  runtime.dispose();
}

node run.mjs EXISTING_SERVICE_ID

استخدم معرّفًا موجودًا في API لديك، وقارن النتيجة مع طلب مباشر. تتوافق كائنات path وquery المتداخلة مع مجموعات المدخلات التي أنشأها المولّد؛ إرسال { id: "123" } وحده لا يطابق هذه Tool. يُحل مسار Config النسبي من مجلد تشغيل process. ضمّن Config المراجع ضمن ملفات نشر الخادم.

لا يحتاج هذا الاستدعاء المباشر إلى Model. لاستخدام chat() باللغة الطبيعية، جهّز Model للمحادثة، أو مرّر model adapter عند إنشاء Runtime. في التطبيق، اربط sessionId بالمستخدم وتعامل مع حالات المتابعة كما يشرح دليل النتائج. معرّف Session الثابت في هذا المثال القصير لا يصلح استراتيجية لإدارة جلسات تطبيقك.

اضبط المصادقة

تتحول HTTP bearer security إلى request.auth.type: session. مرّر token المستخدم الموثّق عبر auth.token في طلبات Runtime. لا يحصل المولّد على token ولا يتحقق منه. تبقى صلاحيات الوصول مسؤولية API.

تحتاج API key في Header إلى اسم متغير بيئة صريح:

npx --no-install agento-openapi openapi.yaml --output config.generated.yml --api-key-env CatalogKey=CATALOG_API_KEY

يجب أن يطابق CatalogKey الاسم الموجود في components.securitySchemes، وليس اسم HTTP Header. أما CATALOG_API_KEY فهو اسم متغير بيئة في الخادم، وليس قيمة المفتاح السرية. تلزم قيمة المفتاح عند بدء Runtime، ولا تلزم للتوليد. كرر --api-key-env عند استخدام عمليات مختلفة لتعريفات مفاتيح مختلفة.

تعطّل security: [] داخل العملية إعداد المصادقة الموروث. لا يدعم المحوّل Basic أو OAuth/OIDC أو API keys في Cookie أو Query أو البدائل المتعددة أو الجمع بين Security Schemes. لا تحذف متطلبات المصادقة الحقيقية حتى ينجح التحويل. عند استخدام آلية غير مدعومة، جهّز التكامل وفق عقد المصادقة المعتاد.

تتطلب الطلبات التي تحمل بيانات اعتماد HTTPS. إذا احتجت HTTP للتجربة المحلية، يجب أن يكون السماح به صريحًا في Config المراجع؛ لا يوفر المولّد خيارًا لتفعيله.

المدخلات المدعومة وحدودها

لا يدعم multipart/form-data أو form-encoded bodies أو scalar/array bodies أو GET/HEAD bodies أو object parameters أو CSV query arrays أو deepObject أو allowReserved: true أو allowEmptyValue: true. تشمل خصائص Schema غير المدعومة composition مثل allOf وanyOf وoneOf، وdefaults، وboolean schemas، وحقول Input ذات readOnly: true، وcustom formats، وكلمات dialect الحديثة في JSON Schema. لا يدعم كذلك OPTIONS أو TRACE أو callbacks أو webhooks.

مثلًا، يمكن تعريف JSON body مدعومة لعملية POST كالتالي:

requestBody:
  required: true
  content:
    application/json:
      schema:
        type: object
        additionalProperties: false
        required: [name]
        properties:
          name:
            type: string
            minLength: 1

لا يستطيع mapper الأصلي إرسال JSON object فارغة أو حفظ حقول غير محددة في المستوى الأول من body. لذلك يرفض المحوّل Schemas التي تسمح بهذه الحالات. لا تشدد Schema الموثقة إلا إذا كانت هذه القيود تصف فعلًا العملية التي تريد إتاحتها. استخدم Config يدويًا للحالات خارج نطاق التحويل عندما يستطيع mapper تمثيلها؛ أما الحالات التي لا يدعمها mapper نفسه فتحتاج تعديل تكامل HTTP أو قدرة تنفيذ إضافية.

تُحذف Numeric formats مثل int32 وint64 بوصفها annotations؛ عرّف الحدود صراحة عند الحاجة. لا تتحول الأمثلة أو XML metadata أو vendor extensions أو تعديلات summary/description على Reference إلى سلوك تنفيذي. لا يثبت إنشاء OpenAPI أو تحويلها أن API المنشورة تطبق العقد الموثق.

عالج أخطاء التحويل

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

استخدم JavaScript API

يوفر المدخل الاختياري agento-runtime/openapi الدالة generateConfig(source, options). نزّل generate-config.mjs:

import { readFile, writeFile } from "node:fs/promises";
import { generateConfig } from "agento-runtime/openapi";

const result = generateConfig(await readFile("openapi.yaml", "utf8"));
for (const diagnostic of result.diagnostics) {
  console.error(diagnostic);
}
if (!result.ok) {
  process.exitCode = 1;
} else {
  await writeFile("config.generated.yml", result.yaml, { flag: "wx" });
}

الخياران الاختياريان هما baseUrl وapiKeyEnv، مثل { baseUrl: "https://api.example.com/v1", apiKeyEnv: { CatalogKey: "CATALOG_API_KEY" } }.

عند النجاح تحتوي النتيجة ok: true وconfig وyaml وdiagnostics. عند الفشل تحتوي ok: false وdiagnostics، دون Config أو YAML. يحتوي كل تشخيص severity وcode وpath وmessage. تستقبل الدالة نصًا ولا تقرأ أو تكتب ملفات، ولا تستدعي شبكة أو Model.

حدّث وصف API دون فقد إعداداتك المراجعة

احفظ ملف المصدر وConfig المراجعة في version control. بعد تغيير عقد API، ولّد ملفًا جديدًا مثل config.candidate.yml، وقارنه مع config.yml، ثم ادمج التغييرات المقصودة. لا يوفر CLI وضع overwrite أو append أو merge تلقائي.

احتفظ بإعدادات Model وConfirmation previews وResponse Schemas وDependencies والعرض عند مراجعة الفرق. اختبر العمليات المتأثرة على staging، ثم انشر Config المراجعة مع إصدار حزمة محدد. لا تعِد التوليد تلقائيًا عند بدء التطبيق. تابع الاستعداد لـ Production.