Agent 365 observerbarhedsattributreference

Dette er den kanoniske attribut-for-attribut-specifikation, der bruges af Agent 365's indtagelsespipeline. Hver span, der indtages af Agent 365 – uanset om den sendes af Microsoft OpenTelemetry Distro, Agent 365 SDK eller sendt over direct OTel – skal overholde den. Hver post viser de operation-typer, attributten gælder for, om det er obligatorisk, feltnavnet din værdi lander i for avancerede jagtforespørgsler (hvor en sådan findes), og hvilken effekt det har, hvis du springer den over.

Hvis du bruger SDK'en eller distributionen, udleverer SDK'en disse attributter for dig, og sektionen Picking values gælder kun, når du skal tilsidesætte en standard. Hvis du er på den direkte OTel-sti, udsender du alle attributter manuelt; for hvordan du samler dem til en anmodning, se integrationsguiden.

Attribute table

Alle værdier sendes som stringValue - token-tællinger skal være "42" (ikke 42); porte skal være "443" (ikke 443).

Operation legend.IA = invoke_agent, ET, = execute_toolCH = chat, OM, = output_messagesAlle = gælder for enhver operation.

Required legend.

  • M: mandatory.
  • M*¹: obligatorisk kun for embodied agents (agenten har sin egen Entra-agent-id brugerkonto).
  • M*²: kun obligatorisk for agent-til-agent opkald.
  • M*³: obligatorisk kun for ikke-root spans. Roden invoke_agent har ingen forælder.
  • O*⁴: valgfrit, kun meningsfuldt når span-status er Fejl.
  • O: optional.
  • Ikke tilsvaret: udsend ikke. Agent 365 udfylder automatisk.

Kolonnen "RawEventData" nævner en JSON-nøgle inden for CloudAppEvents.RawEventData den kanoniske advanced-hunting-forespørgsel i Verifying Ingestion parses. En tom celle betyder, at attributten er not eksponeret i CloudAppEvents i dag – du bør stadig udsende den (ifølge kolonnen Required), fordi Agent 365 bruger den til indlæsning, forældreopløsning og Microsoft Defender's agent-aktivitetsvisninger, men den kan ikke forespørges direkte fra Microsoft Defender avancerede jagt i dag.

Note

Agent 365 udfylder automatisk de statiske postfelter (Id, RecordType, Workload, , UserType) Versionog de genererede anmodnings-/svar-ID'er.

Attribute Applies to Required RawEventData field Noter / effekt hvis den mangler
gen_ai.operation.name All M Operation En af invoke_agent, execute_tool, chat, . output_messages Span faldt, hvis den manglede eller ikke blev genkendt.
microsoft.tenant.id All M OrganizationId URL {tenantId} er autoritativ. Hvis du sætter dette, og det er uenighed, afvises anmodningen (403).
gen_ai.agent.id All M TargetAgentId (IA, også topniveau AgentId); AgentId (ET, CH) Opkaldsappens appId. Skal matche URL {agentId} og den autentificerede app. Mismatch giver 403.
gen_ai.agent.name All M TargetAgentName (IA); AgentName (ET, CH) Defender / administrationscenter viser den rå GUID i stedet for et navn, hvis den mangler.
microsoft.a365.agent.blueprint.id All M TargetAgentBlueprintID (IA); AgentBlueprintId (ET, CH) Tegningen er relevant. For standard entra-apps uden blueprint, genbrug agentens appId. Blueprint-roll-ups i administrationscentret bryder ellers.
gen_ai.agent.description All O -- Detaljevisningen i administrationscentret er tom for agenten.
gen_ai.agent.type All O PlatformTargetAgentType (IA); PlatformAgentType (ET); CopilotEventData.PlatformAgentType (CH) En etiket til dit identitetssystem, kombineret med microsoft.a365.agent.platform.id når agenten ikke har en entra-registrering. Friformtekst; Vælg en værdi, der unikt identificerer dit identitetssystem. Udelad, når agenten har en entra-registrering – Agent 365 klassificerer automatisk. Brug ikke de Microsoft-reserverede værdier (se Picking values).
microsoft.a365.agent.platform.id All O PlatformTargetAgentId (IA, også topniveau AlternateId); PlatformAgentId (ET, CH) Agentens unikke id i dit ikke-Entra-identitetssystem. Free-form text. Sæt sammen med gen_ai.agent.type. Udelad, når agenten har en Entra-registrering. Se Plukværdier.
gen_ai.conversation.id All M ConversationId (IA, ET); CopilotEventData.ConversationId / CopilotEventData.ThreadId (CH) Den primære join-nøgle til et gennemspil. Uden den vises run'et ikke i Defender-agentaktivitetsvisningerne eller administrationscentret.
microsoft.channel.name All M ChannelName (IA, ET) Overfladen, hvor agenten løber. Brug en kort lille token; De kanoniske værdier, der bruges af Defender / administrationscenterfiltre i dag, er msteams og outlook. Brugerdefinerede strenge (for eksempel web, <your-product-name>) accepteres, men vil ikke pivotere i indbyggede kanalfiltre. Samme værdi på alle spænd. Se Plukværdier.
microsoft.channel.link All O -- Channel deep-link.
microsoft.session.id All O SessionIdentity Sessionspivots er blanke, hvis de mangler.
microsoft.session.description All O -- Session description.
microsoft.conversation.item.link All O -- Dyb forbindelse til beskeden.
correlation.id All O -- Cross-service tracing. Ikke dukket op i avanceret jagt i dag.
operation.source All O InvokeSource (IA) Identifikator for SDK'et / tjenesten, der udsender telemetrien. Det kan være en ressourceattribut.
client.address IA, ET, CH M ClientIP (IA, ET) Caller IP. IP-baseret undersøgelse blokeret, hvis den er tom.
server.address IA, ET, CH M ServerAddress (IA, ET) Endpoint din service kalder.
server.port IA, ET, CH M ServerPort (IA) Streng-kodet (for eksempel "443").
user.id IA M UserKey Microsoft Entra objekt-ID for den menneskelige opkalder. "Hvem drev denne agent" er blankt uden det.
user.email IA O UserId UPN på opkalderen.
user.name IA O -- Vises opkalderens navn.
gen_ai.input.messages IA, CH M -- Anmodning om payload (JSON-streng). Fanget til downstream analyse, men endnu ikke dukket op i avanceret jagt.
gen_ai.output.messages IA, CH, OM M -- Responspayload (JSON-streng).
gen_ai.execution.type IA O -- En af HumanToAgent, Agent2Agent, . EventToAgent
microsoft.a365.agent.thought.process IA, CH O -- Fritekst-ræsonnement / tankekæde.
gen_ai.author.app.id OM O -- Microsoft Entra app-ID for den applikation, der skabte eller skabte agenten.
gen_ai.tool.name ET M ToolName Tool name. Defender-værktøjsbrugsvisninger er tomme, hvis de mangler.
gen_ai.tool.type ET M ToolType En af function, , , MCP ServerAPI, , Knowledge Sourcebing_grounding, , code_interpreter, . file_searchPower Platform Connector
gen_ai.tool.call.id ET M ToolId Identifikator for dette værktøjskald.
gen_ai.tool.call.arguments ET M -- Værktøjsargumenter (JSON-streng). Fanget, men endnu ikke dukket op i avanceret jagt.
gen_ai.tool.call.result ET M -- Værktøjsresultat (JSON-streng).
gen_ai.tool.description ET O ToolDescription Tool description.
gen_ai.tool.server.name ET O -- Tool server hostname. Sæt denne attribut for MCP-værktøjer.
gen_ai.request.model CH M -- Modelnavn (for eksempel, gpt-4o). Fanget, men endnu ikke dukket op i avanceret jagt.
gen_ai.provider.name CH M -- Udbydernavn (for eksempel, openai).
gen_ai.usage.input_tokens CH O -- Inputtoken-antal, strengkodet.
gen_ai.usage.output_tokens CH O -- Output-token-antal, strengkodet.
gen_ai.response.finish_reasons CH O -- Finish reason(s).
microsoft.a365.caller.agent.id IA M*² -- Kalder agent appId. Påkrævet for agent-til-agent.
microsoft.a365.caller.agent.name IA M*² -- Kalder agentens displaynavn.
microsoft.a365.caller.agent.blueprint.id IA M*² AgentBlueprintId Kalder agentens blueprint-appId. Påkrævet for indkapslet A2A.
microsoft.a365.caller.agent.user.id IA M*² -- Opkaldsagentens bruger-ID.
microsoft.a365.caller.agent.user.email IA M*² -- Kalder agent UPN.
microsoft.a365.caller.agent.platform.id IA N/A -- Reserveret til alternative ID'er uden for entra.
gen_ai.caller.agent.type IA N/A -- Agent 365 klassificerer automatisk.
microsoft.agent.user.id IA, ET, CH M*¹ TargetAgentUserKey (IA); UserKey (ET, CH) Microsoft Entra objekt-ID for agentens egen brugerkonto. Påkrævet for AI-holdkammerater / legemliggjorte agenter.
microsoft.agent.user.email IA, ET, CH O*¹ UserId (ET, CH) UPN for agentens brugerkonto.
span.SpanId All M OpId OTel SDK udsender dette.
span.ParentSpanId All M*³ ParentId Påkrævet kun for ikke-rodspan; roden invoke_agent har ingen.
span.StartTimeUnixNano All M Top-niveau TimeGenerated (også CreationTime i RawEventData) Unix-epokenanos som en streng.
span.EndTimeUnixNano All M CompletionTime (IA, ET); CopilotEventData.CompletionTime (CH) Varigheden kan ikke beregnes, hvis den mangler.
span.Status.Message All O*⁴ ErrorMessage (IA, ET); CopilotEventData.ErrorMessage (CH) Fejlslagne runs er tom, hvis de mangler.
span.Status.Code All O*⁴ ErrorType (IA); CopilotEventData.ErrorType (CH) Fejlkategori er tom, hvis den mangler.

Note

Flere attributter, du udsender (såsom værktøjsargumenter/resultater, modelparametre og kanal-deeplinks), accepteres af Agent 365 og bruges af downstream Microsoft Defender views, men er endnu ikke eksponeret som en CloudAppEvents.RawEventData JSON-nøgle. Sæt dem alligevel i kolonnen Påkrævet – de kan blive tilføjet til jagtlasten i en fremtidig udgivelse.

At vælge værdier, når du ikke har en naturlig

Nogle nødvendige attributter beskriver koncepter, som måske ikke findes i din agents arkitektur. Hvis den naturlige værdi ikke er der, er her hvad du skal sætte i stedet. Lad ikke et obligatorisk felt stå tomt – selv en GUID med alle nul vil skjule dit run fra nogle kundevendte oplevelser.

Spørgsmål / scenarie Field(s) Hvad skal man sætte
Min agent er en standard Entra app registration (ikke bygget ud fra en Entra-agent-id blueprint). gen_ai.agent.id Entra-appens appId.
↑ Samme scenarie microsoft.a365.agent.blueprint.id Genbrug den samme værdi som gen_ai.agent.id (agentens appId). Skemaet kræver en ikke-tom værdi; Genbrug af agent appID er den sikre standard, når der ikke er nogen blueprint.
Min agent er bygget ud fra en Entra-agent-id blueprint – en eller flere agentidentiteter præget fra samme blueprint. gen_ai.agent.id Agentens identitets appID ( instansens appID, ikke blueprintens).
↑ Samme scenarie microsoft.a365.agent.blueprint.id Tegningen er relevant. Alle instanser, der er præget ud fra samme blueprint, deler denne værdi.
Opkalderen er en menneskelig bruger, ikke en anden agent. Alle microsoft.a365.caller.agent.* og gen_ai.caller.agent.* attributter Omit. De er kun obligatoriske i agent-til-agent-situationer.
I agent-til-agent: den kaldende agent er en standard Entra-app (uden blueprint). microsoft.a365.caller.agent.blueprint.id Genbrug opkaldsagentens appId.
Min agent er ikke en AI-holdkammerat – den har ikke sin egen brugerkonto i lejeren. Alle microsoft.agent.user.* attributter Omit. De er kun obligatoriske, når agenten har sin egen Entra-agent-id-brugerkonto.
Min agent har ingen forståelse for en session ud over en enkelt gennemspilning. microsoft.session.id Valgfrit – udelad. Hvis du vil have, at hver gennemspilning skal være sin egen session, så sæt til en GUID pr. gennemspilning.
Min agent har ingen forståelse for en samtale (one-shot, stateless). gen_ai.conversation.id Generer en frisk GUID pr. gennemspilning. Feltet er obligatorisk; hvis man springer den over, fjernes kørslen fra Defender-agentaktivitetsvisningerne og Microsoft 365 Administration.
Opkalderen har ingen IP (for eksempel en autonom planlagt trigger). client.address Brug en stabil pladsholder, du kontrollerer (for eksempel, "0.0.0.0"). Feltet er obligatorisk; en tom værdi fjerner kørslen fra IP-baserede undersøgelsespivoter.
Agenten kører under behandling; Der kaldes ikke en separat "server". server.address / server.port Brug værtsnavnet på den maskine, der kørte agenten (for eksempel myagent.example.com) og porten, som dit endpoint lytter på. Påkrævet, selv når der ikke er en separat downstream-tjeneste.
Min chat Span bruger ingen modeltoken. gen_ai.usage.input_tokens / gen_ai.usage.output_tokens Valgfrit – udelad. Hvis du har omtrentlige antal, send dem som stringValue.
Min spande har ingen fejl at rapportere. span.Status.Message, span.Status.Code Sæt OTel-status til OK (numerisk kode 1) og udelad beskeden. Pipelinen konsulterer kun disse felter, når status er Error.
Min agent bruger et ikke-entra-identitetssystem (agenten har ingen entra-registrering). microsoft.a365.agent.platform.id Og gen_ai.agent.type Sæt begge dele på hver spændvidde. platform.id er agentens unikke ID i dit identitetssystem; agent.type er en kort etiket, der identificerer, hvilket identitetssystem det er. Begge er fri tekst – vælg det, der giver mening for dit system. Brug ikke de Microsoft-reserverede typeværdier: CustomBuiltAgentsUsingSDK, CopilotStudio, Foundry, DeclarativeAgent, Custom (disse værdier er reserveret til interne Microsoft-overflader). Den opkaldsapp, du autentificerer dig som, kræver stadig en entra-registrering for at bruge disse ruter – det alternative id-par beskriver en målagent , ikke opkalderen.
Hvilken værdi skal jeg tillægge microsoft.channel.namedet? microsoft.channel.name Overfladen, hvor agenten løber. Defender- og admincenterfiltre tager udgangspunkt i den bogstavelige streng, så brug en kort, stabil, lille token. I dag er msteams de kanoniske værdier og outlook; almindelige kundevendte overflader bruger webogså , office, , sharepointeller <your-product-name>. Vælg én værdi og hold dig til den – værktøjer kan ikke forene msteams og Microsoft Teams som den samme kanal.
Skal jeg sætte mig gen_ai.agent.type? gen_ai.agent.type Kun hvis du også sætter microsoft.a365.agent.platform.id (for eksempel hvis din agent ikke har en entra-registrering). Parret fortæller Agent 365, hvilket identitetssystem agenten kommer fra. Vælg en kort bemærk, der unikt identificerer dit identitetssystem. Brug ikke CustomBuiltAgentsUsingSDK, CopilotStudio, Foundry, DeclarativeAgent eller Custom – de værdier er reserveret til intern Microsoft brug. For Entra-registrerede agenter, udelad feltet; Agent 365 fylder den op.
Hvilken OTLP kind skal jeg sætte på mine spans? span.kind Brug heltalsværdien for enum, ikke proto-enum-strengen - 1 (), (SERVER), 2 (), 3 (CLIENT), (), 4 (PRODUCER), (CONSUMER). 5INTERNAL Agent 365 accepterer alle disse og udleder ikke kundesynlig adfærd fra kind, så 1 (INTERNAL) er en sikker standard for alle span. Hvis du vil have en slags til at afspejle kaldets form, INTERNAL er for / output_messagesinvoke_agentog CLIENT for chat / execute_tool rimeligt.

Related content

  • Last updated on