Agent 365 observability attribuut referentie

Dit artikel is de canonieke attribuut-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 verouderde Agent 365 Observability SDK, of rechtstreeks via OTel wordt verzonden – 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, zendt de SDK deze attributen voor je uit. De sectie Picking values geldt alleen als je een standaard moet overschrijven. Als je het directe OTel-pad gebruikt, emitteer je elk attribuut handmatig. Voor hoe je ze samenvoegt tot een verzoek, 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*1: verplicht alleen voor embodied agents (de agent heeft een eigen Entra Agent-ID-gebruikersaccount).
  • M*2: verplicht alleen voor agent-tot-agent gesprekken.
  • M*3: verplicht alleen voor niet-root spans. De wortel invoke_agent heeft geen ouder.
  • O*4: 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 niet zichtbaar CloudAppEvents is. Je zou het nog steeds moeten emitteren (volgens de kolom Vereist) omdat Agent 365 het gebruikt voor inname, ouderoplossing en de agentactiviteitsweergaven van Microsoft Defender. Je kunt het tegenwoordig echter niet direct opvragen via Microsoft Defender advanced hunting.

Note

Agent 365 vult automatisch de statische recordvelden (Id, RecordType, , Workload, UserType) Versionen de gegenereerde verzoek- en 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 deze waarde instelt en het is oneens, wordt het verzoek afgewezen (403).
gen_ai.agent.id All M TargetAgentId (IA); 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 en het administratiecentrum tonen de ruwe GUID in plaats van een naam als ze ontbreken.
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 over als 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- en beheerderscentrafilters worden gebruikt, zijn msteams en outlook. Aangepaste strings (bijvoorbeeld web, <your-product-name>) worden geaccepteerd maar pivoteren niet in ingebouwde kanaalfilters. Gebruik dezelfde waarde op elke overspanning. 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 of dienst die de telemetrie uitzendt. Misschien is het een Resource-attribuut.
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 of gedachtegang.
gen_ai.author.app.id OM O -- Microsoft Entra app-ID van de applicatie die de agent heeft gemaakt of 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, , MCP ServerAPI, , Knowledge Sourcebing_grounding, 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 -- Providernaam (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 reasons.
microsoft.a365.caller.agent.id IA M*2 AgentId (IA) Agent AppId wordt gebeld. Vereist voor agent-tot-agent.
microsoft.a365.caller.agent.name IA M*2 AgentName (IA) Agent wordt weergegeven als naam gebeld.
microsoft.a365.caller.agent.blueprint.id IA M*2 AgentBlueprintId Blauwdruk-appid van de agent bellen. Vereist voor belichaamde A2A.
microsoft.a365.caller.agent.user.id IA M*2 -- Gebruikers-ID van de bellende agent.
microsoft.a365.caller.agent.user.email IA M*2 -- 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*1 TargetAgentUserKey (IA); UserKey (ET, CH) Microsoft Entra object-ID van het eigen gebruikersaccount van de agent. Vereist voor AI-teamgenoten en belichaamde agenten.
microsoft.agent.user.email IA, ET, CH O*1 UserId (ET, CH) UPN van het gebruikersaccount van de agent.
span.SpanId All M OpId OTel SDK zendt dit uit.
span.ParentSpanId All M*3 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*4 ErrorMessage (IA, ET); CopilotEventData.ErrorMessage (CH) De oorzaak van mislukte runs is leeg als ze ontbreken.
span.Status.Code All O*4 ErrorType (IA); CopilotEventData.ErrorType (CH) Foutcategorie leeg als deze ontbreekt.

Note

Agent 365 accepteert verschillende attributen die je uitgeeft, zoals toolargumenten en -resultaten, modelparameters en kanaal-deeplinks. Downstream Microsoft Defender-weergaven gebruiken deze attributen, maar Agent 365 stelt ze nog niet bloot als een CloudAppEvents.RawEventData JSON-sleutel. Stel ze in volgens de kolom Vereist. Ze kunnen in een toekomstige release aan de jachtlading worden toegevoegd.

Important

Op invoke_agent (IA)-records beschrijven de AgentId, AgentName, en velden AgentBlueprintId de aanroepende agent, niet de aangeroepen agent. Agent 365 vult ze uit de microsoft.a365.caller.agent.* attributen. Wanneer een mens je agent aanroept, laat die attributen dan weg, dus AgentId verschijnen als AgentBlueprintId een GUID met nullen (00000000-0000-0000-0000-000000000000) en AgentName is leeg in auditrecords en Microsoft Purview. De waarde van alle nullen wordt verwacht voor door mensen geïnitieerde runs. Om de aangeroepen agent te identificeren, gebruik TargetAgentId, TargetAgentName, en TargetAgentBlueprintID.

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 niet beschikbaar is, stel dan in plaats daarvan de volgende waarden in. Laat geen verplicht veld leeg. Zelfs een GUID met nullen verbergt je run voor sommige klantgerichte ervaringen. Deze regel geldt alleen voor verplichte attributen. Het geldt niet voor de caller-agent-attributen bij door mensen geïnitieerde runs, waar een alles-nul AgentId op invoke_agent records wordt verwacht.

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. Op invoke_agent de records velden de beller een AgentBlueprintId GUID AgentId met nullen. Gebruik TargetAgentId dit om je makelaar te identificeren.
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 je 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 (), (), INTERNAL (2), SERVER (3), (), CLIENT (), (4), (PRODUCER). 5CONSUMER 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 forinvoke_agent / output_messagesen CLIENT for chat / execute_tool redelijk.

Related content

  • Laatst bijgewerkt om