كيفية اختبار استدعاءات أدوات وكيل الذكاء الاصطناعي بـ Apidog قبل تعطلها في بيئة الإنتاج

يعتمد موثوقية عامل الذكاء الاصطناعي (AI agent) على موثوقية واجهات برمجة التطبيقات (APIs) التي يستدعيها. يختار النموذج أداة، يملأ الوسائط، ويرسل طلباً؛ إذا فشل هذا الطلب، أو أعاد شكلاً خاطئاً، أو توقف، فإن عامل الذكاء الاصطناعي الخاص بك يتخذ قراراً واثقاً بناءً على بيانات سيئة. تتجاهل معظم عروض العوامل هذا الجزء. تعتمد العوامل الإنتاجية عليها بشكل كامل.

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

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

إذا تجردنا من التفاصيل، فإن حلقة العامل بسيطة:

1. يتلقى النموذج هدف المستخدم وقائمة من الأدوات.
2. يعيد استدعاء أداة: اسم أداة بالإضافة إلى وسائط JSON.
3. يقوم الكود الخاص بك بتنفيذ هذا الاستدعاء؛ عادةً ما يكون طلب HTTP إلى واجهة برمجة تطبيقات معينة.
4. تعود النتيجة إلى النموذج.
5. يقوم النموذج إما باستدعاء أداة أخرى أو يقدم إجابة.

يحدث كل فشل مهم في الخطوتين 3 و 4. فقد يهلوِس النموذج وسيطة، أو تعيد واجهة برمجة التطبيقات (API) رمز 422، أو ينحرف مخطط الاستجابة، أو تنتهي مهلة الاستدعاء، أو يتم تفعيل حد المعدل في منتصف الحلقة. إذا كنت قد قرأت عن عوامل الذكاء الاصطناعي كمستهلكين جدد لواجهات برمجة التطبيقات (APIs)، فهذه هي النسخة الملموسة لتلك الفكرة: عامل الذكاء الاصطناعي الخاص بك هو عميل يستخدم واجهات برمجة التطبيقات الخاصة بك، ويستحق نفس الدقة في الاختبار مثل أي عميل آخر.

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

الخطوة 1: تصميم الأدوات كعمليات واجهة برمجة تطبيقات حقيقية

قبل أن تكتب سطراً واحداً من كود العامل، حدد كل أداة كنقطة نهاية لواجهة برمجة التطبيقات (API endpoint) في Apidog. تعامل مع مخطط الأداة ومخطط واجهة برمجة التطبيقات على أنهما الشيء نفسه، لأنهما كذلك بالفعل. تشترك أداة get_weather ونقطة النهاية GET /weather في عقد: نفس المعلمات، نفس شكل الاستجابة.

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

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

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

الخطوة 2: محاكاة الأدوات لتتمكن من البناء دون اتصال بالإنترنت

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

يغير هذا طريقة بناء العوامل. يمكنك:

• تطوير حلقة العامل الكاملة قبل وجود واجهات برمجة التطبيقات (APIs) الحقيقية، مقابل عمليات محاكاة تتطابق مع العقد المتفق عليه.
• تشغيل اختبارات التكامل في CI لا تلامس نقطة نهاية مدفوعة أبدًا.
• فرض استجابات محددة؛ نتيجة فارغة، رمز 500، حقل مشوه؛ لمعرفة كيفية تفاعل العامل الخاص بك.

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

الخطوة 3: توصيل العامل لاستدعاء الأدوات

مع وجود نقاط النهاية والمحاكيات في مكانها، يظل كود العامل بسيطًا. إليك شكل حلقة استدعاء الأداة باستخدام Claude Messages API؛ تعكس تعريفات الأداة المخططات التي قمت ببنائها في Apidog.

import anthropic, requests, os

client = anthropic.Anthropic()
TOOL_BASE = os.environ["TOOL_BASE_URL"]  # Apidog mock during dev, real API in prod

tools = [{
    "name": "get_weather",
    "description": "Get current weather for a city",
    "input_schema": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"],
    },
}]

def run_tool(name, args):
    if name == "get_weather":
        r = requests.get(f"{TOOL_BASE}/weather", params={"city": args["city"]}, timeout=10)
        r.raise_for_status()
        return r.json()

messages = [{"role": "user", "content": "What should I wear in Tokyo today?"}]
while True:
    resp = client.messages.create(
        model="claude-fable-5", max_tokens=1024, tools=tools, messages=messages
    )
    if resp.stop_reason == "tool_use":
        block = next(b for b in resp.content if b.type == "tool_use")
        result = run_tool(block.name, block.input)
        messages.append({"role": "assistant", "content": resp.content})
        messages.append({"role": "user", "content": [{
            "type": "tool_result", "tool_use_id": block.id,
            "content": str(result),
        }]})
    else:
        print(resp.content[0].text)
        break

تُعد أسطر timeout=10 و raise_for_status() أهم من استدعاء النموذج. إنها الفرق بين عامل يفشل بوضوح وآخر يغذي طلبًا معلقًا أو خاطئًا بصمت مرة أخرى في الحلقة. للحصول على نظرة أوسع حول كيفية ملاءمة العوامل لسير عمل واجهة برمجة التطبيقات، تُعد الأنماط الموجودة في 5 عوامل ذكاء اصطناعي لسير عمل واجهة برمجة التطبيقات الخاصة بك رفيقًا مفيدًا.

الخطوة 4: اختبار استدعاءات الأدوات، وليس فقط التوقعات

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

لكل نقطة نهاية أداة، تأكد مما يلي:

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

ثم اختبر المسارات غير السعيدة، لأن هذا هو المكان الذي تسلك فيه العوامل سلوكًا خاطئًا:

• أرسل الوسائط المشوهة التي قد يهلوِسها النموذج؛ city فارغة، رقم حيث ينتمي نص؛ وتأكد من حصولك على 400/422 نظيف، وليس 500.
• اجبر استجابة خطأ من المحاكاة وتأكد من أن run_tool الخاص بالعامل يثير استثناءً بدلاً من إعادة بيانات غير مرغوب فيها.
• اختبر نتيجة فارغة وتحقق من أن العامل يتعامل مع "لا توجد بيانات" بدلاً من اختراع إجابة.

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

الخطوة 5: التعامل مع عمليات إعادة المحاولة، والمهلات، وحدود المعدل

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

• المهلات (Timeouts). عيّن مهلة صريحة على كل طلب أداة، كما في المثال أعلاه. ثم استخدم Apidog لمحاكاة نقطة نهاية بطيئة وتأكد من أن عميلك يتخلى عن الطلب بشكل نظيف بدلاً من تعليق الحلقة بأكملها.
• إعادة المحاولة مع التراجع (Retries with backoff). أعد محاولة الفشل المؤقت، ولكن حدد العدد وتراجع. اختبر ذلك مقابل محاكاة تفشل مرتين ثم تنجح، وتأكد من أن العامل الخاص بك يتعافى بدلاً من الدوران إلى الأبد.
• حدود المعدل (Rate limits). توقع ظهور 429s تحت الضغط. حاكِ استجابة محدودة المعدل وتحقق من أن عامل الذكاء الاصطناعي ينتظر ويعيد المحاولة بدلاً من الإفراط في الطلبات. إذا كنت قد تعاملت مع هذا في واجهات برمجة تطبيقات النموذج الخام؛ انظر حدود معدل واجهة برمجة تطبيقات GPT لنفس الفئة من المشاكل؛ فإن نسخة العامل تكون أكثر صرامة لأن الحلقة تضاعف كل استدعاء.
• قاطع الدائرة (Circuit breaking). بعد N فشل في أداة، توقف عن استدعائها ودع العامل يبلغ عن الفشل بدلاً من الدوران. اختبر أن قاطع الدائرة يعمل.

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

الخطوة 6: تشغيله من البداية إلى النهاية مقابل المحاكيات في CI

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

قائمة تحقق لعامل موثوق به

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

إذا حققت كل هذه النقاط الست، فلديك عامل يمكنك وصف موثوقيته بالأدلة، وليس بالأمل.

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

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

هل يجب علي بناء واجهات برمجة التطبيقات (APIs) الحقيقية قبل بناء العامل؟ لا. قم بتعريف عقود الأدوات كمخططات في Apidog، وقم بتوليد محاكيات، وبناء حلقة العامل بأكملها مقابل تلك المحاكيات. قم بتبديل نقاط النهاية الحقيقية لاحقًا عبر متغير بيئة.

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

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

هل يعمل هذا مع أطر عمل مثل LangChain أو Claude Agent SDK؟ نعم. طبقة الأداة هي مجرد HTTP. أي إطار عمل يدفع الحلقة، قم بتوجيه استدعاءات أدواته إلى محاكيات Apidog للاختبار وإلى نقاط النهاية الحقيقية للإنتاج. راجع دليل Claude Code SDK للحصول على مثال لمثل هذه الحلقة.

خاتمة

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