مشاركة عبر

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

مهم

يجب أن تكون جزءًا من برنامج الإصدار الأولي 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 والوصول إليها.

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

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

مهم

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

  1. تنزيل البرنامج النصيNew-Agent365ToolsServicePrincipalProdPublic.ps1 script

  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.

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

عند تشغيل 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 لعمليات البريد). يتم استرداد هذه القيمة من كتالوج خَادِم MCP عند تشغيل add-mcp-servers الأمر .
الجمهور معرف معرف Microsoft Entra URI الذي يعرف مورد واجهة برمجة التطبيقات الهدف. يتم استرداد هذه القيمة أيضا من كتالوج خَادِم MCP.

إشعار

scope يتم ملء القيم و audience تلقائيا بواسطة Agent 365 CLI عند إضافة خَادِم 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 (Python)
  • 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. يتم استرداد نطاقات OAuth وقيم الجماعة المستهدفة من كتالوج خَادِم MCP وتضمينها في ToolingManifest.json. تستخدم أساليب الملحق هذه القيم تلقائيا لإعداد المصادقة - لا يلزم تكوين يدوي.

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

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

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

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.

الاختبار والمراقبة

اختبار عاملك

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

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

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

  • Last updated on