Notitie
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen u aan te melden of de directory te wijzigen.
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen de mappen te wijzigen.
Dit is de canonieke attribut-voor-attribuut specificatie die wordt gebruikt door de ingestiepijplijn van Agent 365. Elke span die door Agent 365 wordt ingevoerd – of deze nu wordt verzonden door de Microsoft OpenTelemetry Distro, de Agent 365 SDK, of verzonden direct OTel – moet eraan voldoen. Elke vermelding vermeldt de bewerkingstypen waarop het attribuut van toepassing is, of het verplicht is, de veldnaam waarin je waarde terechtkomt voor geavanceerde zoekopdrachten (waar die bestaat), en de impact als je het overslaat.
Als je de SDK of de distributie gebruikt, geeft de SDK deze attributen voor je en geldt het gedeelte Picking values alleen als je een standaard moet overschrijven. Als je op het directe OTel-pad zit, emitteer je elk attribuut handmatig; voor hoe je ze tot een verzoek kunt samenvoegen, zie de Integratiegids.
Attribute table
Alle waarden worden verzonden als stringValue - tokentellingen moeten "42" (niet 42); poorten moeten "443" (niet 443).
Operatie legende.IA = invoke_agent, ET, = execute_toolCH = chat, OM, = output_messagesAll = geldt voor elke bewerking.
Required legend.
- M: mandatory.
- M*¹: verplicht alleen voor embodied agents (de agent heeft een eigen Entra Agent-ID gebruikersaccount).
- M*²: verplicht alleen voor agent-tot-agent gesprekken.
-
M*³: verplicht alleen voor niet-root spans. De wortel
invoke_agentheeft geen ouder. - O*⁴: optioneel, alleen betekenisvol wanneer de spanstatus Fout is.
- O: optional.
- N.v.t.: niet uitstralen. Agent 365 vult automatisch in.
De kolom "RawEventData" noemt een JSON-sleutel binnen CloudAppEvents.RawEventData de canonieke advanced-hunting-query in Verifying Ingestion parses. Een lege cel betekent dat het attribuut vandaag not blootgesteld is in CloudAppEvents – je moet het nog steeds emitteren (volgens de kolom Vereist) omdat Agent 365 het gebruikt voor invoer, parent-resolutie en de agent-activiteitsweergaven van Microsoft Defender, maar het is tegenwoordig niet direct opzoekbaar vanuit Microsoft Defender geavanceerde zoeken.
Note
Agent 365 vult automatisch de statische recordvelden (Id, RecordType, Workload, UserType, ) Versionen de gegenereerde verzoek-/respons-ID's in.
| Attribute | Applies to | Required | RawEventData field | Notities / impact als ze ontbreken |
|---|---|---|---|---|
gen_ai.operation.name |
All | M | Operation |
Een vaninvoke_agent, execute_tool, chat, . output_messages Span viel als hij vermist of niet herkend werd. |
microsoft.tenant.id |
All | M | OrganizationId |
De URL {tenantId} is gezaghebbend. Als je dit instelt en het is niet goed, wordt het verzoek afgewezen (403). |
gen_ai.agent.id |
All | M |
TargetAgentId (IA, ook topniveau AgentId); AgentId (ET, CH) |
De app van de bel-app. Moet de URL {agentId} en de geauthenticeerde app overeenkomen. Mismatch levert 403 op. |
gen_ai.agent.name |
All | M |
TargetAgentName (IA); AgentName (ET, CH) |
Defender / admin center tonen de ruwe GUID in plaats van een naam als die ontbreekt. |
microsoft.a365.agent.blueprint.id |
All | M |
TargetAgentBlueprintID (IA); AgentBlueprintId (ET, CH) |
Het blauwdruk is toepasbaar. Voor standaard Entra-apps zonder blauwdruk hergebruik je de appID van de agent. Blueprint-roll-ups in het administratiecentrum gaan anders niet goed. |
gen_ai.agent.description |
All | O | -- | De detailweergave in het administratiecentrum is leeg voor de agent. |
gen_ai.agent.type |
All | O |
PlatformTargetAgentType (IA); PlatformAgentType (ET); CopilotEventData.PlatformAgentType (CH) |
Een label voor je identiteitssysteem, gecombineerd met microsoft.a365.agent.platform.id wanneer de agent geen Entra-registratie heeft. Vrije tekst; Kies een waarde die jouw identiteitssysteem uniek identificeert. Laat het weg wanneer de agent een Entra-registratie heeft—Agent 365 classificeert automatisch. Gebruik niet de Microsoft-gereserveerde waarden (zie Picking values). |
microsoft.a365.agent.platform.id |
All | O |
PlatformTargetAgentId (IA, ook topniveau AlternateId); PlatformAgentId (ET, CH) |
De unieke ID van de agent in je niet-Entra-identiteitssysteem. Free-form text. Samen gezet met gen_ai.agent.type. Laat het over als de agent een entra-registratie heeft. Zie Picking values. |
gen_ai.conversation.id |
All | M |
ConversationId (IA, ET); CopilotEventData.ConversationId / CopilotEventData.ThreadId (CH) |
De primaire join-sleutel voor een run. Zonder die verschijnt de run niet in de Defender-agentactiviteitsweergaven of het beheercentrum. |
microsoft.channel.name |
All | M |
ChannelName (IA, ET) |
Het oppervlak waarin de agent zich bevindt. Gebruik een korte kleine letter; De canonieke waarden die tegenwoordig door Defender / Admin Center-filters worden gebruikt zijn msteams en outlook. Aangepaste strings (bijvoorbeeld web, <your-product-name>) worden geaccepteerd maar draaien niet in ingebouwde kanaalfilters. Dezelfde waarde op elke span. Zie Picking values. |
microsoft.channel.link |
All | O | -- | Channel deep-link. |
microsoft.session.id |
All | O | SessionIdentity |
Sessiepivots zijn leeg als ze ontbreken. |
microsoft.session.description |
All | O | -- | Session description. |
microsoft.conversation.item.link |
All | O | -- | Diepe link naar het bericht. |
correlation.id |
All | O | -- | Cross-service tracing. Niet opgedoken bij gevorderde jacht vandaag. |
operation.source |
All | O |
InvokeSource (IA) |
Identificatie voor de SDK / dienst die de telemetrie uitzendt. Kan een Resource-attribuut zijn. |
client.address |
IA, ET, CH | M |
ClientIP (IA, ET) |
Caller IP. IP-gebaseerd onderzoek geblokkeerd als het leeg is. |
server.address |
IA, ET, CH | M |
ServerAddress (IA, ET) |
Endpoint waar je dienst belt. |
server.port |
IA, ET, CH | M |
ServerPort (IA) |
String-gecodeerd (bijvoorbeeld "443"). |
user.id |
IA | M | UserKey |
Microsoft Entra object-ID van de menselijke beller. "Wie heeft deze agent geleid" is leeg zonder. |
user.email |
IA | O | UserId |
UPN van de beller. |
user.name |
IA | O | -- | Toon de naam van de beller. |
gen_ai.input.messages |
IA, CH | M | -- | Request payload (JSON-string). Gevangen voor analyse stroomafwaarts, maar nog niet opgedoken in geavanceerde jacht. |
gen_ai.output.messages |
IA, CH, OM | M | -- | Response payload (JSON-string). |
gen_ai.execution.type |
IA | O | -- | Eén van HumanToAgent, Agent2Agent, . EventToAgent |
microsoft.a365.agent.thought.process |
IA, CH | O | -- | Vrije tekst redeneren / gedachtegang. |
gen_ai.author.app.id |
OM | O | -- | Microsoft Entra app-ID van de applicatie die de agent heeft gemaakt/gemaakt. |
gen_ai.tool.name |
ET | M | ToolName |
Tool name. Defender-toolgebruiksweergaven zijn leeg als ze ontbreken. |
gen_ai.tool.type |
ET | M | ToolType |
Eén van function, Power Platform Connector, , APIMCP Server, , bing_groundingKnowledge Source, code_interpreter, , file_search. |
gen_ai.tool.call.id |
ET | M | ToolId |
Identificatie voor deze toolcall. |
gen_ai.tool.call.arguments |
ET | M | -- | Toolargumenten (JSON-string). Gevangen genomen maar nog niet opgedoken tijdens gevorderde jacht. |
gen_ai.tool.call.result |
ET | M | -- | Toolresultaat (JSON-string). |
gen_ai.tool.description |
ET | O | ToolDescription |
Tool description. |
gen_ai.tool.server.name |
ET | O | -- | Toolserver-hostnaam. Stel dit attribuut in voor MCP-tools. |
gen_ai.request.model |
CH | M | -- | Modelnaam (bijvoorbeeld gpt-4o). Gevangen genomen maar nog niet opgedoken tijdens gevorderde jacht. |
gen_ai.provider.name |
CH | M | -- | Provider naam (bijvoorbeeld openai). |
gen_ai.usage.input_tokens |
CH | O | -- | Invoertoken-aantal, string-encoded. |
gen_ai.usage.output_tokens |
CH | O | -- | Output token-aantal, string-gecodeerd. |
gen_ai.response.finish_reasons |
CH | O | -- | Finish reason(s). |
microsoft.a365.caller.agent.id |
IA | M*² | -- | Agent AppId wordt gebeld. Vereist voor agent-tot-agent. |
microsoft.a365.caller.agent.name |
IA | M*² | -- | Agent wordt weergegeven als naam gebeld. |
microsoft.a365.caller.agent.blueprint.id |
IA | M*² | AgentBlueprintId |
Blauwdruk-appid van de agent bellen. Vereist voor belichaamde A2A. |
microsoft.a365.caller.agent.user.id |
IA | M*² | -- | Gebruikers-ID van de bellende agent. |
microsoft.a365.caller.agent.user.email |
IA | M*² | -- | Agent UPN wordt gebeld. |
microsoft.a365.caller.agent.platform.id |
IA | N/A | -- | Gereserveerd voor alternatieve ID's zonder Entra. |
gen_ai.caller.agent.type |
IA | N/A | -- | Agent 365 classificeert automatisch. |
microsoft.agent.user.id |
IA, ET, CH | M*¹ |
TargetAgentUserKey (IA); UserKey (ET, CH) |
Microsoft Entra object-ID van het eigen gebruikersaccount van de agent. Vereist voor AI-teamgenoten / belichaamde agenten. |
microsoft.agent.user.email |
IA, ET, CH | O*¹ |
UserId (ET, CH) |
UPN van het gebruikersaccount van de agent. |
span.SpanId |
All | M | OpId |
OTel SDK zendt dit uit. |
span.ParentSpanId |
All | M*³ | ParentId |
Vereist alleen voor niet-root spans; De wortel invoke_agent heeft er geen. |
span.StartTimeUnixNano |
All | M | Top-level TimeGenerated (ook CreationTime in RawEventData) |
Unix-epochnanos als een string. |
span.EndTimeUnixNano |
All | M |
CompletionTime (IA, ET); CopilotEventData.CompletionTime (CH) |
De duur kan niet worden berekend als het ontbreekt. |
span.Status.Message |
All | O*⁴ |
ErrorMessage (IA, ET); CopilotEventData.ErrorMessage (CH) |
De oorzaak van mislukte runs is leeg als ze ontbreken. |
span.Status.Code |
All | O*⁴ |
ErrorType (IA); CopilotEventData.ErrorType (CH) |
Foutcategorie leeg als deze ontbreekt. |
Note
Verschillende attributen die je uitgeeft (zoals toolargumenten/resultaten, modelparameters en kanaal-deeplinks) worden geaccepteerd door Agent 365 en gebruikt door downstream Microsoft Defender views, maar zijn nog niet blootgesteld als een CloudAppEvents.RawEventData JSON-sleutel. Stel ze sowieso in op de kolom Vereist, ze kunnen in een toekomstige release aan de jachtlading worden toegevoegd.
Waarden kiezen als je geen natuurlijke hebt
Sommige vereiste attributen beschrijven concepten die mogelijk niet in de architectuur van je agent bestaan. Als de natuurlijke waarde er niet is, is dit wat je in plaats daarvan kunt instellen. Laat geen verplicht veld leeg – zelfs een GUID met nullen zal je run verbergen voor sommige klantgerichte ervaringen.
| Vraag / scenario | Field(s) | Wat te instellen |
|---|---|---|
| Mijn agent is een standaard entra-appregistratie (niet gebouwd op een Entra Agent-ID blueprint). | gen_ai.agent.id |
De app van de Entra-app. |
| ↑ Zelfde scenario | microsoft.a365.agent.blueprint.id |
Hergebruik dezelfde waarde als gen_ai.agent.id (de appID van de agent). Het schema vereist een niet-lege waarde; Het hergebruiken van de agent appID is de veilige standaard als er geen blauwdruk is. |
| Mijn agent is gebouwd uit een Entra Agent-ID blueprint - één of meerdere agentidentiteiten die uit dezelfde blueprint zijn gemunt. | gen_ai.agent.id |
De appID van de agent identity (de instance appid, niet die van de blueprint). |
| ↑ Zelfde scenario | microsoft.a365.agent.blueprint.id |
Het blauwdruk is toepasbaar. Alle exemplaren die van hetzelfde blauwdruk zijn geslagen, delen deze waarde. |
| De beller is een menselijke gebruiker, geen andere agent. | Alle microsoft.a365.caller.agent.* en attributen gen_ai.caller.agent.* |
Omit. Ze zijn alleen verplicht in agent-tot-agent situaties. |
| In agent-tot-agent: de bellende agent is een standaard Entra-app (zonder blauwdruk). | microsoft.a365.caller.agent.blueprint.id |
Hergebruik de appID van de bellende agent. |
| Mijn agent is geen AI-teamgenoot - hij heeft geen eigen gebruikersaccount in de tenant. | Alle microsoft.agent.user.* attributen |
Omit. Ze zijn alleen verplicht als de agent een eigen Entra Agent-ID-gebruikersaccount heeft. |
| Mijn agent heeft geen idee van een sessie behalve één run. | microsoft.session.id |
Optioneel - laat het weg. Als je wilt dat elke run een eigen sessie is, zet dan een per-run GUID. |
| Mijn agent heeft geen concept van een gesprek (one-shot, stateless). | gen_ai.conversation.id |
Genereer per run een nieuwe GUID. Het veld is verplicht; het overslaan verwijdert de run uit de Defender-agent-activiteitsweergaven en het Microsoft 365-beheercentrum. |
| De beller heeft geen IP (bijvoorbeeld een autonome geplande trigger). | client.address |
Gebruik een stabiele tijdelijke plek die je beheert (bijvoorbeeld, "0.0.0.0"). Het veld is verplicht; een lege waarde verwijdert de run van IP-gebaseerde onderzoekspivots. |
| De agent loopt in proces; Er wordt geen aparte "server" aangeroepen. | server.address / server.port |
Gebruik de hostnaam van de machine die de agent draaide (bijvoorbeeld myagent.example.com) en de poort waarop je endpoint luistert. Verplicht zelfs als er geen aparte downstream-dienst is. |
Mijn chat span gebruikt geen modeltoken. |
gen_ai.usage.input_tokens / gen_ai.usage.output_tokens |
Optioneel - laat het weg. Als je een schatting hebt, stuur ze dan als stringValue. |
| Mijn span heeft geen fouten om te melden. |
span.Status.Message, span.Status.Code |
Stel de OTel-status in op OK (numerieke code 1) en laat het bericht weg. De pipeline raadpleegt deze velden alleen wanneer status is Error. |
| Mijn agent gebruikt een niet-Entra-identiteitssysteem (de agent heeft geen Entra-registratie). |
microsoft.a365.agent.platform.id en gen_ai.agent.type |
Zet beide op elke overspanning.
platform.id is de unieke ID van de agent in jouw identiteitssysteem; agent.type is een kort label dat aangeeft welk identiteitssysteem dat is. Beide zijn vrije tekst - kies wat logisch is voor jouw systeem.
Gebruik niet de Microsoft-gereserveerde typewaarden: CustomBuiltAgentsUsingSDK, CopilotStudio, Foundry, DeclarativeAgent, Custom (deze waarden zijn gereserveerd voor interne Microsoft oppervlakken). De bel-app waarmee je je authenticeert heeft nog steeds een entra-registratie nodig om deze routes te gebruiken – het alternatieve-id paar beschrijft een doelagent , niet de beller. |
Welke waarde moet ik erin hechten microsoft.channel.name? |
microsoft.channel.name |
Het oppervlak waarin de agent zich bevindt. Defender- en admincenterfilters zijn gebaseerd op de letterlijke string, dus gebruik een korte, stabiele, kleine letter token. Tegenwoordig zijn msteams de canonieke waarden en outlook; gebruikmaken ook veelvoorkomende klantgerichte oppervlakken web, office, , sharepointof <your-product-name>. Kies één waarde en houd je daaraan – gereedschap kan msteams en Microsoft Teams niet als hetzelfde kanaal afstemmen. |
Moet ik het instellen gen_ai.agent.type? |
gen_ai.agent.type |
Alleen als je ook een instelling microsoft.a365.agent.platform.id hebt (bijvoorbeeld als je agent geen entra-registratie heeft). Het tweetal vertelt Agent 365 uit welk identiteitssysteem de agent komt. Kies een kort label dat je identiteitssysteem uniek identificeert.
Gebruik geen CustomBuiltAgentsUsingSDK, CopilotStudio, Foundry, DeclarativeAgent of Custom - die waarden zijn gereserveerd voor intern Microsoft gebruik. Voor Entra-geregistreerde agenten, laat het veld weg; Agent 365 vult het op. |
Welke OTLP kind moet ik op mijn spans zetten? |
span.kind |
Gebruik de gehele enumwaarde, niet de proto-enumstring - 1 (), (), 2 (SERVER), 3 (CLIENT), (), 4 (), (PRODUCER), (CONSUMER). 5INTERNAL Agent 365 accepteert al deze en leidt geen klantzichtbaar gedrag af van kind, dus 1 (INTERNAL) is een veilige standaard voor elke span. Als je wilt dat het type de roepvorm weerspiegelt, INTERNAL is for / output_messagesinvoke_agenten CLIENT for chat / execute_tool redelijk. |