הגדרת תבנית סוכן

תוכנית האב של הסוכן מגדירה את הזהות, ההרשאות ודרישות התשתית של הסוכן. צור כל מופע סוכן מתוכנית אב זו של סוכן.

הערה

הגדרת תוכנית אב של סוכן נדרשת כדי להפעיל את היכולות רישום, Work IQ וחבר צוות AI. ראה תחילת העבודה עם פיתוח Agent 365 כדי להבין אילו יכולות חלות על הסוכן שלך.

לקבלת מידע נוסף על זהות Agent 365, ראה זהות Agent 365.

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

לפני שתתחיל, ודא שדרישות מוקדמות אלה מתקיימות:

  1. Agent 365 CLI - ראה התקנת Agent 365 CLI.

  2. ההרשאות הנדרשות:

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

    עצה

    סוכנים (שאינם חברי צוות AI) אינם זקוקים לקובץ תצורה. השתמש ב-a365 setup all --agent-name <name> וה-CLI יפתור באופן אוטומטי את הדייר ואת אפליקציית הלקוח שלך. הגדרת חבר צוות AI דורשת קובץ a365.config.json שנוצר באופן ידני.

יצירת תוכנית אב של סוכן

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

הפעלת ההגדרה

הפעל את פקודת ההגדרה:

a365 setup -h

לפקודה יש אפשרויות שונות. תוכל להשלים את כל ההגדרה בפקודה אחת באמצעות a365 setup all, או לבחור אפשרויות מפורטות יותר.

הערה

a365 setup allכברירת מחדל, a365 setup all משתמש במצב סוכן של תוכנית אב. כדי להגדיר במקום זאת סוכן מסוג חבר צוות AI, העבר את --aiteammate. עבור סוכני M365 ‏(Teams, ‏Copilot), העבר גם את --m365 כדי לרשום באופן אוטומטי את נקודת הקצה להעברת הודעות.

הגדרת סוכן (ברירת מחדל):

# With a config file
a365 setup all

# Config-free — no a365.config.json needed
a365 setup all --agent-name <your-agent-name>

הגדרת סוכן M365 ‏(Teams/Copilot):

# Registers the messaging endpoint via MCP Platform
a365 setup all --m365

הגדרת חבר צוות AI:

a365 setup all --aiteammate

תהליך ההגדרה המלא מבצע את הפעולות הבאות:

  1. יוצר תשתית Azure (אם היא עדיין אינה קיימת):

    • קבוצת משאבים
    • תוכנית App Service עם ה-SKU שצוין
    • אפליקציית אינטרנט של Azure עם זהות מנוהלת מופעלת

  2. רושם תוכנית אב של סוכן:

    • יוצר את תוכנית האב של הסוכן בדייר Microsoft Entra שלך
    • יוצר רישומי אפליקציות של Microsoft Entra
    • מגדיר את זהות הסוכן עם ההרשאות הנדרשות
    • מגדיר את managerApplications בתוכנית האב, כנדרש לצורך יכולת הניהול של הפלטפורמה

    חשוב

    כדי שהפלטפורמה תקבל תוכניות אב, יש להגדיר בהן את managerApplications. ה-CLI מגדיר זאת באופן אוטומטי. אם יש לך תוכנית אב קיימת שנוצרה לפני שהדרישה הזו הונהגה, מחק אותה והפעל שוב את a365 setup all, או תקן אותה ידנית באמצעות Graph API.

  3. מגדיר הרשאות API:

    • מגדיר טווחים של Microsoft Graph API
    • מגדיר הרשאות של Messaging Bot API
    • מחיל הרשאות הניתנות להורשה על מופעי סוכן

  4. מעדכן קובצי תצורה:

    • שומר מזהים ונקודות קצה שנוצרו בקובץ חדש בשם a365.generated.config.json בספריית העבודה שלך
    • רושם מידע על זהות מנוהלת ומשאבים

הערה

ההגדרה נמשכת בדרך כלל 3-5 דקות ושומרת באופן אוטומטי את התצורה ב-a365.generated.config.json. אם אתה פועל כמנהל מערכת כללי, ייתכן שה-CLI יפתח חלון דפדפן לקבלת הסכמת מנהל מערכת - השלם את זרימת ההסכמה כדי להמשיך. אם אתה פועל כמפתח מזהה סוכן, לא יופיע חלון דפדפן; ה-CLI ייצור כתובות URL להסכמה שמנהל מערכת כללי יוכל להשלים מאוחר יותר.

הגדרה באמצעות מפתח מזהה סוכן

אם אתה פועל כמפתח מזהה סוכן (ולא כמנהל מערכת כללי), a365 setup all משלים את רוב השלבים באופן אוטומטי, אך הענקת הרשאות OAuth2 דורשת שלב נפרד של מנהל מערכת כללי.

השלבים שמושלמים באופן אוטומטי:

  • תשתית Azure ‏(קבוצת משאבים, תוכנית App Service, אפליקציית אינטרנט)
  • רישום תוכנית אב של סוכן
  • הרשאות הניתנות להורשה עבור מופעי סוכן

השלבים שדורשים מנהל מערכת כללי:

  • הענקות של הרשאות מואצלות מסוג OAuth2 (הסכמת AllPrincipals) עבור Microsoft Graph, ‏Agent 365 Tools, ‏Messaging Bot API, ‏Observability API ו-Power Platform API

כיצד להשלים את ההגדרה באמצעות חשבון שאינו חשבון מנהל מערכת:

שלב מי פעולה
1 מפתח ‏‏הפעל את a365 setup all. ה-CLI משלים את כל השלבים שביכולתו להשלים ומדפיס את השלבים הבאים, כולל כתובת URL להסכמה שמנהל מערכת כללי יוכל לפתוח.
2 מפתח שתף עם מנהל המערכת הכללי את השלבים הבאים שה-CLI הדפיס.
3 מנהל המערכת הכללי פתח את כתובת ה-URL להסכמה בדפדפן שבו אתה מחובר כמנהל מערכת כללי והענק את ההרשאות המבוקשות.

הפעלת הפקודות:

# Developer runs:
a365 setup all
# Setup completes all steps it can. The CLI prints the next steps
# for a Global Administrator directly in the output, including a
# direct link or consent URL they can open to complete the grants.

שתף עם מנהל המערכת הכללי את השלבים הבאים שה-CLI הדפיס. הוא יוכל לפתוח את הקישור או את כתובת ה-URL להסכמה שסופקו כדי להשלים את הענקות OAuth2.

אימות ההגדרה

כאשר ההגדרה מסתיימת, מוצג סיכום שמציג את כל השלבים שהושלמו. אמת את המשאבים שנוצרו:

  1. אמת את התצורה שנוצרה::

    פתח את a365.generated.config.json בספריית העבודה שלך. לחלופין, השתמש ב-PowerShell:

    Get-Content a365.generated.config.json | ConvertFrom-Json

    הפלט הצפוי כולל ערכים קריטיים אלה:

    {
"managedIdentityPrincipalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"agentBlueprintId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"agentBlueprintObjectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"agentBlueprintServicePrincipalObjectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"agentBlueprintClientSecret": "xxx~xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"agentBlueprintClientSecretProtected": true,
"botId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"botMsaAppId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"messagingEndpoint": "https://your-app.azurewebsites.net/api/messages",
"resourceConsents": [],
"completed": true,
"completedAt": "xxxx-xx-xxTxx:xx:xxZ",
"cliVersion": "x.x.xx"
}

    שדות מרכזיים לאימות:

    שדה מטרה מה לבדוק
    managedIdentityPrincipalId אימות באמצעות זהות מנוהלת של Azure צריך להיות GUID חוקי
    agentBlueprintId המזהה הייחודי של הסוכן שלך משמש בפורטל המפתחים ובמרכז הניהול
    agentBlueprintObjectId מזהה Microsoft Entra ID של תוכנית האב
    messagingEndpoint ניתוב הודעות המקום שאליו Teams/Outlook שולחים הודעות עבור הסוכן שלך
    agentBlueprintClientSecret סוד אימות צריך להיות קיים (הערך מוסתר)
    resourceConsents הרשאות API צריך לכלול משאבים כגון Microsoft Graph, ‏Agent 365 Tools, ‏Messaging Bot API ו-Observability API
    completed מצב ההגדרה צריך אמור להיות true

    הערה

    אם הפעלת את ההגדרה כמנהל מזהה סוכן או כמפתח מזהה סוכן, ייתכן ש-resourceConsents יהיה ריק ו-completed יהיה false עד שמנהל מערכת כללי ישלים את הענקות הרשאות OAuth2 באמצעות השלבים הבאים שה-CLI הדפיס.

  2. אמת משאבי Azure ב-Azure Portal:

    לחלופין, השתמש בפקודת PowerShell az resource list.

    # List all resources in your resource group
az resource list --resource-group <your-resource-group> --output table

    אמת שהמשאבים הבאים נוצרו:

    • קבוצת משאבים::

      • עבור אל קבוצות משאבים> בחר את קבוצת המשאבים שלך
      • אמת שהיא כוללת את תוכנית App Service ואת אפליקציית האינטרנט שלך

    • תוכנית שירות אפליקציה:

      • עבור אל App Services>תוכניות App Service
      • מצא את התוכנית שלך ואמת ששכבת התמחור תואמת ל-SKU של התצורה

    • אפליקציית אינטרנט

      • עבור אל שירותי אפליקציות>אפליקציות אינטרנט
      • מצא את אפליקציית האינטרנט שלך ולאחר מכן עבור אל הגדרות>זהות>מוקצה על-ידי המערכת
      • אמת שהמצב הוא מופעל
      • שים לב שמזהה האובייקט (מנהל השירות) תואם ל-managedIdentityPrincipalId

  3. אמת אפליקציות Microsoft Entra ב-Azure Portal:

    עבור אל Azure Active Directory>רישומי אפליקציות>כל האפליקציות:

    • חפש את תכנית הסוכן שלך לפי agentBlueprintId

    • פתח את האפליקציה ובחר הרשאות API

    • אמת שההרשאות הוענקו ומוצגים לצדן סימני ביקורת ירוקים:

      • Microsoft Graph ‏(הרשאות מואצלות והרשאות אפליקציה)
      • הרשאות Messaging Bot API

    • בכל ההרשאות מוצג "הוענק עבור [הדייר שלך]"

  4. אמת שקובץ התצורה שנוצר קיים::

    אמור להיות לך קובץ בשם a365.generated.config.json שמכיל את כל נתוני התצורה.

    השתמש בפקודת PowerShell ‏Test-Path כדי לבדוק שהוא קיים.

    # Check file exists
Test-Path a365.generated.config.json
# Should return: True

    חשוב

    שמור את שני הקבצים: a365.config.json ו-a365.generated.config.json. ערכים אלה דרושים לך לפריסה ולפתרון בעיות.

  5. אמת שזהות מנוהלת מופעלת באפליקציית האינטרנט:

    השתמש בפקודה az webapp identity show כדי לבדוק אם זהות מנוהלת מופעלת.

    az webapp identity show --name <your-web-app> --resource-group <your-resource-group>

    צפוי:

    {
"principalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"type": "SystemAssigned"
}

  6. אמת שתוכנית האב של הסוכן רשומה ב-Microsoft Entra:

    במרכז הניהול של Microsoft Entra, חפש את agentBlueprintId או חפש לפי שם.

    וודא ש:

    ✅ רישום אפליקציה ויישום ארגוני מופיעים
    ✅בכרטיסיה הרשאות API של רישום האפליקציה של תוכנית האב מוצגות כל ההרשאות ✅
    ✅במצב מוצג "הוענק עבור [הדייר שלך]" ✅

לקבלת עזרה נוספת, ראה:

הרשאות סוכן

לפני שאפליקציות וסוכנים יוכלו לקרוא או לכתוב נתוני Microsoft 365 ‏(משתמשים, דואר, קבצים, Teams, סוכנים וכן הלאה), עליך להעניק להם במפורש הרשאות Microsoft Graph. הרשאות Microsoft Graph הן מודל ההרשאה שקובע לאילו נתונים ופעולות אפליקציה או שירות יכולים לגשת באמצעות ממשקי ה-API של Microsoft Graph ברחבי Microsoft 365 ו-Microsoft Entra ID.

קבל מידע נוסף: מבט כולל על הרשאות Microsoft Graph

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

כדי להבין ולאמת כיצד הרשאות Graph מאפשרות את פעולת הסוכן שלך, תוכל:

החלת הרשאות על תוכנית האב

השתמש ב-a365 setup permissions custom כדי להחיל הרשאות API מותאמות אישית באופן מוטבע על תוכנית האב שלך ב-Microsoft Entra.

a365 setup permissions custom `
  --resource-app-id 00000003-0000-0000-c000-000000000000 `
  --scopes Mail.Read,Mail.Send,Chat.Read,Chat.ReadWrite,Chat.Create,User.Read

לפרטים מלאים על הגדרה והסרה של הרשאות מותאמות אישית, ראה setup permissions custom.

‏‫השלבים הבאים‬

פרוס את קוד הסוכן שלך בענן:

Azure

Amazon Web Services (AWS)

Google Cloud Platform (GCP)

פרסום הסוכן במרכז הניהול של Microsoft

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

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

עצה

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

בעיות אלה מתרחשות לעיתים במהלך הרישום:

שגיאת הרשאות לא מספיקות

תסמין: שגיאת הרשאות לא מספיקות במהלך הפעלת הפקודה a365 setup.

דרוש לך אחד מהתפקידים הבאים בדייר Microsoft Entra שלך:

  • מנהל מערכת כללי של
  • מפתח מזהה סוכן

וכן גישת משתתף או בעלים למנוי Azure.

פתרון: אמת שיש לך את ההרשאות הנדרשות ב-Microsoft Entra.

הערה

אם יש לך תפקיד מנהל מזהה סוכן או מפתח מזהה סוכן (ולא מנהל מערכת כללי), a365 setup all עדיין יושלם בהצלחה אך ידלג על הענקות הרשאות OAuth2. לאחר השלמת ההגדרה, ה-CLI מדפיס את השלבים הבאים שמנהל מערכת כללי צריך לבצע כדי להשלים את ההענקות שנותרו. זרימת עבודה זו צפויה בארגונים שבהם מפתח הסוכן ומנהל המערכת הכללי הם אנשים שונים.

אימות Azure CLI חסר

תסמין: ההגדרה נכשלת עם שגיאות אימות.

פתרון: ודא שאתה מחובר ל-Azure ואמת את החשבון והמנוי שלך.

# Authenticate with Azure
az login

# Verify correct account and subscription
az account show

המשאב כבר קיים

תסמין: ההגדרה נכשלת עם השגיאה Resource already exists עבור קבוצת המשאבים, תוכנית App Service או אפליקציית האינטרנט.

פתרונות: בחר אחד מהפתרונות הבאים.

  • שימוש במשאבים קיימים

    אם המשאבים קיימים וברצונך להשתמש בהם, ודא שהם תואמים לתצורה שלך. השתמש בפקודת PowerShell az resource list.

    az resource list --resource-group <your-resource-group>

  • מחיקת משאבים מתנגשים

    מחק את קבוצת המשאבים או שנה את שמות המשאבים ב-a365.config.json והפעל שוב את ההגדרה.

    השתמש בפקודת PowerShell az group delete כדי למחוק קבוצת משאבים.

    # WARNING: This command deletes all resources in it
az group delete --name <your-resource-group>

  • שימוש בפקודת הניקוי כדי להתחיל מחדש

    השתמש בפקודה cleanup כדי להסיר את כל משאבי Agent 365, ולאחר מכן השתמש בפקודה a365 setup all כדי להפעיל שוב את ההגדרה.

    אזהרה

    הפעלת a365 cleanup היא פעולה הרסנית.

    a365 cleanup
a365 setup all

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

פתרון: בחר בהתאם לתפקיד שלך:

  • מנהל מערכת כללי: הפעל שוב את a365 setup all. ה-CLI מבקש הסכמת מנהל מערכת. השלם את זרימת ההסכמה בחלון הדפדפן שמופיע.

  • מנהל מזהה סוכן או מפתח: אינך יכול להשלים ישירות הענקות OAuth2. הפעל את a365 setup all — סיכום ההגדרה מדפיס את השלבים הבאים עבור מנהל מערכת כללי, כולל קישור ישיר או כתובת URL להסכמה להשלמת ההענקות. שתף פרטים אלה עם מנהל המערכת הכללי.

קובצי התצורה חסרים או אינם חוקיים

תסמין: ההגדרה נכשלת עם השגיאה "התצורה לא נמצאה" או עם שגיאות אימות.

פתרון:

  1. אמת שהקובץ a365.config.json קיים.
  2. אם הוא חסר או אינו חוקי, צור אותו באופן ידני או השתמש ב-a365 setup all --agent-name <name> ‏(סוכנים בלבד).
# Verify a365.config.json exists
Test-Path a365.config.json

ההגדרה הושלמה אבל המשאבים לא נוצרו

תסמין: פקודת ההגדרה הושלמה בהצלחה, אך משאבי Azure אינם קיימים.

פתרון:

  1. בדוק את המשאבים שנוצרו על-ידי פתיחת a365.generated.config.json בספריית העבודה שלך.
  2. אמת שמשאבי Azure קיימים באמצעות הפקודה az resource list.
  3. אם חסרים משאבים, בדוק אם יש שגיאות בפלט ההגדרה והפעל שוב את ההגדרה באמצעות הפקודה a365 setup all.
# Check created resources
Get-Content a365.generated.config.json | ConvertFrom-Json

# Verify Azure resources exist
az resource list --resource-group <your-resource-group> --output table

# If resources missing, check for errors in setup output and re-run
a365 setup all

תוכנית האב של הסוכן אינה רשומה ב-Microsoft Entra

תסמין: ההגדרה הושלמה, אך אינך מצליח למצוא את תוכנית האב של הסוכן במרכז הניהול של Microsoft Entra.

פתרון:

  1. קבל את מזהה תוכנית האב מ-a365.generated.config.json.

    Get-Content a365.generated.config.json | ConvertFrom-Json | Select-Object agentBlueprintId

  2. חפש במרכז הניהול של Microsoft Entra:

    1. עבור אל: מרכז הניהול של Microsoft Entra.
    2. נווט אל רישומי אפליקציות>כל האפליקציות.
    3. חפש את agentBlueprintId.

  3. אם הוא לא נמצא, הפעל שוב את ההגדרה באמצעות הפקודה a365 setup all.

    a365 setup all

הרשאות API לא הוענקו

תסמין: ההגדרה הושלמה, אך ההרשאות מוצגות כ"לא הוענק" ב-Microsoft Entra.

פתרון:

  1. פתח את: מרכז הניהול של Microsoft Entra.

  2. מצא את רישום האפליקציה של תוכנית האב של הסוכן.

  3. עבור אל הרשאות API.

  4. הענק הסכמת מנהל מערכת:

    1. בחר הענקת הסכמת מנהל מערכת עבור [הדייר שלך].
    2. אשר את הפעולה.

  5. אמת שמוצגים סימני ביקורת ירוקים לצד כל ההרשאות.

זהות מנוהלת אינה מופעלת

תסמין: אפליקציית האינטרנט קיימת, אך זהות מנוהלת אינה מופעלת.

פתרון:

  1. בדוק את מצב הזהות המנוהלת באמצעות הפקודה az webapp identity show.
  2. אם היא אינה מופעלת, הפעל אותה באופן ידני באמצעות הפקודה az webapp identity assign.
  3. אמת שהיא מופעלת באמצעות הפקודה az webapp identity show.
# Check managed identity status
az webapp identity show --name <your-web-app> --resource-group <your-resource-group>

# If not enabled, enable it manually
az webapp identity assign --name <your-web-app> --resource-group <your-resource-group>

# Verify it's enabled
az webapp identity show --name <your-web-app> --resource-group <your-resource-group>

ההגדרה נמשכת זמן רב מדי או מפסיקה להגיב

סימפטום: פקודת ההגדרה פועלת יותר מ-10 דקות בלי להסתיים.

פתרון:

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

  2. אם ההגדרה אכן מפסיקה להגיב, בטל אותה (Ctrl++C) ובדוק מה נוצר.

    # Check generated config
Get-Content a365.generated.config.json | ConvertFrom-Json

# Check Azure resources
az resource list --resource-group <your-resource-group>

  3. נקה ונסה שוב.

    a365 cleanup
a365 setup all

ניקוי סוכן ללא קובץ תצורה

תסמין: הקצית סוכן באמצעות a365 setup all --agent-name <name> וכעת ברצונך להסיר אותו, אך אין לך קובץ a365.config.json.

פתרון: השתמש ב-a365 cleanup --agent-name כדי להסיר את הסוכן ללא קובץ תצורה. ה-CLI קורא מזהי משאבים מהתצורה הכללית שנוצרה ונכתבה במהלך הגדרת האתחול.

a365 cleanup --agent-name <your-agent-name>

עצה

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

אם אין לך עוד את התצורה הכללית שנוצרה (לדוגמה, לאחר התקנה מחדש של ה-CLI), השתמש ב-a365 cleanup עם קובץ a365.config.json מינימלי שנוצר ידנית, או הסר משאבים ישירות דרך Azure Portal ומרכז הניהול של Microsoft Entra.

לא ניתן לשלוח את ההודעה הראשונה ב-Teams

תסמין: לאחר הקצאת מופע סוכן, הוא אינו יכול לשלוח הודעת פתיחה למנהל הסוכן.

פתרון: נדרשת הרשאת [Chat.Create][perm-chatcreate] כדי ליצור אובייקט צ'אט חדש. אם כבר קיים צ'אט אחד-על-אחד, פעולה זו מחזירה את הצ'אט הקיים ואינה יוצרת צ'אט חדש.

  • Last updated on