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

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

الخلاصة

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

مقدمة

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

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

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

لماذا تبدو إخفاقات الوكيل كأنها إخفاقات API

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

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

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

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

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

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

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

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

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

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

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 أو تعريفات الأداة. اجعل عملية البناء تفشل إذا لم تكن القائمة فارغة. هذا الفحص الواحد كان سيكشف خطأ التضارب بين (float-vs-cents) في القسم السابق قبل أشهر من إرسال أي رد أموال.

2. بيئات Sandbox والوهمية لنقاط النهاية المدمرة

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

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

3. مفاتيح استقلالية وعمليات حذف ناعمة للعمليات غير القابلة للتراجع

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

البرمجيات الوسيطة تبدو هكذا في 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 لكل عملية منطقية ويعيد استخدامه عند إعادة المحاولة. تُعيد واجهة برمجة التطبيقات (API) الخاصة بك الاستجابة المخزنة مؤقتًا في الاستدعاء الثاني بدلاً من فرض الرسوم مرتين. يحمي هذا النمط نفسه من الإرسالات المزدوجة في واجهات برمجة تطبيقات المراسلة، وإنشاء صفوف مكررة في أنظمة إدارة علاقات العملاء (CRMs)، ومعظم سيناريوهات "أعاد الوكيل المحاولة والآن لدينا فوضى" الأخرى.

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

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

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

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

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

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

اختبار استدعاءات API لوكلاء الذكاء الاصطناعي باستخدام Apidog

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

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

افتح Apidog، أنشئ مشروعًا جديدًا، واستورد ملف OpenAPI 3.x الخاص بك. يحلل Apidog كل مسار ومخطط ومثال وينشئ نقاط نهاية مقابلة في المشروع. إذا لم تكن واجهة برمجة التطبيقات (API) الخاصة بك موثقة في 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.
2. GET /tickets?status=open باستخدام الرمز المميز، والتقاط معرف أول تذكرة.
3. POST /tickets/{id}/triage مع فئة، وتأكيد 200 والتقاط حقل "مُعيّن إلى".
4. POST /notifications برسالة قالبية، وتأكيد أن نص الرسالة يتطابق مع تعبير عادي (regex).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

الخلاصة

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

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

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

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

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

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

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

ما الفرق بين اختبار الوكيل واختبار API؟

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

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

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

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

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

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

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

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

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

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

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