Agent 365 Observability-Attributreferenz

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_agent hat 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.

Related content

  • Last updated on