הערה
הגישה לדף זה מחייבת הרשאה. באפשרותך לנסות להיכנס או לשנות מדריכי כתובות.
הגישה לדף זה מחייבת הרשאה. באפשרותך לנסות לשנות מדריכי כתובות.
זהו המפרט הקנוני מאפיין-אחר-תכונה המשמש בצינור הקליטה של Agent 365. כל מרווח שנצרך על ידי סוכן 365 - בין אם נפלט על ידי Microsoft OpenTelemetry Distro, Agent 365 SDK, או שנשלח direct OTel - חייב להתאים אליו. כל ערך מפרט את סוגי הפעולות שאליהם התכונה חלה, האם היא חובה, שם השדה שבו הערך שלך נוחת בשאילתות ציד מתקדמות (כאשר קיימת), ואת ההשפעה אם תדלג עליה.
אם אתה משתמש ב-SDK או ב-Distro, ה-SDK משדר עבורך את התכונות האלה וחלק Picking values חל רק כשצריך לעקוף ברירת מחדל. אם אתה במסלול הישיר של OTel, אתה משדר כל תכונה ידנית; לאופן הרכיבה שלהם לבקשה, ראו את מדריך האינטגרציה.
Attribute table
כל הערכים נשלחים כ- stringValue - ספירת האסימונים חייבת להיות "42" (לא 42); הפורטים חייבים להיות "443" (לא 443).
מבצע אגדה.IA = invoke_agent, ET = execute_tool, CH, = chatOM = output_messages, All = חל על כל פעולה.
Required legend.
- M: mandatory.
- M*¹: חובה רק לסוכנים מגולמים (לסוכן יש חשבון משתמש מזהה סוכן Entra משלו).
- M*²: חובה רק לשיחות בין סוכן לסוכנים.
-
M*³: חובה רק למרחבים שאינם שורשים. לשורש
invoke_agentאין הורה. - O*⁴: אופציונלי, משמעותי רק כאשר סטטוס המרחק הוא שגיאה.
- O: optional.
- אין תשובה: אל תפלוט. סוכן 365 מתמלא אוטומטית.
עמודת "שדה RawEventData" מציינת מפתח JSON שבתוך CloudAppEvents.RawEventData המפתח מנתחת את שאילתת הציד המתקדם הקנונית ב-Verifying ingestion . תא ריק אומר שהתכונה not חשופה ב-CloudAppEvents היום—עדיין כדאי לשדר אותה (לפי עמודת Required) כי Agent 365 משתמש בו לקליטה, פתרון הורים ותצוגות פעילות של Microsoft Defender, אבל הוא לא ניתן לשאילתה ישירות מחיפוש מתקדם Microsoft Defender כיום.
Note
סוכן 365 ממלא אוטומטית את שדות הרשומות הסטטיות (Id, RecordType, Workload, UserType, Version) ואת מזהי הבקשות / התשובות שנוצרו.
| Attribute | Applies to | Required | RawEventData field | הערות / השפעה אם חסרים |
|---|---|---|---|---|
gen_ai.operation.name |
All | M | Operation |
אחד מinvoke_agent, , , chat. output_messagesexecute_tool הספאן נפל אם נעדר או לא זוהה. |
microsoft.tenant.id |
All | M | OrganizationId |
כתובת URL {tenantId} היא סמכותית. אם תגדיר את זה והוא לא מסכים, הבקשה נדחית (403). |
gen_ai.agent.id |
All | M |
TargetAgentId (IA, גם ברמה AgentIdהעליונה); AgentId (ET, CH) |
האפליקציה של אפליקציית השיחה. חייב להתאים לכתובת ה-URL {agentId} ולאפליקציה המאומתת. חוסר התאמה מחזיר 403. |
gen_ai.agent.name |
All | M |
TargetAgentName (IA); AgentName (ET, CH) |
Defender / admin center מציגים את ה-GUID הגולמי במקום שם אם חסר. |
microsoft.a365.agent.blueprint.id |
All | M |
TargetAgentBlueprintID (IA); AgentBlueprintId (ET, CH) |
התוכנית מיושמת. לאפליקציות Entra סטנדרטיות ללא Blueprint, השתמש שוב ב-appId של הסוכן. רול-אפים של Blueprint במרכז המנהל נשברים אחרת. |
gen_ai.agent.description |
All | O | -- | תצוגת הפרטים במרכז המנהל ריקה עבור הסוכן. |
gen_ai.agent.type |
All | O |
PlatformTargetAgentType (IA); PlatformAgentType (ET); CopilotEventData.PlatformAgentType (CH) |
תווית למערכת הזהות שלך, שמשולבת כשלסוכן microsoft.a365.agent.platform.id אין רישום ב-Entra. טקסט חופשי; בחר ערך שמזהה באופן ייחודי את מערכת הזהות שלך. השמטו כאשר לסוכן יש רישום ב-Entra – סוכן 365 מסווג אוטומטית. אל תשתמש בערכים שמורים Microsoft (ראו בחירת ערך). |
microsoft.a365.agent.platform.id |
All | O |
PlatformTargetAgentId (IA, גם ברמה AlternateIdהעליונה); PlatformAgentId (ET, CH) |
הזהות הייחודית של הסוכן במערכת הזהות הלא-אנטרה שלך. Free-form text. הרכיב יחד עם gen_ai.agent.type. השמטו כשלסוכן יש רישום ב-Entra. ראו בחירת ערכים. |
gen_ai.conversation.id |
All | M |
ConversationId (IA, ET); CopilotEventData.ConversationId / CopilotEventData.ThreadId (CH) |
מפתח ההצטרפות הראשי לריצה. בלעדיו, הריצה לא מופיעה בתצוגות פעילות של סוכנים ב-Defender או במרכז המנהל. |
microsoft.channel.name |
All | M |
ChannelName (IA, ET) |
המשטח שבו הסוכן רץ. השתמש בטוקן קטן קצר; הערכים הקנוניים בהם משתמשים כיום במסנני Defender / מרכזי ניהול הם msteams ו-outlook. מחרוזות מותאמות אישית (למשל web, <your-product-name>) מתקבלות אך לא משתנות במסנני ערוץ מובנים. אותו ערך בכל ספאן. ראו בחירת ערכים. |
microsoft.channel.link |
All | O | -- | Channel deep-link. |
microsoft.session.id |
All | O | SessionIdentity |
הסשן מסתובב ריק אם חסר. |
microsoft.session.description |
All | O | -- | Session description. |
microsoft.conversation.item.link |
All | O | -- | קישור עמוק להודעה. |
correlation.id |
All | O | -- | Cross-service tracing. לא צצה בציד מתקדם היום. |
operation.source |
All | O |
InvokeSource (IA) |
מזהה ל-SDK / השירות שפולט את הטלמטריה. יכול להיות שמדובר בתכונת משאב. |
client.address |
IA, ET, CH | M |
ClientIP (IA, ET) |
Caller IP. חקירה מבוססת קניין רוחני חסומה אם היא ריקה. |
server.address |
IA, ET, CH | M |
ServerAddress (IA, ET) |
נקודת הקצה שהשירות שלך מתקשר אליה. |
server.port |
IA, ET, CH | M |
ServerPort (IA) |
מקודד במחרוזות (למשל "443"). |
user.id |
IA | M | UserKey |
מזהה אובייקט Microsoft Entra של המתקשר האנושי. "מי ניהל את הסוכן הזה" ריק בלעדיה. |
user.email |
IA | O | UserId |
UPN של המתקשר. |
user.name |
IA | O | -- | שם תצוגה של המתקשר. |
gen_ai.input.messages |
IA, CH | M | -- | בקשה למטען (מחרוזת JSON). נתפס לניתוח במורד הזרם אך עדיין לא הופיע בציד מתקדם. |
gen_ai.output.messages |
IA, CH, OM | M | -- | מטען תגובה (מחרוזת JSON). |
gen_ai.execution.type |
IA | O | -- | אחד מHumanToAgent, Agent2Agent, . EventToAgent |
microsoft.a365.agent.thought.process |
IA, CH | O | -- | היגיון בטקסט חופשי / שרשרת מחשבה. |
gen_ai.author.app.id |
OM | O | -- | מזהה אפליקציית Microsoft Entra של היישום שיצר את הסוכן. |
gen_ai.tool.name |
ET | M | ToolName |
Tool name. תצוגות השימוש בכלי Defender ריקות אם חסרות. |
gen_ai.tool.type |
ET | M | ToolType |
אחד מfunction, Power Platform Connector, MCP Server, API, Knowledge Source, bing_groundingcode_interpreter, , file_search. |
gen_ai.tool.call.id |
ET | M | ToolId |
מזהה לקריאת הכלי הזו. |
gen_ai.tool.call.arguments |
ET | M | -- | ארגומנטים של כלי (מחרוזת JSON). נתפס אך עדיין לא עלה לציד מתקדם. |
gen_ai.tool.call.result |
ET | M | -- | תוצאת כלי (מחרוזת JSON). |
gen_ai.tool.description |
ET | O | ToolDescription |
Tool description. |
gen_ai.tool.server.name |
ET | O | -- | שם מארח של שרת הכלים. הגדר תכונה זו עבור כלי MCP. |
gen_ai.request.model |
CH | M | -- | שם הדגם (לדוגמה, gpt-4o). נתפס אך עדיין לא עלה לציד מתקדם. |
gen_ai.provider.name |
CH | M | -- | שם הספק (לדוגמה, openai). |
gen_ai.usage.input_tokens |
CH | O | -- | ספירת אסימוני קלט, מקודדת במחרוזת. |
gen_ai.usage.output_tokens |
CH | O | -- | ספירת אסימוני פלט, מקודדת במחרוזת. |
gen_ai.response.finish_reasons |
CH | O | -- | Finish reason(s). |
microsoft.a365.caller.agent.id |
IA | M*² | -- | מתקשר לסוכן בבקשה. נדרש לסוכן לסוכנים. |
microsoft.a365.caller.agent.name |
IA | M*² | -- | שם תצוגה של סוכן מתקשר. |
microsoft.a365.caller.agent.blueprint.id |
IA | M*² | AgentBlueprintId |
אפליקציית התוכנית של הסוכן מתקשר. נדרש ל-A2A מגולם. |
microsoft.a365.caller.agent.user.id |
IA | M*² | -- | מזהה המשתמש של סוכן המתקשר. |
microsoft.a365.caller.agent.user.email |
IA | M*² | -- | מתקשר לסוכן UPN. |
microsoft.a365.caller.agent.platform.id |
IA | N/A | -- | שמור למזהים חלופיים שאינו של אנטרה. |
gen_ai.caller.agent.type |
IA | N/A | -- | סוכן 365 מסווג אוטומטית. |
microsoft.agent.user.id |
IA, ET, CH | M*¹ |
TargetAgentUserKey (IA); UserKey (ET, CH) |
מזהה אובייקט Microsoft Entra של חשבון המשתמש של הסוכן עצמו. נדרש לחברי צוות בינה מלאכותית / סוכנים מגולמים. |
microsoft.agent.user.email |
IA, ET, CH | O*¹ |
UserId (ET, CH) |
UPN של חשבון המשתמש של הסוכן. |
span.SpanId |
All | M | OpId |
OTel SDK משדר את זה. |
span.ParentSpanId |
All | M*³ | ParentId |
נדרש רק למרחקים שאינם שורשים; לשורש invoke_agent אין כלום. |
span.StartTimeUnixNano |
All | M | רמה TimeGenerated עליונה (גם CreationTime ב RawEventData-) |
ננו של תקופת יוניקס כמחרוזת. |
span.EndTimeUnixNano |
All | M |
CompletionTime (IA, ET); CopilotEventData.CompletionTime (CH) |
אי אפשר לחשב את משך הזמן אם חסר. |
span.Status.Message |
All | O*⁴ |
ErrorMessage (IA, ET); CopilotEventData.ErrorMessage (CH) |
הסיבה השורשית של הריצות שנכשלו היא ריקה אם חסרה. |
span.Status.Code |
All | O*⁴ |
ErrorType (IA); CopilotEventData.ErrorType (CH) |
קטגוריית שגיאה ריקה אם חסרה. |
Note
כמה תכונות שאתה משדר (כמו ארגומנטים / תוצאות של כלי, פרמטרי מודל וקישורים עמוקים בערוץ) מתקבלים על ידי Agent 365 ומשמשים בתצוגות Microsoft Defender במורד הזרם, אך עדיין לא נחשפו כמפתח JSON CloudAppEvents.RawEventData. הגדר אותם לפי עמודת הנדרש בכל מקרה - ייתכן שהם יתווספו למטען הציד במהדורה עתידית.
בחירת ערכים כשאין לך ערכים טבעיים
חלק מהתכונות הנדרשות מתארות מושגים שאולי לא קיימים בארכיטקטורה של הסוכן שלך. אם הערך הטבעי לא קיים, הנה מה להגדיר במקום. אל תשאיר שדה חובה ריק – אפילו GUID אפס בלבד יסתיר את הריצה שלך מחוויות מול לקוחות מסוימים.
| שאלה / תרחיש | Field(s) | מה להגדיר |
|---|---|---|
| הסוכן שלי הוא <הרשמה סטנדרטית לאפליקציית Entra > (לא נבנה מתבנית מזהה סוכן Entra). | gen_ai.agent.id |
האפליקציה של אפליקציית Entra. |
| ↑ אותו תרחיש | microsoft.a365.agent.blueprint.id |
השתמש שוב באותו ערך כמו gen_ai.agent.id (ה-appId של הסוכן). הסכימה דורשת ערך לא ריק; שימוש חוזר באפליקציית הסוכן הוא ברירת המחדל הבטוחה כשאין Blueprint. |
| הסוכן שלי הוא נבנה מתכנית מזהה סוכן Entra - זהויות סוכן אחת או רבות שנוצרו מאותה תכנית. | gen_ai.agent.id |
כתובת האפליקציה של זהות הסוכן (כתובת האפליקציה של המופע, לא של התוכנית). |
| ↑ אותו תרחיש | microsoft.a365.agent.blueprint.id |
התוכנית מיושמת. כל המופעים המונפטים מאותו תכנית חולקים ערך זה. |
| המתקשר הוא משתמש אנושי, לא סוכן נוסף. | הכל microsoft.a365.caller.agent.* ותכונות gen_ai.caller.agent.* |
Omit. הם חובה רק בתרחישי סוכן לסוכנים. |
| בסוכן לסוכן: הסוכן המתקשר הוא אפליקציית Entra סטנדרטית (ללא תכנית). | microsoft.a365.caller.agent.blueprint.id |
השתמש שוב באפליקציה של סוכן השיחה. |
| הסוכן שלי לא חבר צוות מבוסס בינה מלאכותית - אין לו חשבון משתמש משלו בדייר. | כל microsoft.agent.user.* התכונות |
Omit. הם חובה רק כאשר לסוכן יש חשבון משתמש מזהה סוכן Entra משלו. |
| לסוכן שלי אין מושג על סשן מעבר לריצה אחת. | microsoft.session.id |
אופציונלי - להשמיט. אם אתה רוצה שכל ריצה תהיה סשן נפרד, הגדר ל-GUID לכל ריצה. |
| לסוכן שלי אין מושג של שיחה (שיחה חד-פעמית, ללא מדינה). | gen_ai.conversation.id |
יצר GUID חדש בכל ריצה. המגרש הוא חובה; דילוג עליו מסיר את הריצה מהתצוגות של פעילות הסוכנים ב-Defender ומה-מרכז הניהול של Microsoft 365. |
| למתקשר אין כתובת IP (למשל, טריגר מתוזמן אוטונומי). | client.address |
השתמש בתחליף קבוע שאתה שולט בו (למשל, "0.0.0.0"). המגרש הוא חובה; ערך ריק מסיר את הריצה מפיבוטי חקירה מבוססי IP. |
| הסוכן פועל בתהליך; אין "שרת" נפרד שנקרא. | server.address / server.port |
השתמש בשם המארח של המחשב שהפעיל את הסוכן (למשל, myagent.example.com) ובפורט שעליו נקודת הקצה שלך מאזינת. נדרש גם כשאין שירות נפרד במורד הזרם. |
ה-span שלי chat לא משתמש בטוקנים של הדגם. |
gen_ai.usage.input_tokens / gen_ai.usage.output_tokens |
אופציונלי - להשמיט. אם יש לך ספירות משוערות, שלח אותן כ- stringValue. |
| ל-SPAN שלי אין שגיאה לדווח. |
span.Status.Message, span.Status.Code |
הגדר את מצב ה-OTel ל OK -(קוד מספרי 1) והשמט את ההודעה. הצינור מתייעץ עם שדות אלו רק כאשר הסטטוס הוא Error. |
| הסוכן שלי משתמש במערכת זהות שאינה Entra (לסוכן אין רישום ב-Entra). |
microsoft.a365.agent.platform.id ו- gen_ai.agent.type |
קבע את שניהם, על כל מפתח.
platform.id הוא המזהה הייחודי של הסוכן במערכת הזהות שלך ; agent.type היא תווית קצרה שמזהה איזו מערכת זהות היא. שניהם טקסט חופשי - בחר מה שמתאים למערכת שלך.
אל תשתמש בערכי הטיפוס השמורים Microsoft: CustomBuiltAgentsUsingSDK, CopilotStudio, Foundry, DeclarativeAgent, Custom (ערכים אלה שמורים למשטחים פנימיים Microsoft). האפליקציה שמתקשר איתה אתה מאמת עדיין צריכה רישום Entra כדי להשתמש במסלולים האלה - זוג הזהות האלטרנטיבי מתאר סוכן יעד , לא את המתקשר. |
איזה ערך כדאי לי להעניק microsoft.channel.name? |
microsoft.channel.name |
המשטח שבו הסוכן רץ. Defender ו-admin center מסננים את המפתח מהמחרוזת המילולית, אז השתמש בטוקן קצר, יציב וקטן. כיום הערכים הקנוניים הם msteams ו- outlook; משטחים נפוצים הפונים ללקוח משתמשים webגם ב, office, sharepoint, או <your-product-name>. בחר ערך אחד והיצמד אליו - הכלים לא מצליחים להתאים בין msteams ל-Microsoft Teams כאותו ערוץ. |
האם כדאי לי לקבוע gen_ai.agent.type? |
gen_ai.agent.type |
רק אם אתה גם עושה הגדרה microsoft.a365.agent.platform.id (למשל, לסוכן שלך אין רישום ב-Entra). הזוג אומר לסוכן 365 מאיזו מערכת זהות מגיע הסוכן עצמו. בחר תווית קצרה שמזהה באופן ייחודי את מערכת הזהות שלך .
אל תשתמש ב-CustomBuiltAgentsUsingSDK, CopilotStudio, Foundry, DeclarativeAgent, או Custom - הערכים האלה שמורים לשימוש Microsoft פנימי. לסוכנים רשומים ב-Entra, השמיטו את השדה; סוכן 365 ממלא את זה. |
איזה OTLP kind כדאי לי להגדיר על המרחקים שלי? |
span.kind |
השתמשו בערך ה-enum של המספרים השלמים, לא במחרוזת הפרוטו enum - 1 (INTERNAL), 2 (SERVER), 4CLIENTPRODUCER35 ().CONSUMER סוכן 365 מקבל כל אחד מהם ואינו גוזר התנהגות נראית ללקוח מ- kind, כך ש 1 -(INTERNAL) הוא ברירת מחדל בטוחה לכל ספאן. אם אתה רוצה שזה ישקף את צורת הקריאה, INTERNAL ל-ולמען chat / execute_toolinvoke_agentoutput_messagesCLIENT / זה סביר. |