מושגי יכולת צפייה של Agent 365

מאמר זה מסביר את מודל הנתונים שמאחורי יכולת הצפייה של Agent 365 – מה סוכני מדידת השימוש פולטים, מי יכול לפלוט את הנתונים, לאן הם מגיעים, והמגבלות החלות. מושגים אלה חלים על כל נתיב אינטגרציה: Microsoft OpenTelemetry Distro, ערכת SDK של Agent 365, ו- direct OTel.

הערה

פרטים ברמת הפרוטוקול – מסלולי ה-URL באימות, קודי השגיאה של HTTP במגבלות ותנאי שחרור, ומגבלות הגודל והקצב לכל בקשה – חלים במיוחד על נתיב OTel ישיר. ה- SDK ו- Distro מפשטים את זה בשבילך. שאר המאמר הזה (מילון מונחים, זרימת נתונים, מודלים של זהות, היקפים, תנאי השמטה, היכן שהנתונים מופיעים) מתייחס על כל נתיב.

בחר את מסלול האינטגרציה שלך

שלושה מסלולים פולטים את אותו מודל נתונים מסוג דומה אל Agent 365. בחר אחד:

  • Microsoft OpenTelemetry Distro - מומלץ לאינטגרציות חדשות. ערכת SDK מאוחדת ליכולת צפייה עבור Agent 365‏, Microsoft Foundry‏, Azure Monitor ועוד.
  • Agent 365 SDK (‏Observability SDK) – ה-SDK המוקדם יותר. ממשיך לעבוד ללא שינויים המפרים תאימות, אך כבר אינו המסלול המומלץ לאינטגרציות חדשות; הנחיות למעבר למשתמשי SDK קיימים יפורסמו בקרוב.
  • Direct OTel – נתיב OTLP/HTTP הגולמי. השתמש בו רק אם כבר יש לך קו צינור OpenTelemetry, מסגרת הסוכנים שלך לא יכולה להשתמש ב- SDK של Agent 365, או אם הסוכן שלך בשפה שה- SDK עדיין לא תומך בה (כמו Java).

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

מילון מונחים

  • מזהה אפליקציה (appId): מזהה האפליקציה שמונפק כאשר נרשמת אפליקציית Microsoft Entra או מזהה סוכן Microsoft Entra.
    • שווה ל- OAuth client_id, לא למזהה האובייקט של Microsoft Entra.
    • במסמכים הללו, המשמעות של "מזהה סוכן" ו"מזהה תכנית" היא appId.
  • שיחה: שרשור לוגי של אינטראקציות עם סוכנים, כמו שרשור צ'אט ב- Teams.
    • מזוהה על-ידי gen_ai.conversation.id.
    • מפתח ההצטרפות הראשי להפעלה.
  • ערוץ: המשטח שבו הסוכן פועל: msteams, outlook, web, וכן הלאה.
  • הפעלה: הודעת משתמש אחת נכנסת, סוכן אחד משיב. מודל עץ של מרחבי OTelעם traceId משותף.

איך זה עובד?

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

אתה שולח מדידת שימוש כנתוני גילוי מקור של OpenTelemetry:

  • עץ של טווחים המתאר הפעלה אחת (הודעת משתמש אחת נכנסת, תשובת סוכן אחת יוצאת).
  • כל טווח מתאר שלב אחד – קריאת סוכן ברמה העליונה, קריאה ל- LLM, קריאה לכלי או התשובה הסופית.

זרימת נתונים

   Your agent code

        |
        v

   +---------------+
   | OTel SDK or   |
   | raw HTTP      |
   +---------------+

        |
        v

   POST /traces  agent365.svc.cloud.microsoft

        |
        v

  +-------------------------------------+
  | Microsoft Defender                  |
  |   (CloudAppEvents table             |
  |    in advanced hunting)             |
  |                                     |
  | Microsoft Purview                   |
  |                                     |
  | Microsoft 365 admin center          |
  |   (agent inventory and              |
  |    security views)                  |
  +-------------------------------------+

מודלי זהות

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

אם לסוכן שלך אין רישום ל- Microsoft Entra, הוא לא יכול להשתמש במסלולים האלה ישירות. זהה את הסוכן דרך מאפייני מזהה חלופי (ראה הפניה לתכונות) ופנה לצוות Agent 365 לגבי נתיב הכניסה המתאים.

אימות

הסתעפות האימות תלויה בשאלה האם השירות מאמת את עצמו או בשם המשתמש. ההסתעפות קובעת את זרימת ה-OAuth, את תביעת האסימון שנושאת את ההרשאה, ואת מסלול ה-URL.

  • השירות מאמת את עצמו: אין משתמש מחובר – אוטונומי, מתוזמן או מונע אירועים.

    • זרימת OAuth: אישורי לקוח משירות לשירות (S2S).
    • טענת אסימון: roles.
    • נתיב URL: /observabilityService/....

  • השירות מאמת מטעם המשתמש: עבור חברי צוות מבוססי בינה מלאכותית, או עבור חשבון המשתמש של הסוכן עצמו.

    • זרימת OAuth: מסוג On-behalf-of (‏OBO).
    • טענת אסימון: scp.
    • נתיב URL: /observability/....

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

לשיטות אימות המלאות לכל שילוב של מודל זהות וזרימה, ראו שיטות אימות במדריך האינטגרציה.

זהות הסוכן קשורה לכתובת ה- URL

ה- {agentId} שב- URL חייב להיות שווה ל- appId של האפליקציה המתקשר (טענת appid או azp באסימון). אי-התאמות מחזירות 403 Forbidden. בזהויות שנגזרות מתבנית, {agentId} הוא appId של זהות הסוכן, ולא מזהה האפליקציה של התבנית.

בנוסף, כל טווח שתשלח חייב להיות gen_ai.agent.id מוגדר לאותו appId; השרת מאשר את זהות הסוכן בתוך המטען מול הסוכן המאומת ודוחה אי-התאמות. שלב זה תופס ערבוב טווחים מקרי ממספר סוכנים לבקשה אחת.

טווח (מוקצה) או תפקיד אפליקציה (יישום) הוא ההרשאה בשם ש- Microsoft Entra מטביעה לאסימון הגישה. עבור מדידת שימוש של Agent 365, ההרשאה הוא Agent365.Observability.OtelWrite במשאב התצפית של Agent 365 (קהל 9b975845-388f-4429-889e-eab1ef63949c).

אותו שם הרשאה רשום בשני הסוגים:

  • תפקיד אפליקציה לזרימה האוטונומית (S2S / אישורי לקוח). מגיע לטענה roles. נבחר על-ידי <resource>/.default.
  • טווח שהוקצה לזרימת OBO. מגיע לטענה scp. נבחר על-ידי <resource>/Agent365.Observability.OtelWrite (או <resource>/.default).

Agent 365 חושף גם הרשאה בצד הקריאה, Agent365.Observability.OtelRead, המשמשת מפעילים שמבצעים שאילתות במדידת שימוש של Agent 365. רוב השותפים אינם זקוקים לכך – תיעוד זה מתמקד בהזנה בלבד.

הוספת ההרשאה לאפליקציה שלך

  • עבור הרשמה סטנדרטית לאפליקציית Microsoft Entra: בפורטל Azure, הוסף Agent365.Observability.OtelWrite (תפקיד אפליקציה ל- S2S, טווח להקצאה) תחת הרשאות API בהרשמת האפליקציה של הסוכן.
  • עבור תוכנית: סוכנים שהונפקו מתוכנית זהות סוכן של מזהה סוכן Microsoft Entra יורשים את הרשאות ה-OAuth שהוגדרו בתכנית, כך שמנהל דיירים מעניק הרשאות פעם אחת. כל מופע של סוכן שנבנה מהתכנית הזו מקבל אותם אוטומטית. ראה הגדרת הרשאות ניתנות לירושה עבור תוכניות זהות סוכנים.

לפני שאסימונים נושאים את התפקיד / ההיקף, מנהל דיירים בדייר של הלקוח חייב להעניק הסכמה. ראה מתן גישה לסוכן למשאבי Microsoft 365.

ללא הסכמה, רכישת האסימון נכשלת עם AADSTS65001 ("המשתמש או המנהל לא נתן הסכמה") או שהאסימון מונפק ללא הטענה roles / scp, ונקודת הקצה של הקליטה דוחה את הבקשה עם 403.

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

מגבלות ותנאי שחרור

הכרת מגבלות אלו מראש מונעת הפתעות במהלך האינטגרציה – רובן שקטות (ה- API מקבל את הבקשה אך הנתונים לא מופיעים בהמשך).

‏‏מגבלות ברמת הפרוטוקול:

  • api-version=1 נדרש בכל בקשה.
  • גודל גוף הבקשה המרבי הוא 1 MB. בקשות גדולות יותר מקבלות את 413 Payload Too Large.
  • לשני המסלולים יש מגבלות קצב נפרדות. ב- 429, תכבד את Retry-After (מכוון ל- 1 שנייה) וחזור עם תנודתיות.

תגובות שגיאה:

  • 403 Forbidden--לאסימון חסר את תפקיד/היקף האפליקציה הנדרש, או {agentId} בכתובת ה- URL לא תואם את appid / azp של האסימון שלך.
  • 413 Payload Too Large--הגוף עולה על ‎1 MB.
  • 429 Too Many Requests--פגיעה במגבלת קצב; כבד את Retry-After: 1 וחזור עם תנודתיות.

תנאי שחרור (הבקשה התקבלה על-ידי HTTP אך הנתונים לא מופיעים בהמשך):

# תנאי התנהגות
1 הטווח gen_ai.operation.name חסר או לא ב- {invoke_agent, execute_tool, chat, output_messages} שחרור לכל טווח. מוצג ב- partialSuccess.rejectedSpans + errorMessage.
2 לאף משתמש בדייר הלקוח הוקצה רישיון Microsoft 365 E7 או Microsoft Agent 365. לפחות משתמש אחד בדייר חייב לקבל רישיון (העובדה שה- SKU נמצא אצל הדייר אינה מספיקה – ההקצאה מפעילה את זרימת העבודה בקצה העורפי של Defender). המשתמש בעל הרישיון לא חייב להיות המשתמש האנושי שקורא לסוכן. כל הבקשה שוחררה בשקט. מחזיר: 200 { "partialSuccess": null }.

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

היכן הנתונים שלך מופיעים

ברגע שהתקבלו, הטווחים שלך מתגלים בשלוש חוויות מול לקוחות. שלושתם תלויים בטווח invoke_agent תקף בבסיס ההפעלה. הפעלה רק עם chat / execute_tool / output_messages ניתנת לשאילתה בציד המתקדם של Defender (הטבלה CloudAppEvents) אך בלתי נראית לכל משטח אחר מתחתיו.

Microsoft Defender. פעילות סוכן (invoke_agent, execute_tool, chat) מופיעה בתצוגות פעילות הסוכן. מנהלי דיירים ואנליסטים של אבטחה יכולים לבחון לעומק הפעלות, קריאות הסקה וכלים נפרדים. תצוגות פעילות הסוכן מתבססות על הטווח של invoke_agent; ללא טווח כזה, ההפעלה לא תופיע שם, אף שעדיין ניתן לחפש טווחי צאצא באמצעות ציד מתקדם. תצוגת החיפוש המתקדם – CloudAppEvents – מאפשרת כל פעולה: ActionType מייצגת את הפעולה (InvokeAgent, InferenceCall, ExecuteToolBySDK, ExecuteToolByGateway, ExecuteToolByMCPServer) ושדות לכל טווח נמצאים בתוך RawEventData. שמות השדות הנראים ללקוח ממופים ישירות למאפייני הטווח ששלחת: ConversationId ← gen_ai.conversation.id, SessionIdentity ← microsoft.session.id, AgentId ← gen_ai.agent.id, PlatformTargetAgentId ← microsoft.a365.agent.platform.id, וכן הלאה. עיין במדריך התכונות למיפוי המלא.

מרכז הניהול של Microsoft 365. פעילות הסוכנים מופיעה גם בתצוגות מלאי הסוכנים והאבטחה המשמשות מנהלי דיירים כדי לשלוט בסוכנים בדיירים שלהם. מרכז הניהול קולט רק שורות invoke_agent: סוכנים ללא מדידת שימוש של invoke_agent אינם מופיעים במלאי, והפעלות שמשדרות רק chat / execute_tool / output_messages אינן נראות כאן. התכונות שמרכז הניהול קורא (מזהה סוכן, שם סוכן, מזהה תוכנית, זהות מתקשר, מזהה שיחה, ערוץ, מצב שגיאה) כולן מגיעות מהטווח invoke_agent.

Microsoft Purview. פעילות הסוכנים נחשפת גם למנהלי תאימות ב- Microsoft Purview, שם הם יכולים להגדיר כללי טיפול בנתונים ומדיניות על הפעלות סוכנים (מניעת אובדן נתונים, שימור, עמידה בתקשורת ודומיהם). התכונות שמדיניות Purview מכבה (מזהה סוכן / מזהה תוכנית, זהות מתקשר, שיחה / ערוץ, הודעות בקשה ותגובה) כולן מגיעות מהטווח invoke_agent ומהצאצאים שלו.

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

  • Last updated on