Έννοιες παρατηρησιμότητας του Agent 365

Το άρθρο αυτό εξηγεί το μοντέλο δεδομένων πίσω από την παρατηρησιμότητα του Agent 365 – τι εκπέμπουν οι παράγοντες τηλεμετρίας, ποιοι μπορούν να το εκπέμπουν, πού καταλήγει και τα όρια που ισχύουν. Αυτές οι έννοιες εφαρμόζονται σε κάθε διαδρομή ενοποίησης: το Microsoft OpenTelemetry Distro, το Agent 365 SDK και το direct OTel.

Σημείωμα

Λεπτομέρειες σε επίπεδο πρωτοκόλλου – οι διαδρομές URL στην Αυθεντικοποίηση, οι κωδικοί σφαλμάτων HTTP στα Όρια και συνθήκες απόρριψης, καθώς και τα όρια μεγέθους και ρυθμού ανά αίτημα – εφαρμόζονται αποκλειστικά στην απευθείας διαδρομή OTel. Το SDK και το Distro τα αφαιρούν για εσάς. Το υπόλοιπο αυτού του άρθρου (γλωσσάριο, ροή δεδομένων, μοντέλα ταυτότητας, πεδία, συνθήκες απόρριψης, όπου εμφανίζονται τα δεδομένα) ισχύει για κάθε διαδρομή.

Επιλέξτε τη διαδρομή ενσωμάτωσης

Τρεις διαδρομές εκπέμπουν το ίδιο μοντέλο δεδομένων span στο Agent 365. Επιλέξτε ένα:

• Microsoft OpenTelemetry Distro - συνιστάται για νέες ενσωματώσεις. Ενοποιημένο SDK παρατηρησιμότητας για τα Agent 365, Microsoft Foundry, Azure Monitor και άλλα.
• Agent 365 SDK (SDK παρατηρησιμότητας) - το παλαιότερο SDK. Συνεχίζει να λειτουργεί χωρίς μη συμβατές αλλαγές, αλλά δεν αποτελεί πλέον τη συνιστώμενη επιλογή για νέες ενσωματώσεις· οδηγίες μετεγκατάστασης για τους υπάρχοντες χρήστες του SDK θα ακολουθήσουν.
• Direct OTel - η ακατέργαστη διαδρομή OTLP/HTTP. Χρησιμοποιήστε το μόνο αν έχετε ήδη έναν αγωγό OpenTelemetry, το πλαίσιο παράγοντα σας δεν μπορεί να χρησιμοποιήσει το Agent 365 SDK ή ο παράγοντας σας είναι σε γλώσσα που το SDK δεν υποστηρίζει ακόμη (όπως Java).

Όποια διαδρομή κι αν επιλέξετε, το μοντέλο δεδομένων, τα μοντέλα ταυτότητας, τα πεδία, τα όρια και τα κατάντη συστήματα που περιγράφονται παρακάτω ισχύουν.

Γλωσσάριο

• Αναγνωριστικό εφαρμογής (appId): Το αναγνωριστικό εφαρμογής που εκδίδεται όταν καταχωρείται μια εφαρμογή Microsoft Entra ή ταυτότητα παράγοντα αναγνωριστικού παράγοντα Microsoft Entra.
  • Αντιστοιχεί στο OAuth client_id, όχι το αναγνωριστικό αντικειμένου Microsoft Entra.
  • Σε όλο το παρόν τεκμηριωτικό υλικό, οι όροι «παράγοντας id» και «blueprint id» χρησιμοποιούνται εναλλακτικά για να δηλώσουν ένα appId.
• Συνομιλία: Ένα λογικό νήμα αλληλεπιδράσεων παράγοντα, όπως ένα νήμα συνομιλίας στο Teams.
  • Προσδιορίζεται από gen_ai.conversation.id.
  • Το πρωτεύον κλειδί για μια εκτέλεση.
• Κανάλι: Το περιβάλλον στο οποίο τρέχει ο παράγοντας: msteams, outlook, web κ.λπ.
• Εκτέλεση: Ένα μήνυμα χρήστη εισέρχεται, μία απάντηση παράγοντα εξέρχεται. Μοντελοποιείται ως ένα δέντρο από OTel spans που μοιράζονται ένα κλειδίtraceId.

Πώς λειτουργεί

Για μια επισκόπηση του Microsoft Agent 365 και των σημείων όπου καταλήγει η τηλεμετρία, δείτε Επισκόπηση του Microsoft Agent 365.

Αποστέλλετε τηλεμετρία ως δεδομένα ιχνηλάτησης OpenTelemetry:

• Ένα δέντρο από spans που περιγράφει ένα run (ένα μήνυμα χρήστη εισέρχεται, μία απάντηση του παράγοντα εξέρχεται).
• Κάθε span περιγράφει ένα μόνο βήμα – την επίκληση του παράγοντα ανώτατου επιπέδου, μια κλήση 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, συμπεριλαμβανομένων των συμπαικτών AI), ανατρέξτε στο θέμα Γρήγορα αποτελέσματα με την ανάπτυξη του Agent 365. Η επιλογή του μοντέλου ταυτότητας καθορίζει ποια μέθοδο ελέγχου ταυτότητας και ποιο endpoint θα χρησιμοποιήσετε.

Εάν ο παράγοντας σας δεν έχει καταχώριση στο Microsoft Entra, δεν μπορεί να χρησιμοποιήσει αυτές τις διαδρομές απευθείας. Εντοπίστε τον παράγοντα μέσω των εναλλακτικών χαρακτηριστικών αναγνωριστικού (βλ. Αναφορά χαρακτηριστικών) και επικοινωνήστε με την ομάδα του Agent 365 σχετικά με την κατάλληλη διαδρομή εισόδου.

Έλεγχος ταυτότητας

Η διαδικασία ελέγχου ταυτότητας διαφοροποιείται ανάλογα με το αν η υπηρεσία σας αυθεντικοποιείται αυτόνομα ή εκ μέρους ενός χρήστη. Η επιλογή καθορίζει τη ροή OAuth, το claim του διακριτικού που φέρει το δικαίωμα και τη διαδρομή URL.

• Η υπηρεσία πραγματοποιεί έλεγχο ταυτότητας για τον εαυτό της: Δεν υπάρχει συνδεδεμένος χρήστης - αυτόνομη, προγραμματισμένη ή βάσει συμβάντων.

  • Ροή OAuth: Υπηρεσία προς υπηρεσία (S2S), διαπιστευτήρια προγράμματος-πελάτη.
  • Αξίωση διακριτικού: roles.
  • Διαδρομή διεύθυνσης URL: /observabilityService/....

• Η υπηρεσία πραγματοποιεί έλεγχο ταυτότητας για λογαριασμό ενός χρήστη: Για AI βοηθούς ή για τον λογαριασμό χρήστη του παράγοντα.

  • Ροή OAuth: Για λογαριασμό του (OBO).
  • Αξίωση διακριτικού: scp.
  • Διαδρομή διεύθυνσης URL: /observability/....

Η ίδια εφαρμογή παράγοντα μπορεί να συμμετέχει και στις δύο ροές, όπως ένας AI συνεργάτης που εκτελεί επίσης μια αυτόνομη νυχτερινή διαδικασία σύνοψης. Για περισσότερες πληροφορίες, δείτε τη ροή OAuth για αυτόνομη εφαρμογή και τη ροή OAuth τύπου on-behalf-of.

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

Η ταυτότητα του παράγοντα συνδέεται με το URL

Η τιμή {agentId} στη διεύθυνση URL πρέπει να είναι ίση με το appId της εφαρμογής που κάνει την κλήση (την appidαξίωσηazp ή στο διακριτικό σας). Αναντιστοιχίες επιστρέφουν 403 Forbidden. Για ταυτότητες που προέρχονται από Blueprint, το {agentId} είναι το appId της ταυτότητας παράγοντα , και όχι το appId του Blueprint.

Επιπλέον, κάθε span που αποστέλλετε πρέπει να ορίζει το gen_ai.agent.id στο ίδιο appId· ο διακομιστής επικυρώνει την ταυτότητα του παράγοντα εντός του φορτίου έναντι του αυθεντικοποιημένου παράγοντα και απορρίπτει ασυμφωνίες. Αυτό το βήμα ανιχνεύει τυχόν ακούσια ανάμειξη span από διαφορετικούς agents σε ένα αίτημα.

Πεδία εφαρμογής και συγκατάθεση

Ένα πεδίο (με αντιπροσωπεία) ή ρόλος εφαρμογής (εφαρμογή) είναι το ονομαζόμενο δικαίωμα που ενσωματώνει η 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, scope για delegated) στην περιοχή Δικαιώματα API στην καταχώρηση εφαρμογής του παράγοντα.
• Για ένα Blueprint: οι παράγοντες που δημιουργούνται από ένα Blueprint ταυτότητας Microsoft Entra ID παράγοντα κληρονομούν τα OAuth δικαιώματα που ορίζονται στο Blueprint, ώστε ο διαχειριστής μισθωτή να προεγκρίνει τα δικαιώματα μία φορά. Κάθε παρουσία παράγοντα που δημιουργείται από αυτή τη δομή προγράμματος τα λαμβάνει αυτόματα. Δείτε Ρύθμιση κληρονομούμενων δικαιωμάτων για πρότυπα ταυτότητας παράγοντα.

Συναίνεση μισθωτή

Για να φέρουν τα διακριτικά τον ρόλο/εύρος, ένας διαχειριστής μισθωτή στον μισθωτή του πελάτη πρέπει να παραχωρήσει συγκατάθεση. Δείτε Παραχώρηση πρόσβασης σε παράγοντες σε πόρους του Microsoft 365.

Χωρίς συγκατάθεση, η απόκτηση διακριτικού αποτυγχάνει με AADSTS65001 ("ο χρήστης ή ο διαχειριστής δεν έχει δώσει συγκατάθεση") ή το διακριτικό εκδίδεται χωρίς την αξίωση roles / scp και το σημείο εισαγωγής απορρίπτει το αίτημα με 403.

Η συγκατάθεση παρέχεται μία φορά ανά μισθωτή, και εφαρμόζεται σε κάθε εγκατάσταση που δημιουργείται από ένα πρότυπο έκτοτε. Εκ νέου συναίνεση απαιτείται μόνο όταν προστεθεί νέα άδεια στο πρότυπο.

Όρια και συνθήκες απόρριψης

Η γνώση αυτών των ορίων εκ των προτέρων αποτρέπει απρόοπτα κατά την ενσωμάτωση – τα περισσότερα είναι σιωπηλά (το API αποδέχεται το αίτημα αλλά τα δεδομένα δεν εμφανίζονται στο downstream).

Όρια επιπέδου μετάδοσης:

• api-version=1 είναι υποχρεωτικό σε κάθε αίτημα.
• Το μέγιστο μέγεθος σώματος αιτήματος είναι 1 MB. Τα μεγαλύτερα αιτήματα λαμβάνουν 413 Payload Too Large.
• Οι δύο διαδρομές έχουν ξεχωριστά όρια ρυθμού. Στο 429, να τηρείται το Retry-After (ρυθμισμένο στο 1 δευτερόλεπτο) και να γίνεται υποχώρηση με jitter.

Εσφαλμένες απαντήσεις:

• 403 Forbidden--Το διακριτικό που λείπει ο απαιτούμενος ρόλος/εύρος εφαρμογής ή {agentId} στη διεύθυνση URL δεν ταιριάζει με το διακριτικό σας appid / azp.
• 413 Payload Too Large--το σώμα υπερβαίνει το 1 MB.
• 429 Too Many Requests--Υπέρβαση ορίου ρυθμού; τηρήστε Retry-After: 1 και υποχωρήστε με jitter.

Συνθήκες απόρριψης (το αίτημα έγινε αποδεκτό από το HTTP αλλά τα δεδομένα δεν εμφανίζονται κατάντη):

#	Συνθήκη	Συμπεριφορά
1	Span gen_ai.operation.name λείπει ή δεν περιλαμβάνεται στο {invoke_agent, execute_tool, chat, output_messages}	Απόρριψη ανά span. Εμφανίζεται σε partialSuccess.rejectedSpans + errorMessage.
2	Κανένας χρήστης στον μισθωτή πελάτη δεν έχει εκχωρηθεί άδεια χρήσης Microsoft 365 E7 ή Microsoft Agent 365. Τουλάχιστον ένας χρήστης στον μισθωτή πρέπει να έχει ανατεθειμένη την άδεια χρήσης (η παρουσία SKU στον μισθωτή δεν επαρκεί - η ανάθεση ξεκινά τη ροή εργασιών παρασκηνίου του Defender). Ο αδειοδοτημένος χρήστης δεν χρειάζεται να είναι ο φυσικός χρήστης που εκκινεί τον παράγοντα.	Ολόκληρο το αίτημα αγνοείται σιωπηλά. Επιστρέφει 200 { "partialSuccess": null }.

Ένα 200 OK δεν αποτελεί απόδειξη εισαγωγής. Χρησιμοποιήστε τη ροή επαλήθευσης για να επιβεβαιώσετε ότι τα δεδομένα έχουν εισαχθεί.

Πού εμφανίζονται τα δεδομένα σας

Μόλις γίνει αποδεκτή, τα spans σας εμφανίζονται σε τρεις εμπειρίες για τον πελάτη. Και τα τρία εξαρτώνται από ένα έγκυρο invoke_agent span στη ρίζα της εκτέλεσης. Μια εκτέλεση που περιέχει μόνο chat / execute_tool / output_messages spans είναι αναζητήσιμη στο Defender advanced hunting (στον πίνακα CloudAppEvents), αλλά παραμένει αόρατη σε όλες τις υπόλοιπες επιφάνειες παρακάτω.

Microsoft Defender. Η δραστηριότητα παράγοντα (invoke_agent, execute_tool, chat) εμφανίζεται στις προβολές δραστηριότητας παράγοντα. Οι διαχειριστές μισθωτών και οι αναλυτές ασφαλείας μπορούν να εξετάσουν μεμονωμένες εκτελέσεις, εργαλεία και κλήσεις εξαγωγής συμπερασμάτων. Οι προβολές δραστηριότητας παράγοντα βασίζονται στο invoke_agentspan· χωρίς αυτό, η εκτέλεση δεν εμφανίζεται εκεί, παρόλο που τα θυγατρικά spans παραμένουν διαθέσιμα για αναζήτηση μέσω προηγμένης αναζήτησης. Η προβολή προηγμένου κυνηγιού - CloudAppEvents - δέχεται κάθε λειτουργία: ActionType αντικατοπτρίζει τη λειτουργία (InvokeAgent, InferenceCall, ExecuteToolBySDK, ExecuteToolByGateway, ExecuteToolByMCPServer) και τα πεδία ανά span βρίσκονται μέσα στο RawEventData. Τα ονόματα των πεδίων που είναι ορατά στον πελάτη αντιστοιχούν άμεσα στα χαρακτηριστικά span που αποστείλατε: 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 (αναγνωριστικό παράγοντα / blueprint id, caller identity, conversation / channel, request και μηνύματα απάντησης) προέρχονται όλα από το invoke_agent span και τους απογόνους του.

Επόμενα βήματα

• Αναφορά χαρακτηριστικού: - Προδιαγραφή, απαιτήσεις και οδηγίες επιλογής τιμής ανά χαρακτηριστικό.
• Αντιμετώπιση προβλημάτων - Επαλήθευση της απορρόφησης, των κοινών παγίδων και των αποκρίσεων σφαλμάτων.