كان ذلك بعد ظهر يوم الثلاثاء. بعد اثني عشر دورة في جلسة تصحيح الأخطاء، كان الوكيل يخبرني بثقة أن نقطة النهاية /users لدينا تستجيب في سبع وأربعين ثانية. بينما الرقم الحقيقي كان سبعة وأربعين مللي ثانية.
كنت أطارد هذا الخطأ لمدة يومين. في كل مرة أضفت فيها عبارة طباعة إلى خادم MCP، كان رد الوكيل يتغير بما يكفي ليجعلني أعتقد أنني أحرز تقدمًا. في كل مرة أعدت فيها كتابة موجه النظام، بدت الاستجابة أكثر منطقية. لم يكن أي منها صحيحًا.
ما لم أفعله، حتى بعد ظهر ذلك اليوم، هو فتح تتبع التنفيذ الفعلي والنظر في ما تم تمريره بين النموذج والأداة. هذا هو الغرض من مصحح أخطاء وكيل الذكاء الاصطناعي من Apidog. كنت قد قمت بتثبيته قبل ثلاثة أسابيع ونسيته. استغرق الأمر اثنتي عشرة دقيقة للعثور على الخطأ.
هذا ما فاجأني.
الخطأ الذي كنت أطارده
كان الإعداد بسيطًا. وكيل مبني على GPT-5.5. خادم MCP واحد كتبته في عطلة نهاية الأسبوع، يعرض أداة get_response_time(endpoint) التي استعلمت عن خط أنابيب المقاييس لدينا. موجه نظام ربما أربعون كلمة. موجه المستخدم: "ما مدى سرعة نقطة النهاية /users؟"
أجاب الوكيل بسرعة. أجاب بثقة. أجاب بشكل خاطئ، في كل مرة، بطرق مختلفة. أحيانًا "نقطة النهاية تستجيب في 47 ثانية." أحيانًا "حوالي 0.05 ثانية." ومرة، لا تُنسى، "الأداء مقبول."
كنت أفعل الأشياء المعتادة. إضافة تسجيل الدخول إلى خادم MCP. قراءة استجابة النموذج رمزًا تلو الآخر. مقارنة موجهات النظام. الشتم. كان لدي ثلاث نوافذ طرفية مفتوحة وصفحة Notion من الفرضيات الفاشلة بحلول صباح الثلاثاء.
الشيء المتعلق بتصحيح أخطاء الوكلاء هو أن الخطأ نادرًا ما يكون في المكان الذي تبحث فيه أولاً. يمكن أن يكون في موجه النظام، في اختيار النموذج، في تعريف الأداة، في المعلمات التي مررها النموذج إلى الأداة، في البيانات التي أعادتها الأداة، أو في كيفية تفسير النموذج لتلك البيانات. ستة أماكن. سجل وحدة التحكم يظهر لك واحدًا فقط.
ما تظهره لوحة التتبعات بالفعل
يفتح مصحح أخطاء Apidog على ثلاثة أعمدة. الجلسات على اليسار. الأدوار في المنتصف. التتبعات على اليمين. انقر فوق أي جلسة وسيُظهر لك العمود الأوسط الحوار: رسالة المستخدم، استجابة النموذج، استدعاء الأداة، نتيجة الأداة، استجابة النموذج التالية. انقر فوق أي دور وسيوسع العمود الأيمن شجرة التنفيذ الكاملة تحته.
شجرة التنفيذ هي الجزء الذي كنت أفتقده. كل خطوة، بالترتيب:
- موجه النظام كما استلمه النموذج
- موجه المستخدم كما استلمه النموذج
- اسم استدعاء الأداة ومعلماتها، كـ JSON، تمامًا كما أصدرها النموذج
- حمولة نتيجة الأداة، كـ JSON، تمامًا كما أعادتها الأداة
- استجابة النموذج، مع التوقيت والرموز للدورة
فتحت الجلسة الفاشلة. بدا استدعاء الأداة جيدًا: get_response_time(endpoint="/users"). كان النموذج قد اختار الأداة الصحيحة مع الوسيطة الصحيحة.
ثم قمت بتوسيع نتيجة الأداة.
{"value": 47, "p95": 89, "samples": 1240}
كانت تلك هي المشكلة. أعاد خط أنابيب المقاييس القيمة بالمللي ثانية. افترض النموذج أنها ثواني. أصبحت 47 "47 ثانية" عبر هلوسة واثقة لم تكلف نفسها عناء التساؤل عن الوحدة. كانت الأداة صحيحة. كان النموذج خاطئًا. لم يتضمن موجه النظام الخاص بي أي تعليمات حول الوحدات، ولم تتضمن استجابة الأداة أي إشارة للوحدة.
اثنتا عشرة دقيقة من فتح مصحح الأخطاء. يومان كنت ألوم فيهما موجه النظام.
استغرق الإصلاح ستة أسطر
غيرت شيئين. في خادم MCP، قمت بتحديث شكل الاستجابة:
{
"value": { "amount": 47, "unit": "ms" },
"p95": { "amount": 89, "unit": "ms" },
"samples": 1240
}
ثم أضفت جملة واحدة إلى موجه النظام: "نتائج الأداة تعيد الوحدات بشكل صريح. اقرأها بعناية."
قمت بتشغيل نفس موجه /users ثلاث مرات أخرى. ثلاث جلسات مختلفة في اللوحة اليسرى. كلها أعادت بشكل صحيح "نقطة النهاية تستجيب في حوالي 47 مللي ثانية" مع تحليل من مللي ثانية إلى نسبة مئوية في استدلال النموذج. كانت تكلفة الرمز أقل بنسبة ثمانية عشر بالمائة من تشغيلاتي الفاشلة، ربما لأن النموذج لم يكن يولد نصوص استرجاع حول افتراضاته الخاطئة.
قمت بتشغيل نفس الموجه على Claude Opus 4.7 في جلسة ثانية، جنبًا إلى جنب. نفس النتيجة، ضعف التكلفة، أكثر تفصيلاً قليلاً. عرفت أي نموذج سيذهب إلى الإنتاج.
هذا هو الجزء من الأداة الذي أكسبني احترامي. ليس اكتشاف الأخطاء، الذي يجب أن يفعله أي مصحح أخطاء جيد. بل مقارنة النماذج، التي تعمل بتكوينات متطابقة مع مقاييس ملخصة في اللوحة اليسرى: عدد الدورات، عدد الخطوات، الوقت، الرموز، الدولارات. كنت أقوم بهذه المقارنة في جدول بيانات Google لمدة ستة أشهر. الآن أصبحت بثلاث نقرات.
ما كنت أخطئ فيه
الرأي السهل هو أن مصحح أخطاء وكيل الذكاء الاصطناعي هو أداة تسجيل. إنه ليس كذلك. أدوات التسجيل تظهر لك ما حدث. المصحح يظهر لك ما تبادله النموذج والأداة بالفعل، وهو طبقة مختلفة.
إذا كنت تكتب وكلاء وكنت تفعل ما كنت أفعله، وهو قراءة مخرجات النموذج والتخمين حول سبب الفشل، فإليك ما سأدفع به. أنت لا تصحح أخطاء الوكيل. أنت تصحح أخطاء فرضيتك حول الوكيل. هذه أشياء مختلفة، وواحد منها فقط يوصلك إلى حل.
الشيء الذي رفضت استيعابه لمدة ستة أشهر هو أن الوكيل نظام مغلق بين النموذج، الموجه، الأدوات، واستجابات الأدوات. الخطأ دائمًا ما يكمن في أحد هذه الأربعة. إذا كان بإمكانك رؤية الأربعة جميعها في نفس الوقت، يمكنك العثور على الخطأ في اثنتي عشرة دقيقة. إذا لم تتمكن، يمكنك مطاردته لمدة أسبوع.
الشيء الآخر الذي كشفه المصحح، والذي لم أتوقعه، هو عدم التحديد في وكيلي الخاص. قمت بتشغيل نفس الموجه خمس مرات بعد الإصلاح، فقط للتأكيد. ثلاث تشغيلات استدعت get_response_time مرة واحدة. تشغيلتان استدعتاه مرتين، في المرة الثانية بمسار نقطة النهاية بحالة مختلفة. كان مخطط أداتي حساسًا لحالة الأحرف. لم ألاحظ ذلك لأن جميع حالات الاختبار الفاشلة لدي كانت تستخدم أحرفًا صغيرة. كان ذلك خطأ ثانيًا كنت سأقوم بشحنه دون رؤيته.
تحليل التشغيل المتعدد هو الميزة التي سأستخدمها أكثر من غيرها في المستقبل. انقر فوق تشغيل خمس مرات. انظر إلى لوحة الجلسات. أي شيء يختلف عبر التشغيلات هو مكان هش في وكيلك.
جرب بنفسك: جولة إعداد كاملة
إذا كنت تريد نفس الإعداد الذي كان لدي مفتوحًا أثناء البحث عن الأخطاء، فإليك المسار من تثبيت جديد إلى جلسة تصحيح أخطاء قيد التشغيل. خمس شاشات، بالترتيب.
الخطوة 1: إنشاء جلسة تصحيح أخطاء وكيل جديدة
افتح Apidog وانقر على **AI Agent Debugger** في شريط علامات التبويب العلوي. القسم العلوي من الصفحة يقوم بتكوين النموذج وحالة التشغيل.
- اختر مزود النموذج على اليسار (OpenAI، Anthropic، وغيرها)
- اختر النموذج المحدد في المنتصف، على سبيل المثال
gpt-5.5 - يتم ملء عنوان URL الأساسي تلقائيًا بمجرد اختيار المزود، ولا يلزم إدخال يدوي
- انقر فوق **Run** لبدء جلسة
الخطوة 2: تكوين الموجهات
تحتوي علامة تبويب **Prompts** على منطقتين إدخال.
- **System Prompt (موجه النظام)**: يحدد دور الوكيل وأهدافه وقيوده وقواعد استخدام الأداة
- **User Prompt (موجه المستخدم)**: إدخال الاختبار لهذه الجلسة، على سبيل المثال "ما هو Apidog؟"
انقر فوق **Run** في الجزء العلوي الأيمن عند ضبط كليهما. إذا كنت تريد مسح مربع الإدخال تلقائيًا بعد كل تشغيل، حدد **Clear after Send**.
الخطوة 3: تكوين الأدوات
تعرض علامة تبويب **Tools** كل ما يمكن للوكيل استدعاؤه في وقت التشغيل. الرقم الموجود على علامة التبويب هو العدد الحالي للأدوات المتاحة أو المكونة.
**Built-in tools (الأدوات المدمجة)** تأتي مع مصحح الأخطاء. قم بتبديلها تشغيل أو إيقاف حسب الحاجة.
| الأداة | ماذا تفعل |
|---|---|
bash |
تنفيذ الأوامر في جلسة shell مستمرة |
web_fetch |
جلب محتوى الويب وتحويله إلى Markdown، نص، أو HTML |
read |
قراءة ملفات النص، الصور، أو PDF |
edit |
تطبيق استبدالات دقيقة للسلاسل على الملفات |
write |
إنشاء أو الكتابة فوق الملفات |
grep |
البحث في محتوى الملف باستخدام التعبيرات العادية |
glob |
العثور على الملفات باستخدام أنماط glob |
kill_shell |
إعادة تعيين جلسة shell الحالية |
**أدوات MCP** تضيف أنظمة خارجية أو إمكانيات مخصصة عبر خوادم MCP. ثلاث طرق اتصال:
- **STDIO**: تشغيل عملية خادم MCP محلية
- **HTTP**: الاتصال بخادم MCP يدعم HTTP القابل للتدفق
- **SSE**: الاتصال بخادم MCP يعتمد على أحداث الخادم المرسلة
تقبل خوادم MCP التي تتطلب المصادقة رؤوس الطلبات أو تدفقات OAuth 2.0. بمجرد نجاح الاتصال، اختر الأدوات التي سيعرضها الخادم للوكيل.
الخطوة 4: تكوين المهارات والمصادقة ومعلمات النموذج
ثلاث علامات تبويب أصغر تكمل الإعداد.
- **Skills (المهارات)**: سير عمل قابل لإعادة الاستخدام للوكيل. مفيد لسير عمل المشاريع الثابتة، ومواصفات عمليات المهام الشائعة، وتقليل النصوص الطويلة المتكررة في موجهات النظام. يتم تحميل المهارات حسب الحاجة في وقت التشغيل.
- **Authentication (المصادقة)**: بيانات الاعتماد المطلوبة بواسطة خدمات النموذج أو خدمات MCP.
- **Settings (الإعدادات)**: معلمات وقت تشغيل النموذج مثل درجة الحرارة (Temperature)، الحد الأقصى للرموز (Max Tokens)، وأعلى P (Top P). تختلف المعلمات المدعومة حسب المزود، لذا تحقق مما يقبله نموذجك بالفعل.
الخطوة 5: قراءة اللوحات الثلاث
بعد النقر على "تشغيل" (Run)، تظهر الجلسة التي أنشأتها للتو في اللوحة اليسرى. تعرض كل جلسة ملخصًا من سطر واحد:
Session 3
1 turn · 1 step · 10s · 3.1k tokens · $0.02
gpt-5.5
- **Sessions panel (لوحة الجلسات) (يسار)**: سجل كل تشغيل مع مقاييس ملخصة
- **Turns panel (لوحة الدورات) (منتصف)**: كل جولة من حوار المستخدم/النموذج. انقر فوق جولة لتحميل تفاصيل تنفيذها على اليمين.
- **Traces panel (لوحة التتبعات) (يمين)**: سلسلة التنفيذ الكاملة للوكيل بالترتيب، بما في ذلك موجهات النظام والمستخدم، وكل استدعاء للنموذج، وعملية تفكير النموذج إذا كان النموذج يعرضها، واستدعاءات أدوات MCP وتنفيذ المهارات المخصصة، ومعلمات إدخال الأداة، والنتائج، والوقت المستغرق، ورسائل الخطأ، والإخراج النهائي.
عندما يفشل استدعاء أداة أو يعيد النموذج استثناءً، تكون الخطوة الفاشلة موجودة في لوحة التتبعات مع مدخلاتها ومخرجاتها المرئية. لا حاجة للبحث في السجلات.
الخطوة 6: مقارنة أداء النموذج
نفس الموجه، نفس تكوين الأداة، نموذج مختلف. ينشئ كل تشغيل جلسة جديدة، وتتيح لك اللوحة اليسرى مقارنتها جنبًا إلى جنب.
مقاييس مفيدة للمقارنة:
- عدد خطوات التنفيذ لنفس المهمة
- أي نموذج يختار الأدوات بدقة أكبر
- أي نموذج لديه وقت استجابة أقل
- أي نموذج يحافظ على استهلاك الرموز والتكلفة بشكل أكثر قابلية للتنبؤ
الخلاصة
يومان من تصحيح الأخطاء تلخصت في فترة ما بعد الظهر، ولم أتعلم الدرس من الخطأ نفسه. تعلمته من الأدوات. كان السبب في أنني كنت أطارد الإصلاح الخاطئ هو أن الأدوات التي كنت أستخدمها لم تظهر لي ما أحتاج رؤيته. كان لدي إخراج نموذج وإخراج أداة، ولم يكن هناك إطار مشترك للنظر إليهما معًا. والإطار المشترك هو بيت القصيد.
إذا كنت قد كتبت أكثر من وكيل واحد ولم تفتح بعد مصحح أخطاء وكيل الذكاء الاصطناعي من Apidog، فإن الوكيل التالي الذي ستشحنه سيكون به خطأ يكمن بين النموذج والأداة. ستقضي أسبوعًا عليه. ستكتب صفحة Notion من الفرضيات الفاشلة. وسيكون الخطأ بالضبط في المكان الذي كان سيظهره لك مصحح الأخطاء في اليوم الأول.
قم بتنزيل Apidog وافتحه على الوكيل التالي الذي يعطيك إجابة خاطئة بصوت واثق. اثنتا عشرة دقيقة. سبعة وأربعون مللي ثانية، وليس سبعة وأربعين ثانية.
المرجع الكامل للميزات، بما في ذلك إعداد نقل MCP وتوافر الخطط، موجود في Apidog AI Agent Debugger: التوافر، التغطية، والإعداد.