أضف AI Model للمحادثة

Tool البحث تعمل الآن عبر invoke(): أنت تختار اسمها وتقدّم مدخلاتها. نريد أن يكتب المستخدم طلبه بلغته، فتحدد المكتبة الـ Tool المناسبة وتستخرج مدخلاتها بمساعدة AI Model.

هذا هو دور models.routing. لا تحتاج إلى تغيير request.url أو Mapping لإضافة المحادثة؛ سنستخدم تعريف الـ Tool نفسه الذي نجح مع API.

اختر Provider وAI Model، ثم ضع المفتاح في Environment Variable

يدعم الإصدار الموثّق Providers openai وanthropic وmistral وcohere وollama. اسم الـ Provider يحدد بروتوكول الاتصال، بينما model يحدد الـ AI Model الفعلي في حسابك. لا يكفي كتابة اسم الـ Provider وحده.

أضف هذا القسم إلى جذر config.yml، بجانب version وtools. المثال يستخدم OpenAI؛ استخدم ID لـ AI Model متاح في حسابك ويدعم استخدام الـ Tools.

models:
  routing:
    provider: openai
    model: YOUR_TOOL_CAPABLE_MODEL
    api_key: $ENV:OPENAI_API_KEY
    timeout_ms: 30000

api_key هنا مرجع إلى Environment Variable، وليس المفتاح نفسه. القيمة $ENV:OPENAI_API_KEY تطلب من المكتبة قراءة متغير اسمه OPENAI_API_KEY عند إنشاء Runtime. غيابه يمنع تشغيل إعداد يحتاج إليه.

ضع المفتاح في بيئة الخادم الذي سيشغّل AGENTO. المكتبة لا تقرأ ملف .env تلقائيًا؛ حمّله بآلية مشروعك أو خيار Node المناسب. لا ترسل مفتاح الـ AI Model إلى المتصفح أو تخلطه مع Token الذي تستخدمه API لديك.

timeout_ms: 30000 يحدد مهلة استدعاء الـ AI Model بثلاثين ثانية. هذه ليست مهلة طلب API للـ Tool؛ تلك تُضبط داخل request في الـ Tool.

جرّب رسالة بدل الـ Input الجاهزة

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

const result = await runtime.chat({
  sessionId: authenticatedConversationId,
  message: "ابحث عن خدمات صبغة الشعر",
  presentation: "raw",
});

يفترض هذا المقطع أن runtime موجود في خادمك، وأن authenticatedConversationId Session ID مرتبط بالمستخدم الحالي. إذا كانت الـ Tool تحتاج Token أو context، مرّرهما كما فعلت في الاستدعاء المباشر.

في invoke() كتبت اسم الـ Tool وarguments بنفسك. في chat() ترسل الرسالة، ويختار الـ AI Model Tool من الـ Tools المسموحة ويقترح قيمًا لمدخلاتها. بعدها تطبّق المكتبة قواعد التحقق والـ Mapping نفسها.

افحص result.tool لترى ما إذا اختيرت الـ Tool المتوقعة، وresult.status لتعرف الخطوة التالية. نجاح الرد اللغوي لا يثبت وحده أن HTTP نُفّذ؛ يمكن أن تنتهي تحية مثل «مرحبًا» دون Tool.

افصل فهم الطلب عن صياغة النتيجة

ابدأ بـraw كما في المثال؛ تستطيع اختبار اختيار الـ Tool دون إضافة صياغة لغوية للنتيجة. إذا أردت عرضًا لغويًا، استخدم ai أو both بعد ضبط الـ Response.

يمكنك تعريف models.presentation لاستخدام AI Model مختلف لصياغة النتائج. هذا اختياري؛ عند غيابه تُستخدم إمكانات الـ AI Model الخاص بالـ Routing لصياغة النتائج. وتستخدم المحادثة العامة AI Model لصياغة النتائج افتراضيًا إذا كان موجودًا، وفق assistant.conversation.use_presentation_model.

لا تضف AI Model ثانيًا لمجرد أن القسم متاح. أضفه عندما تحتاج إلى اختلاف واضح في الكلفة أو زمن الرد أو جودة الصياغة.

اختبر اللغة قبل تعديل القدرات المتقدمة

جرّب طلب بحث واضحًا، وصياغة أخرى له، وطلبًا تنقصه معلومة، وتحية لا تحتاج إلى API. إذا فشل invoke() بالقيم نفسها، أصلح التكامل أولًا. وإذا نجح وفشل اختيار الـ Tool من الرسالة، تابع فصل Routing.

بقية هذا الفصل مرجع للـ Providers والـ Adapters المخصصة. لا تحتاج إلى كتابة ModelAdapter كي تبدأ باستخدام Provider مدعوم.

تصف capability flags قدرات فعلية

تحدد nativeTools إمكانية استخدام Native Tool Calling. إذا لم تكن مدعومة، فقد يستخدم AGENTO Structured Output أو JSON يتحقق من صحته. وتصف strictSchema وsystemMessages وtemperature ميزات البروتوكول؛ لا تضمن هذه الخيارات جودة فهم الـ AI Model أو صحة قرارات العمل.

لا تفعّل flags لإخفاء مشكلة تكامل. اختبر اختيار Tool صحيحًا، وقيم Input غير صالحة، وإجابة دون Tool، وإلغاء طلب، وانتهاء مهلة. وعند بناء adapter مخصص، أعد البنية وقيم usage الموثقة؛ سيظل Runtime يتحقق من Selection والـ Input.

IDs الخاصة بالـ Providers المدمجة

تقبل إعدادات AGENTO المدمجة:

• OpenAI
• Anthropic
• Mistral
• Cohere
• Ollama

تختلف القدرات بين Providers والـ AI Models. يصرّح adapter بالميزات التي يدعمها، بدل افتراض أن كل AI Model يدعم كل ميزات البروتوكول.

واجهة تعريف القدرات

interface ModelCapabilities {
  nativeTools: boolean;
  structuredOutput: boolean;
  strictSchema: boolean;
  systemMessages: boolean;
  temperature: boolean;
}

تأخذ native tool calling الأولوية. وعند غيابها، قد يستخدم AGENTO Structured Output أو JSON بديلًا يجري التحقق منه، بحسب القدرات المعلنة.

ملخص سلوك Providers

يصف الجدول سلوك adapters، ولا يضمن أن كل AI Model منشور يدعم جميع الميزات.

ModelAdapter مخصص

الواجهة العامة صغيرة:

interface ModelAdapter {
  capabilities(): ModelCapabilities;
  generateText(request: GenerationRequest): Promise<TextGenerationResult>;
  generateStructured(
    request: GenerationRequest & { schema: JsonSchema }
  ): Promise<StructuredGenerationResult>;
  selectTool(request: ToolSelectionRequest): Promise<ToolSelectionResult>;
}

لتمرير adapter:

const runtime = await AgentRuntime.create({
  config: configObject,
  model: myRoutingModel,
  presentationModel: myPresentationModel,
});

متطلبات adapter

ينبغي أن يحقق adapter المخصص لـ Production ما يلي:

• احترام AbortSignal.
• إعادة بيانات استخدام محدودة الحجم.
• عدم جمع عدة استدعاءات Tools غير مراجعة في إجراء واحد.
• الحفاظ على Schemas الـ Tools التي يراها الـ AI Model.
• إظهار فشل Provider كخطأ، بدل تمرير نص الخطأ ضمن رسالة عادية من المساعد.
• التصريح بوضوح عن القدرات غير المدعومة.

اختبر النشر الفعلي لديك

تتغير بروتوكولات Providers ودعم AI Models. شغّل حالات اختبار Routing والتقييم على IDs الخاصة بالـ AI Models والـ REST Endpoints نفسها التي تنوي استخدامها.