تتبع استدعاءات أدوات وكيل الذكاء الاصطناعي: ماذا نسجل في كل طلب

مراقبة وكلاء الذكاء الاصطناعي: سجّل القرار، لا النتيجة فقط

أفاد مستخدم أن الوكيل «فعل شيئًا غريبًا» بعد ظهر أمس. عند فتح السجلات، وجدت:

جرّب Apidog اليوم

INFO  agent run started
INFO  calling tool: updateOrder
INFO  tool returned 200
INFO  agent run completed

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

تفشل أنظمة الوكلاء بطرق لا يمكن فهمها إلا بأثر رجعي؛ لذلك يصبح السجل جزءًا من الناتج نفسه. يوضح هذا الدليل:

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

تغطي مقالة مراقبة واجهة برمجة التطبيقات (API observability) جانب الخدمة، بينما نركز هنا على طبقة الوكيل التي تعلوها.

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

ثلاث طبقات، وتتبع واحد

ينتج الوكيل أحداثًا على ثلاثة مستويات، لكن معظم الفرق تسجل المستوى الأوسط فقط.

1. طبقة الاستدلال

هنا يتخذ النموذج قراراته:

• ما الذي كان موجودًا في السياق؟
• ما الأدوات المتاحة؟
• أي أداة اختار؟
• ما الوسائط التي أنتجها؟

2. طبقة الأداة

هذه هي طبقة المنفّذ. وهي مسؤولة عن:

• التحقق من صحة الوسائط.
• تطبيق السياسة.
• ربط الاستدعاء بطلب HTTP.
• التعامل مع النتيجة وإعادة المحاولة.

3. طبقة HTTP

تمثل الاتصال الفعلي:

• الطريقة.
• عنوان URL.
• الرؤوس.
• النص الأساسي.
• رمز الحالة.
• زمن الاستجابة.

يتطلب تصحيح الأخطاء الربط بين الطبقات الثلاث. فعبارة «أرسل الوكيل معرّف عميل خاطئًا» تصف مشكلة في الاستدلال، لكنها لا تظهر إلا في طبقة HTTP. وعبارة «أعادت واجهة البرمجة 200 مع نص فارغ» تصف مشكلة HTTP قد تظهر لاحقًا كاستدلال غريب.

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

استخدم إذن:

• معرف تتبع واحد لكل تشغيل وكيل.
• معرف نطاق واحد لكل استدعاء أداة.
• ختم كلا المعرفين على كل سجل في الطبقات الثلاث.

صُممت تتبعات OpenTelemetry لهذا النوع من الارتباط، كما توفر الاصطلاحات الدلالية للذكاء الاصطناعي التوليدي (GenAI semantic conventions) أسماء موحدة للسمات، ما يجعل بياناتك قابلة للنقل بين الأدوات.

ما يجب تسجيله في كل استدعاء أداة

يجب أن يجيب السجل على أسئلة التحقيق الفعلية، مثل: أي أداة استُدعيت؟ بأي وسائط؟ بعد أي خطوة؟ وما الذي حدث على الشبكة؟

{
  "trace_id": "run_01J8ZK3M2Q",
  "span_id": "call_004",
  "parent_span_id": "call_003",
  "timestamp": "2026-08-26T14:03:11.482Z",
  "agent": "billing",
  "step": 4,

  "tool_name": "refundOrder",
  "tool_args": { "orderId": "ord_92", "amount": 1200, "reason": "duplicate" },
  "tools_available": ["getOrder", "listOrders", "refundOrder", "voidInvoice"],

  "http": {
    "method": "POST",
    "url": "/v1/orders/ord_92/refund",
    "request_body_hash": "sha256:1f4c...",
    "status": 200,
    "duration_ms": 412,
    "retry_count": 1,
    "idempotency_key": "9f2b7c14-6d3a-4b18"
  },

  "outcome": "success",
  "tokens": { "prompt": 8420, "completion": 96 },
  "policy": { "approval_required": true, "approved_by": "user_31", "dry_run": false }
}

الحقول الأكثر أهمية

tool_args

هذا أكثر حقل يُفقد، وهو غالبًا أهم حقل في التحقيق. سجّل الوسائط التي أنتجها النموذج قبل أن يقوم المنفّذ بتطبيعها. إذا أرسل الوكيل معرّفًا خاطئًا، فستجده هنا.

tools_available

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

retry_count

يفصل بين:

• واجهة برمجة كانت بطيئة.
• واجهة برمجة فشلت مرتين ثم نجحت.

بدونه، قد تبدو ثلاث محاولات كأنها استدعاء واحد.

outcome

استخدم تعدادًا صريحًا بدل استنتاج النتيجة من رمز الحالة:

• success
• failed
• timed_out
• blocked_by_policy
• rejected_by_human

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

policy

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

سجّل القرار، وليس الإجراء فقط

أصعب أخطاء الوكلاء هي أخطاء الاختيار، لذلك خزّن ما يكفي لإعادة بناء القرار.

خزّن تعريفات الأدوات أو تجزئتها

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

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

سجّل النموذج وإعداداته

يجب أن يتضمن سجل التشغيل:

• معرف النموذج.
• درجة الحرارة.
• إصدار الطلب (prompt version).
• إصدار مجموعة الأدوات.

يتغير السلوك بين إصدارات النماذج، ومن دون هذه الحقول قد تقضي وقتًا في التحقيق في كود لم يتغير.

سجّل ما رآه النموذج

قد يكون تخزين الطلب الكامل مكلفًا وحساسًا. في الحد الأدنى، سجّل:

• عدد رموز الطلب والاستجابة.
• تجزئة الطلب.
• حجم السياق.
• إصدار التعليمات.

إذا كان الطلب ضعف حجمه المعتاد، فهذه إشارة إلى إضافة محتوى غير متوقع.

خزّن النتيجة الخام للأداة

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

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

احذف البيانات الحساسة قبل التخزين

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

لا تخزن بيانات الاعتماد

جرّد قبل التسجيل:

• Authorization
• مفاتيح API.
• ملفات تعريف الارتباط.
• عناوين URL الموقعة.
• الرموز المميزة.

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

احذف عند حدود التسجيل

لا تنتظر حتى وقت الاستعلام لتصفية الأسرار؛ ففي تلك المرحلة قد تكون كُتبت على القرص، ونُسخت، وأُدرجت في نسخ احتياطية.

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

جزّئ الحمولات التي لا يمكنك تخزينها

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

حدّد فترة الاحتفاظ حسب الحساسية

نمط عملي:

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

يحدث معظم تصحيح الأخطاء خلال أيام، بينما تظهر أسئلة التدقيق خلال أشهر.

حوّل التتبعات إلى اختبارات

لا تقتصر قيمة التتبع الجيد على تصحيح الأخطاء؛ فهو مصدر مباشر لحالات اختبار واقعية.

كل تشغيل فاشل هو سيناريو اختبار

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

في Apidog، يمكنك:

1. إعادة بناء الطلب الفاشل كحالة محفوظة.
2. التحقق من السلوك الصحيح.
3. تشغيل الحالة في التكامل المستمر (CI).
4. الاحتفاظ بالحادثة كاختبار دائم.

بهذه الطريقة تتحول حادثة واحدة إلى تغطية مستمرة.

استخدم التتبعات لتحديد ما يجب محاكاته

توضح التتبعات:

• نقاط النهاية التي يستدعيها الوكيل أكثر من غيرها.
• حالات الفشل التي يواجهها فعليًا.
• الاستجابات التي تؤثر في قراراته.

ابنِ المحاكاة حول هذه الحالات بدل التخمين، كما يشرح دليل تشغيل الوكلاء مقابل المحاكاة بدلًا من الإنتاج.

راقب الانجراف البطيء

تتبّع أسبوعيًا على الأقل:

• توزيع اختيار الأدوات.
• معدل إعادة المحاولة لكل نقطة نهاية.
• عدد الاستدعاءات لكل مهمة مكتملة.
• نسبة التشغيلات المحظورة بواسطة السياسة.

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

ثلاثة تحقيقات يجب أن يصمد أمامها التتبع

«فرض الوكيل رسومًا على العميل الخطأ»

تحتاج إلى:

• وسائط النموذج.
• عنوان URL المحلل.
• الخطوة السابقة.
• نتيجة الأداة السابقة.
• أي غموض في البيانات.

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

«توقف الوكيل عن العمل يوم الثلاثاء»

قارن تشغيلًا ناجحًا بآخر فاشل حقلًا بحقل:

• معرف النموذج.
• تجزئة مجموعة الأدوات.
• إصدار الطلب.
• متوسط حجم الاستجابة.
• عدد الرموز.
• معدلات إعادة المحاولة.

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

«هل وافق أحد على هذا؟»

يجب أن تكون كتلة السياسة موجودة لحظة اتخاذ القرار:

{
  "approval_required": true,
  "approved_by": "user_31",
  "approved_at": "2026-08-26T14:03:11.400Z",
  "dry_run": false
}

تحول هذه الحقول سؤالًا حساسًا إلى عملية بحث واضحة.

القاسم المشترك بين التحقيقات الثلاثة هو أنها لا يمكن الإجابة عنها بعبارة «أعادت الأداة 200». تعتمد الإجابة على حقول رخيصة في التخزين، لكنها مستحيلة الاستعادة بعد وقوع الحدث.

المعاينة: ما لا يجب إسقاطه أبدًا

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

احتفظ دائمًا بـ:

• كل تشغيل فاشل.
• كل تشغيل وصل إلى حاجز سياسة.
• كل تشغيل يتضمن عملية كتابة.
• كل تشغيل انتهى بإعادة محاولة غير متوقعة.

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

يوضح فصل المراقبة في Google SRE لماذا يجب أن تعتمد المعاينة على الإشارة لا على الحجم.

حتى عند حذف الحمولات، احتفظ بسجل هيكلي يتضمن:

• أسماء الأدوات.
• النتائج.
• المدد.
• عدد المحاولات.
• قرارات السياسة.

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

تنبيه حول Tail Sampling

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

أين يجب أن يعيش التتبع؟

يفترض هذا التصميم أن لديك تخزينًا مركزيًا، وهو مناسب عندما يكون الوكيل خدمة تستدعي واجهات البرمجة الخاصة بك.

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

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

• الهدف.
• الحالة.
• مسار التعليقات.
• مراجعة الإنسان للعمل.

الفرق العملي هو قابلية الاسترجاع. يصبح سؤال «لماذا فعل الوكيل ذلك؟» سؤالًا تجيب عنه بفتح المهمة، بدل البحث عن الجهاز والجلسة وسجل التمرير.

لا يحل هذا محل التتبع أو وقت التشغيل؛ فما زالت أدوات مثل Claude Code وCodex تنفذ العمل. التغيير هو مكان انتهاء السجل عندما لا يكون الوكيل خدمة منشورة تملكها.

راقب أربعة أرقام

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

الاستدعاءات لكل مهمة مكتملة

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

معدل إعادة المحاولة حسب نقطة النهاية

يحدد الاعتماديات الأقل موثوقية ويظهر متى تتدهور إحداها. راجع استعادة أخطاء الوكيل لمعالجة الأسباب الشائعة.

معدل الحظر بواسطة السياسة

يجب أن يكون منخفضًا ومستقرًا. الارتفاع المفاجئ يعني أحد أمرين:

• الوكيل يحاول تنفيذ أشياء لا ينبغي له تنفيذها.
• السياسة أصبحت صارمة لدرجة أنها تعيق العمل الطبيعي.

الوقت حتى أول استدعاء أداة

البداية البطيئة تعني غالبًا وجود طلب متضخم. حجم الطلب من الأشياء التي تنمو تدريجيًا دون أن يقرر أحد زيادتها.

قائمة مراجعة عملية

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

الهدف بسيط: عندما يسأل أحدهم «لماذا فعل الوكيل ذلك؟» يجب أن تجيب من السجل بدل التخمين. يمكنك تنزيل Apidog لإعادة تشغيل الاستدعاءات والاحتفاظ بها كاختبارات.

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

هل أستخدم OpenTelemetry أم أداة مراقبة متخصصة للوكلاء؟

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

كم يكلف تخزين التتبع الكامل؟

أقل مما قد تتوقع إذا قسمت التخزين إلى طبقات:

• الحمولات الكاملة لبضعة أيام.
• سجلات منظمة بلا نصوص أساسية لفترة أطول.
• مقاييس مجمعة لفترة طويلة.

تعد تفريغات الطلب الجزء الأغلى، لذلك جزّئها وحدد حجمها بدل تخزينها افتراضيًا.

هل أحتاج إلى تسجيل نص استدلال النموذج؟

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

كيف أتتبع وكلاء متعددين؟

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

ماذا لو كان الوكيل يعمل على جهاز العميل؟

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

هل تجزئة نص الطلب مفيدة فعلًا؟

نعم. تثبت التجزئة أن استدعاءين كانا متطابقين، ما يحل معظم تحقيقات التكرار دون الاحتفاظ بالحمولة نفسها. اقرنها بمفاتيح التكرار (idempotency keys) التي تمنع التكرار، كما يوضح دليل مفاتيح التكرار للوكلاء.