Agent 365 observabilitetsattributreferens

Detta är den kanoniska attribut-för-attribut-specifikationen som används av Agent 365:s intagningspipeline. Varje spann som tas in av Agent 365 – oavsett om den sänds ut av Microsoft OpenTelemetry Distro, Agent 365 SDK eller skickas över direkt OTel – måste uppfylla den. Varje post listar de operationstyper som attributet gäller för, om det är obligatoriskt, fältnamnet ditt värde hamnar i för avancerade jaktfrågor (där en sådan finns), och effekten om du hoppar över det.

Om du använder SDK:n eller distributionen skickar SDK:n dessa attribut åt dig och avsnittet Picking values gäller bara när du behöver åsidosätta en standard. Om du är på den direkta OTel-vägen emitterar du varje attribut manuellt; för hur man sätter ihop dem till en förfrågan, se integrationsguiden.

Attribute table

Alla värden skickas som stringValue - tokenantal måste vara "42" (inte 42); portar måste vara "443" (inte 443).

Operation legend.IA = invoke_agent, ET, = execute_toolCH = chat, OM, = output_messagesAll = gäller för varje operation.

Required legend.

  • M: mandatory.
  • M*¹: obligatoriskt endast för embodied agents (agenten har sitt eget Entra agent-ID användarkonto).
  • M*²: obligatoriskt endast för agent-till-agent-samtal.
  • M*³: obligatoriskt endast för icke-root spans. Roten invoke_agent har ingen förälder.
  • O*⁴: valfritt, endast meningsfullt när spannstatusen är Fel.
  • O: optional.
  • Ej tillgängligt: avger inte. Agent 365 fylls i automatiskt.

Kolumnen "RawEventData" nämner en JSON-nyckel inuti CloudAppEvents.RawEventData den kanoniska avancerade jaktfrågan i Verifying Ingestion parses. En tom cell innebär att attributet är not exponerat i CloudAppEvents idag – du bör fortfarande smitera det (enligt kolumnen Required) eftersom Agent 365 använder det för inmatning, föräldraupplösning och Microsoft Defender agentaktivitetsvyer, men det är inte direkt frågebart från Microsoft Defender avancerad jakt idag.

Note

Agent 365 fyller automatiskt i de statiska postfälten (Id, RecordType, Workload, UserType, ) Versionoch de genererade förfrågnings-/svars-ID:na.

Attribute Applies to Required RawEventData field Anteckningar / påverkan om det saknas
gen_ai.operation.name All M Operation En av invoke_agent, execute_tool, chat, output_messages. Span föll om den saknades eller inte blev igenkänd.
microsoft.tenant.id All M OrganizationId URL {tenantId} är auktoritativ. Om du ställer in detta och det inte stämmer, avslås begäran (403).
gen_ai.agent.id All M TargetAgentId (IA, också på toppnivå AgentId); AgentId (ET, CH) Appens appID för samtal. Måste matcha URL {agentId} och den autentiserade appen. Mismatch ger 403.
gen_ai.agent.name All M TargetAgentName (IA); AgentName (ET, CH) Defender / admin center visar rå GUID istället för ett namn om det saknas.
microsoft.a365.agent.blueprint.id All M TargetAgentBlueprintID (IA); AgentBlueprintId (ET, CH) Ritningen är aktuell. För vanliga entraappar utan blueprint, återanvänd agentens appId. Blueprint-roll-ups i administrationscentret går annars sönder.
gen_ai.agent.description All O -- Detaljvyn i administrationscentret är tom för agenten.
gen_ai.agent.type All O PlatformTargetAgentType (IA); PlatformAgentType (ET); CopilotEventData.PlatformAgentType (CH) En etikett för ditt identitetssystem, ihopparat med microsoft.a365.agent.platform.id när agenten inte har en entra-registrering. Friformad text; Välj ett värde som unikt identifierar ditt identitetssystem. Utelämna när agenten har en entra-registrering – Agent 365 klassificerar automatiskt. Använd inte de Microsoft-reserverade värdena (se Picking values).
microsoft.a365.agent.platform.id All O PlatformTargetAgentId (IA, också på toppnivå AlternateId); PlatformAgentId (ET, CH) Agentens unika ID i ditt icke-Entra-identitetssystem. Free-form text. Sätt ihop med gen_ai.agent.type. Utelämna när agenten har en entra-registrering. Se Plockvärden.
gen_ai.conversation.id All M ConversationId (IA, ET); CopilotEventData.ConversationId / CopilotEventData.ThreadId (CH) Den primära join-nyckeln för en runda. Utan den visas inte körningen i Defender-agentaktivitetsvyer eller administrationscenter.
microsoft.channel.name All M ChannelName (IA, ET) Ytan där agenten springer. Använd en kort liten token; De kanoniska värdena som används av Defender / Admin Center-filter idag är och . Anpassade strängar (till exempel web, <your-product-name>) accepteras men kan inte pivotera i inbyggda kanalfilter. Samma värde på varje spann. Se Plockvärden.
microsoft.channel.link All O -- Channel deep-link.
microsoft.session.id All O SessionIdentity Sessionspivots är tomma om de saknas.
microsoft.session.description All O -- Session description.
microsoft.conversation.item.link All O -- Djup länk till meddelandet.
correlation.id All O -- Cross-service tracing. Inte dykt upp vid avancerad jakt idag.
operation.source All O InvokeSource (IA) Identifierare för SDK:n / tjänsten som sänder telemetrin. Det kan vara ett resursattribut.
client.address IA, ET, CH M ClientIP (IA, ET) Caller IP. IP-baserad undersökning blockeras om den är tom.
server.address IA, ET, CH M ServerAddress (IA, ET) Endpoint, din tjänst ringer.
server.port IA, ET, CH M ServerPort (IA) Strängkodad (till exempel "443").
user.id IA M UserKey Microsoft Entra objekt-ID för den mänskliga uppringaren. "Vem drev denna agent" är tomt utan det.
user.email IA O UserId UPN på den som ringde.
user.name IA O -- Visa uppringarens namn.
gen_ai.input.messages IA, CH M -- Begär nyttolast (JSON-sträng). Fångad för analys nedströms men ännu inte dykt upp i avancerad jakt.
gen_ai.output.messages IA, CH, OM M -- Responspayload (JSON-sträng).
gen_ai.execution.type IA O -- En av HumanToAgent, Agent2Agent, EventToAgent.
microsoft.a365.agent.thought.process IA, CH O -- Fri text-resonemang / tankekedja.
gen_ai.author.app.id OM O -- Microsoft Entra-app-ID för applikationen som skapade eller skapade agenten.
gen_ai.tool.name ET M ToolName Tool name. Defender-verktygsanvändningsvyer är tomma om de saknas.
gen_ai.tool.type ET M ToolType En av function, , , MCP Server, API, Knowledge Sourcebing_grounding, , code_interpreter, . file_searchPower Platform Connector
gen_ai.tool.call.id ET M ToolId Identifierare för detta verktygsanrop.
gen_ai.tool.call.arguments ET M -- Verktygsargument (JSON-sträng). Fångad men ännu inte dykt upp i avancerad jakt.
gen_ai.tool.call.result ET M -- Verktygsresultat (JSON-sträng).
gen_ai.tool.description ET O ToolDescription Tool description.
gen_ai.tool.server.name ET O -- Verktygsserverns värdnamn. Ställ in denna attribut för MCP-verktyg.
gen_ai.request.model CH M -- Modellnamn (till exempel, gpt-4o). Fångad men ännu inte dykt upp i avancerad jakt.
gen_ai.provider.name CH M -- Leverantörsnamn (till exempel, openai).
gen_ai.usage.input_tokens CH O -- Antal inmatningstoken, strängkodat.
gen_ai.usage.output_tokens CH O -- Utdata av token, strängkodad.
gen_ai.response.finish_reasons CH O -- Finish reason(s).
microsoft.a365.caller.agent.id IA M*² -- Ringer agent AppId. Krävs för agent-till-agent.
microsoft.a365.caller.agent.name IA M*² -- Anropar agentens visningsnamn.
microsoft.a365.caller.agent.blueprint.id IA M*² AgentBlueprintId Ringer agentens ritningsapp. Krävs för förkroppsligad A2A.
microsoft.a365.caller.agent.user.id IA M*² -- Call-agentens användar-ID.
microsoft.a365.caller.agent.user.email IA M*² -- Ringer agent UPN.
microsoft.a365.caller.agent.platform.id IA N/A -- Reserverat för alternativa ID:n som inte är Entra.
gen_ai.caller.agent.type IA N/A -- Agent 365 klassificerar automatiskt.
microsoft.agent.user.id IA, ET, CH M*¹ TargetAgentUserKey (IA); UserKey (ET, CH) Microsoft Entra-objekt-ID för agentens eget användarkonto. Krävs för AI-lagkamrater / förkroppsligade agenter.
microsoft.agent.user.email IA, ET, CH O*¹ UserId (ET, CH) UPN för agentens användarkonto.
span.SpanId All M OpId OTel SDK sänder ut detta.
span.ParentSpanId All M*³ ParentId Krävs endast för icke-rotspan; roten invoke_agent har ingen.
span.StartTimeUnixNano All M Toppnivå TimeGenerated (även CreationTime i RawEventData) Unix-epoknanos som en sträng.
span.EndTimeUnixNano All M CompletionTime (IA, ET); CopilotEventData.CompletionTime (CH) Varaktigheten kan inte beräknas om den saknas.
span.Status.Message All O*⁴ ErrorMessage (IA, ET); CopilotEventData.ErrorMessage (CH) Orsaken till misslyckade körningar är tom om den saknas.
span.Status.Code All O*⁴ ErrorType (IA); CopilotEventData.ErrorType (CH) Felkategori är tom om den saknas.

Note

Flera attribut du genererar (såsom verktygsargument/resultat, modellparametrar och kanaldjuplänkar) accepteras av Agent 365 och används av nedströms Microsoft Defender vyer, men är ännu inte exponerade som en CloudAppEvents.RawEventData JSON-nyckel. Ställ in dem enligt kolumnen Required ändå – de kan läggas till i jaktlasten i en framtida release.

Att välja värden när du inte har ett naturligt

Vissa nödvändiga attribut beskriver koncept som kanske inte finns i din agents arkitektur. Om det naturliga värdet inte finns där, här är vad du ska ställa in istället. Lämna inte ett obligatoriskt fält tomt – även en GUID med bara nollor döljer din runda från vissa kundnära upplevelser.

Fråga / scenario Field(s) Vad man ska sätta
Min agent är en standard Entra app-registrering (inte byggd på en Entra agent-ID blueprint). gen_ai.agent.id Entra-appens appId.
↑ samma scenario microsoft.a365.agent.blueprint.id Återanvänd samma värde som gen_ai.agent.id (agentens appId). Schemat kräver ett icke-tomt värde; Att återanvända agentens appID är den säkra standarden när det inte finns någon ritning.
Min agent är byggd från en Entra agent-ID blueprint – en eller flera agentidentiteter som präglats från samma blueprint. gen_ai.agent.id Agentidentitetens appID ( instansens appID, inte blueprintens).
↑ samma scenario microsoft.a365.agent.blueprint.id Ritningen är aktuell. Alla instanser som präglats från samma ritning delar detta värde.
Uppringaren är en mänsklig användare, inte en annan agent. Alla microsoft.a365.caller.agent.* och gen_ai.caller.agent.* attribut Omit. De är obligatoriska endast i agent-till-agent-situationer.
I agent-till-agent: den anropande agenten är en standard Entra-app (utan ritning). microsoft.a365.caller.agent.blueprint.id Återanvänd den uppringande agentens appId.
Min agent är inte en AI-lagkamrat – den har inget eget användarkonto i hyresgästen. Alla microsoft.agent.user.* egenskaper Omit. De är obligatoriska endast när agenten har sitt eget Entra agent-ID-användarkonto.
Min agent har ingen uppfattning om en session utöver en enda runda. microsoft.session.id Valfritt – utelämna. Om du vill att varje genomspelning ska vara en egen session, sätt in en GUID per genomspelning.
Min agent har inget begrepp om en konversation (one-shot, stateless). gen_ai.conversation.id Generera en ny GUID per genomspelning. Fältet är obligatoriskt; att hoppa över den tar bort körningen från Defender-agentaktivitetsvyerna och Administrationscenter för Microsoft 365.
Uppringaren har ingen IP (till exempel en autonom schemalagd trigger). client.address Använd en stabil platshållare som du kontrollerar (till exempel "0.0.0.0"). Fältet är obligatoriskt; ett tomt värde tar bort körningen från IP-baserade undersökningspivotar.
Agenten körs under processen; Det finns ingen separat "server" som anropas. server.address / server.port Använd värdnamnet på maskinen som körde agenten (till exempel myagent.example.com) och porten som din endpoint lyssnar på. Krävs även när det inte finns någon separat nedströmstjänst.
Min chat span använder ingen modelltoken. gen_ai.usage.input_tokens / gen_ai.usage.output_tokens Valfritt – utelämna. Om du har ungefärliga antal, skicka dem som stringValue.
Min span har inga fel att rapportera. span.Status.Message, span.Status.Code Sätt OTel-statusen till OK (numerisk kod 1) och utelämna meddelandet. Pipelinen konsulterar endast dessa fält när status är Error.
Min agent använder ett icke-entra-identitetssystem (agenten har ingen entra-registrering). microsoft.a365.agent.platform.id och gen_ai.agent.type Ställ båda, på varje spann. platform.id är agentens unika ID i ditt identitetssystem; agent.type är en kort etikett som identifierar vilket identitetssystem det är. Båda är fri text – välj det som passar ditt system. Använd inte de Microsoft-reserverade typvärdena: CustomBuiltAgentsUsingSDK, CopilotStudio, Foundry, DeclarativeAgent, Custom (dessa värden är reserverade för interna Microsoft ytor). Den samtalsapp du autentiserar dig som kräver fortfarande en entra-registrering för att använda dessa rutter – det alternativa ID-paret beskriver en målagent , inte uppringaren.
Vilket värde bör jag lägga på microsoft.channel.name? microsoft.channel.name Ytan där agenten springer. Defender- och admincenterfilter bygger på bokstavssträngen, så använd en kort, stabil, gemener token. Idag är msteams de kanoniska värdena och outlook; vanliga kundvända ytor använder webockså , office, , sharepointeller <your-product-name>. Välj ett värde och håll dig till det – verktygen kan inte stämma av msteams och Microsoft Teams som samma kanal.
Ska jag ställa in gen_ai.agent.type? gen_ai.agent.type Endast om du också gör en inställning microsoft.a365.agent.platform.id (till exempel om din agent inte har någon entra-registrering). Paret berättar för Agent 365 vilket identitetssystem agenten kommer ifrån. Välj en kort etikett som unikt identifierar ditt identitetssystem. Använd inte CustomBuiltAgentsUsingSDK, CopilotStudio, Foundry, DeclarativeAgent eller Custom – dessa värden är reserverade för intern Microsoft användning. För Entra-registrerade agenter, utelämna fältet; Agent 365 fyller på den.
Vilken OTLP kind ska jag ställa in på mina spans? span.kind Använd heltalsvärdet enum, inte proto-enumsträngen - 1 (INTERNAL), (), 2 (SERVER), 3 (CLIENT), (), 4 (), (PRODUCER), (), 5 (CONSUMER). Agent 365 accepterar något av dessa och härleder inte kundsynligt beteende från kind, så 1 (INTERNAL) är en säker standard för varje spann. Om du vill att slaget ska spegla anropsformen är INTERNAL för / output_messagesinvoke_agentoch CLIENT för chat / execute_tool rimligt.

Related content

  • Last updated on