DEV Community

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

Posted on Originally published at apidog.com

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

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

جرّب Apidog اليوم

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

مخطط أدوات الوكيل

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

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

عند الاختيار، يرى النموذج:

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

لذلك يجب أن يعيش كل توضيح للغموض داخل تعريف الأداة. تؤكد وثائق OpenAI لاستدعاء الدوال ووثائق Anthropic لاستخدام الأدوات أن الوصف المفصل أهم جزء في تعريف الأداة.

تعامل مع أنماط الفشل الأربعة التالية مباشرة:

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

سمِّ الأدوات بحسب ما تفعله

استخدم نمطًا ثابتًا مثل verbNoun:

createOrder
refundOrder
getOrderStatus
Enter fullscreen mode Exit fullscreen mode

طبّق هذه القواعد:

  • سمِّ الكائن بدقة: searchCustomersByEmail أفضل من search.
  • استخدم لغة المهمة، لا المصطلحات الداخلية. إذا قال العميل «خطة»، فلا تسمِّ الأداة باسم داخلي غامض مثل manageEntity.
  • لا تكرر أسماء عامة مثل list عبر مساحات أسماء متعددة.
  • اجعل النمط متسقًا عبر المجموعة كلها؛ خلط order_create وgetOrder وrefund يزيد الغموض.

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

الوصف الجيد يجيب عن أربعة أسئلة:

  1. ماذا تفعل الأداة؟
  2. ما الذي تغيره؟
  3. متى تستخدم؟
  4. متى لا تستخدم؟

هذا تعريف ضعيف:

{ "name": "updateUser", "description": "Updates a user." }
{ "name": "deactivateUser", "description": "Deactivates a user." }
Enter fullscreen mode Exit fullscreen mode

وهذا تعريف قابل للاستخدام:

{
  "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."
}
Enter fullscreen mode Exit fullscreen mode 
{
  "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."
}
Enter fullscreen mode Exit fullscreen mode

استخدم هذه التقنيات في كل وصف:

  • اذكر الأداة الشقيقة: «استخدم deactivateUser بدلًا من ذلك».
  • أضف لغة العملاء: مثل «إغلاق»، «إلغاء»، «إيقاف مؤقت»، و«تعليق».
  • اذكر ما لا تفعله الأداة: المعلومات السلبية تزيل الالتباس بسرعة.
  • بيّن قابلية التراجع: أخبر النموذج إن كان الإجراء قابلًا للعكس أو مدمّرًا. طبّق الحماية الفعلية أيضًا كما في حواجز حماية وكلاء الذكاء الاصطناعي.

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

صمّم المعلمات لمنع الوسائط الخاطئة

بعد اختيار الأداة الصحيحة، تصبح المعلمات مصدر الخطأ التالي. استخدم قيود JSON Schema بوضوح.

استخدم التعدادات للقيم المغلقة 

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

ضع الوحدات في اسم المعلمة

استخدم:

amount_cents
timeout_seconds
distance_meters
duration_ms
Enter fullscreen mode Exit fullscreen mode

بدلًا من:

amount
timeout
distance
duration
Enter fullscreen mode Exit fullscreen mode

أضف أمثلة للتنسيقات 

{
  "description": "تاريخ البدء بتنسيق ISO 8601، على سبيل المثال 2026-08-26"
}
Enter fullscreen mode Exit fullscreen mode

اجعل الحقول المطلوبة صادقة

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

فضّل البنية المسطحة

هذا أصعب على النموذج:

{
  "customer": {
    "address": {
      "postal_code": "..."
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

وهذا أبسط:

{
  "customer_postal_code": "..."
}
Enter fullscreen mode Exit fullscreen mode

سطّح البيانات عند حد الأداة، ثم أعد تجميعها داخل المنفذ.

قسّم الأدوات المحملة

إذا كانت قيمة 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."
}
Enter fullscreen mode Exit fullscreen mode

ينطبق ذلك على:

  • الإنشاء قبل التحديث.
  • التحميل قبل المعالجة.
  • التفويض قبل الالتقاط.
  • أي خطوة تتطلب معرّفًا من استدعاء سابق.

إذا امتد التسلسل بين وكلاء فرعيين، طبّق قواعد تمرير السياق بين الوكلاء الفرعيين.

اختبر اختيار الأداة في CI

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

اختبر الاسم المختار فقط، لأن الوسائط قد تختلف بين مرات التشغيل، لكن اختيار الأداة يجب أن يبقى ثابتًا.

ابدأ بهذه الحالات:

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

شغّل كل موجه عدة مرات. إذا فازت أداة صحيحة 4 مرات من أصل 5، فالنتيجة غير موثوقة في الإنتاج ويجب تعديل الوصف.

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

ثلاث مجموعات أدوات تفشل بالطريقة نفسها

1. مجموعة CRUD

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

2. مجموعة الإدارة

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

3. المجموعة القديمة

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

Deprecated. Use createOrderV2 instead.
Enter fullscreen mode Exit fullscreen mode

ضع التحذير في البداية، لا في آخر الوصف.

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

لا تجعل تعريفات الأدوات ملفًا محليًا يملكه أول من أعد الوكيل. راجعها وشاركها كواجهة مشتركة، لأن أي تعديل في وصف أداة يؤثر في سلوك جميع الوكلاء.

منصات مثل Sharkly تمثل هذا المفهوم عبر إعدادات محفوظة تشمل التعليمات ووقت التشغيل والمهارات والمستودعات. القيمة ليست في التخزين، بل في جعل التغييرات قابلة للمراجعة وإعادة الاستخدام عبر الفريق.

راقب مفردات المستخدمين

غالبًا لا تكون المشكلة في الاستدلال، بل في المفردات:

لغة API لغة المستخدم
subscription plan، membership، billing
deactivate cancel، close، turn off

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

عندما لا يختار الوكيل أداة ويرد من معرفته، فغالبًا لم تتطابق لغة المهمة مع نص الأداة أصلًا.

قائمة مراجعة

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

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

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

كم يجب أن يكون طول وصف الأداة؟

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

هل يجب أن أضع أمثلة في الوصف؟

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

هل الأفضل استخدام أدوات ضيقة أم أدوات مرنة قليلة؟

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

هل يمكن إصلاح الاختيار من موجه النظام؟

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

ماذا لو استمر النموذج في اختراع قيم المعلمات؟

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

هل تنطبق هذه القواعد على خوادم MCP؟

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

Top comments (0)