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

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

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

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

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

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

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

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

طبقة **الاستدلال (reasoning layer)** هي حيث يتخذ النموذج قراراته. ما كان في السياق، الأدوات التي عُرضت، أي أداة اختارها، وبأي وسائط.

طبقة **الأداة (tool layer)** هي المنفّذ الخاص بك. إنها تتحقق من صحة الوسائط، وتطبق السياسة، وتربط الاستدعاء بطلب HTTP، وتتعامل مع النتيجة.

طبقة **HTTP (HTTP layer)** هي الاتصال. الطريقة (Method)، عنوان URL، الرؤوس (headers)، النص الأساسي (body)، الحالة (status)، زمن الاستجابة (latency).

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

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

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

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

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

سجل ما رآه النموذج، أو على الأقل حجمه. تفريغ الطلب الكامل مكلف للتخزين وغالبًا ما يكون حساسًا. يعطيك عدد الرموز المميزة (token count) بالإضافة إلى تجزئة (hash) معظم القيمة التشخيصية: التشغيل الذي يكون فيه الطلب ضعف الحجم المعتاد هو تشغيل تم فيه إضافة شيء ما لم يكن يجب إضافته.

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

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

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

أربع قواعد تجعل هذا قابلًا للإدارة.

لا تخزن بيانات الاعتماد أبدًا. قم بتجريد Authorization ومفاتيح API وملفات تعريف الارتباط (cookies) وأي عنوان URL موقّع. سجل معرّف بيانات الاعتماد، مثل معرّف المفتاح، وليس القيمة. تغطي مقالتنا حول مفاتيح API ذات الامتيازات الأقل للوكلاء سبب رغبتك في هذا المعرّف: فهو يخبرك أي وكيل قام بالإجراء.

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

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

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

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

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

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

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

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

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

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

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

**"هل وافق أحد على هذا؟"** كتلة السياسة (policy block) هي الإجابة الكاملة، ويجب كتابتها لحظة اتخاذ القرار، وليس إعادة بنائها لاحقًا. approval_required (مطلوب موافقة)، approved_by (تمت الموافقة بواسطة)، وطابع زمني يحول المحادثة المتوترة إلى عملية بحث.

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

المعاينة (Sampling)، وما لا يجب معاينته أبدًا

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

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

لا يزال فصل كتاب Google SRE حول المراقبة هو أوضح بيان لسبب قيامك بالمعاينة للإشارة وليس للحجم، وينتقل المنطق مباشرة.

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

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

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

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

Sharkly يتبع نهجًا آخر: يتم إرفاق تتبع التنفيذ بالمهمة التي تم تعيينها للوكيل. يجلس سجل التشغيل، وسجل التنفيذ، والنتيجة بجانب الهدف، والحالة، ومسار التعليقات حيث قام إنسان بمراجعة العمل. الفرق العملي هو الاسترجاع. يصبح السؤال "لماذا فعل الوكيل ذلك؟" سؤالًا تجيب عليه بفتح المهمة، بدلاً من البحث عن الجهاز، والجلسة، وسجل التمرير.

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

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

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

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

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

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

**الوقت حتى أول استدعاء أداة.** تعني البداية البطيئة عادةً وجود طلب (prompt) متضخم، وحجم الطلب هو الشيء الذي ينمو دون أن يقرر أحد زيادته.

قائمة مراجعة

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

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

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

**هل يجب أن أستخدم OpenTelemetry أم أداة مراقبة وكيل (agent observability) مصممة خصيصًا؟** استخدم OpenTelemetry للنقل ونموذج التتبع، لأنه يتعامل بالفعل مع الارتباط ومن المحتمل أن تتوافق بنيتك التحتية معه. تضيف الأدوات الخاصة بالوكلاء عروضًا مفيدة فوق ذلك؛ لكن البيانات الأساسية يجب أن تظل قابلة للنقل.

**كم يكلف تخزين التتبع الكامل؟** أقل مما يتوقع الناس، إذا قمت بتقسيمه طبقات. الحمولات الكاملة لبضعة أيام والسجلات المنظمة بدون نصوص أساسية لفترة أطول تحافظ على انخفاض معظم الحجم. تعد تفريغات الطلبات (prompt dumps) الجزء المكلف، لذا قم بتجزئتها وتحديد حجمها بدلاً من تخزينها افتراضيًا.

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

**كيف يمكنني التتبع عبر وكلاء متعددين؟** احتفظ بمعرف تتبع واحد للمهمة بأكملها وأعطِ كل وكيل نطاقه الخاص، مع تسجيل عملية التسليم (handoff) كحدث. تغطي مقالتنا حول تسليم السياق بين الوكلاء المتعددين ما يجب أن يكون في سجل التسليم هذا.

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

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