اختبار العوامل باستخدام Microsoft Agent 365 SDK

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

بمجرد أن يعمل وكيلك محليا، اتبع دورة حياة التطوير Agent 365 للاختبار في تطبيقات Microsoft 365 مثل Teams Word Outlook.

المتطلبات الأساسية

قبل البدء في اختبار الوكيل الخاص بك، تأكد من تثبيت المتطلبات الأساسية التالية:

المتطلبات الأساسية الشائعة

المتطلبات الأساسية الخاصة باللغة

تكوين بيئة اختبار العامل

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

إعداد بيئة اختبار العامل باتباع سير العمل التسلسلي هذا:

  1. تكوين بيئتك - أنشئ أو حدث ملف تكوين البيئة الخاص بك.

  2. تكوين LLM - احصل على مفاتيح واجهة برمجة التطبيقات وقم بتكوين إعدادات OpenAI أو Azure OpenAI.

  3. تكوين المصادقة - قم بإعداد المصادقة الوكيلية.

  4. مرجع متغيرات البيئة - تكوين متغيرات البيئة المطلوبة:

    1. متغيرات المصادقة
    2. تكوين نقطة نهاية MCP
    3. متغيرات المراقبة
    4. تكوين خادم تطبيق العامل

بعد إكمال هذه الخطوات، تكون مستعدا لبدء اختبار وكيلك في Agents Playground.

الخطوة 1: تكوين البيئة الخاصة بك

إعداد ملف التكوين الخاص بك:

cp .env.template .env

ملاحظة

للحصول على قوالب التكوين التي تعرض الحقول المطلوبة، راجع عينات Microsoft Agent 365 SDK.

الخطوة 2: تكوين LLM

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

قم بإضافة إلى ملفك: .env

# Replace with your actual OpenAI API key
OPENAI_API_KEY=

# Azure OpenAI Configuration
AZURE_OPENAI_API_KEY=
AZURE_OPENAI_ENDPOINT=
AZURE_OPENAI_DEPLOYMENT=
AZURE_OPENAI_API_VERSION=

متغيرات بيئة Python LLM

المتغير الوصف مطلوب مثال
OPENAI_API_KEY مفتاح واجهة برمجة التطبيقات لخدمة OpenAI لـ OpenAI sk-proj-...
AZURE_OPENAI_API_KEY مفتاح API لخدمة Azure OpenAI لمنصة Azure OpenAI a1b2c3d4e5f6...
AZURE_OPENAI_ENDPOINT عنوان URL لنقطة نهاية خدمة Azure OpenAI لمنصة Azure OpenAI https://your-resource.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT اسم التوزيع في Azure OpenAI لمنصة Azure OpenAI gpt-4
AZURE_OPENAI_API_VERSION إصدار واجهة برمجة التطبيقات ل Azure OpenAI لمنصة Azure OpenAI 2024-02-15-preview

الخطوة 3: قم بتكوين المصادقة لوكيلك

اختر واحدة من طرق المصادقة التالية لوكيلك:

  • المصادقة الوكائلية - استخدامها في سيناريوهات الإنتاج عندما تتوفر هوية مستخدم وكيلية.
  • مصادقة OBO (نيابة عن) - استخدم لسيناريوهات الإنتاج عندما تحتاج إلى أذونات المستخدم المفوضة دون هوية مستخدم عاملية.
  • مصادقة رموز الحامل - تستخدم فقط في سيناريوهات التطوير والاختبار المبكرة قبل تكوين مصادقة الإنتاج.

المصادقة الوكائلية

افتح a365.generated.config.json في دليل العمل لاسترداد بيانات اعتماد الوكيل المخطط. انسخ القيم التالية:

Value الوصف
agentBlueprintId معرف عميل وكيلك
agentBlueprintClientSecret سر عميل وكيلك
tenantId معرف مستأجر Microsoft Entra

استخدم هذه القيم لتكوين مصادقة الوكيل في وكيلك:

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

USE_AGENTIC_AUTH=true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID=<agentBlueprintId>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET=<agentBlueprintClientSecret>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID=<your-tenant-id>
المتغير الوصف مطلوب مثال
USE_AGENTIC_AUTH تمكين وضع المصادقة العاملية نعم true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID معرف عميل مخطط العامل من a365.generated.config.json نعم 11112222-bbbb-3333-cccc-4444dddd5555
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET سر عميل مخطط العامل من a365.generated.config.json نعم abc~123...
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID معرف المستأجر Microsoft Entra من a365.generated.config.json نعم 22223333-cccc-4444-dddd-5555eeee6666

مصادقة OBO

باستخدام مصادقة On-Behalf-Of (OBO)، يمكن للعامل الوصول إلى أدوات خادم MCP باستخدام أذونات المستخدم المفوضة دون الحاجة إلى هوية مستخدم عامل. في هذا التدفق، يستلم الوكيل الرمز المفوض للمستخدم ويبدله لأداء الإجراءات نيابة عنه.

مصادقة OBO مناسبة لسيناريوهات الإنتاج حيث:

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

لمزيد من التفاصيل حول كيفية عمل تدفق OBO، راجع تدفقات المصادقة. للحصول على مثال تنفيذ كامل، راجع نموذج تخويل OBO في Microsoft 365 Agents SDK.

مصادقة رمز الحامل

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

أولا، استخدم a365 develop add-permissions إضافة صلاحيات خادم MCP المطلوبة إلى تطبيقك:

a365 develop add-permissions

ثم، استخدم a365 develop get-token لاسترجاع وتكوين رموز الحامل:

a365 develop get-token

الأمر get-token تلقائيا:

  • يقرأ ToolingManifest.json لاكتشاف جميع خوادم MCP المعدة.
  • الحصول على رمز مميز واحد لكل جمهور - تتلقى خوادم MCP لكل خادم رمزا مميزا محدد النطاق لمعرف التطبيق الخاص بها؛ تتلقى خوادم ATG المشتركة رمزا مميزا محدد النطاق لمعرف تطبيق Agent Tools Gateway المشترك (ea9ffc3e-8a23-4a7d-836d-234d7c7565c1).
  • يكتب الرموز المميزة إلى ملفات تكوين المشروع:
    • الرموز المميزة لكل خادم: BEARER_TOKEN_<SERVER_NAME> (على سبيل المثال، BEARER_TOKEN_MCP_MAILTOOLS)
    • الرمز المميز المشترك لـATG: BEARER_TOKEN

قبل تشغيل get-token، أضف إدخالات العنصر النائب إلى ملف تكوين المشروع:

  • .NET: إضافة "BEARER_TOKEN": "" و/أو "BEARER_TOKEN_<SERVER_NAME>": "" إلى environmentVariables في كل ملف تعريف في Properties/launchSettings.json. يقوم الأمر فقط بتحديث ملفات التعريف التي تم تعريف هذه المفاتيح بالفعل.
  • Python/Node.js: إنشاء ملف .env مع BEARER_TOKEN= و/أو BEARER_TOKEN_<SERVER_NAME>= قبل التشغيل. إذا كان الملف مفقودا، يتخطى الأمر الحفظ ويعرض الإرشادات.

ملاحظة

إذا قمت بتشغيل a365 develop get-token --app-id <id> بدون a365.config.json ملف، فلن يتم حفظ الرموز المميزة تلقائيا. انسخها والصقها يدويا في Properties/launchSettings.json (.NET) أو ملف .env (Python/Node.js).

تنتهي صلاحية رموز الحامل بعد حوالي ساعة واحدة. تستخدمها a365 develop get-token لتحديث الرموز المنتهية الصلاحية.

الخطوة 4: مرجع متغيرات البيئة

أكمل إعداد البيئة الخاصة بك عن طريق تكوين متغيرات البيئة المطلوبة التالية:

متغيرات المصادقة

تكوين إعدادات معالج المصادقة المطلوبة لكي تعمل المصادقة الوكيلية بشكل مثالي.

قم بإضافة إلى ملفك: .env

# Agentic Authentication Settings
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__TYPE=AgenticUserAuthorization
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__SCOPES=https://graph.microsoft.com/.default
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALTERNATEBLUEPRINTCONNECTIONNAME=service_connection

# Connection Mapping
CONNECTIONSMAP_0_SERVICEURL=*
CONNECTIONSMAP_0_CONNECTION=SERVICE_CONNECTION
المتغير الوصف مطلوب
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__TYPE نوع معالج المصادقة نعم
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__SCOPES نطاقات المصادقة لبرنامج Microsoft Graph نعم
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALTERNATEBLUEPRINTCONNECTIONNAME اسم اتصال المخطط البديل نعم
CONNECTIONSMAP_0_SERVICEURL نمط عنوان URL للخدمة لرسم خرائط الاتصال نعم
CONNECTIONSMAP_0_CONNECTION اسم الاتصال للتعيين نعم

متغيرات الرمز المميز للحامل (التطوير المحلي فقط)

المتغير الوصف مطلوب
BEARER_TOKEN الرمز المميز للحامل المشترك لخوادم ATG MCP المشتركة. a365 develop get-token يقوم الأمر تلقائيا بكتابة هذا الرمز المميز. للتطوير المحلي ل ATG المشترك
BEARER_TOKEN_<SERVER_NAME> الرمز المميز للحامل لكل خادم. يقوم SDK باشتقاق الاسم عن طريق تحويل mcpServerName إلى أحرف كبيرة من ToolingManifest.json (مثال: mcp_MailTools → BEARER_TOKEN_MCP_MAILTOOLS). a365 develop get-token يقوم الأمر تلقائيا بكتابة هذا الرمز المميز. للتطوير المحلي لكل خادم على حدة
SKIP_TOOLING_ON_ERRORS اضبط على true للعودة إلى LLM المجرد إذا فشلت أدوات MCP في التحميل. يتم تكريمه فقط عندما ASPNETCORE_ENVIRONMENT أو ENVIRONMENT هو Development. لا

Important

الرموز المميزة للحامل مخصصة للتنمية المحلية فقط. لا تقم بتعيين BEARER_TOKEN أو BEARER_TOKEN_<SERVER_NAME> في عمليات توزيع الإنتاج.

تكوين نقطة نهاية MCP

حدد نقطة نهاية منصة Agent 365 التي يتصل بها وكيلك. عند إنشاء بيان الأدوات الذي يحدد خوادم الأدوات لوكيلك، حدد نقطة نهاية منصة MCP. تحدد نقطة النهاية هذه البيئة (التي تم توفيرها مسبقا أو اختبارها أو إنتاجها) التي تتصل بها خوادم أدوات MCP لإمكانيات تكامل Microsoft 365.

قم بإضافة إلى ملفك: .env

# MCP Server Configuration
MCP_PLATFORM_ENDPOINT=<MCP endpoint>
المتغير الوصف مطلوب افتراضي مثال
MCP_PLATFORM_ENDPOINT عنوان URL لنقطة نهاية منصة MCP (preprod أو test أو prod) لا نقطة نهاية الإنتاج

مهم: إذا لم تحدد MCP_PLATFORM_ENDPOINT، فإن التطبيق يستخدم نقطة الإنتاج.

ملاحظة

إذا كنت تستخدم خادم الأدوات التجريبية من CLI، اضبط نقطة النهاية باستخدام http://localhost:<port> رقم المنفذ الذي استخدمته. المنفذ الافتراضي هو 5309.

متغيرات المراقبة

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

ملاحظة

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

المتغير الوصف افتراضي مثال
ENABLE_A365_OBSERVABILITY_EXPORTER تصدير التتبعات إلى خدمة المراقبة. عندما false، يمتد التصدير إلى وحدة التحكم بدلا من ذلك. false true
A365_OBSERVABILITY_LOG_LEVEL مستوى التسجيل الداخلي لمجموعة أدوات تطوير البرمجيات للملاحظة. مفيد لتصحيح مشكلات التصدير أثناء الاختبار. none info، ، warn، errordebug

تكوين خادم تطبيق العميل

قم بتكوين المنفذ الذي يعمل عليه خادم تطبيق الوكيل الخاص بك. هذا الإعداد اختياري وينطبق على عوامل Python وJavaScript.

قم بإضافة إلى ملفك: .env

# Server Configuration
PORT=3978
المتغير الوصف مطلوب افتراضي مثال
PORT رقم المنفذ حيث يتم تشغيل خادم العامل لا 3978 3978

تثبيت التبعيات وبدء تشغيل خادم تطبيق العامل

بعد إعداد بيئتك، قم بتثبيت التبعيات المطلوبة وتشغيل خادم تطبيق الوكيل محليا للاختبار.

تثبيت التبعيات

uv pip install -e .

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

بدء تشغيل خادم تطبيق الوكيل

python <main.py>

استبدل <main.py> باسم ملف Python الرئيسي الذي يحتوي على نقطة الإدخال لتطبيق العامل الخاص بك (على سبيل المثال، start_with_generic_host.pyأو app.pyأو main.py).

أو استخدم الأشعة فوق البنفسجية:

uv run python <main.py>

خادم العامل الخاص بك قيد التشغيل الآن وجاهز لتلقي الطلبات من Agents Playground أو تطبيقات Microsoft 365.

عامل اختبار في Agents Playground

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

تكوين ملعب الوكلاء للمصادقة الوكائلية

ملاحظة

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

عند استخدام المصادقة الوكيلة، قم بتكوين ملف إعدادات Agents Playground YAML بالتفاصيل المتعلقة بالوكيل الخاص بك:

  1. قم بإعداد ملف التكوين: أنشئ أو حدث الملف .m365agentsplayground.yml في المجلد الذي تشغل فيه Agents Playground. للحصول على تعليمات إعداد مفصلة، راجع تخصيص سياق الفرق.

  2. تحديث تكوين البوت: أضف التفاصيل التالية للبوت إلى ملفك .m365agentsplayground.yml ، واستبدل قيم البوت المؤقتة ببيانات اعتماد الوكيل الفعلي:

    bot:
  id: <your-agent-email>@<your-tenant>.onmicrosoft.com
  name: <Your Agent Name>
  role: agenticUser
  agenticUserId: <your-agentic-user-id>
  agenticAppId: <your-agentic-app-id>
    الخاصية الوصف مطلوب
    id عنوان بريد مستخدم وكيلك الإلكتروني في الصيغة agentusername@tenant.onmicrosoft.com نعم
    name اسم العرض لمستخدم وكيلك نعم
    role يجب ضبطه على agenticUser للمصادقة الوكائلية نعم
    agenticUserId معرف الكائن المستخدم للوكيل. ابحث عن هذه القيمة في مركز إدارة Microsoft Entra في صفحة ملف تعريف مستخدم العامل. نعم
    agenticAppId معرف المستخدم المرتبط بالوكيل. ابحث عن هذه القيمة في مركز إدارة Microsoft Entra في صفحة ملف تعريف مستخدم العامل. نعم

افتح محطة طرفية جديدة (PowerShell على Windows) وابدأ تشغيل Agents Playground:

agentsplayground

يفتح هذا الأمر متصفح ويب بواجهة تسمى "Agents Playground". تعرض الأداة واجهة دردشة حيث يمكنك إرسال رسائل إلى وكيلك.

اختبار أساسي

ابدأ بالتحقق من تكوين عاملك بشكل صحيح. إرسال رسالة إلى العامل:

What can you do?

يرد الوكيل بالتعليمات التي تم تكوينه بها، بناء على موجه النظام الخاص بوكيلك وقدراته. هذا الرد يؤكد أن:

  • وكيلك يعمل بشكل صحيح.
  • يمكن للوكيل معالجة الرسائل والرد.
  • عملية التواصل بين Agents Playground ووكيلكم تعمل بشكل صحيح.

استدعاءات أداة الاختبار

بعد تكوين خوادم أدوات MCP الخاصة بك ( toolingManifest.json انظر الأدوات لتعليمات الإعداد)، اختبر استدعاءات الأدوات باستخدام أمثلة مثل هذه الأمثلة:

أولا، تحقق من الأدوات المتوفرة:

List all tools I have access to

ثم اختبر استدعاءات الأدوات المحددة:

أدوات البريد

Send email to your-email@example.com with subject "Test" and message "Hello from my agent"

الرد المتوقع: يرسل الوكيل بريدا إلكترونيا باستخدام خادم Mail MCP ويؤكد إرسال الرسالة.

أدوات التقويم

List my calendar events for today

الاستجابة المتوقعة: يقوم الوكيل باسترجاع وعرض أحداث تقويمك لليوم الحالي.

أدوات SharePoint

List all SharePoint sites I have access to

الاستجابة المتوقعة: يستعلم العامل SharePoint ويعيد قائمة بالمواقع التي يمكنك الوصول إليها.

يمكنك عرض استدعاءات الأداة في:

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

اختبار مع أنشطة الإشعارات

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

شاشة تعرض واجهة Agents Playground مع توسيع قائمة Mock an Activity، وتعرض خيارات Trigger Notification Activity بما في ذلك إرسال رسالة بريد إلكتروني والإشارة في Word.

قبل اختبار أنشطة الإشعارات، تأكد من:

إشعارات البريد الإلكتروني التجريبي

لاختبار التعامل مع إشعارات البريد الإلكتروني:

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

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

اختبار إشعارات الإشارة في وورد

لاختبار إشعارات الإشارة في مستندات Word

  1. ابدأ وكيلك وبيئة البرمجة الخاصة بالوكلاء.
  2. في ملعب الوكلاء، اذهب إلى محاكاة نشاط> ثم إلى نشاط تفعيل الإشعارات.
  3. اختر Mention في Word.
  4. في مربع حوار الحمولة، قم بتحديث تفاصيل التعليق الوهمي مثل معرف المستند ونص التعليق حسب الحاجة.
  5. اختر إرسال النشاط.
  6. شاهد النتيجة في كل من محادثة الدردشة ولوحة السجل.

يتلقى العميل تنبيهاً محاكياً للإشارة إلى Word ويستجيب وفقاً للمنطق المعتمد لمعالجة الإشعارات. للحصول على تفاصيل حول بنية حمولة إعلام التعليق Word، راجع حمولة إعلام التعليق Document.

اختبار تثبيت عامل الأحداث وإلغاء تثبيتها

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

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

  1. ابدأ تشغيل خادم الوكيل الخاص بك.
  2. افتح "Agents Playground". تتصل منصة الاختبار بالوكيل الخاص بك وتُشغل حدث التثبيت تلقائيًا.
  3. تأكد من ظهور رسالة الترحيب في محادثة الدردشة.

لقطة شاشة تعرض واجهة Agents Playground مع رسالة ترحيب الوكيل

للحصول على تفاصيل حول تنفيذ المعالج، راجع معالجة تثبيت العامل وإلغاء تثبيت الأحداث.

عرض سجلات إمكانية المراقبة

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

  • تتبعات استدعاء الوكيل
  • تفاصيل تنفيذ الأداة
  • استدعاءات الاستدلال LLM
  • رسائل الإدخال والإخراج
  • اِسْتِخْدَام الرمز المميز
  • أوقات الاستجابة
  • معلومات الخطأ

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

الخطوات التالية

بعد اختبار الوكيل محليا، انشره على Azure ونشره على Microsoft 365.

لاختبار وكيلك في تطبيقات Microsoft 365 مثل Teams وWord وOutlook، راجع دورة حياة تطوير العامل 365.

استكشاف الأخطاء وإصلاحها

يقدم هذا القسم حلولا للمشاكل الشائعة التي قد تواجهها عند اختبار وكيلك محليا.

Tip

يحتوي دليل استكشاف أخطاء العميل 365 على توصيات عالية المستوى، وأفضل الممارسات، وروابط لمحتوى استكشاف الأخطاء لكل جزء من دورة تطوير الوكيل 365.

مشاكل الاتصال والبيئة

تتعلق هذه المشاكل باتصال الشبكة وتعارضات المنفذ ومشاكل إعداد البيئة التي تمنع الوكيل من الاتصال بشكل صحيح.

مشاكل الاتصال بملعب الوكلاء

العرض: Agents Playground لا يستطيع الاتصال بوكيلك.

الحلول‏‎:

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

إصدار Agents Playground القديم

العرض: أخطاء غير متوقعة أو ميزات مفقودة في بيئة الوكلاء.

الحل: قم بإلغاء تثبيت وإعادة تثبيت Agents Playground.

winget uninstall agentsplayground
winget install agentsplayground

تعارضات المنافذ

العرض: خطأ يشير إلى أن المنفذ قيد الاستخدام بالفعل.

الحل:

  • أوقف أي مثيلات أخرى لوكيلك.
  • غير المنفذ في إعدادك.
  • قم بإيقاف أي عمليات باستخدام المنفذ.
# Windows PowerShell
Get-Process -Id (Get-NetTCPConnection -LocalPort <port>).OwningProcess | Stop-Process

لا يمكن إضافة DeveloperMCPServer

Symptom: خطأ عند محاولة إضافة DeveloperMCPServer في تعليمة Visual Studio برمجية.

الحل: أغلق تعليمة Visual Studio برمجية وأعد فتحه، ثم حاول إضافة الخادم مرة أخرى.

مشاكل المصادقة والرموز

تحدث هذه المشاكل عندما يتعذر على الوكيل المصادقة بشكل صحيح مع خدمات Microsoft 365 أو عند انتهاء صلاحية بيانات الاعتماد أو تكوينها بشكل خاطئ.

الأعراض:

  • 401 أخطاء غير مصرح بها
  • رسائل "رمز الحامل انتهت صلاحيتها"
  • فشل المصادقة الذاتية

السبب الجذري:

  • تنتهي صلاحية الرموز بعد حوالي ساعة واحدة
  • تكوين المصادقة غير الصحيح
  • بيانات الاعتماد المفقودة أو غير الصالحة

الحلول‏‎:

  • بالنسبة لانتهاء انتهاء الرمز الحامل

    حدث الرمز الخاص بك وحدث متغيرات البيئة.

    # Get a new token
a365 develop get-token

# Update your .env file with the new token

  • لحالات فشل الرمز المميز للحامل لكل خادم

    تحقق من أن ملف التكوين الخاص بك يحتوي على إدخالات عنصر نائب لكل خادم (BEARER_TOKEN_<SERVER_NAME>)، ثم أعد تشغيله a365 develop get-token لملئه. تستمد مجموعة تطوير البرمجيات (SDK) اسم المتغير عن طريق تحويل الأحرف mcpServerName إلى أحرف كبيرة في ToolingManifest.json واستبدال الواصلات بشرطة سفلية (على سبيل المثال، mcp_MailTools → BEARER_TOKEN_MCP_MAILTOOLS).

  • لأخطاء المصادقة الوكيلية (Python)

    تحقق من ملفك .env :

    # Should be (with underscore):
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=SERVICE_CONNECTION

# Not:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=ServiceConnection

  • بسبب الشهادات المفقودة

    تأكد من وجود الاعتمادات المطلوبة قبل الاختبار.

    ضمان احتواء .env أو appsettings.json

    • مفاتيح وأسرار واجهة برمجة التطبيقات
    • معرف المستأجر
    • معرّف العميل
    • معرف Blueprint ID (إذا كنت تستخدم المصادقة الوكيلية)

    التحقق:

    اختبر بطلب بسيط في ملعب الوكلاء. يجب أن تتلقى ردا بدون أخطاء 401.

  • مشاكل الأداة والإشعارات

    تشمل هذه المشاكل مشاكل في استدعاءات الأدوات، وتفاعلات خوادم MCP، وتسليم الإشعارات.

لم يتم استلام البريد الإلكتروني

الأعراض: يشير العامل إلى أنه تم إرسال البريد الإلكتروني، ولكنك لم تتلقه

الحلول‏‎:

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

ردود التعليقات في برنامج وورد لا تعمل

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

الرسائل لا تصل إلى الوكيل

العرض: تطبيق الوكيل الخاص بك لا يستقبل الرسائل التي ترسل إلى الوكيل في مايكروسوفت تيمز.

الأسباب المحتملة:

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

الحلول‏‎:

  • تحقق من تكوين بوابة المطورين:

    تأكد من إكمال تكوين مخطط الوكيل في بوابة المطورين. تعلم كيفية تكوين مخطط الوكيل في بوابة المطورين.

  • تحقق من صحة Azure Web App:

    إذا قمت بنشر عاملك على Azure، فتحقق من تشغيل تطبيق الويب بشكل صحيح:

    1. انتقل إلى مدخل Azure.
    2. اذهب إلى مورد تطبيق الويب الخاص بك.
    3. تحقق مننظرة عامة>حالة (يجب أن يظهر "قيد التشغيل").
    4. تحقق من تدفق السجلات تحت قسم المراقبة بحثا عن أخطاء وقت التشغيل.
    5. راجع سجلات مركز النشر للتحقق من نجاح النشر.
    6. تحقق من أن إعدادات التطبيق>تحتوي على جميع المتغيرات البيئية المطلوبة.

  • تحقق من إنشاء مثيل الوكيل:

    تأكد من إنشاء مثيل العامل بشكل صحيح في Microsoft Teams:

    1. افتح Microsoft Teams.
    2. اذهب إلى التطبيقات وابحث عن وكيلك.
    3. تحقق من ظهور الوكيل في نتائج البحث.
    4. إذا لم يتم العثور عليه، فتحقق من نشره في مركز إدارة Microsoft 365 - Agents.
    5. أنشئ مثيلًا جديدًا باختيار إضافة في وكيلك.
    6. للحصول على تعليمات تفصيلية، راجع وكلاء الخدمة.

استكشاف أخطاء سجلات إمكانية المراقبة وإصلاحها

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

  • Last updated on