הערה
הגישה לדף זה מחייבת הרשאה. באפשרותך לנסות להיכנס או לשנות מדריכי כתובות.
הגישה לדף זה מחייבת הרשאה. באפשרותך לנסות לשנות מדריכי כתובות.
מאמר זה הוא המפרט הקנוני של תכונה אחר תכונה שמשמש את צינור הקליטה של Agent 365. כל מרווח שנצרך על ידי סוכן 365 - בין אם נפלט על ידי הפצת Microsoft OpenTelemetry, מ-Agent 365 Observability SDK המיושן, או נשלח ישירות ל-OTel - חייב להתאים אליו. כל ערך מפרט את סוגי הפעולות שאליהם התכונה חלה, האם היא חובה, שם השדה שבו הערך שלך נוחת בשאילתות ציד מתקדמות (כאשר קיימת), ואת ההשפעה אם תדלג עליה.
אם אתה משתמש ב-SDK או ב-Distro, ה-SDK משדר עבורך את התכונות האלה. סעיף בחירת ערכי הבחירה חל רק כאשר צריך לעקוף ברירת מחדל. אם אתה משתמש בנתיב הישיר של OTel, אתה משדר כל תכונה ידנית. למידע כיצד להרכיב אותם לבקשה, ראו את מדריך האינטגרציה.
Attribute table
כל הערכים נשלחים כ- stringValue - ספירת האסימונים חייבת להיות "42" (לא 42); הפורטים חייבים להיות "443" (לא 443).
מבצע אגדה.IA = invoke_agent, ET = execute_tool, CH, = chatOM = output_messages, All = חל על כל פעולה.
Required legend.
- M: mandatory.
- M*1: חובה רק לסוכנים מגולמים (לסוכן יש חשבון משתמש מזהה סוכן Entra משלו).
- M*2: חובה רק לשיחות בין סוכנים.
-
M*3: חובה רק למרחבים שאינם שורשים. לשורש
invoke_agentאין הורה. - O*4: אופציונלי, משמעותי רק כאשר מצב הספין הוא שגיאה.
- O: optional.
- אין תשובה: אל תפלוט. סוכן 365 מתמלא אוטומטית.
עמודת "שדה RawEventData" מציינת מפתח JSON שבתוך CloudAppEvents.RawEventData המפתח מנתחת את שאילתת הציד המתקדם הקנונית ב-Verifying ingestion . תא ריק אומר שהתכונה לא נחשפת 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, , , execute_tool. chatoutput_messages הספאן נפל אם נעדר או לא זוהה. |
microsoft.tenant.id |
All | M | OrganizationId |
כתובת URL {tenantId} היא סמכותית. אם תגדיר ערך זה והוא לא מסכים, הבקשה נדחית (403). |
gen_ai.agent.id |
All | M |
TargetAgentId (IA); 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 ו-admin center הם 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 reasons. |
microsoft.a365.caller.agent.id |
IA | M*2 |
AgentId (IA) |
מתקשר לסוכן בבקשה. נדרש לסוכן לסוכנים. |
microsoft.a365.caller.agent.name |
IA | M*2 |
AgentName (IA) |
שם תצוגה של סוכן מתקשר. |
microsoft.a365.caller.agent.blueprint.id |
IA | M*2 | AgentBlueprintId |
אפליקציית התוכנית של הסוכן מתקשר. נדרש ל-A2A מגולם. |
microsoft.a365.caller.agent.user.id |
IA | M*2 | -- | מזהה המשתמש של סוכן המתקשר. |
microsoft.a365.caller.agent.user.email |
IA | M*2 | -- | מתקשר לסוכן 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*1 |
TargetAgentUserKey (IA); UserKey (ET, ch) |
מזהה אובייקט Microsoft Entra של חשבון המשתמש של הסוכן עצמו. נדרש לחברי צוות בינה מלאכותית וסוכנים מגולמים. |
microsoft.agent.user.email |
IA, ET, CH | O*1 |
UserId (ET, CH) |
UPN של חשבון המשתמש של הסוכן. |
span.SpanId |
All | M | OpId |
OTel SDK משדר את זה. |
span.ParentSpanId |
All | M*3 | 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*4 |
ErrorMessage (IA, ET); CopilotEventData.ErrorMessage (CH) |
הסיבה השורשית של הריצות שנכשלו היא ריקה אם חסרה. |
span.Status.Code |
All | O*4 |
ErrorType (IA); CopilotEventData.ErrorType (CH) |
קטגוריית שגיאה ריקה אם חסרה. |
Note
Agent 365 מקבל מספר תכונות שאתה משדר, כמו ארגומנטים ותוצאות, פרמטרי מודל, וקישורים עמוקים של ערוץ. תצוגות Microsoft Defender במורד הזרם משתמשות בתכונות אלו, אך Agent 365 עדיין לא חושף אותן כמפתח CloudAppEvents.RawEventData JSON. הגדר אותם לפי עמודת הנדרש. ייתכן שהם יתווספו למטען הציד במהדורה עתידית.
Important
ברשומות invoke_agent (IA), ה- AgentId, AgentName, והשדות AgentBlueprintId מתארים את הסוכן המתקשר , לא את הסוכן המופעל. סוכן 365 מאכלס אותם מהתכונות microsoft.a365.caller.agent.* . כשאדם מזמן את הסוכן שלך, השמט את התכונות האלה, כך AgentId ומופיע AgentBlueprintId כ-GUID של אפסים (00000000-0000-0000-0000-000000000000) והוא AgentName ריק ברשומות הביקורת וב-Microsoft Purview. ערך האפסים בלבד צפוי לריצות שיזמו בני אדם. כדי לזהות את הסוכן המופעל, השתמשו TargetAgentIdב-, TargetAgentName, ו- TargetAgentBlueprintID.
בחירת ערכים כשאין לך ערכים טבעיים
חלק מהתכונות הנדרשות מתארות מושגים שאולי לא קיימים בארכיטקטורה של הסוכן שלך. אם הערך הטבעי אינו זמין, הגדר את הערכים הבאים במקום.
אל תשאיר שדה חובה ריק. אפילו GUID עם אפסים בלבד מסתיר את הריצה שלך מחוויות שמתאימות ללקוחות. כלל זה חל רק על תכונות חובה. זה לא חל על מאפייני הקולר-סוכן בריצות שמופעלות על ידי אדם, שבהן מצופה לאפס AgentId הכל ברשומות invoke_agent .
| שאלה / תרחיש | 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. הם חובה רק בתרחישי סוכן לסוכנים. ברשומות invoke_agent , המתקשר מציג AgentIdAgentBlueprintId GUID של אפסים בלבד. השתמש TargetAgentId בו כדי לזהות את הסוכן שלך. |
| בסוכן לסוכן: הסוכן המתקשר הוא אפליקציית 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), 3CLIENT4PRODUCER5 ().CONSUMER סוכן 365 מקבל כל אחד מהם ואינו גוזר התנהגות נראית ללקוח מ- kind, כך ש 1 -(INTERNAL) הוא ברירת מחדל בטוחה לכל ספאן. אם אתה רוצה שזה ישקף את צורת הקריאה, INTERNAL ל-ולמען invoke_agent / output_messagesCLIENTchat / execute_toolזה סביר. |