بدء سريع: إعداد نموذج عامل إطار عمل وكيل بايثون وتشغيله

في هذا الدليل السريع، ستتعلم كيفية إعداد إطار عمل لوكيل Python باستخدام Agent 365 بهدف استخدام الأدوات، والإشعارات، وتحقيق إمكانية الرصد، واختبار الوكيل باستخدام منصات Agents Playground وTeams.

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

  • إذا كنت تخطط لاستخدام تعليمة Visual Studio برمجية، فيجب أن يكون لديك .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 برمجية، ثم افتح لوحة 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 365 باستخدام نموذج بايثون.

  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.

عندما تعمل مع أدوات Microsoft 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."

Observability

مهم

تستخدم هذه العينة مجموعة SDK قابلية الملاحظة Agent 365 المهجورة. تجنب استخدام هذا النمط لتكامل جديد لإمكانية المراقبة. استخدم توزيعة Microsoft OpenTelemetry بدلا من ذلك.

يظهر المقتطف التالي إعداد Agent 365 Observability SDK المهمل المستخدم في المثال.

تظهر التعليمة البرمجية التالية مثالاً مبسطًا لقابلية الملاحظة في الملف 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}")

يستخدم هذا الكود إعداد SDK قابلية الملاحظة Agent 365 القديم المطلوب لنموذج إطار عمل Python + Agent. للاطلاع على الإعداد الكامل وإرشادات ترحيل Microsoft OpenTelemetry، راجع وثائق SDK المهملة.

اختبار وكيلك

قم بتعيين متغيرات البيئة المطلوبة، وحدد وضع المصادقة، وابدأ تشغيل العامل محليًا. يمكنك اختبار كل شيء من طرف إلى طرف باستخدام 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 يتولى التغليف: يقوم بتحديث البيان الخاص بك، ويجمع كل شيء، ويرفع الوكيل إلى مركز إدارة مايكروسوفت.

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

مهم

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

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

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

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