تتبع أخطاء الوكلاء باستخدام مركز التحكم في Microsoft Foundry Toolkit

يتيح لك مركز التحكم بالعامل في Microsoft Foundry Toolkit for تعليمة Visual Studio برمجية إرسال الطلبات إلى وكيل محلي، وفحص نشاط النموذج والأدوات، وتصحيح التعليمات البرمجية الخاصة بك. استخدمه للتحقيق في الاستجابات غير المتوقعة قبل نشر تغيير.

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

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

المتطلبات المسبقه

  • تعليمة Visual Studio برمجية مع ملحق مجموعة أدوات Foundry العامة الحالية. راجع تثبيت مجموعة أدوات Foundry.
  • مشروع عامل محلي مع تبعياته وتكوين النموذج وبيانات الاعتماد التي تم إعدادها. للبدء من عينة، اتبع التشغيل السريع للعامل المستضاف من خلال الاختبار المحلي.
  • مصحح الأخطاء المطلوب من قبل مشروعك. يستخدم نموذج Python ملحق Python وdebugpy. اللغات والعينات الأخرى لها متطلبات مختلفة.

بالنسبة لمشروع موجود، يمكن أن تساعد أدوات مجموعة أدوات Foundry Copilot في إعداد التكوين. راجع الملفات التي تم إنشاؤها واتبع المشروع README.md. لا تستبدل ملفات التشغيل بتكوين عام.

مهم

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

الاتصال والتصحيح

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

  1. ابدأ العامل بتكوين تتبع الأخطاء الموثق الخاص به. للحصول على نموذج Python العامل المستضاف، حدد Debug Local Agent HTTP Server واضغط F5.
  2. إذا لم يكن Inspector مفتوحا، فحدد Foundry Toolkit في شريط النشاط، ثم Developer Tools>Build>Agent Inspector.
  3. تحقق من نقطة النهاية في رأس Inspector. تستخدم http://localhost:8088سقالة Python الحالية . بالنسبة لمنفذ خادم مختلف، حدد زر القلم الرصاص بجوار نقطة النهاية، وأدخل المنفذ، وحدد اتصال.
  4. تأكد من أن الرأس يظهر متصلا. يكشف المفتش تلقائيا عن بروتوكول الاستجابات أو استدعاءات عندما يكون الوصول إلى نقطة النهاية قابلا للوصول.
  5. قم بتعيين نقطة توقف في التعليمات البرمجية للعامل الخاص بك وأرسل رسالة في الملعب. افحص المتغيرات عند إيقاف التنفيذ مؤقتا، ثم تابع وراجع الاستجابة.

لقطة شاشة لتكوين تتبع أخطاء العامل المحلي ومفتش العامل المتصل ب localhost على المنفذ 8088 مع استجابة ناجحة.

فتح Inspector وحده لا يقوم بتشغيل خادم أو إرفاق مصحح أخطاء. يستخدم تكوين Python الذي تم إنشاؤه المنفذ 5679 لمصحح الأخطاء والمنفذ 8088 لطلبات HTTP للعامل. هذه المنافذ منفصلة عن منافذ تتبع OTLP.

الاتصال بنقطة نهاية استجابات عامة

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

لا يعني الاتصال الناجح أن الخادم يوفر مواقع المصدر أو استخدام الرمز المميز أو المنطق.

إرسال استدعاء HTTP

استخدم استدعاءات HTTP عندما يقبل الوكيل نص طلب مخصص بدلا من رسالة محادثة. يحدد تنسيق طلب الخادم وبروتوكول الاستجابة كيفية إرسال Inspector وعرض النتيجة.

  1. الاتصال بخادم استدعاءات HTTP قيد التشغيل. يكتشف المفتش البروتوكول تلقائيا.
  2. أدخل نص الطلب المطلوب من قبل وكيلك. إذا كشف الخادم مواصفات OpenAPI متوافقة، يمكن للمفتش ملء مثال. راجعه قبل الإرسال، أو اتبع تنسيق طلب العينة إذا لم يتوفر أي مثال.
  3. حدد الترس Request settings بجوار الإدخال لتعيين Content-Type و Accept كما هو مطلوب من قبل الخادم. على سبيل المثال، استخدم application/json لجسم JSON وعندما text/event-stream يدعم الخادم استجابة دفق.
  4. حدد إرسال وفحص حالة الاستجابة والنص الأساسي.
  5. التبديل بين معاينة للإخراج المنسق و Raw للاستجابة الأساسية. يتضمن جزء التفاصيل أيضا مكالمات الإدخال/الإخراج و LLM. تعتمد تفاصيل النموذج والأداة والرمز المميز على أحداث الخادم المعترف بها، لذلك لا تملأ كل استجابة كل علامة تبويب.

يتعامل المفتش مع استجابة HTTP عادية أو دفق من الأحداث المرسلة من الخادم أو استجابة غير متزامنة. للحصول على استجابة غير متزامنة 202 Accepted ، فإنه يستقصي استدعاء حتى الاكتمال أو الفشل. لا يؤدي تحديد تنسيق استجابة إلى إضافة دعم دفق أو دعم غير متزامن إلى الخادم.

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

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

استخدام المفتش

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

  1. أرسل الطلب في الملعب وراجع استجابة الدفق.
  2. استخدم علامات تبويب التفاصيل للعثور على العملية البطيئة أو الفاشلة.
  3. افحص الحدث أو استدعاء الأداة ذي الصلة، وغير التعليمات البرمجية أو التكوين، وكرر الطلب.

اضغط على مفتاح الإدخال Enter لإرسال أو Shift+Enter لإضافة سطر جديد. لاستدعاء طلب سابق، ضع علامة الإقصار في بداية الإدخال واضغط على سهم لأعلى. اضغط على السهم لأسفل في النهاية للانتقال نحو طلبات أحدث والعودة إلى المسودة غير المرسلة.

يمكنك تحرير طلب تم استدعائه قبل إرساله. محفوظات الإدخال هي راحة داخل Inspector، وليست مخزنا دائما من المطالبات المحفوظة.

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

يعرض تذييل الاستجابة النموذج والمدة واستخدام الرمز المميز ومعلومات الطابع الزمني عند توفيرها. يظهر نص المنطق وملخصات المنطق في أقسام منفصلة قابلة للطي عندما يصدرها العامل. لا ينشئ المفتش المنطق المفقود أو يعرض المعلومات التي لا يرجعها موفر النموذج.

فحص الأدوات والأذونات

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

لقطة شاشة لعلامة التبويب أدوات مع استدعاءات مجمعة حسب التشغيل واستدعاء أداة موسع يعرض الوسيطات والنتيجة.

عندما تتوقف الاستجابة مؤقتا للموافقة على بروتوكول سياق النموذج (MCP) أو موافقة OAuth، تظهر الطلبات المعلقة فوق إدخال الرسالة. امنح الوصول الذي تنوي السماح به فقط.

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

للحصول على موافقة OAuth، أكمل كل من تخويل المستعرض وتأكيد المفتش:

  1. حدد Open consent للطلب المعلق.
  2. أكمل التخويل في المتصفح، وارجع إلى Inspector، وحدد Consent done. لرفض التخويل، حدد إلغاء بدلا من ذلك.
  3. حل طلبات الموافقة المتبقية. استخدم كل ما تم، عند توفره، فقط بعد إكمال التخويل لجميع الطلبات المفتوحة.

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

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

فحص مهام سير العمل ورمز المصدر

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

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

يمكنك اختبار مهام سير عمل LangGraph في الملعب، ولكن مرئيات سير العمل غير مدعومة لهم. لا يزال بإمكان الخادم الذي لا يحتوي على بيانات تعريف سير العمل إرجاع أحداث استجابة مفيدة.

التحقيق في حالات الفشل باستخدام Copilot

استخدم إجراءات الخطأ في الأحداث لإعداد طلب مركز GitHub Copilot بدلا من نسخ المحادثة بأكملها.

  1. ابحث عن الحدث الفاشل وراجع تفاصيله للمحتوى الحساس قبل مشاركته.
  2. حدد إصلاح بجانب الحدث الفاشل لإعداد مطالبة لهذا الفشل. بالنسبة للعديد من حالات الفشل، قم بتضييق القائمة باستخدام عوامل تصفية البحث والفئة، ثم حدد حل باستخدام Copilot. يتضمن هذا الإجراء حالات الفشل المرئية.
  3. راجع المطالبة المعدة في Copilot Chat GitHub قبل إرسالها. راجع أي تغييرات مقترحة، ثم أعد تشغيل طلب العامل الأصلي لتأكيد النتيجة.

لا تتطلب هذه الإجراءات مجمع OTLP. لا يؤدي إعداد مطالبة تشخيصية إلى إصلاح العامل أو إعادة تشغيل العملية الفاشلة.

لقطة شاشة لعلامة تبويب الأحداث مع الاستجابات الفاشلة وعناصر التحكم في البحث والتصفية وإجراءات التصدير وتفاصيل التشخيص المعدة في Copilot Chat.

حفظ الأحداث التشخيصية

احفظ لقطة حدث لمقارنة فشل مع تشغيل لاحق أو مشاركة نسخة مركزة.

  1. في الأحداث، قم بتضييق القائمة باستخدام حقل البحث وعامل تصفية الفئة.
  2. حدد نسخ الأحداث المرئية لنسخ الأحداث التي تمت تصفيتها ك JSONL. بدلا من ذلك، حدد Download visible events لفتح التصدير في VS Code.
  3. للتصدير المفتوح، استخدم حفظ الملف>باسم لحفظ نسخة في موقع تتحكم فيه قبل إغلاق المستند. التصدير المفتوح هو ملف مؤقت، وليس تنزيلا دائما.

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

احتياط

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

بدء محادثة جديدة

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

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

لا تعتمد على حالة Inspector المحلية كأرشيف محادثة دائم. يمتلك الخادم استمرارية المحادثة، والتي يمكن أن تختلف بين التطوير المحلي والعامل المستضاف المنشور. لا يحذف Clearing Inspector التتبعات التي تم جمعها بالفعل محليا أو المخزنة في Application Insights.

كيف يختلف المفتش والتتبع

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

لا تتطلب هذه التشخيصات المباشرة جامع OTLP المحلي. تفتح علامة تبويب التتبع الخاصة بالمفتش عارض التتبع المنفصل. لا يحول أحداث البروتوكول إلى امتدادات OpenTelemetry المخزنة.

لتجميع الامتدادات لتحليلها لاحقا، قم بتكوين التتبع المحلي. بالنسبة للوكلاء الموزعين، استخدم تتبعات الوكيل المستضاف.

بعد الاختبار المحلي، انشر العامل المستضاف. اختبره بشكل منفصل لأن هويته وبيئته والوصول إلى الشبكة يختلف عن العملية المحلية.

Troubleshooting

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

المحتوى ذو الصلة

  • تاريخ آخر تحديث في