افهم config.yml

يمكنك كتابة Config يدويًا أو استخدام مولّد OpenAPI في إصدار يحتويه. يستخدم الناتج صيغة Config الأصلية نفسها؛ راجعه وأضف إعدادات تطبيقك.

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

الإعداد ليس وصفًا عامًا ترسله للـ AI Model وتنتظر منه التصرف. تقرأه المكتبة عند إنشاء Runtime، وتحوّله إلى تعريفات وقواعد تتحقق منها قبل التنفيذ. لذلك يمكن رفض الملف قبل إرسال أي طلب HTTP.

ابدأ بثلاثة أسئلة، وليس بقائمة خيارات

ماذا يستطيع المستخدم طلبه؟ هذا يحدد الـ Tool ووصفها. «ابحث عن خدمة» عملية مختلفة عن «احجز موعدًا»؛ وضعهما تحت وصف مبهم يجعل اختيار الـ Tool أصعب.

ما البيانات المقبولة لتنفيذ العملية؟ هذا يحدد tool.input_schema. في البحث، قد تحتاج نصًا اسمه query. وفي الحجز، قد تحتاج تاريخًا وID للموعد. وجود حقل مطلوب لا يعني أن المستخدم يعرفه؛ سنحدد مصدر هذه الـ IDs عبر Dependencies لاحقًا.

كيف تستقبل API هذه البيانات؟ هذا يحدد request وrequest.map. إذا كان اسم حقل الـ Tool query لكن API تستخدم q، فلا يكفي إعلان الحقل في Schema؛ يجب ربطهما.

في ملف البداية تكون العلاقة هكذا:

arguments.query = "hair"
        |
        v
input_schema: accept a non-empty string
        |
        v
request.map.query: q <- $.query
        |
        v
GET /services?q=hair

ابدأ من القيمة في أعلى المسار. إذا كانت رقمًا، ترفضها Schema. إذا كانت نصًا صحيحًا لكن Mapping غائب، فلا يرسلها مجرد تعريفها. وإذا كان Mapping صحيحًا والعنوان خاطئًا، يصل الطلب إلى المكان الخطأ أو يفشل. بهذا تستطيع تشخيص الطبقة المسؤولة بدل تغيير الوصف عشوائيًا.

افهم مستويات الملف

الجذر هو المستوى الذي يحتوي version وtools. إعدادات الجذر تنطبق على Runtime كله. أما كل عنصر داخل tools فيصف Tool واحدة.

داخل الـ Tool يوجد tool لوصف الـ Input، وrequest لبناء HTTP. أضف response بجوارهما عندما تريد ضبط البيانات المعادة. وأضف depends_on أو behavior على مستوى الـ Tool أيضًا عند الحاجة.

هذا رسم لمواضع الأقسام، وليس ملفًا تنسخه للتشغيل:

config.yml
├── version
├── models                  used by chat
├── assistant               conversation guidance
├── session                 conversation state limits
└── tools
    └── one tool
        ├── id
        ├── tool
        │   ├── description
        │   └── input_schema
        ├── request
        │   ├── method / url / auth
        │   └── map
        ├── response
        ├── depends_on
        └── behavior

المسافات في YAML جزء من البنية. مثلًا، models ليس داخل tools، وinput_schema ليس مباشرةً بجانب request؛ مكانه داخل tool. إذا رفضت المكتبة مفتاحًا معروفًا، تأكد من موضعه قبل تغيير اسمه.

يقبل الجذر version وassistant وrouting وsession وrate_limits وmodels وtools فقط. الإصدار هو النص "2"، وقائمة الـ Tools لا يجوز أن تكون فارغة.

أضف كل قسم عندما تظهر الحاجة إليه

عند نجاح أول طلب، أضف response.output_schema إذا تحققت من شكل الـ Response الذي تضمنه الـ API. ستلاحظ فرقًا مهمًا: HTTP 200 لا يكفي للنجاح إذا خالفت البيانات الشكل الذي يعتمد عليه تطبيقك.

عندما تريد استقبال كلام المستخدم، أضف models.routing، ثم استخدم chat(). دور هذا الإعداد اختيار الـ Tool واستخراج مدخلاتها. لا تحتاجه لمجرد إرسال الطلب المعروف عبر invoke().

عندما تحتاج العملية إلى ID لا يعرفه المستخدم، أضف depends_on لجلبه من Tool قراءة. النتيجة قد تصبح needs_selection؛ أي إن المكتبة تنتظر اختيارًا، وليست معطّلة.

عندما تغيّر العملية بيانات، عرّف behavior.effect والـ Confirmation. ستصبح النتيجة needs_confirmation قبل الكتابة. لا يكفي تغيير method من GET إلى POST.

وعندما يصبح التكامل جزءًا من تطبيق متعدد المستخدمين، راجع Auth والـ Sessions وسياسات الأعطال. زيادة عدد الخيارات لا تعني أن الـ Tool أصبحت أفضل؛ كل خيار يجب أن يحل مشكلة تستطيع تسميتها.

تحقّق مما يفحصه الإعداد وما لا يفحصه

يرفض التحقق مفاتيح غير معروفة، وIDs مكررة، وربطًا يقرأ مدخلًا غير معلن، والـ Dependencies تشير إلى Tool غير موجودة. لكنه لا يعرف أن Endpoint عندك تغيّرت أمس، ولا يثبت أن Token يملك صلاحية الوصول.

لذلك افصل بين تجربتين: إنشاء Runtime بنجاح يثبت صلاحية الإعداد وفق قواعد المكتبة؛ وتنفيذ Tool على API لديك يختبر صحة التكامل الفعلي. ثم تأتي تجربة ثالثة للمحادثة: هل اختار الـ AI Model الـ Tool المناسبة من كلام المستخدم؟

توقّف هنا في القراءة الأولى، وانتقل إلى تعريف الـ Input. بقية الفصل مرجع لإعدادات الجذر. ارجع إلى القسم الذي تحتاجه عندما تبدأ ضبط المحادثة أو الـ Sessions أو حدود الاستهلاك.

Assistant للغة والمحادثة، وليس لمنح صلاحية التنفيذ

assistant:
  name: Booking assistant
  language: auto
  timezone: Asia/Hebron
  system_prompt: |
    Help users find and book appointments using the available tools.
    Do not invent availability or claim a booking before it completes.
  conversation:
    enabled: true
    include_capability_summary: true
    capability_summary:
      include_title: true
      include_description: true
    use_presentation_model: true

الحقل name اختياري، بطول 1 إلى 100 حرف. القيمة الافتراضية لـ language هي auto؛ تحدد لغة الردود، وتظهر رسائل Selection بالعربية عند ضبطها على ar أو اكتشاف العربية في آخر رسالة للمستخدم. القيمة الافتراضية لـ timezone هي UTC، ويجب أن تكون منطقة زمنية صالحة وفق IANA. اضبطها لفهم التواريخ النسبية، لكنها لا تعيد كتابة timestamps المخزنة في API.

يوجّه system_prompt المحادثة وعرض النتائج. لا يمنح إذن كتابة، ولا يتجاوز mapper. ضع قواعد التنفيذ في Schemas والسياسات.

استخدم system_prompt لتحديد شخصية الـ AI Model ونبرة ردوده في المحادثة.

تكون conversation.enabled مفعّلة افتراضيًا. تعطيلها يحوّل حالة عدم اختيار Tool إلى ROUTING_NO_MATCH بدل المحادثة العادية؛ وللعمل المعلّق قواعده الخاصة في الحفاظ على الحالة. أبقها مفعّلة إذا كان المساعد يحتاج إلى الإجابة عن التحيات والأسئلة الجانبية.

تحدد خيارات capability summary ما إذا كانت المحادثة ترى أسماء الـ Tools وأوصافها. يقلل تعطيلها السياق، لكنه يقلل معرفة المساعد بقدراته؛ ولا يحذف الـ Tools من Routing. تكون use_presentation_model مفعّلة افتراضيًا؛ تستخدم المحادثة الـ AI Model المحدد لصياغة النتائج، أو الـ AI Model الخاص بالـ Routing إذا لم تحدد واحدًا منفصلًا.

Routing للموازنة بين العثور على الـ Tool والكلفة والزمن

routing:
  candidate_limit: 6
  fallback_attempts: 2
  lexical:
    enabled: true
    min_score: 1
    normalize_unicode: true
    normalize_arabic: true
    phrase_matching: true
  semantic_recall:
    enabled: true
    candidate_limit: 6
    max_catalog_tools: 100
    max_catalog_chars: 100000
    metadata:
      include_id: true
      include_title: true
      include_description: true
    allow_no_match: true
    multilingual: true

هذه القيم الافتراضية.

• يحدد candidate_limit أقصى عدد من الـ Tools المرشحة للـ Selection النهائي، من 1 إلى 100. ارفعه عندما تُستبعد Tools مناسبة؛ القوائم الأكبر قد تزيد الكلفة وتصعّب Selection.

• يسمح fallback_attempts بمحاولة إلى ثلاث محاولات بديلة للـ Selection عبر Structured Output أو JSON. لا يضبط Retry HTTP.

• يتحكم lexical.enabled في المطابقة قليلة الكلفة مع بيانات الـ Tools، ويحدد min_score عتبة الثقة. تعطيل normalization قد يفوّت تطابقات لصيغ Unicode أو عربية متكافئة. يعطي phrase_matching وزنًا إضافيًا لمطابقة العبارات المحددة في الـ Config.

• يسمح semantic_recall.enabled بالبحث بمساعدة الـ AI Model عندما تضعف المطابقة عبر Lexical Retrieval. قد يقلل تعطيله عدد الاستدعاءات، لكنه يفوّت إعادة الصياغة والمطابقة بين اللغات.

• يحد semantic_recall.candidate_limit الداخلي من IDs المسترجعة. ويحد max_catalog_tools وmax_catalog_chars من بيانات الكتالوج المرسلة للـ AI Model؛ زيادتهما تسمح بكتالوج أوسع على حساب السياق. الحد الأعلى 10,000 Tool و1,000,000 حرف.

• خيارات title وdescription توازن بين وضوح الوصف وحجم prompt. أما include_id وallow_no_match وmultilingual فلا تقبل حاليًا إلا true؛ ليست مفاتيح تعطيل.

قِس نتائج Routing على رسائل تمثل الاستخدام الفعلي قبل تعديل الحدود. غالبًا يفيد تحسين الوصف أكثر من رفع كل الأرقام.

Session: مدة الصلاحية والسجل وحدود التنفيذ

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

Rate limits تحسب العمل الفعلي

rate_limits:
  ai_calls: 60
  tool_calls: 120
  messages: 120
  messages_per_session: 1000
  window_ms: 60000

يحسب التنفيذ الافتراضي حدود الاستهلاك لكل Session خلال الفترة المحددة. يشمل ai_calls استدعاءات الـ AI Model للـ Routing وSemantic Recall والمحادثة وصياغة النتائج؛ قد تحتاج الرسالة الواحدة إلى عدة استدعاءات. ويحسب tool_calls كل محاولة HTTP، بما فيها Retry. أما messages فيحسب العمليات الواردة خلال الفترة، ومنها invoke() وselect() وconfirm() وcancel(). ويحسب messages_per_session العمليات طوال عمر الـ Session.

إطالة window_ms مع إبقاء الميزانية كما هي تجعل المعدل المسموح أشد تقييدًا. وقد توقف الميزانية الصغيرة تدفقًا صحيحًا من عدة خطوات. تعامل مع RATE_LIMITED صراحةً. يحتاج التطبيق الموزع إلى limiter مشترك؛ هذه الإعدادات ليست سقف فوترة عامًّا للحساب.

Models لتفعيل العمل الذي تحتاجه

يحدد models.routing الـ AI Model الذي تستخدمه chat() لاختيار الـ Tool، ويمكن استخدام models.presentation لفصل صياغة النتائج والمحادثة عن Routing. Providers المدعومون هم openai وanthropic وmistral وcohere وollama.

يحتاج كل إعداد إلى المفتاحين provider وmodel. تحتاج الخدمات المستضافة إلى api_key: $ENV:NAME، وغياب Environment Variable يفشل compilation. يحدد base_url الاختياري عنوان الـ Provider، وtimeout_ms افتراضيًا 30,000. أما temperature فاختيارية بين صفر واثنين، ويجب أن يدعمها الـ AI Model.

تصف capability overrides قدرات حقيقية للـ Provider والـ AI Model؛ كتابة nativeTools: true لا تضيف tool calling إلى AI Model لا يدعمه. اقرأ Providers قبل تعديلها.

تحقّق من الإعداد قبل التشغيل

import { readFile } from "node:fs/promises";
import { compileConfig } from "agento-runtime";

const compiled = compileConfig(await readFile("./config.yml", "utf8"));
console.log(compiled.tools.values());

يفحص compilation علاقات لا يكشفها محلّل YAML وحده، مثل تكرار IDs، والـ Schemas غير الصالحة، وplaceholders غير المربوطة، والمسارات غير المعلنة، ودورات الـ Dependencies، وتعارض الوجهات، وبيانات الاعتماد غير الآمنة، وغياب Confirmation.

لكنه لا يثبت أن API تعيد الشكل المعلن، أو أن الـ AI Model يختار الـ Tool الصحيحة. نفّذ طلبًا على بيئة الاختبار في API لديك، ثم جرّب رسائل تمثل استخدام المنتج. تستطيع لاحقًا تثبيت حالات الخطأ في اختبارات آلية ببيانات محفوظة؛ يوضح تمرين الحجز هذا النوع من الاختبار.