DEV Community

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

Posted on • Originally published at apidog.com

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

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

جرّب Apidog اليوم

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

الخلاصة

تفشل الوكلاء في الإنتاج عندما تكون أدواتها متصلة بـ APIs بلا حواجز أمان: لا حدود معدل، لا idempotency، عمليات حذف مباشرة، أو مخططات أدوات منحرفة عن OpenAPI.

الإصلاح العملي:

  1. اختبر تعريفات أدوات الوكيل مقابل مواصفات OpenAPI.
  2. شغّل mock server لنقاط النهاية المدمرة.
  3. أضف idempotency keys وحدود ميزانية لكل وكيل.
  4. أعد تشغيل سيناريوهات الفشل في CI.

يوفر لك Apidog استيراد OpenAPI، والمحاكاة، وتشغيل السيناريوهات من مكان واحد.

مقدمة

اختبار وكيل ذكاء اصطناعي لم يعد يعني فقط كتابة prompt جيد ومراجعة الإجابة. الوكلاء اليوم يستدعون أدوات، والأدوات تستدعي APIs، والـ APIs قد تصل إلى قواعد بيانات إنتاج، أنظمة دفع، أو خدمات طرف ثالث.

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

الفكرة الأساسية في هذا المقال:

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

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

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

عند تحليل حوادث الوكلاء، يظهر نمط ثابت: الوكيل غالبًا ينفذ بالضبط ما تسمح به واجهة API.

1. Prompt injection يصل إلى API إدارية

مثال:

  • مستخدم يرفع PDF يحتوي على تعليمات مخفية.
  • الوكيل يقرأها.
  • الاستدعاء التالي يذهب إلى /admin/users مع delete_all=true.

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

هذا يتوافق مع مخاطر OWASP LLM Top 10: التفويض يجب أن يُفرض في طبقة API، لا في prompt.

2. مخطط أداة لا يطابق OpenAPI

مثال:

  • OpenAPI يقول إن amount عدد صحيح بالسنتات.
  • تعريف أداة الوكيل يقول إن amount رقم عشري بالدولار.
  • الوكيل يرسل 19.
  • النظام يفسرها كـ 19 دولارًا بدل 19 سنتًا.

النموذج لم يخترع الخطأ. هو استخدم المخطط الذي أعطيته له.

3. لا توجد حدود معدل

وكيل يدخل حلقة retry ويستدعي API البريد الإلكتروني ألف مرة خلال دقيقتين. كل استدعاء يكلف مالًا وقد يرسل بريدًا حقيقيًا.

الخطأ هنا ليس "النموذج سيئ". الخطأ أن endpoint لا يملك سقفًا.

4. لا توجد idempotency

الوكيل يستدعي:

POST /payments
Enter fullscreen mode Exit fullscreen mode

ثم يحصل timeout. يعيد المحاولة. العميل يُخصم منه مرتين.

الوكيل لا يستطيع معرفة هل نجح الطلب الأول أم لا. API يجب أن توفر Idempotency-Key.

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

ابدأ بهذه الضوابط الأربعة. إذا طبقتها، ستغطي معظم أنماط الفشل الواقعية.

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

اجعل OpenAPI مصدر الحقيقة. ثم افحص تعريفات أدوات الوكيل ضدها في CI.

مثال Python مبسط:

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
Enter fullscreen mode Exit fullscreen mode

شغّل هذا الفحص عند كل Pull Request يغير:

  • ملف OpenAPI
  • تعريفات أدوات الوكيل
  • مخططات request/response

مثال GitHub Actions:

name: agent-api-contracts

on:
  pull_request:
    paths:
      - "openapi.yaml"
      - "agent/tools/**"

jobs:
  contract-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - run: pip install jsonschema pyyaml
      - run: python scripts/validate_agent_tools.py
Enter fullscreen mode Exit fullscreen mode

القاعدة: إذا انحرف تعريف الأداة عن OpenAPI، افشل البناء.

2. Sandbox و mock server لنقاط النهاية المدمرة

أي endpoint يغير الحالة يجب ألا يُختبر مباشرة في الإنتاج.

صنّف endpoints حسب الخطورة:

النوع أمثلة بيئة الاختبار
قراءة فقط GET /users, GET /tickets mock أو staging
كتابة قابلة للعكس PATCH /profile sandbox
كتابة مالية POST /payments, POST /refunds sandbox مع حدود صارمة
حذف DELETE /users/{id} mock فقط أثناء تطوير الوكيل

ينشئ Apidog محاكيات من OpenAPI. يمكنك تشغيل mock server ثم توجيه الوكيل إليه بدل الإنتاج.

اقرأ أيضًا: التطوير القائم على العقد أولاً.

3. مفاتيح idempotency وعمليات حذف ناعمة

كل عملية كتابة يمكن أن يستدعيها وكيل يجب أن تقبل Idempotency-Key.

مثال 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);
Enter fullscreen mode Exit fullscreen mode

من جهة الوكيل:

import { randomUUID } from "crypto";

async function createPayment(payment) {
  const idempotencyKey = randomUUID();

  return fetch("https://api.example.com/payments", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Idempotency-Key": idempotencyKey
    },
    body: JSON.stringify(payment)
  });
}
Enter fullscreen mode Exit fullscreen mode

أما الحذف، فاجعله soft delete افتراضيًا:

UPDATE users
SET deleted_at = NOW()
WHERE id = $1;
Enter fullscreen mode Exit fullscreen mode

ولا تجعل hard delete متاحًا للوكيل مباشرة. اجعله خلف موافقة بشرية أو مسار إداري منفصل.

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

كل وكيل يحتاج ميزانية. عندما تنتهي، يتوقف.

ضع حدودًا مثل:

  • عدد الرموز لكل جلسة: 50,000
  • عدد استدعاءات API في الدقيقة: 30
  • تكلفة بالدولار لكل مهمة: 5
  • عمق استدعاء الأدوات: 10

عند تجاوز الحد، أعد:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-Budget-Exceeded: api_calls_per_minute
Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode 
{
  "error": "budget_exceeded",
  "limit": "api_calls_per_minute",
  "action": "escalate_to_human"
}
Enter fullscreen mode Exit fullscreen mode

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

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

إليك سير عمل عملي يمكنك نسخه.

ستحتاج إلى:

  • ملف OpenAPI 3.x
  • تعريفات أدوات الوكيل
  • بيئة test أو staging
  • حساب في Apidog

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

في Apidog:

  1. أنشئ مشروعًا جديدًا.
  2. اختر استيراد OpenAPI.
  3. ارفع openapi.yaml أو openapi.json.
  4. راجع endpoints والمخططات والأمثلة.

إذا لم يكن لديك OpenAPI بعد، ابدأ من التصميم أولًا. هذا الدليل مفيد: دليل سير عمل API بتصميم أولاً.

الخطوة 2: إنشاء mock responses للعمليات الخطرة

ابحث عن كل endpoint من الأنواع:

  • POST
  • PUT
  • PATCH
  • DELETE

ثم أنشئ response وهمي.

نصيحة عملية: استخدم بيانات اختبار واضحة:

{
  "id": "mock_user_123",
  "email": "mock_user_123@example.test",
  "deleted_at": "1970-01-01T00:00:00Z"
}
Enter fullscreen mode Exit fullscreen mode

الهدف أن يظهر أي تسرب فورًا في السجلات.

بعد تشغيل mock server، ستحصل على URL مشابه:

https://mock.apidog.com/m1/your-project-id/
Enter fullscreen mode Exit fullscreen mode

ثم اجعل الوكيل يستخدمه عبر متغير بيئة:

AGENT_API_BASE_URL=https://mock.apidog.com/m1/your-project-id/
Enter fullscreen mode Exit fullscreen mode

لا تضع URL الوهمي مباشرة داخل prompt أو الكود.

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

مثال لوكيل يفرز تذاكر الدعم:

  1. POST /auth/token
  2. GET /tickets?status=open
  3. POST /tickets/{id}/triage
  4. POST /notifications

أضف assertions في كل خطوة:

  • status code يساوي 200
  • response يحتوي الحقول المطلوبة
  • القيم ضمن enum المتوقع
  • نص الرسالة يطابق regex

مثال assertion منطقي:

pm.test("triage category is valid", function () {
  const body = pm.response.json();
  pm.expect(["billing", "bug", "account"]).to.include(body.category);
});
Enter fullscreen mode Exit fullscreen mode

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

للمزيد: اختبار API لمهندسي ضمان الجودة.

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

اجعل كل PR يغير API أو أدوات الوكيل يعيد تشغيل السيناريوهات.

مثال أمر:

apidog run -t scenario-id --env test
Enter fullscreen mode Exit fullscreen mode

مثال pipeline:

name: apidog-scenarios

on:
  pull_request:
    paths:
      - "openapi.yaml"
      - "agent/tools/**"
      - "src/api/**"

jobs:
  api-scenarios:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Apidog scenarios
        run: apidog run -t ${{ secrets.APIDOG_SCENARIO_ID }} --env test
Enter fullscreen mode Exit fullscreen mode

الهدف: أي تغيير يكسر سيناريو الوكيل يفشل قبل الوصول إلى الإنتاج.

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

عند الترقية من نموذج إلى آخر:

  1. شغّل الوكيل بالنموذج A ضد نفس سيناريو Apidog.
  2. خزّن trace لاستدعاءات الأدوات.
  3. شغّل الوكيل بالنموذج B.
  4. قارن request bodies.

ابحث عن اختلافات مثل:

  • حقل ناقص
  • enum مختلف
  • تنسيق تاريخ مختلف
  • قيمة priority غير متوقعة
  • استدعاءات إضافية غير ضرورية

هذا النمط مهم عند تقييم نماذج جديدة، كما في تكامل API لـ GPT-5.5.

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

ثبّت درجة الحرارة على صفر أثناء الاختبارات

عند اختبار tool calling، لا تختبر الإبداع. اختبر السلوك.

استخدم:

{
  "temperature": 0
}
Enter fullscreen mode Exit fullscreen mode

واجعل مجموعة prompts ثابتة.

التقط traces لاستدعاءات الأدوات

سجل لكل تشغيل:

{
  "tool": "create_refund",
  "arguments": {
    "payment_id": "pay_123",
    "amount": 1900
  },
  "timestamp": "2026-01-01T10:00:00Z"
}
Enter fullscreen mode Exit fullscreen mode

ثم قارنها مع baseline.

إذا بدأ الوكيل يستدعي /users مرتين بدل مرة واحدة، يجب أن تعرف ذلك في CI، لا عند وصول الفاتورة.

لا تمنح الوكيل بيانات اعتماد الإنتاج

استخدم service accounts محددة الصلاحيات.

قاعدة جيدة:

المهمة نوع المفتاح
قراءة بيانات read-only
تعديل محدود scoped write
عمليات مالية write + approval
حذف دائم human-only

افصل مفاتيح القراءة عن الكتابة

معظم مهام الوكلاء read-heavy. لا تعطيها مفتاح كتابة إن لم تكن تحتاجه.

استخدم HTTP 423 للعمليات التي تحتاج موافقة بشرية

بدل 403 Forbidden، أعد:

HTTP/1.1 423 Locked
Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode 
{
  "error": "human_confirmation_required",
  "confirmation_url": "https://app.example.com/approve/req_123"
}
Enter fullscreen mode Exit fullscreen mode

هذا يخبر الوكيل أن العملية ليست ممنوعة نهائيًا، لكنها تحتاج تأكيدًا.

افشل عند انحراف المخطط

لا تجعل schema drift مجرد warning. اجعله error.

تكلفة build فاشل أقل بكثير من حادث إنتاج.

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

  • ترميز mock URL مباشرة في prompt أو الكود.
  • تخطي idempotency في endpoints "الصغيرة".
  • تسجيل request bodies كاملة في الإنتاج.
  • السماح للوكلاء بالوصول المباشر إلى قاعدة البيانات.
  • الثقة في confidence score الخاص بالنموذج كدليل أمان.
  • استخدام نفس API key للقراءة والكتابة.
  • تشغيل اختبارات الوكيل ضد production endpoints.

إذا كانت خدماتك موزعة على microservices، راجع أنماط اختبار الخدمات المصغرة.

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

لديك عدة أساليب لاختبار تكامل الوكيل مع API.

النهج وقت الإعداد القوة الضعف الأفضل لـ
اختبارات وحدة مخصصة منخفض تحكم كامل صيانة عالية وقد تنحرف عن API الحقيقي المشاريع الصغيرة
LangSmith / LangGraph evals متوسط ممتازة لتتبع سلوك الوكيل تركيز أقل على طبقة API فرق AI التي تركز على التقييم
Postman + Postbot متوسط واجهة مألوفة وقوالب كثيرة المحاكاة قد تكون إضافة مدفوعة وسيناريوهاتها أقل حداثة فرق تستخدم Postman بالفعل
Apidog scenarios + mocks متوسط OpenAPI، محاكيات، وسيناريوهات CI في مشروع واحد أقل شهرة من Postman فرق تريد أداة واحدة للتصميم والاختبار والمحاكاة

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

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

وكيل يحدث صفوف قاعدة بيانات الإنتاج

فريق دعم العملاء بنى وكيلًا يحدّث حقول الحسابات من تذاكر الدعم.

قبل الإطلاق:

  • أضافوا Idempotency-Key لكل endpoint كتابة.
  • شغّلوا 200 replay في Apidog ضد قاعدة بيانات sandbox.
  • اكتشفوا أن الوكيل يحاول أحيانًا ضبط subscription_status إلى قيمة غير موجودة في enum.

الإصلاح:

  • أضافوا schema validation.
  • منعوا القيم غير المعروفة.
  • أطلقوا الوكيل دون حادث.

وكيل يستدعي API مدفوعات

فريق fintech بنى وكيل refunds.

القيود:

  • 5 عمليات refund كحد أقصى لكل جلسة.
  • 50 دولارًا كحد أقصى لكل refund.
  • idempotency مطلوبة في كل طلب.
  • اختبارات عقد ضد OpenAPI في كل PR.

استخدموا مجموعة اختبارات العقد لضبط الانحراف مبكرًا.

وكيل يفرز مشكلات GitHub

فريق منصة بنى وكيل triage مستوحى من Clawsweeper.

ما فعلوه:

  • حاكوا GitHub API في Apidog.
  • شغلوا 50 سيناريو يغطي:
    • issues محذوفة
    • labels مفقودة
    • إدخال مستخدم مشوه
    • permissions غير كافية
  • أصلحوا 3 أعطال قبل الإطلاق.

الخلاصة

إذا أخذت فكرة واحدة فقط، فلتكن هذه:

الوكيل ليس المشكلة دائمًا. API هي المشكلة أو الحل، حسب ما إذا كنت اختبرتها.

قائمة التنفيذ المختصرة:

  • عامل tool schemas كعقود.
  • شغّل contract tests في CI.
  • استخدم mock server لكل endpoint مدمر.
  • أضف Idempotency-Key لكل write operation.
  • ضع budget limits لكل وكيل.
  • افصل read keys عن write keys.
  • أعد تشغيل سيناريوهات الوكيل في كل PR.

ابدأ بخطوة واحدة: قم بتنزيل Apidog وأنشئ mock server لأول endpoint خطير لديك. هذا وحده قد يمنع حادثًا هذا الربع.

للمزيد:

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

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

شغّل الوكيل ضد mock server أثناء التطوير. يعيد Apidog استجابات واقعية من OpenAPI دون استدعاء خدمات حقيقية. ثبّت temperature على 0 واستخدم مجموعة prompts صغيرة وثابتة. راجع قائمة التحقق لاختبار مهندس ضمان الجودة.

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

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

اختبار API يتحقق هل endpoint نفسها تتصرف بشكل صحيح عند استدعائها.

تحتاج الاثنين. وكيل ممتاز يستدعي API معطوبة سينتج خطأ. وAPI ممتازة لا تمنع وكيلًا يرسل مدخلات خاطئة إن لم تكن لديها validation.

هل أحتاج idempotency keys على كل endpoint؟

على كل endpoint كتابة: نعم.

عمليات القراءة idempotent بطبيعتها. عمليات الكتابة ليست كذلك. والوكلاء يعيدون المحاولة.

كيف أمنع prompt injection من تشغيل استدعاءات API خطيرة؟

لا تعتمد على prompt فقط. API يجب أن تفرض التفويض بناءً على سياق المستخدم الأصلي.

إذا لم يكن المستخدم قادرًا على استدعاء:

POST /admin/delete-all-users
Enter fullscreen mode Exit fullscreen mode

فلا يجب أن يستطيع الوكيل استدعاءها نيابة عنه، مهما كانت التعليمات داخل prompt أو ملف مرفوع.

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

نعم من حيث النمط العام: اجعل تعريفات الأدوات تستخدم base URL قابلًا للتبديل عبر environment variable.

مثال:

AGENT_API_BASE_URL=https://mock.apidog.com/m1/project-id/
Enter fullscreen mode Exit fullscreen mode

وعند الانتقال إلى staging:

AGENT_API_BASE_URL=https://staging-api.example.com
Enter fullscreen mode Exit fullscreen mode

ما حد الميزانية المناسب للوكيل؟

ابدأ بصرامة ثم عدّل بالأرقام.

نقطة بداية عملية:

  • 50,000 token لكل جلسة
  • 30 API call في الدقيقة
  • 5 دولارات لكل مهمة
  • 10 tool calls متداخلة

راقب أسبوعين، ثم ارفع الحدود التي تُستخدم بشكل مشروع وخفّض الحدود التي لا تُستخدم.

كيف أكتشف schema drift بين أدوات الوكيل وAPI؟

شغّل مقارنة بين JSON schema الخاص بتعريف الأداة وrequest schema في OpenAPI داخل CI. إذا اختلف النوع، الحقول المطلوبة، أو enum، افشل البناء. مقتطف Python في قسم "اختبارات عقد مخطط الأداة" يكفي كبداية ويمكن ربطه مباشرة بـ GitHub Actions.

Top comments (0)