التثبيت من npm

في الإصدارات التي تحتوي agento-openapi، يمكنك إنشاء Config من OpenAPI. يوثق دليلها هذه الميزة الاختيارية بصورة مستقلة عن خطوات تثبيت 1.0.0 أدناه.

AGENTO حزمة ESM تعمل على الخادم. استخدم npm لإضافة المكتبة إلى تطبيقك، وGitHub لقراءة المصدر والإبلاغ عن المشاكل والمساهمة. استنساخ المستودع ليس خطوة مطلوبة لتثبيت المكتبة داخل التطبيق.

المتطلبات وتوافر الإصدار

تتطلب الحزمة العامة agento-runtime إصدار Node.js 20.11 أو أحدث. يشرح هذا الدليل الإصدار العام v1.0.0. أما version: "2" داخل config.yml فهي إصدار صيغة الـ Config ولا ترتبط برقم إصدار حزمة npm.

التحقق من التوافر: افحص الحزمة وdist-tags في سجل npm قبل التثبيت. إذا ظهر E404 فهذا يعني أن الحزمة أو الإصدار المطلوب غير متاح في السجل، وليس خطأ في الـ Config.

node --version
npm --version
npm view agento-runtime version dist-tags

١. أضف الحزمة إلى تطبيقك

npm install agento-runtime

٢. استخدم ESM import

داخل ملف .mjs، أو تطبيق TypeScript معدّ لاستخدام ESM:

import { AgentRuntime } from "agento-runtime";

إذا استخدمت ملفات .js، أضف "type": "module" إلى package.json الخاص بتطبيقك. شغّل المكتبة داخل Node backend، وليس في كود المتصفح.

٣. حمّل config.yml مرة عند بدء التطبيق

أنشئ config.yml من دليل أول Tool. اسم الملف اختياري؛ يقرأ Runtime المسار الذي تمرّره له.

import { AgentRuntime } from "agento-runtime";

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

يُحسب المسار النسبي من مجلد العمل الحالي للعملية التي تشغّل تطبيقك. ضمّن YAML في ملفات النشر، أو مرّر configYml كنص أو config ككائن. استخدم خيارًا واحدًا فقط من هذه الخيارات الثلاثة.

يُحلّل الإعداد كاملًا ويُتحقق منه عند الإنشاء. المفاتيح غير المعروفة، والـ Mapping غير الصحيح، والـ Dependencies غير الآمنة، وغياب مفاتيح الاعتماد المطلوبة، والكتابة دون Confirmation، كلها تفشل بدء التشغيل. عالج الخطأ أثناء بدء تشغيل التطبيق، ولا تبدأ استقبال الطلبات بالـ Runtime غير صالح.

احتفظ بنسخة Runtime لكل process وإعداد ثابت. مرّر sessionId المصرّح به وauth.token وcontext وإشارة الإلغاء عند كل عملية. استدعِ dispose() عند الإغلاق لإيقاف مؤقت تنظيف بيانات الاعتماد.

٤. أضف البيانات الحساسة عندما تحتاجها الميزة

لا يحتاج invoke() المباشر مع العرض الخام إلى مفتاح AI Model. عند تفعيل AI Model، يكون مفتاح YAML مرجعًا إلى Environment Variable:

# Root fragment; use a model ID supported by your account.
models:
  routing:
    provider: openai
    model: YOUR_TOOL_CAPABLE_MODEL
    api_key: $ENV:OPENAI_API_KEY

ضع القيمة في بيئة الخادم أو secret manager. وللتطوير المحلي:

# Bash
export OPENAI_API_KEY="your-development-key"

# PowerShell
$env:OPENAI_API_KEY = "your-development-key"

لا يحمّل AGENTO ملف .env تلقائيًا. استخدم آلية framework لديك، أو خيار Node المسمّى --env-file. لا تحفظ المفاتيح الحقيقية في المستودع.

يستخدم API key الخاص بالخدمة request.auth.env: SERVICE_KEY دون بادئة $ENV:. أما access Token الخاص بالمستخدم فيمر عبر auth في الاستدعاء. هذه ثلاث قنوات مختلفة؛ راجع Auth.

٥. انتقل إلى أول طلب فعلي

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

تحتاج طلبات HTTP التي تحمل بيانات اعتماد إلى HTTPS، ما لم تسمح صراحةً بالنقل المحلي عبر request.allow_insecure_http: true. لا تستخدم إعداد التطوير هذا في Production.

ساهم عبر GitHub

لتطوير المكتبة نفسها، استنسخ KhALiLXD/agento، وثبّت Dependencies التطوير، وشغّل الاختبارات. هذا المسار لتعديل المكتبة. أما مطوّر التطبيق فيثبّت الحزمة من npm ويضبط config.yml الخاص به.