Αναφορά χαρακτηριστικού παρατηρησιμότητας πράκτορα 365

Αυτή είναι η κανονική προδιαγραφή χαρακτηριστικού προς χαρακτηριστικό που χρησιμοποιείται από τη διοχέτευση απορρόφησης του Agent 365. Κάθε εύρος που απορροφάται από τον πράκτορα 365 - είτε εκπέμπεται από το Microsoft OpenTelemetry Distro, το Agent 365 SDK είτε αποστέλλεται μέσω direct OTel - πρέπει να συμμορφώνεται με αυτό. Κάθε καταχώρηση παραθέτει τους τύπους λειτουργιών στους οποίους εφαρμόζεται το χαρακτηριστικό, εάν είναι υποχρεωτικό, το όνομα του πεδίου στο οποίο καταλήγει η τιμή σας για ερωτήματα προηγμένου κυνηγιού (όπου υπάρχει) και τον αντίκτυπο εάν το παραλείψετε.

Εάν χρησιμοποιείτε το SDK ή τη διανομή, το SDK εκπέμπει αυτά τα χαρακτηριστικά για εσάς και η ενότητα Επιλογή τιμών ισχύει μόνο όταν πρέπει να παρακάμψετε μια προεπιλογή. Εάν βρίσκεστε στην άμεση διαδρομή OTel, εκπέμπετε κάθε χαρακτηριστικό χειροκίνητα. Για το πώς να τα συγκεντρώσετε σε ένα αίτημα, ανατρέξτε στον Οδηγό ενσωμάτωσης.

Attribute table

Όλες οι τιμές αποστέλλονται ως stringValue - Οι μετρήσεις διακριτικών πρέπει να είναι "42" (όχι 42); Οι θύρες πρέπει να είναι "443" (όχι 443).

Θρύλος της επιχείρησης.IA, = invoke_agentET, = execute_toolCH, = chatOM, = output_messagesAll = ισχύει για κάθε λειτουργία.

Required legend.

  • M: mandatory.
  • M*1: υποχρεωτικό μόνο για ενσωματωμένους πράκτορες (ο πράκτορας έχει τον δικό του λογαριασμό χρήστη Entra ID παράγοντα).
  • M*2: υποχρεωτικό μόνο για κλήσεις από πράκτορα σε πράκτορα.
  • M*3: υποχρεωτικό μόνο για μη ριζικά ανοίγματα. Η ρίζα invoke_agent δεν έχει γονέα.
  • O*4: προαιρετικό, με νόημα μόνο όταν η κατάσταση εύρους είναι Σφάλμα.
  • O: optional.
  • N/A: μην εκπέμπετε. Ο πράκτορας 365 συμπληρώνεται αυτόματα.

Η στήλη "Πεδίο RawEventData" ονομάζει ένα κλειδί JSON μέσα CloudAppEvents.RawEventData στο οποίο αναλύει το κανονικό ερώτημα προηγμένης αναζήτησης στην Επαλήθευση πρόσληψης . Ένα κενό κελί σημαίνει ότι το χαρακτηριστικό είναι not εκτεθειμένο στο CloudAppEvents σήμερα--θα πρέπει να το εκπέμπετε (σύμφωνα με τη στήλη Απαιτείται) επειδή ο παράγοντας 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, chat, . output_messages Το εύρος μειώθηκε εάν λείπει ή δεν αναγνωρίζεται.
microsoft.tenant.id All M OrganizationId Η διεύθυνση URL {tenantId} είναι έγκυρη. Εάν το ορίσετε και διαφωνεί, το αίτημα απορρίπτεται (403).
gen_ai.agent.id All M TargetAgentId (IA, επίσης ανώτατου επιπέδου AgentId). AgentId (ET, CH) Το appId της εφαρμογής κλήσης. Πρέπει να αντιστοιχεί στη διεύθυνση URL {agentId} και στην εφαρμογή που έχει υποβληθεί σε έλεγχο ταυτότητας. Η αναντιστοιχία επιστρέφει 403.
gen_ai.agent.name All M TargetAgentName (ΙΑ)· AgentName (ET, CH) Το Defender / admin center εμφανίζει το ακατέργαστο GUID αντί για ένα όνομα εάν λείπει.
microsoft.a365.agent.blueprint.id All M TargetAgentBlueprintID (ΙΑ)· AgentBlueprintId (ET, CH) Το appId του σχεδιαγράμματος. Για τυπικές εφαρμογές Entra χωρίς σχεδιάγραμμα, χρησιμοποιήστε ξανά το appId του copilot. Διαφορετικά, οι συναθροίσεις σχεδιαγραμμάτων στο κέντρο διαχείρισης διακόπτονται.
gen_ai.agent.description All O -- Η προβολή λεπτομερειών στο κέντρο διαχείρισης είναι κενή για τον εκπρόσωπο.
gen_ai.agent.type All O PlatformTargetAgentType (ΙΑ)· PlatformAgentType (ET); CopilotEventData.PlatformAgentType (Χ.) Μια ετικέτα για το σύστημα ταυτότητάς σας, σε συνδυασμό με microsoft.a365.agent.platform.id όταν ο εκπρόσωπος δεν έχει εγγραφή στο Entra. Κείμενο ελεύθερης μορφής. Επιλέξτε μια τιμή που προσδιορίζει μοναδικά το σύστημα ταυτότητάς σας. Παραλείψτε όταν ο πράκτορας έχει εγγραφή στο Entra --Ο πράκτορας 365 ταξινομείται αυτόματα. Μην χρησιμοποιείτε τις δεσμευμένες τιμές Microsoft (δείτε Τιμές συλλογής).
microsoft.a365.agent.platform.id All O PlatformTargetAgentId (IA, επίσης ανώτατου επιπέδου AlternateId). PlatformAgentId (ET, CH) Το μοναδικό αναγνωριστικό του εκπροσώπου στο σύστημα ταυτότητάς σας που δεν είναι Entra. Free-form text. Ορίστε μαζί με gen_ai.agent.type. Παραλείψτε όταν ο πράκτορας έχει εγγραφή στο Entra. Δείτε: Επιλογή τιμών.
gen_ai.conversation.id All M ConversationId (IA, ET); CopilotEventData.ConversationId / CopilotEventData.ThreadId (Χ.) Το πρωτεύον πλήκτρο σύνδεσης για μια εκτέλεση. Χωρίς αυτό, η εκτέλεση δεν εμφανίζεται στις προβολές δραστηριότητας εκπροσώπου του Defender ή στο κέντρο διαχείρισης.
microsoft.channel.name All M ChannelName (ΙΑ, ΕΤ) Η επιφάνεια στην οποία τρέχει ο παράγοντας. Χρησιμοποιήστε ένα σύντομο πεζό διακριτικό. Οι κανονικές τιμές που χρησιμοποιούνται σήμερα από τα φίλτρα Defender / Κέντρου διαχείρισης είναι και . Οι προσαρμοσμένες συμβολοσειρές (για παράδειγμα 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 (ΙΑ) Αναγνωριστικό για το SDK / υπηρεσία που εκπέμπει την τηλεμετρία. Μπορεί να είναι ένα χαρακτηριστικό Resource.
client.address IA, ET, CH M ClientIP (ΙΑ, ΕΤ) Caller IP. Η έρευνα που βασίζεται σε IP μπλοκάρεται εάν είναι κενή.
server.address IA, ET, CH M ServerAddress (ΙΑ, ΕΤ) Τελικό σημείο που καλεί η υπηρεσία σας.
server.port IA, ET, CH M ServerPort (ΙΑ) Κωδικοποίηση συμβολοσειράς (για παράδειγμα "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_grounding, code_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*2 -- Καλών αντιπρόσωπος appId. Απαιτείται για πράκτορα σε πράκτορα.
microsoft.a365.caller.agent.name IA M*2 -- Εμφανιζόμενο όνομα καλούντος αντιπροσώπου.
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 -- Προορίζεται για εναλλακτικά αναγνωριστικά που δεν ανήκουν στην Entra.
gen_ai.caller.agent.type IA N/A -- Ο πράκτορας 365 ταξινομεί αυτόματα.
microsoft.agent.user.id IA, ET, CH M*1 TargetAgentUserKey (ΙΑ)· UserKey (ET, CH) Αναγνωριστικό αντικειμένου Microsoft Entra του λογαριασμού χρήστη του εκπροσώπου. Απαιτείται για συμπαίκτες AI / ενσωματωμένους πράκτορες.
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) Τα nanos της εποχής του Unix ως συμβολοσειρά.
span.EndTimeUnixNano All M CompletionTime (IA, ET); CopilotEventData.CompletionTime (Χ.) Η διάρκεια δεν μπορεί να υπολογιστεί εάν λείπει.
span.Status.Message All O*4 ErrorMessage (IA, ET); CopilotEventData.ErrorMessage (Χ.) Η βασική αιτία των αποτυχημένων εκτελέσεων είναι κενή εάν λείπει.
span.Status.Code All O*4 ErrorType (ΙΑ)· CopilotEventData.ErrorType (Χ.) Η κατηγορία σφάλματος είναι κενή εάν λείπει.

Note

Πολλά χαρακτηριστικά που εκπέμπετε (όπως ορίσματα/αποτελέσματα εργαλείου, παράμετροι μοντέλου και συνδέσεις σε βάθος καναλιού) γίνονται αποδεκτά από τον παράγοντα 365 και χρησιμοποιούνται από μεταγενέστερες προβολές Microsoft Defender, αλλά δεν έχουν ακόμη εκτεθεί ως κλειδί JSON CloudAppEvents.RawEventData. Ορίστε τα σύμφωνα με τη στήλη Απαιτείται ούτως ή άλλως - μπορεί να προστεθούν στο ωφέλιμο φορτίο κυνηγιού σε μελλοντική έκδοση.

Επιλέγοντας τιμές όταν δεν έχετε φυσική

Ορισμένα απαιτούμενα χαρακτηριστικά περιγράφουν έννοιες που μπορεί να μην υπάρχουν στην αρχιτεκτονική του copilot σας. Εάν η φυσική αξία δεν υπάρχει, ορίστε τι πρέπει να ορίσετε. Μην αφήνετε ένα υποχρεωτικό πεδίο κενό--ακόμη και ένα GUID με μηδενικά θα κρύψει την εκτέλεσή σας από ορισμένες εμπειρίες που απευθύνονται σε πελάτες.

Ερώτηση / σενάριο Field(s) Τι να ρυθμίσετε
Ο αντιπρόσωπός μου είναι μια τυπική εγγραφή εφαρμογής Entra (δεν έχει κατασκευαστεί από Entra ID παράγοντα σχέδιο). gen_ai.agent.id Το appId της εφαρμογής Entra.
↑ ίδιο σενάριο microsoft.a365.agent.blueprint.id Χρησιμοποιήστε ξανά την ίδια τιμή με gen_ai.agent.id (το appId του copilot). Το σχήμα απαιτεί μια μη κενή τιμή. Η επαναχρησιμοποίηση του appId εκπροσώπου είναι η ασφαλής προεπιλογή όταν δεν υπάρχει σχέδιο.
Ο πράκτοράς μου είναι κατασκευασμένος από ένα Entra ID παράγοντα σχέδιο - μία ή πολλές ταυτότητες πρακτόρων που έχουν κοπεί από το ίδιο σχέδιο. gen_ai.agent.id Το appId της ταυτότητας εκπροσώπου (η παρουσία appId, όχι του σχεδιαγράμματος).
↑ ίδιο σενάριο microsoft.a365.agent.blueprint.id Το appId του σχεδιαγράμματος. Όλες οι περιπτώσεις που έχουν κοπεί από το ίδιο σχέδιο μοιράζονται αυτήν την τιμή.
Ο καλών είναι ανθρώπινος χρήστης, όχι άλλος πράκτορας. Όλα microsoft.a365.caller.agent.* και gen_ai.caller.agent.* χαρακτηριστικά Omit. Είναι υποχρεωτικά μόνο σε σενάρια από πράκτορα σε πράκτορα.
Σε πράκτορα σε πράκτορα: ο καλών πράκτορας είναι μια τυπική εφαρμογή Entra (χωρίς σχέδιο). microsoft.a365.caller.agent.blueprint.id Χρησιμοποιήστε ξανά το appId του καλούντος αντιπροσώπου.
Το copilot μου δεν είναι συμπαίκτης AI - δεν έχει δικό του λογαριασμό χρήστη στον μισθωτή. Όλα τα microsoft.agent.user.* χαρακτηριστικά Omit. Είναι υποχρεωτικά μόνο όταν ο εκπρόσωπος έχει τον δικό του λογαριασμό χρήστη Entra ID παράγοντα.
Ο ατζέντης μου δεν έχει ιδέα για μια συνεδρία πέρα από μία μόνο εκτέλεση. microsoft.session.id Προαιρετικό - παραλείπεται. Εάν θέλετε κάθε εκτέλεση να είναι η δική της περίοδος λειτουργίας, ορίστε σε ένα GUID ανά εκτέλεση.
Ο ατζέντης μου δεν έχει ιδέα για συνομιλία (one-shot, stateless). gen_ai.conversation.id Δημιουργήστε ένα νέο GUID ανά εκτέλεση. Το πεδίο είναι υποχρεωτικό. Η παράλειψή του καταργεί την εκτέλεση από τις προβολές δραστηριότητας εκπροσώπου του Defender και το Κέντρο διαχείρισης Microsoft 365.
Ο καλών δεν έχει IP (για παράδειγμα, ένα αυτόνομο προγραμματισμένο έναυσμα). client.address Χρησιμοποιήστε ένα σταθερό σύμβολο κράτησης θέσης που ελέγχετε (για παράδειγμα, "0.0.0.0"). Το πεδίο είναι υποχρεωτικό. μια κενή τιμή καταργεί την εκτέλεση από pivot έρευνας που βασίζονται σε 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 και το κέντρο διαχείρισης φιλτράρουν το κλειδί από την κυριολεκτική συμβολοσειρά, επομένως χρησιμοποιήστε ένα σύντομο, σταθερό, πεζό διακριτικό. Σήμερα οι κανονικές τιμές είναι 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 πρέπει να ορίσω στα spans μου; span.kind Χρησιμοποιήστε την ακέραια τιμή απαρίθμησης, όχι τη συμβολοσειρά proto enum - 1 (INTERNAL), 2 (SERVER), 3 (CLIENT), 4PRODUCER(), 5 (CONSUMER). Ο παράγοντας 365 αποδέχεται οποιοδήποτε από αυτά και δεν αντλεί συμπεριφορά ορατή από τον πελάτη από kindτο , επομένως 1 το (INTERNAL) είναι μια ασφαλής προεπιλογή για κάθε διάστημα. Εάν θέλετε το είδος να αντικατοπτρίζει το σχήμα κλήσης, INTERNAL γιαinvoke_agent / output_messagesκαι CLIENT για chat / execute_tool είναι λογικό.

Related content

  • Last updated on