הוסף ונהל כלים

מודול Tooling מסיע למפתחים לגלות, להגדיר ולשלב שרתי Model Context Protocol (MCP) בתהליכי העבודה של סוכני AI. שרתי MCP חושפים יכולות חיצוניות ככלים שסוכני AI יכולים להפעיל. לקבלת סקירה של שרתי Tooling זמינים, ראה שרתי כלים של Agent 365.

מדגים את זרימת הבקשה והתגובה

‏‫‏‫מבט כולל

האינטגרציה של כלי Agent 365 פועלת בהתאם לזרימת העבודה הבאה:

  1. הגדר MCP שרתים - השתמש ב-Agent 365 CLI על מנת לגלות ולהוסיף שרתי MCP
  2. צור מינפסט - ‏CLI יוצר ToolingManifest.json בתיקית הפרויקט שלך עם תצורות השרת.
  3. החל הרשאות על blueprint - מנהל מערכת גלובלי מעניק הרשאות OAuth2 לסוכן blueprint באמצעות הפעלת a365 setup all (בפעם הראשונה בלבד) או a365 setup permissions mcp (אם ה-blueprint כבר קים). בכל מקרה, הפקודה קוראת את ToolingManifest.json ודורשת הסכמת מנהל מערכת. שלב זה תמיד נפרד מהוספת שרתים ל-מינפסט.
  4. שלב בתוך code - טען את ה-מינפסט ורשום את הכלים אצל המתאם שלך.
  5. הפעל tools - הסוכן קורא לכלים במהלך הביצוע על מנת לבצע פעולות.

‏‫דרישות מוקדמות‬

לפני קביעת התצורה של שרתי MCP, ודא שיש לך:

  • Agent 365 CLI מותקן ומוגדר
  • .NET 8.0 SDK או גרסה מתקדמת יותר - הורד
  • הרשאות Global Administrator בדיר Microsoft 365 שלך

הגדרת זהות הסוכן

אם אתה משתמש ב-סוכני אימות, השלם את תהליך רישום הסוכן על מנת ליצור את זהות הסוכן שלך לפני קביעת התצורה של שרתי MCP. תהליך זה יוצר את מזהה סוכן Entra ואת משתמש הסוכן, המאפשרים לסוכן שלך לבצע אימות ולגשת לכלי MCP.

הגדרת אימות OBO

אם אתה משתמש באימות On-Behalf-Of (OBO) במקום באימות סוכני, הסוכן שלך יכול לגשת לכלי MCP באמצעות הרשאות משתמש מואצלות, ללא זהות משתמש של סוכן. בזרימת OBO, הסוכן מחליף אסימון מואצל של משתמש על מנת לבצע פעולות בשמו של המשתמש.

למידע נוסף על אופן הפעולה של זרימת OBO, ראה אימות flows. לדוגמה מלאה של מימוש, ראה את OBO authorization sample ב-Microsoft 365 Agents SDK.

הגדרת מנהל שירות

הפעל סקריפט הגדרה חד-פעמי זה על מנת ליצור את ה-שירות מנהל עבור כלי Agent 365 בדייר.

חשוב

פעולה חד-פעמית זו לכל דיר דורשת הרשאות של Global Administrator.

  1. הורד את New-סוכן365ToolsשירותPrincipalProdPublic.ps1 script.

  2. פתח את PowerShell כמנהל מערכת ועבור אל ספרית קובץ ה-script.

  3. הפעל את ה-script.

    .\New-Agent365ToolsServicePrincipalProdPublic.ps1

  4. היכנס באמצעות אישורי Azure שלך כאשר תתבקש לעשות זאת.

לאחר השלמת התהליך, הדיר שלך מוכן לפיתוח סוכנים ולהגדרת שרתי MCP.

הגדר שרתי MCP

השתמש ב-Agent 365 CLI על מנת לגלות, להוסיף ולנהל שרתי MCP עבור הסוכן. לרשימה מלאה של שרתי MCP הזמינים והיכולות שלהם, ראה את MCP server catalog.

גלה שרתים זמינים

הצג את כל שרתי ה-MCP שניתן להגדיר:

a365 develop list-available

הוסף שרתי MCP

הוסף שרת MCP אחד או יותר לתצורת הסוכן שלך:

a365 develop add-mcp-servers mcp_MailTools

חשוב

פקודה זו מעדכנת רק את ToolingManifest.json בתיקית הפרויקט שלך — היא אינה מעניקה הרשאות כלשהן ל-blueprint. אופן החלת ההרשאות תלוי בשלב שבו אתה נמצא בתהליך ההגדרה:

  • לפני ההגדרה הראשונית: הפעל a365 develop add-mcp-servers תחילה, ולאחר מכן המשך עם a365 setup all. ה- setup all הפקודה כוללת את שלב הרשאות ה-MCP כחלק מיצירת ה-blueprint.
  • לאחר שה-blueprint כבר קים: על Global Administrator להפעיל 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 develop command.

השתמש בשרת Tooling מדומה לצורך בדיקות

לצורך בדיקות ופיתוח, השתמש בשרת הכלים המדומה של Agent 365 CLI במקום להתחבר לשרתי MCP אמתיים. השרת המדומה מדמה אינטראקציות עם שרתי MCP, כך שתוכל לבדוק את הסוכן שלך באופן מקומי ללא תלות בגורמים חיצונים כגון אימות.

השרת‎ ‎המדמה‎ ‎מציע‎ ‎את‎ ‎היתרונות‎ ‎הבאים‎ ‎לפיתוח‎ ‎ולבדיקות‎ ‎מקומיות‎:

  • פיתוח‎ ‎לא‎ ‎מקוון‎: ‎בדוק‎ ‎את‎ ‎הסוכן‎ ‎שלך‎ ‎ללא‎ ‎חיבור‎ ‎לאינטרנט‎ ‎או‎ ‎תלות‎ ‎חיצונית‎.
  • בדיקות‎ ‎עקביות‎: ‎קבל‎ ‎תגובות‎ ‎צפויות‎ ‎לבדוק‎ ‎מקרים‎ ‎קצה‎.
  • איתור באגים‎: ‎צפה‎ ‎בכל‎ ‎הבקשות‎ ‎והתשובות‎ ‎בזמן‎ ‎אמת
  • חזרה‎ ‎מהירה‎: ‎אין‎ ‎צורך‎ ‎לחכות‎ ‎לקריאות‎ API ‎חיצוניות‎ ‎או‎ ‎להקים‎ ‎סביבות‎ ‎בדיקה‎ ‎מורכבות‎.

הפעל את שרת ה-mock tooling באמצעות a365 develop start-mock-tooling-server הפקודה.

למד כיצד להגדיר ולקבוע את התצורה של שרת ה-Tooling המדומה.

הערה

הסעיפים הבאים להגדרת מניפסט ולשילוב כלים בסוכן פועלים באותו אופן, בין אם אתה משתמש בשרת כלים מדומה ובין אם בשרתי MCP אמתיים. הגדר את MCP_PLATFORM_ENDPOINT משתנה הסביבה כך שיצביע על שרת ה-mock (לדוגמה: 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 כוללת:

פרמטר Description
mcpServerName שם התצוגה של שרת ה-MCP.
mcpServerUniqueName הid היחודי של מופע שרת ה-MCP.
היקף היקף ה-OAuth הנדרש על מנת לגשת ליכולות של שרת ה-MCP (לדוגמה: McpServers.Mail.All עבור פעולות דואר). ה- add-mcp-servers פקודה מאחזרת ערך זה מתוך MCP server catalog.
קהל יעד כתובת ה-URI של Microsoft Entra ID שמזהה את משאב ה-API ביעד. ה- add-mcp-servers פקודה מאחזרת ערך זה מתוך MCP server catalog.

הערה

Agent 365 CLI מאכלס באופן אוטומטי את הערכים scope ו-audience בעת הוספת שרת MCP. ערכים אלה מגיעים מתוך MCP server catalog ומגדירים את ההרשאות הנדרשות לגישה לכל שרת MCP.

שלב כלים בסוכן שלך

לאחר יצירת מניפסט הכלים, שלב את שרתי MCP שהוגדרו בקוד הסוכן. סעיף זה מכסה את שלב הבדיקה האופציונלי ואת שלבי השילוב הנדרשים.

הצג רשימת שרתי כלים (אופציונלי)

עצה

שלב זה הוא אופציונלי. השתמש בשירות תצורת שרת הכלים על מנת לבדוק את שרתי הכלים הזמינים מתוך מניפסט הכלים לפני הוספתם למתאם.

השתמש בשירות תצורת שרת הכלים על מנת לגלות אילו שרתי כלים זמינים עבור הסוכן מתוך מניפסט הכלים. שיטה זו מאפשרת לך:

  • בצע שאילתה עבור כל שרתי MCP שהוגדרו מתוך ToolingManifest.json הקובץ.
  • אחזר מטא-נתונים ויכולות של השרת.
  • ודא את זמינות השרת לפני הרישום.

השיטה להצגת רשימת שרתי כלים זמינה בחבילות ה-Tooling המרכזיות:

# 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)

פרמטרים:

פרמטר סוג Description ערך צפוי נדרש/אופציונלי
agentic_app_id str הid היחודי של מופע ישום הסוכן מחרוזת מזהה ישום סוכן חוקית נדרש
auth_token str אסימון Bearer לצורך אימות באמצעות שער שרת ה-MCP אסימון Bearer תקין של 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 scopes ו-audience מתוך MCP server catalog וכותב אותם אל ToolingManifest.json. שיטות ההרחבה משתמשות בערכים אלה על מנת להגדיר אימות בזמן הריצה — לא נדרשת הגדרה ידנית בקוד הסוכן שלך. עם זאת, על Global Administrator עדין להעניק הרשאות אלה ל-סוכן blueprint לפני שהסוכן שלך יוכל להשתמש בהן בסביבת היצור: באמצעות a365 setup all (הגדרה ראשונית) או a365 setup permissions mcp (אם ה-סוכן blueprint כבר קים).

לדוגמאות מפורטות של מימוש, ראה את דוגמאות של Agent 365.

דוגמאות מימוש

הדוגמאות הבאות מראות כיצד לשלב את סוכן כלים של Agent 365 עם מסגרות תיאום שונות.

Python עם OpenAI

דוגמה זו מראה כיצד לשלב כלי MCP עם OpenAI בישום Python.

1. הוסף משפטי import

הוסף את ה-imports הנדרשים על מנת לגשת למודול Tooling ולהרחבות OpenAI:

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

2. אתחל את שירותי ה-Tooling

צור מופעים של שירותי התצורה ורישום הכלים:

# 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 method על מנת לרשום את כל כלי ה-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.

פרמטר Description
agent מופע סוכן OpenAI שבו יש לרשום את הכלים.
agentic_app_id המזהה הייחודי של הסוכן (מזהה יישום סוכני).
auth הקשר ההרשאה של המשתמש.
context הקשר סבב השיחה הנוכחי מתוך Agents SDK. מספק את זהות המשתמש, מטא-נתוני השיחה והקשר האימות לצורך רישום מאובטח של כלים.
auth_token (אופציונלי) אסימון Bearer עבור תרחישי אימות שאינם סוכני.

4. קרא במהלך האתחול

ודא שאתה קורא לשיטת ההגדרה במהלך האתחול לפני הפעלת הסוכן:

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

ה add_tool_servers_to_agent שיטה מבצעת באופן אוטומטי

  • טוענת את כל שרתי ה-MCP מהקובץ ToolingManifest.json.
  • רושמת את הכלים שלהם אצל סוכן OpenAI.
  • מגדירה את האימות בהתאם לתצורת ה-מינפסט.
  • הופכת את הכלים לזמינים להפעלה על-ידי הסוכן שלך.

לדוגמאות עבודה מלאות, ראה את מאגר הדוגמאות של Agent 365..

דרכים אחרות לגשת לשרתי MCP של Agent 365

בנוסף ל-Agent 365 SDK, אפשר לגשת לשרתי MCP של Agent 365 באמצעות חוויות פיתוח אחרות:

  • Visual Studio Code - התחבר ישירות לשרתי MCP עבור תהליכי עבודה מותאמים אישית של פיתוח.
  • Microsoft Copilot Studio - שלב שרתי MCP בזרימות שיחה באמצעות חווית Low-code.
  • Azure בינה מלאכותית Foundry - השתמש בשרתי MCP עם תמיכה מלאה ב-SDK ויכולות Orchestration מתקדמות.

לקבלת סקירה מלאה של שרתי MCP הזמינים ואפשרויות השילוב בפלטפורמות אלה, ראה שרתי כלים של Agent 365 – סקירה כללית.

שרת MCP משלך (BYO)

התכונה 'הבא שרת MCP משלך' (BYO) מאפשרת לרשום שרתי MCP חיצונים משלך עם Microsoft Agent 365, כך שניתן יהיה לנהל, לאשר ולנטר אותם באופן מרכזי במרכז הניהול של Microsoft 365. היא מנתבת שרתים אלה דרך שער הכלים של Agent 365 ומעניקה למנהלי המערכת שליטה על אישורים, גישה וכללי מדיניות, תוך שהיא מאפשרת לצוותי אבטחה לעקוב אחר השימוש באמצעות מדידת השימוש. כמפתח, באפשרותך לרשום שרת MCP משלך באמצעות Agent 365 CLI ולאחר מכן לאפשר למנהל המערכת לסקור ולאשר את הרישום ולהעניק הרשאות. לאחר מכן ניתן להשתמש בשרת שאושר בכלי לקוח נתמכים, כאשר ניטור מתמשך מבטיח תאימות ונראות בכל השילובים.

לקבלת הוראות מלאות, ראה Bring your own (BYO) MCP server.

בדקו את הסוכן

לאחר שילוב כלי MCP בסוכן שלך, בדוק את הפעלות הכלים על מנת לוודא שהם פועלים כראוי ומטפלים בתרחישים שונים. פעל בהתאם ל- testing guide על מנת להגדיר את הסביבה שלך. לאחר מכן, התמקד בעיקר ב- Test tool invocations על מנת לוודא שכלי ה-MCP שלך פועלים כמצופה. בנוסף, עין ב- mock tooling server על מנת לבדוק את החיבור לשרת MCP ואת הפעלות הכלים ללא טיפול באימות.

הוסף יכולת ניטור

הוסף יכולת ניטור לסוכן שלך על מנת לנטר ולעקוב אחר הפעלות כלי ה-MCP של הסוכן שלך. באמצעות הוספת יכולות ניטור, באפשרותך לעקוב אחר ביצועים, לנפות באגים בבעיות ולהבין דפוסי שימוש בכלים. למד עוד על ישום מעקב וניטור.

‏‫פתרון בעיות

סעיף זה מפרט בעיות נפוצות בעת הגדרה ושימוש בשרתי MCP ובכלים.

עצה

מדריך פתרון הבעיות של Agent 365 כולל המלצות מתקדמות לפתרון תקלות, שיטות עבודה מומלצות וקישורים לתוכן פתרון תקלות לכל חלק במחזור החיים של פיתוח Agent 365.

בעיות בשרתי MCP וב-Tooling

תסמינים:

  • כשלי קריאות לכלים.
  • שגיאות "MCP server not found".
  • שגיאות דחית הרשאה בעת קריאה לכלים.

גורם שורש:

  • שרת MCP אינו מוגדר.
  • הרשאות חסרות.
  • שירות principal אינו מוגדר.
  • בלבול בין שרתים מדומים ושרתים בסביבת יצור.

פתרונות: נסה את הפתרונות הבאים על מנת לטפל בבעיה.

  • ודא ששרתי MCP מוגדרים

    הצג רשימת שרתים מוגדרים והוסף שרתים חסרים.

    # List configured servers
a365 develop list-configured

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

  • בדוק ש-שירות principal קים

    ודא ש-שירות principal הנדרש נוצר עבור ה-Tooling.

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

  • לצורך פיתוח ובדיקות מוקדמים, השתמש בשרתים מדומים

    השתמש בשרת ה-Tooling המדומה לצורך פיתוח מקומי מוקדם ובדיקות אם ברצונך לבדוק את שאר הסוכן שלך ללא רכיבי Tooling בסביבת יצור.

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

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

    למד על שרת ה-tooling המדומה..

  • אמת הרשאות במרכז הניהול

    ודא שלסוכן שלך יש את הרשאות ה-MCP הנדרשות.

    • ודא שהרשאות ה-API של תוכנית הזהות של הסוכן שלך בפורטל Azure מציגות את כל הרשאות שרתי ה-MCP.

    אימות:

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