OpenAPI إلى أدوات وكلاء الذكاء الاصطناعي: تجاوز الأغلفة البرمجية اليدوية

تحتوي معظم قواعد بيانات الأكواد الخاصة بالوكلاء على ملف لا يستمتع أحد بصيانته. إنه يحتوي على أربعين تعريفًا للأداة، كل واحد منها عبارة عن مخطط JSON مكتوب يدويًا يصف نقطة نهاية تحتوي بالفعل على مخطط في مكان آخر. يقوم فريق واجهة برمجة التطبيقات (API) بشحن حقل جديد مطلوب، ويتم تحديث المواصفات، وتحديث الوثائق، ويستمر الوكيل في إرسال الحمولة القديمة حتى يلاحظ أحدهم أخطاء 400.

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

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

Apidog مهم هنا لأن المواصفات يجب أن تكون صحيحة قبل أن يكون أي شيء يتم إنشاؤه منها كذلك. تعريف الأداة يرث كل فجوة في المستند الذي جاء منه.

تكلفة تعريفات الأدوات المكتوبة يدويًا

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

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

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

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

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

كيف تصبح عملية OpenAPI أداة

الربط أكثر مباشرة مما يبدو. لنأخذ عملية واحدة:

paths:
  /orders/{orderId}/refund:
    post:
      operationId: refundOrder
      summary: Refund an order
      description: >
        Issues a full or partial refund against a completed order.
        Refunds are irreversible. Partial refunds require an amount
        no greater than the remaining refundable balance.
      parameters:
        - name: orderId
          in: path
          required: true
          schema: { type: string }
          description: The order to refund.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [reason]
              properties:
                amount:
                  type: integer
                  description: Amount in cents. Omit for a full refund.
                reason:
                  type: string
                  enum: [duplicate, fraudulent, requested_by_customer]

تعريف الأداة الذي يخرج منها:

{
  "name": "refundOrder",
  "description": "Issues a full or partial refund against a completed order. Refunds are irreversible. Partial refunds require an amount no greater than the remaining refundable balance.",
  "input_schema": {
    "type": "object",
    "required": ["orderId", "reason"],
    "properties": {
      "orderId": { "type": "string", "description": "The order to refund." },
      "amount": { "type": "integer", "description": "Amount in cents. Omit for a full refund." },
      "reason": { "type": "string", "enum": ["duplicate", "fraudulent", "requested_by_customer"] }
    }
  }
}

أربع قواعد تقوم بمعظم العمل:

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

المنفذ هو النصف الآخر، وهو صغير:

def execute(tool_name, args, spec_index, http):
    op = spec_index[tool_name]          # method, path template, param locations
    path = op.path
    query, body = {}, {}

    for name, value in args.items():
        location = op.locations[name]   # "path" | "query" | "header" | "body"
        if location == "path":
            path = path.replace("{" + name + "}", str(value))
        elif location == "query":
            query[name] = value
        elif location == "body":
            body[name] = value

    return http.request(op.method, path, params=query, json=body or None)

هذا هو الجسر بأكمله. كل ما تبقى هو التنظيف على طول الطريق.

ما يجب على المولد إصلاحه

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

حل مؤشرات $ref. تقبل معظم واجهات برمجة تطبيقات استدعاء الأدوات مجموعة فرعية من مخطط JSON ولن تتبع المراجع إلى قسم components. قم بتضمينها. انتبه للمخططات المتكررة، التي سيتوسع تضمينها إلى الأبد؛ اقطع التكرار عند عمق ثابت واوصف البنية الأعمق بالنص.

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

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

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

حمل علامات الأمان. يجب وضع علامة على عمليات الكتابة بحيث يمكن للمنفذ الخاص بك توجيهها عبر بوابة الموافقة. إذا كانت مواصفاتك تستخدم امتدادًا مثل x-agent-requires-approval، فاقرأه والتزم به. قم بإقران هذا بالأنماط الموجودة في دليلنا حواجز حماية وكيل الذكاء الاصطناعي.

لا تعطِ النموذج جميع نقاط النهاية البالغ عددها 200

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

ثلاث طرق لتقليصها، بترتيب تقريبي لمدى فعاليتها.

التصفية حسب الوسم (Tag). تحمل عمليات OpenAPI علامات (tags)، وعادة ما تتوافق العلامات مع مناطق المنتج. يحتاج الوكيل الذي يتعامل مع المبالغ المستردة إلى علامات orders و payments، وليس admin أو analytics. هذا مرشح من سطر واحد وعادة ما يزيل معظم السطح.

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

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

هناك أيضًا مسار البروتوكول. يوحد بروتوكول سياق النموذج (Model Context Protocol) كيفية كشف الخادم للأدوات للعميل، ويمنحك خادم MCP مدعوم بوثيقة OpenAPI نقطة تكامل واحدة بدلاً من واحدة لكل إطار عمل. يغطي شرحنا حول ما هو MCP (بروتوكول سياق النموذج) النموذج، ويغطي بناء خادم MCP باستخدام Apidog عملية البناء.

يجب أن تكون المواصفات صحيحة أولاً

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

لذا قم بمراجعة المواصفات من خلال عيون الوكيل قبل إنشاء أي شيء:

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

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

شارك مجموعة الأدوات، لا تنسخها

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

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

اختبار الأدوات المُنشأة

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

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

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

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

إلى أين يقودك هذا

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

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

الأسئلة المتكررة

هل يمكنني إنشاء أدوات من مستند Swagger 2.0؟ نعم، ولكن قم بتحويله إلى OpenAPI 3.x أولاً. يختلف نموذج النص في الإصدار 2.0 بشكل كافٍ بحيث يتعامل معه المولدات بشكل غير متسق، والإصدار 3.x هو ما تستهدفه الأدوات الحالية. يوثق مستودع مواصفات OpenAPI الاختلافات.

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

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

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

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

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