مشاركة عبر

التشغيل السريع: إعداد وتفعيل وكيل العينة باستخدام إطار عمل Python

Important

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

في هذا التشغيل السريع، سيتم استعراض إعداد عامل إطار عمل Agent لـ Python باستخدام Agent 365 للأدوات، والإشعارات، والرصد، واختبار العامل باستخدام Agents Playground وTeams.

المتطلبات

  • إذا كنت تخطط لاستخدام Visual Studio Code، فيجب أن يكون لديك .NET مثبتا. (يوصى .NET 8.0.)

  • Python 3.11+ مثبتة

  • تم تثبيت مدير حزمة UV. قم بتثبيت هذا في محطة طرفية باستخدام pip install uv.

  • تبعيات مجموعة أدوات Microsoft Agents / Agent Framework

    تعتمد العينة المستخدمة في المعاينة على مكتبات إطار عمل العامل المقدمة من خلال مجموعة أدوات Microsoft 365 Agents أو ATK. ستقوم بتثبيت هذه تلقائيًا عند استخدام ملحق برنامج مجموعة أدوات Agents في VS Code لدعم النموذج، أو يمكنك تثبيت الحزمة يدويًا باستخدام هذا الأمر:

    uv pip install -e . --prerelease=allow

  • الوصول إلى GitHub

  • هناك مشروع وكيل الذكاء الاصطناعي موجود. يستخدم هذا البدء السريع عامل عينة Agent 365 من مجموعة أدوات عامل Microsoft 365 المعروفة أيضا باسم ATK في VS Code.

  • A365 CLI

  • مصادقة هوية العامل

إعداد نموذج إطار عمل العامل + Python من مجموعة أدوات Microsoft 365 Agents

لإعداد كل شيء، يمكنك تثبيت مجموعة أدوات Microsoft 365 Agents في VS Code، وافتح معرض العينات، وقم بدعم إطار عمل العامل + Python عينة محليا حتى تتمكن من تكوينه وتشغيله لاحقا. تظهر لقطات الشاشة التالية ما يجب أن تتوقع رؤيته أثناء التنقل.

  1. افتح Visual Studio Code، ثم افتح لوحة ExtensionsCtrl+Shift+X.

  2. في شريط البحث، اكتب "Agents Toolkit".
    يجب أن تشاهد النتيجة الموضحة في لقطة الشاشة هنا:

    لقطة شاشة للبحث في Extensions Marketplace عن Agents Toolkit.

  3. حدد Microsoft 365 Agents Toolkit.

  4. حدد تثبيت.

    تظهر VS Code طريقة عرض تفاصيل الملحق مشابهة لـ:

    لقطة شاشة لصفحة تفاصيل الملحق مع أزرار التثبيت والتمكين.

  5. بمجرد التثبيت، تظهر أيقونة M365 Agents Toolkit في شريط التنقل الأيمن.

  6. اختره لفتح تجربة الترحيب.

    يجب أن تشاهد الآن خيارات مثل إنشاء عامل تعريفي، إنشاء عامل/تطبيق جديد، و عرض العينات، كما هو موضح هنا:

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

  7. حدد عرض العينات.

  8. في قائمة العينات، قم بالتمرير للعثور على إطار عمل Agent + نموذج عامل Python.

  9. حدده.

    سترى خيارين: إنشاء (سقالة محليا) أو عرض على GitHub.

  10. اختر إنشاء.

    لقطة شاشة لعامل Agent Framework مع Agent 365 SDK باستخدام نموذج Python.

  11. عند المطالبة، حدد مجلدًا على جهازك حيث يجب إنشاء العينة. على سبيل المثال: C:\A365-python-sample

    تقوم مجموعة الأدوات بدعم إطار عمل العامل + عينة Python في مجلد فرعي (مثل sample_agent) ثم تفتحه تلقائيا في VS Code.

    بمجرد اكتمال التدعيم، لديك الآن إطار عمل عامل يعمل بكامل طاقته + مشروع عامل Python على جهازك

  12. تثبيت حزم Agent 365 المطلوبة

    قبل تشغيل النموذج، افتح pyproject.toml في مشروعك وتأكد من إدراج جميع التبعيات المطلوبة لـ Agent 365 وAgent framework. تتضمن العينة التي تم إنشاؤها بواسطة مجموعة أدوات Microsoft 365 Agents بالفعل هذه الإدخالات.

    بعد مراجعة pyproject.toml، قم بتثبيت كل شيء عن طريق تشغيل هذا الأمر:

    uv pip install -e . --prerelease=allow

    يؤدي هذا إلى سحب جميع مكتبات Agent 365 SDK وتبعيات Agent Framework ومكونات الاستضافة وأي تبعيات أخرى محددة في العينة.

  13. بعد التثبيت، تحقق من إنشاء المشروع وتشغيله عن طريق بدء تشغيل خادم التطوير باستخدام هذا الأمر:

    uv run python start_with_generic_host.py

إضافة أدوات Microsoft 365 (خوادم MCP)

يمكنك استكشاف وإدارة خوادم MCP باستخدام أوامر تطوير a365 في CLI.

عند العمل مع خوادم MCP، يمكنك:

  • اكتشاف خوادم MCP المتوفرة للاستخدام
  • أضف خادمًا واحدًا أو أكثر من خوادم MCP إلى تكوين العامل الخاص بك
  • مراجعة خوادم MCP التي تم تكوينها حاليًا
  • إزالة خوادم MCP التي لم تعد بحاجة إليها

بعد إضافة خوادم MCP، يتوسع بيان أدوات العامل الخاص بك ليشمل إدخالات مشابهة لـ:

{
   "mcpServers": [
      {
         "mcpServerName": "mcp_MailTools",
         "mcpServerUniqueName": "mcp_MailTools",
         "scope": "McpServers.Mail.All",
         "audience": "api://00001111-aaaa-2222-bbbb-3333cccc4444"
      }
   ]
}

تعرف على كيفية إضافة الأدوات وإدارتها

الاشتراك في الإعلامات ومعالجتها

يشترك وكيل العينة في جميع إشعارات SDK الخاصة بوكيل 365 باستخدام onAgentNotification("*") ويقوم بتوجيهها إلى معالج واحد. يسمح هذا المعالج للعامل بالتفاعل مع أحداث الخلفية أو النظام، وليس فقط رسائل المستخدم المباشرة.

تعرف على كيفية إعلام العوامل

توضح التعليمة البرمجية التالية كيفية تكوين الإعلام في الملف agent.py.

if notification_type == NotificationTypes.EMAIL_NOTIFICATION: 
if not hasattr(notification_activity, "email") or not notification_activity.email: return "I could not find the email notification details."
email = notification_activity.email
email_body = getattr(email, "html_body", "") or getattr(email, "body", "")

message = (
    "You have received the following email. "
    "Please follow any instructions in it. "
    f"{email_body}"
)

result = await self.agent.run(message)
return self._extract_result(result) or "Email notification processed."

قابلية الملاحظة

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

تظهر التعليمة البرمجية التالية مثالاً مبسطًا لقابلية الملاحظة في الملف agent.py.

def _enable_agentframework_instrumentation(self): 
"""Enable Agent Framework instrumentation.""" 
try: 
AgentFrameworkInstrumentor().instrument() 
logger.info("✅ Instrumentation enabled")
 except Exception as e: 
logger.warning(f"⚠️ Instrumentation failed: {e}")

هذه التعليمة البرمجية هي إعداد إمكانية المراقبة الكامل المطلوب لعينة إطار عمل Python + Agent. اعرف المزيد حول إمكانية المراقبة

اختبار عاملك

قم بتعيين متغيرات البيئة المطلوبة، وحدد وضع المصادقة، وابدأ تشغيل العامل محليًا. يمكنك اختبار كل شيء من طرف إلى طرف باستخدام Agents Playground دون الحاجة إلى مستأجر Microsoft 365 إلا إذا كنت تريد نشر العامل واستخدامه في تطبيقات مثل Teams أو Outlook.

نظرة عامة على خطوات الاختبار

  • أضف مفاتيح واجهة برمجة التطبيقات وإعدادات النموذج إلى ملفل .env حتى يتمكن النموذج من التحدث إلى LLM.
  • اختر وضع المصادقة الخاص بك. للتطوير المحلي، تدعم العينة المصادقة الوكيلة باستخدام القيم التي تم إنشاؤها من Agent Blueprint.
  • ابدأ تشغيل العامل محليًا، مما يعرضه لأدوات مثل Agents Playground.
  • استخدم Agents Playground لاختبار الرسائل والأدوات والإعلامات دون إعداد مستأجر أو نشر أي شيء.
  • عندما تكون مستعدا للسلوك في العالم الحقيقي، انشر مستأجرا Microsoft 365 واختبر العامل داخل Teams أو Outlook أو أسطح Microsoft 365 الأخرى.

اعرف المزيد حول الاختبار

نشر الوكيل الخاص بك

عندما يكون وكيلك جاهزا لتجارب Microsoft 365 الفعلية مثل دردشات Teams، Outlook الرسائل، Word @mentions، يمكنك نشره إلى مستأجر Microsoft 365. أمر CLI publish الخاص بالوكيل 365 يتولى التغليف: يقوم بتحديث البيان الخاص بك، ويجمع كل شيء، ويرفع الوكيل إلى مركز إدارة مايكروسوفت.

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

Important

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

يمكنك عرض الوكلاء المنشورين هنا: https://admin.cloud.microsoft/#/agents/all

تعرف على المزيد حول سير العمل الكامل والإرشادات خطوة بخطوة

  • Last updated on