Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Dies ist die kanonische Attribut-für-Attribut-Spezifikation, die von Agent 365s Ingestion-Pipeline verwendet wird. Jede von Agent 365 aufgenommene Spann – egal ob sie vom Microsoft OpenTelemetry Distro, dem Agent 365 SDK oder gesendet über direct OTel gesendet wird – muss diesem entsprechen. Jeder Eintrag listet die Operationstypen auf, auf die das Attribut angewendet wird, ob es verpflichtend ist, den Feldnamen, in dem dein Wert für fortgeschrittene Jagd-Abfragen landet (sofern es eine gibt), und welche Auswirkungen es hat, wenn man ihn überspringt.
Wenn du das SDK oder die Distribution verwendest, gibt das SDK diese Attribute für dich aus, und der Abschnitt "Picking Values" gilt nur, wenn du eine Standardfunktion überschreiben musst. Wenn du auf dem direkten OTel-Pfad bist, emittierst du jedes Attribut manuell; Wie man sie zu einer Anfrage zusammensetzt, siehe den Integrationsleitfaden.
Attribute table
Alle Werte werden als folgt stringValuegesendet - Die Tokenzählungen müssen "42" (nicht 42sein); Ports müssen (nicht 443) sein "443" .
Operation Legende.IA = invoke_agent, ET, = execute_toolCH = chat, OM, = output_messagesAll = gilt für jede Operation.
Required legend.
- M: mandatory.
- M*¹: Pflichtpflicht nur für verkörperte Agenten (der Agent hat ein eigenes Entra-Agent-ID Benutzerkonto).
- M*²: Pflicht nur für Agent-zu-Agent-Anrufe.
-
M*³: Pflicht nur für Nicht-Wurzelspans. Die Wurzel
invoke_agenthat keinen Elternteil. - O*⁴: optional, nur sinnvoll, wenn der Spannstatus Fehler ist.
- O: optional.
- N/A: Nicht emittieren. Agent 365 füllt automatisch ein.
Die Spalte "RawEventData" nennt einen JSON-Schlüssel innerhalb CloudAppEvents.RawEventData der kanonischen fortgeschrittenen Jagd-Abfrage in Verifying Ingestion Parses. Eine leere Zelle bedeutet, dass das Attribut nicht heute in CloudAppEvents offengelegt ist – du solltest es trotzdem aussenden (laut Spalte erforderlich), weil Agent 365 es für Aufnahme, Parent-Auflösung und die Agentenaktivitätsansichten von Microsoft Defender verwendet, aber es ist heute nicht direkt abfragbar von Microsoft Defender fortgeschrittenen Suche.
Note
Agent 365 füllt automatisch die statischen Datensatzfelder (Id, RecordType, Workload, UserType, ) Versionund die generierten Anfrage-/Antwort-IDs aus.
| Attribute | Applies to | Required | RawEventData field | Notizen / Auswirkung, falls sie fehlen |
|---|---|---|---|---|
gen_ai.operation.name |
All | M | Operation |
Einer von invoke_agent, execute_tool, chat, output_messages. Span fiel ab, wenn er fehlte oder nicht erkannt wurde. |
microsoft.tenant.id |
All | M | OrganizationId |
Die URL {tenantId} ist autoritativ. Wenn du das einstellst und es widerspricht, wird der Antrag abgelehnt (403). |
gen_ai.agent.id |
All | M |
TargetAgentId (IA, ebenfalls auf höchster Ebene AgentId); AgentId (ET, CH) |
Die App der Anruf-App. Muss URL {agentId} und authentifizierte App übereinstimmen. Mismatch bringt 403 zurück. |
gen_ai.agent.name |
All | M |
TargetAgentName (IA); AgentName (ET, CH) |
Defender / Admin Center zeigt die rohe GUID anstelle eines Namens, falls sie fehlen. |
microsoft.a365.agent.blueprint.id |
All | M |
TargetAgentBlueprintID (IA); AgentBlueprintId (ET, CH) |
Der Bauplan wird angewendet. Für Standard-Entra-Apps ohne Blueprint verwenden Sie die AppID des Agenten wieder. Blueprint-Rollups im Verwaltungszentrum brechen sonst nicht. |
gen_ai.agent.description |
All | O | -- | Die Detailansicht im Verwaltungszentrum ist für den Agenten leer. |
gen_ai.agent.type |
All | O |
PlatformTargetAgentType (IA); PlatformAgentType (ET); CopilotEventData.PlatformAgentType (CH) |
Ein Etikett für dein Identitätssystem, kombiniert mit microsoft.a365.agent.platform.id dem Fall, dass der Agent keine Entra-Registrierung hat. Freier Text; Wählen Sie einen Wert, der Ihr Identitätssystem eindeutig identifiziert. Weglassen, wenn der Agent eine Entra-Registrierung hat – Agent 365 klassifiziert automatisch. Verwenden Sie nicht die Microsoft-reservierten Werte (siehe Picking values). |
microsoft.a365.agent.platform.id |
All | O |
PlatformTargetAgentId (IA, ebenfalls auf höchster Ebene AlternateId); PlatformAgentId (ET, CH) |
Die eindeutige ID des Agenten in deinem nicht-entra-Identitätssystem. Free-form text. Setze zusammen mit gen_ai.agent.type. Lassen Sie es weg, wenn der Agent eine Entra-Registrierung hat. Siehe Picking-Werte. |
gen_ai.conversation.id |
All | M |
ConversationId (IA, ET); CopilotEventData.ConversationId / CopilotEventData.ThreadId (CH) |
Die primäre Join-Taste für einen Durchlauf. Ohne sie erscheint der Lauf nicht in den Agenten-Aktivitätsansichten oder im Admin-Center von Defender. |
microsoft.channel.name |
All | M |
ChannelName (IA, ET) |
Die Oberfläche, in der der Agent läuft. Verwenden Sie einen kurzen Kleinbuchstaben-Token; Die kanonischen Werte, die heute von Defender / Verwaltungszentrum-Filtern verwendet werden, sind msteams und outlook. Benutzerdefinierte Zeichenketten (zum Beispiel web, <your-product-name>) werden akzeptiert, pivotieren aber nicht in eingebauten Kanalfiltern. Gleicher Wert auf jeder Spannweite. Siehe Picking-Werte. |
microsoft.channel.link |
All | O | -- | Channel deep-link. |
microsoft.session.id |
All | O | SessionIdentity |
Sitzungspivots sind leer, wenn sie fehlen. |
microsoft.session.description |
All | O | -- | Session description. |
microsoft.conversation.item.link |
All | O | -- | Tiefer Link zur Botschaft. |
correlation.id |
All | O | -- | Cross-service tracing. Heute ist es bei der fortgeschrittenen Jagd nicht aufgetaucht. |
operation.source |
All | O |
InvokeSource (IA) |
Identifikator für das SDK / den Dienst, der die Telemetrie aussendet. Könnte ein Ressourcenattribut sein. |
client.address |
IA, ET, CH | M |
ClientIP (IA, ET) |
Caller IP. IP-basierte Untersuchung blockiert, falls sie leer ist. |
server.address |
IA, ET, CH | M |
ServerAddress (IA, ET) |
Endpunkt, dein Dienst ruft an. |
server.port |
IA, ET, CH | M |
ServerPort (IA) |
String-codiert (zum Beispiel "443"). |
user.id |
IA | M | UserKey |
Microsoft Entra-Objekt-ID des menschlichen Anrufers. "Wer hat diesen Agenten geleitet?" ist ohne das Papier leer. |
user.email |
IA | O | UserId |
UPN des Anrufers. |
user.name |
IA | O | -- | Anzeige-Name des Anrufers. |
gen_ai.input.messages |
IA, CH | M | -- | Payload (JSON-String) anfordern. Gefangen für die Analysen flussabwärts, aber noch nicht bei fortgeschrittener Jagd aufgetaucht. |
gen_ai.output.messages |
IA, CH, OM | M | -- | Response Payload (JSON-String). |
gen_ai.execution.type |
IA | O | -- | Einer von HumanToAgent, Agent2Agent, EventToAgent. |
microsoft.a365.agent.thought.process |
IA, CH | O | -- | Freitext-Argumentation / Gedankenkette. |
gen_ai.author.app.id |
OM | O | -- | Microsoft Entra-App-ID der Anwendung, die den Agenten erstellt oder erstellt hat. |
gen_ai.tool.name |
ET | M | ToolName |
Tool name. Defender-Tool-Nutzungsansichten sind leer, wenn sie fehlen. |
gen_ai.tool.type |
ET | M | ToolType |
Einer von , , , , , Knowledge Source, bing_grounding, code_interpreter, . file_searchAPIMCP ServerPower Platform Connectorfunction |
gen_ai.tool.call.id |
ET | M | ToolId |
Identifikator für diesen Werkzeugaufruf. |
gen_ai.tool.call.arguments |
ET | M | -- | Werkzeugargumente (JSON-String). Gefangen, aber noch nicht bei fortgeschrittener Jagd aufgetaucht. |
gen_ai.tool.call.result |
ET | M | -- | Werkzeugergebnis (JSON-String). |
gen_ai.tool.description |
ET | O | ToolDescription |
Tool description. |
gen_ai.tool.server.name |
ET | O | -- | Tool-Server-Hostname. Setze dieses Attribut für MCP-Werkzeuge. |
gen_ai.request.model |
CH | M | -- | Modellname (zum Beispiel, gpt-4o). Gefangen, aber noch nicht bei fortgeschrittener Jagd aufgetaucht. |
gen_ai.provider.name |
CH | M | -- | Anbietername (zum Beispiel, openai). |
gen_ai.usage.input_tokens |
CH | O | -- | Eingabe-Token-Anzahl, string-codiert. |
gen_ai.usage.output_tokens |
CH | O | -- | Ausgabe-Token-Zahl, string-codiert. |
gen_ai.response.finish_reasons |
CH | O | -- | Finish reason(s). |
microsoft.a365.caller.agent.id |
IA | M*² | -- | Rufe Agent AppId an. Erforderlich für Agenten-zu-Agenten. |
microsoft.a365.caller.agent.name |
IA | M*² | -- | Rufe den Agenten-Anzeigenamen an. |
microsoft.a365.caller.agent.blueprint.id |
IA | M*² | AgentBlueprintId |
Anrufende Bauplan-AppId des Agenten. Erforderlich für verkörpertes A2A. |
microsoft.a365.caller.agent.user.id |
IA | M*² | -- | Benutzer-ID des Anrufers. |
microsoft.a365.caller.agent.user.email |
IA | M*² | -- | Rufe Agent UPN an. |
microsoft.a365.caller.agent.platform.id |
IA | N/A | -- | Reserviert für alternative IDs ohne Entra. |
gen_ai.caller.agent.type |
IA | N/A | -- | Agent 365 klassifiziert automatisch. |
microsoft.agent.user.id |
IA, ET, CH | M*¹ |
TargetAgentUserKey (IA); UserKey (ET, CH) |
Microsoft Entra-Objekt-ID des eigenen Benutzerkontos des Agenten. Erforderlich für KI-Teammitglieder / verkörperte Agenten. |
microsoft.agent.user.email |
IA, ET, CH | O*¹ |
UserId (ET, CH) |
UPN des Benutzerkontos des Agenten. |
span.SpanId |
All | M | OpId |
Das OTel SDK erzeugt dies. |
span.ParentSpanId |
All | M*³ | ParentId |
Erforderlich nur für Nicht-Wurzelspans; Die Wurzel invoke_agent hat keine. |
span.StartTimeUnixNano |
All | M | Top-Level TimeGenerated (ebenfalls CreationTime in RawEventData) |
Unix-Epoch-Nanos als Saite. |
span.EndTimeUnixNano |
All | M |
CompletionTime (IA, ET); CopilotEventData.CompletionTime (CH) |
Die Dauer kann nicht berechnet werden, wenn sie fehlt. |
span.Status.Message |
All | O*⁴ |
ErrorMessage (IA, ET); CopilotEventData.ErrorMessage (CH) |
Die Ursache für fehlgeschlagene Durchläufe ist leer, wenn sie fehlen. |
span.Status.Code |
All | O*⁴ |
ErrorType (IA); CopilotEventData.ErrorType (CH) |
Fehlerkategorie ist leer, falls fehlt. |
Note
Mehrere von dir ausgegebene Attribute (wie Werkzeugargumente/-ergebnisse, Modellparameter und Kanal-Deeplinks) werden von Agent 365 akzeptiert und von nachgeschalteten Microsoft Defender Views verwendet, sind aber noch nicht als CloudAppEvents.RawEventData JSON-Schlüssel verfügbar. Setze sie trotzdem nach der Kolonne "Erforderlich" – sie könnten in einer zukünftigen Version zur Jagdnutzlast hinzugefügt werden.
Werte auswählen, wenn du keinen natürlichen hast
Einige erforderliche Attribute beschreiben Konzepte, die in der Architektur Ihres Agenten möglicherweise nicht existieren. Wenn der natürliche Wert nicht vorhanden ist, ist Folgendes, was man stattdessen setzen sollte. Lassen Sie kein obligatorisches Feld leer – selbst ein GUID mit nur Nullen verbirgt Ihren Lauf vor einigen kundenorientierten Erlebnissen.
| Frage / Szenario | Field(s) | Was zu setzen ist |
|---|---|---|
| Mein Agent ist ein Standard Entra App Registration (nicht auf einem Entra-Agent-ID Blueprint aufgebaut). | gen_ai.agent.id |
Die Anwendung der Entra-App. |
| ↑ Gleiches Szenario | microsoft.a365.agent.blueprint.id |
Verwenden Sie denselben Wert wie gen_ai.agent.id (die AppId des Agenten) wieder. Das Schema erfordert einen nichtleeren Wert; Die Wiederverwendung der Agent-AppID ist die sichere Standardeinstellung, wenn kein Blueprint vorhanden ist. |
| Mein Agent ist aufgebaut aus einem Entra-Agent-ID Blueprint – eine oder mehrere Agentenidentitäten, die aus demselben Blueprint stammen. | gen_ai.agent.id |
Die AppID der Agentenidentität (die Instanz-AppID , nicht die des Blueprints). |
| ↑ Gleiches Szenario | microsoft.a365.agent.blueprint.id |
Der Bauplan wird angewendet. Alle Instanzen, die aus demselben Blueprint geprägt werden, teilen diesen Wert. |
| Der Anrufer ist ein menschlicher Nutzer, kein anderer Agent. | Alle microsoft.a365.caller.agent.* und gen_ai.caller.agent.* Attribute |
Omit. Sie sind nur in Agenten-zu-Agenten-Szenarien verpflichtend. |
| Im Agent-zu-Agenten-Modus ist der anrufende Agent eine Standard-Entra-App (ohne Bauplan). | microsoft.a365.caller.agent.blueprint.id |
Verwenden Sie die AppID des anrufenden Agenten wieder. |
| Mein Agent ist kein KI-Teammitglied – er hat kein eigenes Benutzerkonto im Tenant. | Alle microsoft.agent.user.* Attribute |
Omit. Sie sind nur dann verpflichtend, wenn der Agent ein eigenes Entra-Agent-ID-Benutzerkonto hat. |
| Mein Agent hat kein Konzept von einer Sitzung über einen einzelnen Durchlauf hinaus. | microsoft.session.id |
Optional – lass es weg. Wenn du möchtest, dass jeder Durchlauf eine eigene Sitzung ist, setze auf einen GUID pro Durchlauf. |
| Mein Agent hat kein Konzept von einem Gespräch (One-Shot, staatenlos). | gen_ai.conversation.id |
Generiere pro Durchlauf einen frischen GUID. Das Feld ist verpflichtend; das Überspringen entfernt den Run aus den Agenten-Aktivitätsansichten von Defender und dem Microsoft 365 Admin Center. |
| Der Anrufer hat keine IP (zum Beispiel einen autonomen geplanten Auslöser). | client.address |
Verwenden Sie einen stabilen Platzhalter, den Sie kontrollieren (zum Beispiel, "0.0.0.0"). Das Feld ist verpflichtend; ein leerer Wert entfernt den Run aus IP-basierten Untersuchungspivots. |
| Der Agent läuft im Verfahren; Es wird kein separater "Server" aufgerufen. | server.address / server.port |
Verwenden Sie den Hostnamen der Maschine, die den Agenten ausgeführt hat (zum Beispiel myagent.example.com), und den Port, auf dem Ihr Endpunkt hört. Erforderlich, selbst wenn es keinen separaten Downstream-Service gibt. |
Mein chat Span verwendet keine Modell-Token-Nutzung. |
gen_ai.usage.input_tokens / gen_ai.usage.output_tokens |
Optional – lass es weg. Wenn Sie ungefähre Zahlen haben, senden Sie sie als stringValue. |
| Mein Span hat keinen Fehler zu melden. |
span.Status.Message, span.Status.Code |
Setzen Sie den OTel-Status auf OK (numerischer Code 1) und lassen Sie die Nachricht weg. Die Pipeline konsultiert diese Felder nur, wenn der Status lautet Error. |
| Mein Mitarbeiter verwendet ein Identitätssystem ohne Entra (der Agent hat keine Eintra-Registrierung). |
microsoft.a365.agent.platform.id und gen_ai.agent.type |
Setze beide auf jede Spannweite.
platform.id ist die eindeutige ID des Agenten in deinem Identitätssystem; agent.type ist ein kurzes Etikett, das angibt, welches Identitätssystem das ist. Beide sind freie Texte – wähle das, was für dein System sinnvoll ist.
Verwenden Sie nicht die Microsoft-reservierten Typwerte: CustomBuiltAgentsUsingSDK, CopilotStudio, Foundry, DeclarativeAgent, Custom (diese Werte sind für interne Microsoft Flächen reserviert). Die Anruf-App, mit der du dich authentifizierst, benötigt weiterhin eine Entra-Registrierung, um diese Routen zu nutzen – das Alternativ-ID-Paar beschreibt einen Zielagenten , nicht den Anrufer. |
Welchen Wert sollte ich beimessen microsoft.channel.name? |
microsoft.channel.name |
Die Oberfläche, in der der Agent läuft. Defender- und Admin-Center-Filter orientieren sich an der Literal-String, also verwenden Sie einen kurzen, stabilen Kleinbuchstaben-Token. Heute sind msteams die kanonischen Werte und outlook; häufige kundenorientierte Oberflächen verwenden webebenfalls , office, , sharepointoder <your-product-name>. Wähle einen Wert und bleib dabei – Werkzeuge können msteams und Microsoft Teams nicht als denselben Kanal abstimmen. |
Sollte ich einstellen gen_ai.agent.type? |
gen_ai.agent.type |
Nur wenn du auch Setting microsoft.a365.agent.platform.id (zum Beispiel, wenn dein Agent keine Entra-Registrierung hat). Das Paar teilt Agent 365 mit, aus welchem Identitätssystem der Agent stammt. Wählen Sie ein kurzes Etikett, das Ihr Identitätssystem eindeutig identifiziert.
Verwenden Sie nicht CustomBuiltAgentsUsingSDK, CopilotStudio, Foundry, DeclarativeAgent oder Custom – diese Werte sind für interne Microsoft verwendet. Für Entra-registrierte Vertreter sollten Sie das Feld weglassen; Agent 365 füllt es wieder auf. |
Welches OTLP kind sollte ich für meine Spannen festlegen? |
span.kind |
Verwenden Sie den ganzzahligen Enumwert, nicht die Proto-Enum-Zeichenkette – 1 (), (SERVER), 23 (CLIENT), 4 (PRODUCER), (), 5CONSUMERINTERNAL(). Agent 365 akzeptiert all diese und leitet kein kundensichtbares Verhalten aus kindab, daher 1 ist (INTERNAL) für jede Spanne ein sicherer Standard. Wenn Sie möchten, dass die Art die Rufform widerspiegelt, INTERNAL ist for / output_messagesinvoke_agentund CLIENT for chat / execute_tool sinnvoll. |