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

قام عامل ترميز بالذكاء الاصطناعي بتشغيل نص برمجي، وشاهده ينجح، ثم شاهد جدول قاعدة بيانات إنتاج يختفي. انتشر تقرير ما بعد الوفاة على Hacker News بعنوان حاد: "الذكاء الاصطناعي لم يحذف قاعدة بياناتك، بل أنت من فعلت ذلك." ووصلت الفكرة لأنها حقيقية. اتبع العامل تعريف أداة، وضربت الأداة نقطة نهاية حقيقية، ولم تكن نقطة النهاية تحتوي على أي حواجز أمان، وسلم إنسان المفاتيح لعملية لا تتوقف لتسأل عما إذا كان DELETE FROM users يبدو مشبوهًا. أخبر موضوع منفصل على r/ClaudeAI قصة مشابهة من زاوية مختلفة: عامل في حلقة فوترة استهلك مئات الدولارات من الرموز قبل أن يلاحظها أحد. سطح مختلف، نفس فئة الفشل. المشكلة ليست أن النموذج غبي. المشكلة هي أن لا أحد اختبر واجهة برمجة التطبيقات (API).

زر

الخلاصة

تفشل العوامل في الإنتاج عندما لا تحتوي أدواتها على حواجز أمان من جانب واجهة برمجة التطبيقات (API): حدود معدل مفقودة، لا خاصية التكرارية (idempotency)، عمليات حذف ساخنة، مخططات معطلة. يمكنك إصلاح ذلك بأربع خطوات: اختبار تعريفات أدوات العامل مقابل مواصفات OpenAPI الخاصة بك، تشغيل خادم وهمي لنقاط النهاية المدمرة، فرض ميزانيات ومفاتيح التكرارية لكل عامل، وإعادة تشغيل سيناريوهات الفشل في CI. يمنحك Apidog استيراد OpenAPI، والمحاكاة، ومشغل السيناريوهات للقيام بكل ذلك من مشروع واحد.

مقدمة

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

استحوذت قصة Hacker News الفيروسية هذا الشهر على التحول. جادل المؤلف بأن الذكاء الاصطناعي لم يحذف قاعدة البيانات؛ بل فعل ذلك الإنسان، من خلال منح العامل حق الوصول للكتابة دون وضع أي ضوابط بين النموذج والبيانات. انفجر الموضوع لأن كل مطور يقرأه فكر، "كدت أن أقوم بنشر ذلك." قبل بضعة أسابيع، وصفت مشاركة على Reddit حلقة فوترة حيث أعاد عامل محاولة استدعاء فاشل عدة مرات لدرجة أن الفاتورة تجاوزت 800 يورو قبل أن يلاحظها أحد. نفس السبب الجذري: الثقة وضعت في الطبقة الخاطئة.

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

لماذا تبدو إخفاقات العوامل وكأنها إخفاقات في واجهة برمجة التطبيقات (API)

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

خذ حقن الأوامر (prompt injection) على سبيل المثال. يقوم مستخدم بتحميل ملف PDF يحتوي على تعليمات مخفية، يقرأها العامل، ويذهب استدعاء الأداة التالي إلى نقطة نهاية /admin/users الخاصة بك مع delete_all=true. لم يختر النموذج هذا؛ بل اتبع تعليمات لم يكن لديه سبب لعدم الثقة بها. الإصلاح ليس في تقوية الأمر (prompt). الإصلاح هو بناء واجهة برمجة تطبيقات لا تعرض delete_all=true لرمز جاء من جلسة سياق المستخدم. تسمي OWASP هذا LLM01 في قائمتها لأهم 10 مخاطر للنماذج اللغوية الكبيرة (LLM Top 10)، والحل هو تفويض من جانب واجهة برمجة التطبيقات، وليس هندسة الأوامر (prompt engineering).

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

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

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

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

حواجز الأمان الأربعة التي تحتاجها كل عملية تكامل بين العامل وواجهة برمجة التطبيقات

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

1. اختبارات عقد مخطط الأداة

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

إليك فحص Python بسيط يتحقق من صحة تعريف أداة على غرار Claude مقابل مواصفات OpenAPI المباشرة:

import json
from jsonschema import Draft202012Validator

def validate_tool_against_openapi(tool_def: dict, openapi_spec: dict) -> list[str]:
    """Return a list of mismatch errors, empty list = pass."""
    errors = []
    op = openapi_spec["paths"][tool_def["path"]][tool_def["method"].lower()]
    api_schema = op["requestBody"]["content"]["application/json"]["schema"]
    tool_schema = tool_def["input_schema"]

    api_props = set(api_schema.get("properties", {}).keys())
    tool_props = set(tool_schema.get("properties", {}).keys())

    for missing in api_props - tool_props:
        if missing in api_schema.get("required", []):
            errors.append(f"Tool missing required field: {missing}")
    for extra in tool_props - api_props:
        errors.append(f"Tool defines field not in API: {extra}")

    for prop, api_def in api_schema.get("properties", {}).items():
        if prop in tool_schema.get("properties", {}):
            tool_def_prop = tool_schema["properties"][prop]
            if api_def.get("type") != tool_def_prop.get("type"):
                errors.append(
                    f"Type mismatch on {prop}: API={api_def.get('type')} "
                    f"tool={tool_def_prop.get('type')}"
                )
    return errors

قم بتشغيل هذا على كل طلب سحب (PR) يمس مواصفات OpenAPI أو تعريفات الأدوات. أفشل عملية البناء إذا كانت القائمة غير فارغة. كان هذا الفحص الوحيد سيكتشف خطأ "العدد العشري مقابل السنتات" في القسم السابق قبل أشهر من صرف أي استرداد.

2. بيئات التجربة (Sandbox) والمحاكاة (Mock) لنقاط النهاية المدمرة

تحتاج العوامل إلى مكان للتدرب. لا ينبغي أن تتدرب أبدًا في بيئة الإنتاج. النمط مباشر: كل نقطة نهاية تغير الحالة لها مكافئ وهمي (mock equivalent) يعيد نفس شكل الاستجابة دون القيام بالعمل الفعلي. تستخدم حلقة تطوير العامل الخاص بك المحاكيات. تستخدم اختبارات التدريج قاعدة بيانات تجريبية (sandbox database). يبقى الإنتاج دون تغيير حتى يوافق إنسان على النشر.

يُنشئ Apidog محاكيات مباشرة من مواصفات OpenAPI، بما في ذلك قيم حقول واقعية مدفوعة بأنماط Faker. يمكنك توجيه عنوان URL الأساسي للعامل الخاص بك إلى الخادم الوهمي، وتشغيل مائة تكرار من طلبك، ومشاهدة كيفية تصرفه. إذا استمر العامل في محاولة PUT إلى /users/{id}/delete لأنه أساء فهم الوثائق، فإن المحاكي يلتقطه. جدول المستخدمين في الإنتاج لا يرى الخطأ أبدًا. انظر التطوير القائم على العقد أولاً للنمط الأوسع الذي يتناسب معه هذا.

3. مفاتيح التكرارية وعمليات الحذف الناعمة للعمليات غير القابلة للإلغاء

يجب أن تقبل كل نقطة نهاية كتابة يمكن لعامل الذكاء الاصطناعي استدعاءها مفتاح تكرارية (idempotency key). يجب أن تكون كل عملية حذف حذفًا ناعمًا (soft delete) بشكل افتراضي مع مسار حذف صعب (hard-delete) منفصل يصرح به البشر.

يبدو برنامج الوسيط (middleware) بهذا الشكل في Express:

const idempotencyCache = new Map();

function idempotency(req, res, next) {
  const key = req.headers['idempotency-key'];
  if (!key) {
    return res.status(400).json({ error: 'Missing Idempotency-Key header' });
  }
  if (idempotencyCache.has(key)) {
    const cached = idempotencyCache.get(key);
    return res.status(cached.status).json(cached.body);
  }
  const originalJson = res.json.bind(res);
  res.json = function (body) {
    idempotencyCache.set(key, { status: res.statusCode, body });
    setTimeout(() => idempotencyCache.delete(key), 24 * 60 * 60 * 1000);
    return originalJson(body);
  };
  next();
}

app.post('/payments', idempotency, createPayment);

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

4. حدود الميزانية لكل عامل

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

قد يقوم برنامج وسيط للميزانية يحيط ببوابة API الخاصة بك بتتبع:

• عدد الرموز لكل جلسة، بحد أقصى 50,000
• عدد استدعاءات API في الدقيقة، بحد أقصى 30
• الإنفاق التراكمي بالسنت، بحد أقصى 500
• عمق استدعاء الأداة، بحد أقصى 10 استدعاءات متداخلة

عند الوصول إلى أي حد، أرجع رمز HTTP 429 مع ترويسة Retry-After منظمة وترويسة X-Budget-Exceeded تسمي الحد. يمكن لمخطط العامل بعد ذلك إما التصعيد إلى إنسان أو التراجع عن المهمة. اجمع هذا مع التسجيل (logging) حتى تتمكن من رؤية العوامل التي تتجاوز الحدود وتعديلها وفقًا لذلك.

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

اختبار استدعاءات API للعامل باستخدام Apidog

الآن الجزء العملي. إليك كيفية إعداد سير عمل كامل لاختبار تكامل العامل مع واجهة برمجة التطبيقات (API) في Apidog. ستحتاج إلى مواصفات OpenAPI لواجهة برمجة التطبيقات التي يستدعيها العامل الخاص بك، بالإضافة إلى قائمة بتعريفات أدوات العامل.

الخطوة 1: استيراد مواصفات OpenAPI

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

الخطوة 2: تحديد استجابات وهمية لنقاط النهاية المدمرة

ابحث عن كل نقطة نهاية تُعدّل البيانات: POST, PUT, PATCH, DELETE. لكل منها، انقر فوق نقطة النهاية وأضف استجابة وهمية. يمكن لـ Apidog إنشاء محاكيات واقعية تلقائيًا من مخططك، ولكن يجب عليك تجاوز قيم الحقول بحيث تبدو كبيانات اختبار، وليس بيانات إنتاج. استخدم بادئات مثل mock_user_ وطوابع زمنية في عام 1970 بحيث يكون أي تسرب واضحًا في السجلات.

ابدأ تشغيل الخادم الوهمي. يمنحك Apidog عنوان URL ثابتًا مثل https://mock.apidog.com/m1/your-project-id/. وجّه عنوان URL الأساسي لواجهة برمجة التطبيقات الخاصة بعميلك إلى الخادم الوهمي أثناء التطوير. الآن يعيد DELETE /users/{id} رمز 200 مع حمولة مستخدم وهمية، وقاعدة بياناتك الحقيقية آمنة.

الخطوة 3: كتابة سيناريو يحاكي تسلسل استدعاء العميل

تتيح لك سيناريوهات Apidog ربط استدعاءات API مع تأكيدات، بنفس طريقة مجموعات الاختبار. بالنسبة لعامل يقوم بفرز تذاكر الدعم، قد يكون السيناريو:

1. POST /auth/token مع بيانات اعتماد الاختبار، والتقاط رمز حامل المفتاح (bearer token)
2. GET /tickets?status=open باستخدام الرمز، والتقاط معرف التذكرة الأول
3. POST /tickets/{id}/triage مع فئة، والتأكد من رمز 200 والتقاط حقل "معين إلى" (assigned-to)
4. POST /notifications مع رسالة قالبية، والتأكد من أن نص الرسالة يطابق تعبيرًا عاديًا (regex)

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

الخطوة 4: التشغيل من CI (التكامل المستمر)

يأتي Apidog مزودًا بواجهة سطر أوامر (CLI) تقوم بتشغيل السيناريوهات من GitHub Action أو GitLab pipeline أو أي مشغل CI. يبدو الأمر مثل apidog run -t scenario-id --env test. قم بربطه بخط أنابيب طلب السحب (PR) الخاص بك بحيث يؤدي كل تغيير في مواصفات OpenAPI أو تعريفات أدوات العامل إلى إعادة تشغيل كاملة للسيناريو.

الخطوة 5: مقارنة إصدارين من النموذج جنبًا إلى جنب

عند تقييم ما إذا كنت ستقوم بالترقية من نموذج إلى آخر، فأنت تريد معرفة ما إذا كانت استدعاءات أدوات النموذج الجديد تتصرف بنفس الطريقة في نفس السيناريوهات. قم بتشغيل العامل مقابل نفس سيناريو Apidog مع النموذج A، والتقط التتبع. قم بالتشغيل مرة أخرى مع النموذج B، والتقط التتبع. قارن نصوص الطلبات. تظهر المفاجآت على الفور: النموذج B يمرر قيمة priority مختلفة، أو يحذف حقلاً، أو يستخدم تنسيقًا مختلفًا للتواريخ. تلتقط الانحراف السلوكي قبل أن يتم نشره. هذا أحد الأنماط التي تمت تغطيتها في تكامل API GPT-5.5، حيث يعد تقييم سلوك النموذج الجديد حاجة متكررة.

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

تقنيات متقدمة ونصائح احترافية

بعض الأنماط التي تلجأ إليها الفرق ذات الخبرة بعد تطبيق الأساسيات.

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

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

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

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

استخدم رمز HTTP 423 Locked لنقاط النهاية التي تتطلب موافقة بشرية. عندما يحاول عامل استدعاء نقطة نهاية تتطلب تأكيدًا بشريًا، أرجع رمز 423 مع حقل confirmation_url. يرى مخطط العامل الحالة المقفلة، ويعرض عنوان URL على إنسان، وينتظر. هذا أنظف من 403، لأن 403 تعني "لا يمكنك فعل ذلك" بينما 423 تعني "لا يمكنك فعل ذلك بعد".

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

الأخطاء الشائعة التي يجب تجنبها:

• ترميز عنوان URL الوهمي (mock URL) بشكل ثابت في أوامر العميل. استخدم متغيرات البيئة بحيث يتم تشغيل نفس الأمر مقابل بيئات المحاكاة والتدريج والإنتاج.
• تجاهل خاصية التكرارية (idempotency) في نقاط النهاية "الصغيرة". كل عملية كتابة تحتاج إليها. إرسال البريد الإلكتروني ليس استثناءً.
• تسجيل نصوص الطلبات الكاملة في الإنتاج. تتسرب معلومات التعريف الشخصية (PII) إلى مكدس المراقبة الخاص بك. قم بحذف الرموز ورسائل البريد الإلكتروني والمعرفات قبل أن تصل إلى السجلات.
• السماح للعوامل بالوصول المباشر إلى قاعدة البيانات. دائمًا مر عبر واجهة برمجة التطبيقات (API). واجهة برمجة التطبيقات هي المكان الذي تعيش فيه اختباراتك.
• الثقة في درجة ثقة العامل. تعكس النتيجة يقين النموذج بشأن الإجابة، وليس أمان واجهة برمجة التطبيقات. يمكن لعامل واثق بنسبة 99 بالمائة أن يستدعي نقطة النهاية الخطأ.

إذا كان عامل الذكاء الاصطناعي الخاص بك يتحدث إلى خدمات داخلية ليست خلف بوابة API واحدة، فإن أنماط اختبار الخدمات المصغرة تغطي كيفية توزيع اختبارات السيناريو عبر الخدمات.

البدائل والأدوات

لديك خيارات. إليك مقارنة عادلة بين الأساليب الأربعة الشائعة.

الملخص الصادق: إذا كنت تستخدم LangSmith، استمر في فعل ما ينجح من جانب العميل وأضف طبقة اختبار API منفصلة. إذا تجاوزت أسعار Postman أو نموذج المحاكاة الخاص به، فإن Apidog هو بديل قوي. إذا كنت تبدأ من جديد، فاختر الأداة التي تتعامل مع OpenAPI والمحاكاة والسيناريوهات في مشروع واحد، لأن هذا هو المكان الذي يذهب فيه 80 بالمائة من وقت اختبار تكامل العميل مع واجهة برمجة التطبيقات.

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

حالات استخدام واقعية

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

عامل يستدعي واجهة برمجة تطبيقات المدفوعات. وضع فريق تقنيات مالية يبني عاملًا آليًا لاسترداد الأموال حدودًا صارمة: بحد أقصى 5 عمليات استرداد لكل جلسة، بحد أقصى 50 دولارًا لكل عملية استرداد، وتطلب خاصية التكرارية (idempotency) في كل استدعاء. قاموا بتشغيل مجموعة اختبارات العقد ضد OpenAPI لـ Stripe في كل طلب سحب (PR). بعد ستة أشهر، قاموا بمعالجة 12,000 عملية استرداد بدون رسوم مكررة.

عامل يفرز مشكلات GitHub. بنى فريق المنصة عاملًا لفرز المشكلات مستوحى من Clawsweeper. قاموا بمحاكاة GitHub API في Apidog، وشغلوا العامل خلال 50 اختبار سيناريو تغطي الحالات الهامشية (المشكلات المحذوفة، التسميات المفقودة، إدخال المستخدم المشوه)، ووجدوا ثلاثة أعطال قبل الإطلاق. يتعامل العامل الآن مع الفرز في مستودع عام يحتوي على 5,000 مشكلة مفتوحة.

الخلاصة

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

خمس نقاط رئيسية:

• تعامل مع مخططات الأدوات كعقود وقم بتشغيل اختبارات العقود في CI.
• قم بمحاكاة نقاط النهاية المدمرة لكل حلقة تطوير عامل.
• اطلب مفاتيح التكرارية (idempotency keys) على كل عملية كتابة يمكن لعامل الذكاء الاصطناعي استدعاءها.
• ضع حدود ميزانية لكل عامل تفشل بشكل مغلق عند تجاوزها.
• أعد تشغيل السيناريوهات على كل طلب سحب (PR) يمس واجهة برمجة التطبيقات أو تعريفات الأدوات.

لن تكون الحوادث الفيروسية هذا العام هي الأخيرة. كل فريق يقوم بنشر عملاء سيواجه أحد أوضاع الفشل هذه على الأقل مرة واحدة. الفرق التي تتعافى بسرعة هي الفرق التي كانت لديها حواجز الأمان بالفعل. قم بتنزيل Apidog وابدأ بخطوة الخادم الوهمي؛ وهذا وحده سيوفر عليك ليلة بلا نوم هذا الربع. للحصول على منظور فريق ضمان الجودة حول هذه المشكلة نفسها، راجع أدوات اختبار API لمهندسي ضمان الجودة. للحصول على سياق أوسع حول كتابة تعريفات الأدوات التي يمكن للعملاء استخدامها بأمان، راجع كيفية كتابة ملفات AGENTS.md.

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

كيف يمكنني اختبار استدعاءات API لعوامل الذكاء الاصطناعي دون إنفاق المال على الرموز؟

شغّل عميلك مقابل خادم وهمي أثناء التطوير. تُرجع عناوين URL الوهمية لـ Apidog استجابات واقعية مجانًا، لذا لن تستهلك حلقات الاختبار الخاصة بك رصيد API حقيقي. ثبت درجة الحرارة عند 0 واستخدم مجموعة أوامر ثابتة صغيرة. يمكنك تشغيل آلاف من تكرارات الاختبار بتكلفة الخادم الوهمي، وهي صفر. راجع قائمة التحقق لاختبار مهندس ضمان الجودة للإعداد الكامل.

ما الفرق بين اختبار العميل واختبار واجهة برمجة التطبيقات (API)؟

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

هل أحتاج إلى مفاتيح التكرارية (idempotency keys) على كل نقطة نهاية؟

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

كيف أمنع حقن الأوامر (prompt injection) من تشغيل استدعاءات API سيئة؟

لا تعتمد على طبقة الأوامر وحدها. يجب أن تفرض واجهة برمجة التطبيقات التفويض بناءً على سياق المستخدم الأصلي، وليس طلب العامل. إذا لم تتمكن جلسة سياق المستخدم عادةً من استهداف /admin/delete-all-users، فلا ينبغي للعامل الذي يتصرف نيابة عن هذا المستخدم أن يتمكن من ذلك أيضًا، بغض النظر عما يقوله الأمر. تغطي قائمة OWASP لأهم 10 مخاطر للنماذج اللغوية الكبيرة (LLM Top 10) هذا بالتفصيل.

هل يمكنني استخدام Apidog مع Claude أو GPT مباشرة، دون كتابة طبقة أدوات خاصة بي؟

توجه تعريفات أدوات العامل الخاص بك إلى عنوان URL الوهمي (mock URL) لـ Apidog أثناء الاختبار. يدعم كل من Claude و GPT عناوين URL أساسية HTTP عشوائية في تعريفات أدواتهما، لذا فإن التبديل يتم عبر متغير بيئة واحد. عندما تكون جاهزًا للاختبار مقابل بيئة التدريج أو الإنتاج، قم بتغيير المتغير.

ما هو الحد الأقصى الصحيح لميزانية العامل؟

ابدأ صارمًا وتخفف مع البيانات. ابدأ بـ 50,000 رمز لكل جلسة، 30 استدعاء API في الدقيقة، 5 دولارات لكل مهمة. راقب المقاييس لمدة أسبوعين. ارفع الحدود التي تصطدم بها بشكل مشروع. خفض الحدود التي لم تصل إليها أبدًا. راجع شهريًا. الهدف ليس رقمًا ثابتًا؛ بل هو رقم محكم بما يكفي لالتقاط الحلقات الجامحة ومريح بما يكفي للسماح بالعمل الحقيقي بالحدوث.

كيف أكتشف انحراف المخطط بين أدوات العامل الخاص بي وواجهة برمجة التطبيقات الخاصة بي؟

شغّل مقارنة مخطط (schema diff) في CI على كل طلب سحب (PR). قارن تعريف أداة العامل (مخطط JSON) مقابل مخطط نص طلب OpenAPI لنقطة النهاية نفسها. أفشل عملية البناء إذا تباعدا. يقوم مقتطف Python المكون من 30 سطرًا في قسم حواجز الأمان أعلاه بذلك؛ انسخه إلى مستودعك وقم بدمجه في GitHub Actions.