استدعاء الأدوات: تصميم واجهة يفهمها النموذج

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

ما الذي يراه النموذج فعلًا

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

{
  "name": "create_refund",
  "description": "ينشئ طلب استرداد لطلب مكتمل الدفع خلال ٣٠ يومًا من الشراء. لا يُستعمل للطلبات الملغاة أو غير المدفوعة — تحقّق أولًا بـsearch_orders. يعيد رقم طلب الاسترداد وحالته.",
  "input_schema": {
    "type": "object",
    "properties": {
      "order_id": { "type": "string", "pattern": "^ORD-[0-9]{5}$" },
      "amount": { "type": "number", "minimum": 1 },
      "reason": {
        "type": "string",
        "enum": ["damaged", "wrong_item", "late_delivery", "other"]
      }
    },
    "required": ["order_id", "reason"],
    "additionalProperties": false
  }
}

أربعة قرارات في هذا المخطط تمنع أخطاءً حقيقية:

1. pattern على المعرّف: يمنع تمرير رقم مخترَع بصيغة خاطئة.
2. enum للسبب: نصّ حرّ هنا يعني تصنيفات لا نهائية في قاعدة بياناتك.
3. minimum للمبلغ: يمنع الصفر والسالب.
4. additionalProperties: false: يمنع حقولًا مخترَعة تمرّ صامتة.

الوصف: اكتب متى لا تُستعمل

أكثر جملة نافعة في وصف الأداة هي جملة المنع. «لا يُستعمل للطلبات الملغاة» تمنع مسارًا خاطئًا كاملًا. والوصف الجيد يجيب عن أربعة:

• ماذا تفعل الأداة بدقّة؟
• متى تُستعمل، ومتى لا تُستعمل؟
• ما الذي تعيده، وما الذي لا تعيده؟ («لا تعيد بيانات الدفع»)
• ما شرطها المسبق؟ («تحقّق أولًا بـ…»)

رسائل الخطأ توجيه لا سجلّ

الوكيل يقرأ نتيجة الأداة ويقرّر الخطوة التالية. قارن:

الأولى تنتج تكرارًا أعمى للمحاولة نفسها؛ الثانية تنتج تصحيحًا في الدورة التالية.

متى تدمج الأدوات ومتى تفصلها

ادمج حين تختلف الأدوات في معامل واحد فقط (get_user_by_id وget_user_by_email ← get_user بحقلين متبادلين). افصل حين تختلف الصلاحيات أو العواقب: القراءة أداة، والكتابة أداة أخرى تمرّ بموافقة. الخلط بينهما يجعل تقييد الخطر مستحيلًا.

متى لا تحتاج أدوات أصلًا

إن كان المسار ثابتًا معروفًا — استرجاع ثم إجابة — فاستدعِ الدوال في كودك مباشرةً بلا وسيط. استدعاء الأدوات يُبرَّر حين يكون قرار أيّ دالة تُستدعى غير معروف مسبقًا.

اختبار الأدوات: ما الذي يُختبر بالضبط

الأداة تُختبر على ثلاث مستويات، وأكثر الفرق يختبر واحدًا منها فقط:

1. الدالّة نفسها — اختبار وحدة عادي، بلا نموذج أصلًا. هذا هو المستوى الذي لا يُنسى غالبًا، وهو أقلّها كشفًا لأعطال الأدوات.
2. الاختيار: هل يستدعي النموذج الأداة الصحيحة في الحالة الصحيحة؟ جهّز عشرين مدخلًا — منها ما لا يحتاج أداة إطلاقًا — وتحقّق من قرار الاستدعاء وحده قبل النظر في الوسائط. الحالات التي لا تحتاج أداة هي أهمّها: النموذج المفرط في الاستدعاء يكلّف ويُبطئ ويخطئ.
3. الوسائط: هل الحقول مكتملة وأنواعها صحيحة وقيمها ضمن المدى؟ افحصها بالمخطَّط برمجيًّا، ولا تعتمد على قراءة عينية.

وثلاث حالات تستحقّ اختبارًا صريحًا لأنها تكسر الأنظمة أكثر من غيرها: أداة تُرجع خطأً (هل يتعافى النموذج أم يعيد المحاولة إلى ما لا نهاية؟)، وأداة تُرجع نتيجة فارغة (هل يقول «لم أجد» أم يخترع؟)، وأداة بطيئة تتجاوز المهلة (هل يوجد سقف، أم ينتظر المستخدم إلى الأبد؟).

الأخطاء الشائعة

1. أوصاف من سطر واحد تصف الاسم لا السلوك.
2. نصّ حرّ حيث يجب enum.
3. عشرون أداة متشابهة بدل خمس واضحة.
4. أخطاء صامتة أو غامضة تُبقي الوكيل يدور.
5. أداة واحدة تقرأ وتكتب معًا، فيتعذّر تقييدها.
6. غياب سقف للتكرار عند فشل متكرّر.

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

كم أداة يحتمل النموذج؟

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

هل أصف الأدوات بالعربية أم الإنجليزية؟

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

كيف أختبر أن الوصف جيد؟

اعرضه على زميل لم يكتب الأداة واسأله: متى تستعملها ومتى لا؟ إن تردّد، سيتردّد النموذج. ثم شغّل مجموعة سيناريوهات وقِس نسبة الاستدعاءات الصحيحة من أول محاولة.

المراجع

1. Yao, S. et al. ReAct: Synergizing Reasoning and Acting in Language Models. arXiv:2210.03629
2. Anthropic. Model Context Protocol — Specification. modelcontextprotocol.io
3. Schick, T. et al. Toolformer: Language Models Can Teach Themselves to Use Tools. arXiv:2302.04761
4. OWASP. Top 10 for LLM Applications. owasp.org