استدعاء الأدوات

الدورة الكاملة

1. يرسل التطبيق السؤال مع تعريفات الأدوات.
2. يعيد النموذج إما إجابة نصية أو طلب استدعاء (اسم + معاملات).
3. يتحقق التطبيق من الطلب وينفذ الدالة.
4. تُرسل النتيجة إلى النموذج.
5. يكرر النموذج أو يصوغ الإجابة النهائية.

تعريف أداة

{
  "name": "get_track_info",
  "description": "يعيد معلومات مسار في الأكاديمية: عدد الدروس والمستويات والرابط.",
  "input_schema": {
    "type": "object",
    "properties": {
      "slug": {"type": "string", "description": "المعرّف النصي للمسار مثل machine-learning"}
    },
    "required": ["slug"],
    "additionalProperties": false
  }
}

اسم الحقل الذي يحمل المخطط (input_schema أو parameters) يختلف بين المزودين؛ الفكرة واحدة.

التنفيذ الآمن

from jsonschema import validate, ValidationError

TOOLS = {
    "get_track_info": {
        "fn": lambda slug: {"slug": slug, "lessons": 17},
        "schema": {"type": "object", "properties": {"slug": {"type": "string", "pattern": "^[a-z0-9-]{2,60}$"}},
                   "required": ["slug"], "additionalProperties": False},
        "dangerous": False,
    },
}

def execute(call, approve=lambda c: False):
    spec = TOOLS.get(call["name"])
    if spec is None:
        return {"error": "unknown tool"}
    try:
        validate(call["args"], spec["schema"])
    except ValidationError as e:
        return {"error": f"invalid args: {e.message}"}
    if spec["dangerous"] and not approve(call):
        return {"error": "user approval required"}
    try:
        return {"result": spec["fn"](**call["args"])}
    except Exception as e:                 # أعد الخطأ للنموذج بدلاً من إسقاط التطبيق
        return {"error": str(e)}

تصميم أدوات جيدة

• أسماء ووصف واضحان يشرحان متى تُستخدم الأداة.
• معاملات قليلة ومحددة بأنواع وقيود.
• مخرجات مختصرة ومنظمة (لا تعد صفحات ضخمة).
• رسائل خطأ مفيدة تساعد النموذج على التصحيح.

الأمان

• أقل الصلاحيات: أداة قراءة لا تحتاج صلاحية كتابة.
• لا تمرر مدخلات النموذج مباشرة إلى أوامر النظام أو استعلامات SQL.
• عامل نتائج الأدوات (صفحات ويب، ملفات) كبيانات قد تحتوي تعليمات خبيثة.
• سجّل كل استدعاء للمراجعة.