تصميم مخطط الأدوات: مساعدة وكلاء الذكاء الاصطناعي في اختيار الواجهة البرمجية الصحيحة

لقد منحت الوكيل أداتين: updateUser و deactivateUser. تقول تذكرة دعم "إغلاق هذا الحساب". استدعى الوكيل deactivateUser. في الأسبوع الماضي، تسببت تذكرة شبه متطابقة في استدعاء updateUser مع status: "closed"، وهو ما قبله واجهة برمجة التطبيقات الخاصة بك، وكان يعني شيئًا مختلفًا قليلاً في العمليات اللاحقة.

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

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

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

ما يراه النموذج

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

هذا يعني أن كل توضيح للغموض يجب أن يُكتب في التعريف نفسه. كل من دليل استدعاء وظائف OpenAI و وثائق استخدام أدوات Anthropic يشيران إلى نفس النقطة: الوصف هو النص الأكثر أهمية في التعريف بأكمله، ويجب أن يكون مفصلاً بدلاً من كونه موجزًا.

تأتي أخطاء الاختيار بأربعة أشكال، ولكل منها حل مختلف.

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

سمِّ الأدوات بناءً على ما تفعله

تحمل الأسماء إشارة أكثر مما يوحي طولها، لأن النموذج يقرأها أولاً.

استخدم فعل اسم (verbNoun)، بنفس النمط عبر مجموعة الأدوات بأكملها: createOrder، refundOrder، getOrderStatus. الاتساق مهم بقدر أهمية الاختيار الفردي، لأن المجموعة التي تجمع بين order_create و getOrder و refund تجعل كل اسم أصعب قليلاً في القراءة.

كن محددًا بشأن الكائن. search اسم أداة سيء. searchCustomersByEmail اسم جيد، ويخبر النموذج ما يبحث عنه وكيف.

تجنب المصطلحات الداخلية. إذا كانت واجهة برمجة التطبيقات الخاصة بك تسمي العميل "كيانًا" والاشتراك "أداة"، فلن يربط النموذج ذلك بتذكرة تقول "عميل" و "خطة". سمِّ الأدوات بلغة المهمة، وليس بلغة المخطط.

لا تعيد استخدام الاسم أبدًا عبر السياقات. أداتان تسمى list في مساحات أسماء مختلفة تنهار إلى غموض بمجرد ظهورها في قائمة واحدة.

اكتب أوصافًا تميز بين الأدوات

الوصف المفيد يجيب على أربعة أسئلة: ماذا يفعل، وماذا يغير، ومتى يستخدم، ومتى لا يستخدم.

إليك زوج ضعيف:

{ "name": "updateUser", "description": "Updates a user." }
{ "name": "deactivateUser", "description": "Deactivates a user." }

وزوج يميز فعليًا:

{
  "name": "updateUser",
  "description": "Updates profile fields on an active user, such as name, email, or timezone. Use for corrections and profile edits requested by the user. Does NOT change account status. To disable an account, use deactivateUser instead. Do not use to close or cancel an account."
}
{
  "name": "deactivateUser",
  "description": "Disables a user account, revoking all sessions and blocking sign-in. Reversible with reactivateUser. Use when a customer asks to close, cancel, pause, or suspend their account. Does NOT delete data. For permanent deletion use deleteUser, which cannot be undone."
}

أربع تقنيات تقوم بالعمل هنا.

اذكر الأداة الشقيقة. "استخدم deactivateUser بدلاً من ذلك" يحل الغموض مباشرة، في اللحظة التي يقارن فيها النموذج بينهما.

ضمِّن مفردات المستخدم. تظهر الكلمات "إغلاق"، "إلغاء"، "إيقاف مؤقت"، و "تعليق" لأن هذه هي الكلمات التي تظهر في التذاكر. هذا هو التعديل الوحيد ذو العائد الأعلى الذي يمكنك إجراؤه، وهو مجاني تقريبًا.

اذكر ما لا تفعله. البيانات السلبية أكثر تمييزًا من الإيجابية، لأن الادعاءات الإيجابية لأداتين متجاورتين تميل إلى التشابه.

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

الطول لا بأس به. وصف مكون من مائة كلمة يمنع استدعاء خاطئًا واحدًا لنقطة نهاية مدمرة يعتبر رخيصًا.

صمم المعلمات بحيث يصعب تمرير وسائط خاطئة

بمجرد اختيار الأداة الصحيحة، تكون الوسائط هي الخطأ التالي.

يوفر لك JSON Schema معظم القيود التي تحتاجها هنا، و مفردات التحقق من JSON Schema تستحق التصفح للتعرف على الكلمات المفتاحية التي تدعمها واجهة برمجة التطبيقات الخاصة باستدعاء الأدوات.

استخدم التعدادات (enums) حيثما تكون المجموعة مغلقة. معلمة status من نوع سلسلة نصية تدعو إلى الابتكار. عند كتابتها كتعداد (enum)، فإنها تقيد النموذج بالقيم التي تقبلها واجهة برمجة التطبيقات الخاصة بك.

"status": {
  "type": "string",
  "enum": ["pending", "paid", "refunded", "cancelled"],
  "description": "Order status. 'cancelled' means never fulfilled; 'refunded' means fulfilled then reversed."
}

ضع الوحدات في الاسم. amount غامض وستخمّن النماذج الدولارات أو السنتات بشكل غير متسق. amount_cents لا يكون كذلك أبدًا. وينطبق الشيء نفسه على timeout_seconds، distance_meters، و duration_ms.

قدم أمثلة لتنسيقات التاريخ. "description": "تاريخ البدء بتنسيق ISO 8601، على سبيل المثال 2026-08-26" ينتج تواريخ منسقة بشكل صحيح أكثر بكثير من "تاريخ البدء" وحده.

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

فضل البنية المسطحة على المتداخلة. النموذج الذي يملأ {"customer": {"address": {"postal_code": "..."}}} يرتكب أخطاء هيكلية لا يرتكبها عند استخدام customer_postal_code. قم بتسطيح البيانات عند حدود الأداة وأعد تجميعها في المنفذ الخاص بك.

قسّم الأدوات المحملة بشكل زائد. الأداة التي تحتوي على معلمة mode وتغير معنى كل حقل آخر هي في الواقع أداتان. تقسيمها يحسن الاختيار ويبسط كلا المخططين.

اذكر المتطلبات المسبقة والترتيب

تفشل الأعمال متعددة الخطوات عندما لا يعرف النموذج التسلسل. اذكره في وصف الأداة التابعة:

{
  "name": "captureCharge",
  "description": "Captures a previously authorized charge. Requires an authorization_id from authorizeCharge. Call authorizeCharge first if you do not already have one. Cannot capture more than the authorized amount."
}

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

اختبر الاختيار كأي سلوك آخر

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

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

ابدأ بالحالات الأكثر عرضة للتعطل:

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

قم بتشغيل كل موجه عدة مرات. الأداة التي تفوز بأربع مرات من خمسة هي بمثابة رمي عملة معدنية في بيئة الإنتاج، ويحتاج وصفها إلى تعديل.

وجه عمليات التشغيل نحو النماذج الوهمية (mocks) بحيث لا يلامس اختبار الاختيار البيانات الحية أبدًا. يغطي منشورنا حول تشغيل الوكلاء مقابل النماذج الوهمية بدلاً من الإنتاج الإعداد، ويمكن لـ Apidog تقديم هذه النماذج الوهمية من نفس التعريف الذي تم إنشاء أدواتك منه، مما يحافظ على توافق المخطط والسلوك.

ثلاث مجموعات تخطئ بنفس الطريقة

مجموعة CRUD. تعرض واجهة برمجة تطبيقات getUser، listUsers، searchUsers، و queryUsers، وكلها تم إنشاؤها من نقاط نهاية تطورت على مر السنين. بالنسبة للنموذج، هذه أربعة أسماء لفكرة واحدة. الحل ليس في أوصاف أفضل للأربعة جميعًا؛ بل في عرض واحد منها للوكيل واستبعاد البقية من قائمة الأدوات. المجموعة المنسقة تتفوق على المجموعة الكاملة في كل مرة.

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

المجموعة القديمة. نقطتا نهاية تقومان بنفس المهمة، إحداهما مهملة. لا تزال المواصفات تسرد كلتيهما، لذا ينشئ المولد كلتيهما، ويختار الوكيل القديمة حوالي نصف الوقت. إما أن تسقط العملية المهملة من الأدوات التي تم إنشاؤها أو تبدأ وصفها بالكلمات "مهملة. استخدم createOrderV2 بدلاً من ذلك." تحترم النماذج هذا السطر عندما يكون أولاً، وتتجاهله عندما يكون مدفونًا في النهاية.

الأوصاف هي تهيئة مشتركة

بمجرد قبولك أن أوصاف الأدوات توجه السلوك، يصبح السؤال التالي هو من يمتلكها. في معظم الفرق، تكون الإجابة عرضية: من قام بإعداد الوكيل أولاً، في ملف على جهازهم.

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

راقب الكلمات التي يجلبها المستخدمون

الفجوة الأكثر شيوعًا هي المفردات. واجهة برمجة التطبيقات الخاصة بك تقول subscription، بينما يقول عملاؤك plan، membership، و billing. واجهة برمجة التطبيقات الخاصة بك تقول deactivate، بينما يقولون cancel، close، و turn off.

اجمع اللغة الحقيقية. استخرج العبارات الأكثر شيوعًا من تذاكر الدعم، وسجلات البحث، أو نصوص تشغيل الوكلاء الفاشلة، ثم ادمجها في أوصاف الأدوات التي كان ينبغي أن تتطابق معها. هذا يكلف ساعة واحدة وعادة ما يحسن دقة الاختيار أكثر من أي قدر من تعديل المخطط.

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

قائمة مرجعية لمجموعة الأدوات

• تتبع الأسماء اصطلاح verbNoun واحد وتسمي كائنًا محددًا.
• يحدد كل وصف ما يتغير، ومتى يجب استخدامه، ومتى لا يجب.
• تذكر الأدوات المتداخلة بعضها البعض بشكل صريح.
• تتضمن الأوصاف الكلمات التي يستخدمها المستخدمون فعليًا، وليس فقط المصطلحات الداخلية.
• توضح الإجراءات المدمرة وغير القابلة للإلغاء ذلك في الوصف.
• يتم الإعلان عن التعدادات (Enums) لكل مجموعة مغلقة.
• تعيش الوحدات والتنسيقات في أسماء المعلمات أو أوصافها، مع أمثلة.
• تتطابق القوائم المطلوبة مع ما تفرضه واجهة برمجة التطبيقات بالفعل.
• تذكر الأدوات التابعة المتطلب الأساسي لها.
• تُشغل مجموعة الاختيار في التكامل المستمر (CI) مقابل النماذج الوهمية (mocks).

يقوم النموذج بمطابقة الأنماط مع النص الذي كتبته. عندما يختار خطأً، يكون النص هو أول مكان تنظر إليه، وعادة ما يكون المكان الوحيد الذي تحتاج إلى تغييره. قم بتنزيل Apidog إذا كنت تريد الأوصاف والنماذج الوهمية والاختبارات في مشروع واحد.

الأسئلة الشائعة

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

هل يجب أن أضع أمثلة في الوصف؟ نعم للتنسيقات والوحدات، حيث يزيل المثال فئة كاملة من الأخطاء. تخطى أمثلة الاستخدام الطويلة، لأنها تكلف السياق ونادراً ما تغير الاختيار.

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

هل يمكنني إصلاح الاختيار في الموجه النظامي بدلاً من ذلك؟ جزئياً، وهو حل مؤقت معقول لحالة أو اثنتين من الالتباسات المعروفة. لكنه لا يتوسع، لأن الموجه مشترك عبر جميع الأدوات بينما ينتقل الوصف مع الأداة التي تحتاجه.

ماذا لو استمر النموذج في اختراع قيم المعلمات؟ قم بتقييد النوع، وأضف تعدادًا (enum)، واذكر في الوصف أن القيمة يجب أن تأتي من استدعاء سابق بدلاً من أن يتم إنشاؤها. إذا استمر هذا في الحدوث، قم بالتحقق في الغلاف وأرجع خطأ يحدد القيم المسموح بها.

هل تنطبق هذه القواعد على خوادم MCP أيضًا؟ نعم. يعرض خادم MCP الأسماء والأوصاف والمخططات بنفس الشكل، لذا تنطبق نفس قواعد الصياغة. يغطي شرحنا حول ما هو MCP البروتوكول نفسه.