حدّد القرار الذي فشل أولًا
قد يفشل الطلب في العثور على الـ Tool، أو اختيارها، أو استخراج الـ Input، أو التنفيذ. لا تعالج كل الحالات بتكبير system prompt.
في كتالوج الحجز، يجب أن يصل «اعرض الأوقات المتاحة» إلى availability، و«احجز غدًا» إلى book، بينما قد لا تحتاج «شكرًا» إلى Tool. أنشئ مجموعة تقييم صغيرة تضم هذه الحالات وإعادة صياغتها ومرادفاتها باللغتين والطلبات الملتبسة. دوّن ID الـ Tool المتوقع وقيم Input المستخدم المتوقعة لكل رسالة.
const runtime = await AgentRuntime.create({
configPath: "./config.yml",
debug: true,
});
const result = await runtime.chat({
sessionId: "routing-check-1",
message: "What times are available tomorrow?",
});
console.log(result.status, result.tool, result.meta, result.debug);
runtime.dispose();
يحتاج مقطع التطبيق هذا إلى AI Model للـ Routing وبيانات اعتماده. يختبر العثور على الـ Tool واستخراج الـ Input، بعكس الأمثلة التي لا تحتاج إلى AI Model.
إذا غابت availability عن المرشحين، حسّن وصفها وتلميحاتها أو افحص حدود recall. وإذا ظهرت لكن فازت Tool أخرى، ميّز بين الوصفين. وإذا اختيرت الـ Tool الصحيحة وغاب التاريخ، افحص Schema وسياق التواريخ النسبية. وإذا فشل invoke() بالـ Input نفسه، فابحث في الإعداد أو API بدل Routing.
افهم كلفة التغيير
قد تسمح إضافة عبارة واضحة ضمن تلميحات الـ Tool بتجاوز استدعاء Semantic Recall بفضل Lexical Retrieval. وقد يقلل تعطيل Semantic Recall الاستدعاءات لكنه يفوّت إعادة الصياغة. أما زيادة candidate limit فتعرض Tools أكثر على الـ AI Model، وقد تصعّب التمييز بين النيات المتقاربة.
إذا تجاوز فهرس Semantic Recall الحد المسموح لحجمه، يتوقف استخدام هذه المرحلة. لا يقسّم AGENTO الفهرس تلقائيًا ليمر على جميع الـ Tools. استخدم retriever انتقائيًا للنطاقات الكبيرة. قارن دقة Selection وmodelRecallCalls قبل التعديل وبعده؛ نجاح prompt واحدة ليس تقييمًا.
يعتمد AGENTO على مسار توجيه هجين، بدل إرسال جميع الـ Tools وتفاصيل تنفيذها إلى الـ AI Model.
المرحلة الأولى: Lexical Retrieval
يبحث LexicalToolRetriever في ID الخاص بالـ Tool وعنوانها ووصفها وعبارات الاستدلال والكلمات المفتاحية، مع مراعاة وزن كل كلمة. يطبّق افتراضيًا Unicode normalization ومعالجة مناسبة للعربية، مثل إزالة التشكيل والتطويل وتوحيد أشكال الألف الشائعة.
إذا كانت المطابقة عبر Lexical Retrieval قوية، يتجاوز AGENTO مرحلة Semantic Recall بالكامل.
المرحلة الثانية: Semantic Recall عند ضعف المطابقة
إذا كانت درجة أفضل نتيجة من Lexical Retrieval أقل من routing.lexical.min_score، فقد يستخدم AGENTO الـ AI Model المحدد للـ Routing لإضافة Tools محتملة عبر Semantic Recall. يختار الـ AI Model الـ IDs من فهرس مختصر للـ Tools.
يحتوي هذا الفهرس على بيانات آمنة فقط، مثل:
id
optional title
description
ولا يتضمن URLs الخاصة بـREST Endpoints، أو إعدادات Auth، أو Mappings، أو بيانات الـ Dependencies، أو حقائق الـ Session، أو Responses API، أو بيانات الاعتماد.
يُتجاوز Semantic Recall إذا تخطى الفهرس الحدود المحددة لعدد الـ Tools أو المحارف. في التطبيقات الضخمة، استخدم ToolRetriever مخصصًا ينتقي المرشحين بدقة.
المرحلة الثالثة: دمج المرشحين
يدمج AGENTO نتائج Lexical Retrieval وSemantic Recall، ويحذف التكرارات، ثم يحتفظ بعدد محدود من الـ Tools المرشحة.
المرحلة الرابعة: اختيار الـ Tool عبر AI Model
لا يرى الـ AI Model إلا تعريفات الـ Tools المرشحة المخصصة له. عليه اختيار Tool مناسبة واحدة أو عدم اختيار Tool، ويستخرج فقط الـ Input المعرّف في الـ Schema والذي قدّمه المستخدم.
يرفض AGENTO:
- اختيار Tool خارج مجموعة المرشحين.
- مفاتيح
argumentsغير المعروفة. - أسماء
argumentsالحساسة. - قيم Input التي تفشل في التحقق الجزئي من Input Schema.
عدم اختيار Tool إجابة صحيحة
إذا لم تناسب الطلب أي Tool وكانت المحادثة مفعّلة، يستدعي AGENTO ConversationResponder بدل إعادة فشل في Routing.
يتيح ذلك تبادلًا طبيعيًا مثل:
User: مرحبا
Assistant: أهلًا! كيف أقدر أساعدك؟
دون اختراع Tool وهمية باسم greeting.
المحادثة ليست تنفيذًا
توضّح تعليمات المحادثة صراحةً أن الرد الحواري وحده لا ينفّذ أي Tool API. لذلك يجب ألا يدّعي الرد إتمام إجراء لم يحدث.
قد تتلقى المحادثة ملخصات آمنة ومحدودة للقدرات، وحقائق قابلة للعرض عن العمل المعلّق، لكنها لا تتلقى بيانات الاعتماد أبدًا.
تعطيل المحادثة والاكتفاء بالـ Routing
assistant:
conversation:
enabled: false
عندها يعيد قرار عدم وجود Tool مناسبة ROUTING_NO_MATCH.
التواريخ والأوقات
يتلقى prompt Routing المنطقة الزمنية الموثوقة للتطبيق والتاريخ المحلي. يمكن تحويل التواريخ النسبية الصريحة، مثل «اليوم» و«غدًا»، إلى YYYY-MM-DD إذا عرّفت الـ Tool حقل تاريخ مناسبًا. وبالمثل، يمكن توحيد الوقت الصريح إلى HH:mm عندما يتطلب حقل الوقت ذلك.
هذا لا يغني عن تقويم عملك أو REST Endpoint للاستعلام عن التوافر؛ فتوحيد التاريخ يفسّر الـ Input، ولا يثبت حقائق العمل.