عرّف Input الـ Tool

في البداية السريعة سمّينا مدخل البحث query وربطناه بحقل q في API. نركّز الآن على الـ Input نفسه: ما نوعه؟ هل يمكن حذفه؟ وما الذي يحدث إذا قدّم الـ AI Model قيمة غير صالحة؟

input_schema هي القواعد التي تجيب عن هذه الأسئلة. تستخدم JSON Schema؛ لا تكتب فيها عنوان Endpoint أو طريقة Auth.

ابدأ من Input يعرفها المستخدم

للبحث، يعرف المستخدم الكلمات التي يريد البحث عنها. لذلك يمكن للـ Tool قبول query كنص. إذا كانت API تسمح بتحديد عدد النتائج، تستطيع إضافة limit كعدد صحيح، بشرط أن تطابق حدوده ما تدعمه API بالفعل.

المقطع التالي يستبدل كتلة tool داخل Tool البحث. احتفظ بـid وrequest من إعدادك. يفترض المثال أن الـ API تقبل حدًا للنتائج من 1 إلى 20. اضبط هذه القيم وفق ما تدعمه الـ Endpoint لديك.

tool:
  description: Search services by name. Use this to find services, not to create a booking.
  input_schema:
    type: object
    additionalProperties: false
    properties:
      query:
        type: string
        minLength: 1
        description: The search phrase supplied by the user.
      limit:
        type: integer
        minimum: 1
        maximum: 20
        default: 5
    required: [query]

تعني type: object أن الـ Input كائن ذو حقول، مثل { "query": "hair" }. تحت properties نعرّف أسماء الحقول وقواعدها. ثم تحدد required أي هذه الحقول لا يمكن الاستغناء عنه.

لذلك، وجود limit داخل properties لا يجعله مطلوبًا. لا تضعه داخل required إلا إذا كان غيابه يمنع تنفيذ العملية. هنا اخترنا قيمة افتراضية تسمح للمستخدم بالبحث دون تحديد عدد.

ميّز بين غياب القيمة وفسادها

عند إرسال {}، ينقص الحقل query. تعيد المكتبة needs_input كي يحصل تطبيقك على القيمة من المستخدم، ولا ترسل الطلب الناقص.

عند إرسال { "query": "" }، الحقل موجود لكنه يخالف minLength: 1. هذه مشكلة تحقق، وليست حقلًا غائبًا. ستجد INPUT_SCHEMA_VIOLATION بدل إكمال الطلب.

عند إرسال { "query": "hair" }، يملأ التحقق limit بالقيمة 5. أما { "query": "hair", "limit": "5" } فتفشل؛ علامات الاقتباس تجعل القيمة نصًا، والمكتبة لا تحوّل الأنواع تلقائيًا. ولا تستبدل القيمة الافتراضية قيمةً موجودةً لكنها خاطئة.

إذا أرسلت limit: 50، تُرفض القيمة بسبب maximum: 20. يحدد هذا القيد قيمة قيم Input المقبولة، ولا يجبر الـ API على إعادة عشرين عنصرًا؛ تبقى هي المسؤولة عن تقسيم النتائج.

أضف limit فقط إذا كانت الـ API تدعمه، واضبط قيوده وفق توثيقها.

الحقل المقبول لا يُرسل تلقائيًا

أضف الآن Mapping التالي تحت request.map لـ Tool البحث:

query:
  q: $.query
  limit: $.limit

بعد التحقق تصبح الـ Input { "query": "hair", "limit": 5 }. يرسل Mapping q=hair&limit=5. لو أضفت الحقل إلى Schema ونسيت هذا Mapping، فلن تُرسل قيمته إلى API.

قبل أن تضيف حقلًا، حدّد فائدته ومكانه في طلب HTTP. لا تضف خصائص لأن الـ AI Model قد يجدها مفيدة؛ يجب أن تكون لها وظيفة معروفة في Endpoint العملية.

اكتب وصفًا يمكن التمييز به بين الـ Tools

وصف «إدارة الخدمات» لا يوضح هل الـ Tool تبحث أم تضيف أم تحذف. وصف «ابحث عن الخدمات بالاسم، ولا تستخدم هذه الـ Tool لإنشاء حجز» يوضح العملية والحد الفاصل بينها وبين Tool الحجز.

يحتاج الـ AI Model إلى هذا الوصف عند Routing، لكنه لا يغير ما تستطيع الـ Tool تنفيذه. يبقى العنوان والطريقة والـ Mapping تحت request. أما title فهو اسم اختياري أكثر ملاءمة للعرض، وid اسم ثابت يحدد الـ Tool في الاستدعاءات والـ Dependencies. لا يتجاوز title مقدار 200 حرف، أما description فهو مطلوب، وغير فارغ، ولا يتجاوز 8000 حرف.

اختر IDs واضحة مثل search-services وbook. يجب أن تكون فريدة، وتبدأ بحرف أو underscore، وألا تتجاوز ٦٤ حرفاً. يسمح بعدها بالأحرف والأرقام وunderscores وhyphens. إذا غيّرت ID، حدّث كل المواضع التي تشير إليه.

لا تطلب من الـ AI Model بيانات يملكها الخادم أو API

قد يتطلب الحجز date وslot_token. التاريخ يستطيع المستخدم تحديده، لكن Token يأتي من API بعد البحث عن موعد. عرّف الحقلين في قواعد التنفيذ، ثم استخدم Dependency لتحديد مصدر Token.

تخفي المكتبة حقول المستوى الأول التي تملؤها Dependencies أو References عن Schema التي يراها الـ AI Model. تبقى مطلوبة لتنفيذ العملية، لكنها ليست معلومات يُطلب من الـ AI Model اختراعها. افحص runtime.listTools() لترى الـ Tools والـ Input المتاحة له، ولا تفترض أنه يرى YAML كاملًا.

بيانات المستخدم الموثوقة، مثل الجهة التي ينتمي إليها، يوفّرها خادمك عبر context عند الحاجة؛ لا تجعل المستخدم يختار جهة أخرى بمجرد كتابة ID. وبيانات الاعتماد تمر عبر إعدادات Auth، لا عبر Schema. راجع مصادر Mapping وAuth.

استخدم قواعد إضافية حين يكون لها معنى

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

تستخدم المكتبة JSON Schema draft-07 مع تحقق صارم عبر AJV، دون جلب Schema References بعيدة أو تحويل أنواع القيم تلقائيًا. يمكنك تعريف نوع رقم، وحدوده، وقائمة قيم مسموحة عبر enum، أو شكل كائن متداخل. اكتب القيود وفق متطلبات الـ API؛ لا تستنتجها من أسماء الحقول فقط.

لا تضف trigger_hints وkeywords قبل نجاح التنفيذ. تساعد التلميحات والكلمات المفتاحية ذات الأوزان الموجبة في Lexical Retrieval. لا تمنح صلاحية التنفيذ ولا تضمن المطابقة؛ إعطاء كلمة عامة وزنًا كبيرًا قد يستبعد Tool أنسب. نشرحها في اختيار الـ Tool بعد إضافة الـ AI Model.

جرب كل حالة قبل الانتقال إلى Mapping

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

ترفض المكتبة حقولًا مثل access_token لأنها تبدو كبيانات اعتماد. مرّر الـ Token عبر auth أو استخدم Environment Variable تحت request.auth. تثبت الـ Schema شكل البيانات وقيودها، لكنها لا تثبت ملكية المستخدم للـ ID أو بقاء الموعد متاحًا.

بعد ذلك تابع إلى ربط القيم. هناك سنقرأ الطلب من جهة API، ونحدد كيف تصل إليه القيم التي أصبحت تعرف كيف تتحقق منها.