مشاركة عبر

إضافة الأدوات وإدارتها

مهم

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

تساعد وحدة الأدوات المطورين على اكتشاف وتكوين ودمج خوادم بروتوكول السياق النموذجي (MCP) في سير عمل الوكلاء الذكاء الاصطناعي. تعرض خوادم MCP القدرات الخارجية كأدوات يمكن للوكلاء الذَّكَاءُ الاصْطِنَاعِيُّ استدعاءها. للحصول على نظرة عامة على خوادم الأدوات المتوفرة، راجع خوادم أدوات Agent 365.

يوضح تدفق الطلب والاستجابة

نظرة عامة

يتبع تكامل أدوات Agent 365 سير عمل مكون من أربع خطوات:

  1. تكوين خوادم MCP - استخدم Agent 365 CLI لاكتشاف خوادم MCP وإضافتها
  2. إنشاء بيان - ينشئ ToolingManifest.json CLI مع تكوينات الخَادِم
  3. التكامل في التعليمات البرمجية - تحميل بيان وتسجيل الأدوات مع المنسق الخاص بك
  4. استدعاء الأدوات - أدوات استدعاء العامل أثناء التنفيذ لتنفيذ العمليات

المتطلبات

قبل تكوين خوادم MCP، تأكد من أن لديك:

إعداد هوية العامل

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

إعداد مصادقة OBO

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

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

إعداد كيان الخدمة

شغل هذا السكريبت لمرة واحدة لإنشاء مبدأ الخدمة لأدوات Agent 365 في المستأجر الخاص بك.

مهم

تتطلب هذه العملية لمرة واحدة لكل مستأجر صلاحيات المسؤول العام.

  1. حمل نص New-Agent365ToolsServicePrincipalProdPublic.ps1 .

  2. افتح PowerShell كمسؤول واذهب إلى مجلد السكريبت.

  3. تشغيل البرنامج النصي.

    .\New-Agent365ToolsServicePrincipalProdPublic.ps1

  4. سجل الدخول باستخدام بيانات اعتماد Azure عند طلب الطلب.

بعد الانتهاء، يكون المستأجر الخاص بك جاهزا لتطوير العامل وتكوين خَادِم MCP.

تكوين خوادم MCP

استخدم Agent 365 CLI لاكتشاف خوادم MCP وإضافتها وإدارتها لوكيلك. للحصول على قائمة كاملة بخوادم MCP المتوفرة وقدراتها، راجع كتالوج خَادِم MCP.

اكتشاف الخوادم المتوفرة

قم بإدراج جميع خوادم MCP التي يمكنك تهيئتها:

a365 develop list-available

إضافة خوادم MCP

أضف خَادِما واحدا أو أكثر من خوادم MCP إلى تكوين العامل الخاص بك:

a365 develop add-mcp-servers mcp_MailTools

قائمة الخوادم المكونة

عرض خوادم MCP المكونة حاليا:

a365 develop list-configured

إزالة خوادم MCP

إزالة خَادِم MCP من التكوين الخاص بك:

a365 develop remove-mcp-servers mcp_MailTools

للحصول على مرجع CLI الكامل، انظر a365 development command.

استخدم خادم أدوات المحاكاة للاختبار

للاختبار والتطوير، استخدم خادم أدوات CLI التجريبي Agent 365 بدلا من الاتصال بخوادم MCP الفعلية. يقوم خادم الوداع بمحاكاة تفاعلات خوادم MCP، لذا يمكنك اختبار وكيل التصنيع محليا دون تبعيات خارجية مثل المصادقة.

يقدم خادم النماذج الفوائد التالية للتطوير المحلي والاختبار:

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

ابدأ خادم الأدوات التجريبية باستخدام a365 develop start-mock-tooling-server الأمر.

تعلم إعداد وتكوين خادم الأدوات الوهمية.

إشعار

الأقسام التالية لتكوين القوائم ودمج الأدوات مع وكيلك تعمل بنفس الطريقة سواء كنت تستخدم خادم الأدوات التجريبية أو خوادم MCP الفعلية. قم بتعيين متغير البيئة ليشير MCP_PLATFORM_ENDPOINT إلى خادم المحاكاة (على سبيل المثال: http://localhost:5309) بدلا من نقطة الإنتاج.

فهم بيان الأدوات

عند تشغيل a365 develop add-mcp-servers، ينشئ CLI ملفا ToolingManifest.json يحتوي على تكوين لكافة خوادم MCP. يستخدم وقت تشغيل العامل هذا البيان لفهم الخوادم المتوفرة وكيفية المصادقة معها.

بنية البيان

مثال ToolingManifest.json:

{
  "mcpServers": [
    {
      "mcpServerName": "mcp_MailTools",
      "mcpServerUniqueName": "mcp_MailTools",
      "scope": "McpServers.Mail.All",
      "audience": "api://05879165-0320-489e-b644-f72b33f3edf0"
    }
  ]
}

المعلمات الظاهرة

يحتوي كل إدخال خَادِم MCP على:

المعلمات الأوصاف
mcpServerName اسم العرض لخَادِم MCP
mcpServerUniqueName المعرف الفريد لمثيل خَادِم MCP
نطاق نطاق OAuth المطلوب للوصول إلى قدرات خَادِم MCP (على سبيل المثال: McpServers.Mail.All لعمليات البريد). تسترجع add-mcp-servers هذه القيمة من كتالوج خادم MCP.
الجمهور معرف معرف Microsoft Entra URI الذي يعرف مورد واجهة برمجة التطبيقات الهدف. تسترجع add-mcp-servers هذه القيمة من كتالوج خادم MCP.

إشعار

يقوم CLI الوكيل 365 تلقائيا بملء قيم scope و audience عند إضافة خادم MCP. تأتي هذه القيم من كتالوج خَادِم MCP وتحدد الأذونات المطلوبة للوصول إلى كل خَادِم MCP.

دمج الأدوات في المندوب الخاص بك

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

خوادم أدوات القوائم (اختياري)

تلميح

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

استخدم خدمة تكوين خَادِم الأدوات لاكتشاف خوادم الأدوات المتوفرة للعامل الخاص بك من بيان الأدوات. يسمح لك هذا الأسلوب ب:

  • استعلام جميع خوادم MCP المكونة من الملف ToolingManifest.json .
  • استرجاع بيانات تعريف الخادم وقدراتها.
  • تحقق من توفر الخادم قبل التسجيل.

يتوفر أسلوب سرد خوادم الأدوات في حزم الأدوات الأساسية:

# Use McpToolServerConfigurationService.list_tool_servers
from microsoft.agents.a365.tooling import McpToolServerConfigurationService

config_service = McpToolServerConfigurationService()
tool_servers = await config_service.list_tool_servers(agentic_app_id, auth_token)

المعلمات:

المعلمة‬ النوع الوصف القيمة المتوقعة مطلوب/اختياري
agentic_app_id str المعرف الفريد لمثيل تطبيق العامل سلسلة معرف تطبيق عامل صالحة مطلوبة
auth_token str الرمز المميز للحامل للمصادقة مع بوابة خَادِم MCP رمز حامل OAuth صالح مطلوبة

الحزمة: microsoft-agents-a365-tooling

تسجيل الأدوات مع المنسق الخاص بك

استخدم أسلوب الملحق الخاص بإطار العمل لتسجيل جميع خوادم MCP مع إطار عمل التنسيق الخاص بك:

  • AddToolServersToAgentAsync (.NET)
  • add_tool_servers_to_agent (بايثون)
  • addToolServersToAgent (Node.js)

هذه الأساليب:

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

اختر ملحق المنسق الخاص بك

توفر وحدة أدوات Agent 365 حزم ملحقة مخصصة لأطر عمل تنسيق مختلفة:

  • microsoft-agents-a365-tooling: وظيفة الأدوات الأساسية
  • microsoft-agents-a365-tooling-extensions-agentframework: تكامل Agent Framework
  • microsoft-agents-a365-tooling-extensions-azureaifoundry: تكامل Azure الذَّكَاءُ الاصْطِنَاعِيُّ Foundry
  • microsoft-agents-a365-tooling-extensions-openai: تكامل OpenAI
  • microsoft-agents-a365-tooling-extensions-semantickernel: تكامل Kernel الدلالي

إشعار

يتم تكوين المصادقة تلقائيا بواسطة Agent 365 CLI عند تشغيل a365 develop add-mcp-servers. يقوم كتالوج خوادم MCP باسترجاع نطاقات OAuth وقيم الجمهور ويدرجها في .ToolingManifest.json تستخدم أساليب الملحق هذه القيم تلقائيا لإعداد المصادقة - لا يلزم تكوين يدوي.

للحصول على أمثلة تنفيذ مفصلة، راجع عينات Agent 365.

أمثلة التنفيذ

توضح الأمثلة التالية كيفية دمج أدوات الوكيل 365 مع أطر تنسيق مختلفة.

Python مع OpenAI

يوضح هذا المثال كيفية دمج أدوات MCP مع OpenAI في تطبيق Python.

1. إضافة عبارات الاستيراد

أضف عمليات الاستيراد المطلوبة للوصول إلى وحدة الأدوات وملحقات OpenAI:

from microsoft.agents.a365.tooling import McpToolServerConfigurationService
from microsoft.agents.a365.tooling.extensions.openai import mcp_tool_registration_service

2. تهيئة خَدَمَات الأدوات

إنشاء مثيلات من خَدَمَات التكوين وتسجيل الأدوات:

# Create configuration service and tool service with dependency injection
self.config_service = McpToolServerConfigurationService()
self.tool_service = mcp_tool_registration_service.McpToolRegistrationService()

3. تسجيل أدوات MCP مع عامل OpenAI

add_tool_servers_to_agent استخدم الأسلوب لتسجيل جميع أدوات MCP المكونة مع عامل OpenAI الخاص بك. يعالج هذا الأسلوب كلا من سيناريوهات المصادقة الوكيلة وغير القديمة:

async def setup_mcp_servers(self, auth: Authorization, context: TurnContext):
    """Set up MCP server connections"""
    try:
        use_agentic_auth = os.getenv("USE_AGENTIC_AUTH", "false").lower() == "true"
        if use_agentic_auth:
            self.agent = await self.tool_service.add_tool_servers_to_agent(
                agent=self.agent,
                agentic_app_id=agentic_app_id,
                auth=auth,
                context=context,
            )
        else:
            self.agent = await self.tool_service.add_tool_servers_to_agent(
                agent=self.agent,
                agentic_app_id=agentic_app_id,
                auth=auth,
                context=context,
                auth_token=self.auth_options.bearer_token,
            )

    except Exception as e:
        logger.error(f"Error setting up MCP servers: {e}")

معلمات الأسلوب

يوضح الجدول التالي المعلمات التي يجب اِسْتِخْدَامها مع add_tool_servers_to_agent.

المعلمات الأوصاف
agent مثيل عامل OpenAI لتسجيل الأدوات به.
agentic_app_id المعرف الفريد للعامل (معرف التطبيق العامل).
auth سياق التخويل للمستخدم.
context تحول المحادثة الحالية السياق من Agents SDK. يوفر هوية المستخدم وبيانات تعريف المحادثة وسياق المصادقة لتسجيل الأداة الآمنة.
auth_token (اختياري) الرمز المميز للحامل لسيناريوهات المصادقة غير القديمة.

4. الاتصال أثناء التهيئة

تأكد من استدعاء أسلوب الإعداد أثناء التهيئة قبل تشغيل العامل:

# Setup MCP servers during initialization
await self.setup_mcp_servers(auth, context)

add_tool_servers_to_agent الاسلوب تلقائيا:

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

للحصول على أمثلة عمل كاملة، راجع مستودع Agent 365 Samples.

طرق أخرى للوصول إلى خوادم العميل 365 MCP

بالإضافة إلى حزمة تطوير Agent 365، يمكنك الوصول إلى خوادم Agent 365 MCP من خلال تجارب تطوير أخرى:

  • كود فيجوال ستوديو - اتصل مباشرة بخوادم MCP لسير عمل التطوير المخصص.
  • Microsoft Copilot Studio - دمج خوادم MCP في تدفقات المحادثة باستخدام تجربة منخفضة الكود.
  • Azure AI Foundry - استخدم خوادم MCP مع دعم كامل لمجموعات تطوير البرمجيات وقدرات تنسيق متقدمة.

للحصول على نظرة شاملة على خوادم MCP المتاحة وخيارات التكامل عبر هذه المنصات، راجع نظرة عامة على خوادم أدوات Agent 365.

اختبار عاملك

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

اضافة إمكانية المراقبة

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

Troubleshooting

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

تلميح

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

مشاكل خادم MCP وأدوات التصنيع

الأعراض:

  • فشل استدعاء الأدوات.
  • أخطاء "خادم MCP لم يعثر".
  • تم رفض الإذن وتظهر أخطاء عند استدعاء الأدوات.

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

  • خادم MCP غير مهيأ.
  • الأصوات المفقودة.
  • مدير الخدمة غير معد.
  • ارتباك بين خوادم التمثيل والإنتاج.

الحلول: جرب الحلول التالية لمعالجة المشكلة.

  • تحقق من تكوين خوادم MCP

    قم بإدراج الخوادم المهيأة وأضف أي خوادم مفقودة.

    # List configured servers
a365 develop list-configured

# If empty, add required servers (example: Mail MCP server)
a365 develop add-mcp-servers mcp_MailTools

  • تحقق من وجود مبدأ الخدمة

    تأكد من إنشاء مبدأ الخدمة المطلوب للأدوات الجاهزة.

    # Run the one-time setup script
# https://github.com/microsoft/Agent365-devTools/blob/main/scripts/cli/Auth/New-Agent365ToolsServicePrincipalProdPublic.ps1

  • للتطوير والاختبار المبكر، استخدم خوادم تجريبية

    استخدم خادم الأدوات التجريبية للتطوير المحلي المبكر والاختبار إذا كنت تريد اختبار بقية وكيلك بدون مكونات أدوات الإنتاج.

    # Start mock tooling server
a365 develop start-mock-tooling-server

# Update your .env
MCP_PLATFORM_ENDPOINT=http://localhost:5309

    تعرف على خادم أدوات النماذج الوهمية.

  • تحقق من الأدنوات في مركز الإدارة

    تأكد من أن وكيلك لديه صلاحيات MCP اللازمة.

    • تحقق من أن صلاحيات واجهة برمجة تطبيقات المخطط للوكيل في بوابة Azure تظهر جميع صلاحيات خادم MCP.

    التحقق:

    # Test a tool call in Agents Playground
# Should execute without permission errors
  • Last updated on