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

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

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

نظرة عامة

يتبع تكامل أدوات العامل 365 سير العمل هذا:

  1. تكوين خوادم MCP - استخدم Agent 365 CLI لاكتشاف خوادم MCP وإضافتها
  2. إنشاء بيان - ينشئ ToolingManifest.json CLI في مجلد المشروع الخاص بك مع تكوينات الخادم.
  3. تطبيق الأذونات على المخطط - يمنح المسؤول العام أذونات OAuth2 لمخطط العامل عن طريق تشغيل a365 setup all (الإعداد لأول مرة) أو a365 setup permissions mcp (إذا كان المخطط موجودا بالفعل). وفي كلتا الحالتين ToolingManifest.json ، يقرأ الأمر ويتطلب موافقة المسؤول. هذه الخطوة دائما منفصلة عن إضافة خوادم إلى البيان.
  4. التكامل في التعليمات البرمجية - تحميل مكونات البرنامج وتسجيل الأدوات مع المنسق الخاص بك.
  5. استدعاء الأدوات - يستدعي العامل أدوات أثناء التنفيذ لتنفيذ العمليات.

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

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

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

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

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

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

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

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

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

Important

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

  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

Important

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

  • قبل الإعداد الأولي: قم بتشغيل a365 develop add-mcp-servers أولا، ثم تابع مع a365 setup all. setup all يتضمن الأمر خطوة أذونات MCP كجزء من إنشاء المخطط.
  • بعد وجود المخطط بالفعل: يجب تشغيل a365 setup permissions mcp المسؤول العام بشكل منفصل. يجب أن يشير a365.config.json المسؤول deploymentProjectPath إلى مجلد المشروع الذي يحتوي على المحدث ToolingManifest.json. حتى تكتمل هذه الخطوة، لا تكون أذونات خادم MCP الجديدة مرئية في المخطط.

قائمة الخوادم المُعَدَّة

عرض خوادم 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 ID URI الذي يحدد مورد واجهة برمجة التطبيقات الهدف. تسترجع add-mcp-servers هذه القيمة من كتالوج خادم MCP.

ملاحظة

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

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

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

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

Tip

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

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

  • استخلص جميع خوادم 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)

البارامترات:

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

الحزمة: microsoft_agents_a365.tooling

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

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

  • AddToolServersToAgentAsync (.NET)
  • add_tool_servers_to_agent (Python)
  • addToolServersToAgent (Node.js)

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

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

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

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

ملاحظة

عند تشغيل a365 develop add-mcp-servers، يسترد CLI تلقائيا نطاقات OAuth وقيم الجمهور من كتالوج خادم MCP ويكتبها إلى ToolingManifest.json. تستخدم أساليب الملحق هذه القيم لإعداد المصادقة في وقت التشغيل — لا يلزم تكوين يدوي في التعليمات البرمجية للعامل. ومع ذلك، يجب على المسؤول العام منح هذه الأذونات لمخطط العامل قبل أن يتمكن الوكيل من استخدامها في الإنتاج: عبر a365 setup all (الإعداد لأول مرة) أو a365 setup permissions mcp (إذا كان المخطط موجودا بالفعل).

للحصول على أمثلة تنفيذ مفصلة، راجع عينات 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 من خلال تجارب تطوير أخرى:

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

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

اختبار وكيلك

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

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

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

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

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

Tip

يحتوي دليل استكشاف أخطاء العميل 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