Reference atributu pozorovatelnosti agenta 365

Toto je kanonická specifikace podle atributů používaná v pipeline Agenta 365. Každý rozsah přijatý Agentem 365 – ať už vysílaný distribucí Microsoft OpenTelemetry, Agent 365 SDK nebo přenášený přes direct OTel – musí být v souladu s tímto požadavkem. Každý záznam uvádí typy operací, na které se atribut vztahuje, zda je to povinné, název pole, do kterého se vaše hodnota dostane pro dotazy na pokročilé hledání (pokud existuje), a jaký dopad máte, pokud ho přeskočíte.

Pokud používáte SDK nebo distribuci, SDK vám tyto atributy generuje a sekce Picking values se použije jen tehdy, když potřebujete přepsat výchozí nastavení. Pokud jste na přímé OTel cestě, každý atribut vydáváte ručně; pro způsob, jak je sestavit do požadavku, viz Průvodce integrací.

Attribute table

Všechny hodnoty jsou odeslány jako stringValue - počet tokenů musí být "42" (ne); 42porty musí být "443" (ne 443).

Operace legenda.IA = invoke_agent, ET = execute_tool, CH = chat, OM = output_messages, All = platí pro každou operaci.

Required legend.

  • M: mandatory.
  • M*1: povinné pouze pro emtělované agenty (agent má vlastní uživatelský účet Entra ID agenta).
  • M*2: povinné pouze pro hovory mezi agenty.
  • M*3: povinné pouze pro nekořenové rozpětí. Kořen invoke_agent nemá rodiče.
  • O*4: volitelné, smysluplné pouze tehdy, když je stav span Error.
  • O: optional.
  • N/A: nevyzařujte. Agent 365 se automaticky naplňuje.

Sloupec "RawEventData field" uvádí JSON klíč uvnitř CloudAppEvents.RawEventData , který kanonický dotaz pro pokročilé hledání v Ověřování ingesce analyzuje. Prázdná buňka znamená, že atribut je ne dnes v CloudAppEvents – měl byste ho stále emitovat (podle sloupce Požadované), protože Agent 365 ho používá pro vstup, parent-resolution a zobrazení agentové aktivity Microsoft Defender, ale dnes už není přímo dotazovatelný z Microsoft Defender advanced search.

Note

Agent 365 automaticky doplňuje pole statických záznamů (Id, RecordType, Workload, UserType, Version) a generované ID požadavků / odpovědí.

Attribute Applies to Required RawEventData field Poznámky / dopad, pokud chybí
gen_ai.operation.name All M Operation Jeden z invoke_agent, execute_tool, chat, output_messages. Rozsah klesl, pokud chybí nebo není rozpoznán.
microsoft.tenant.id All M OrganizationId URL je {tenantId} autoritativní. Pokud to nastavíte a nesouhlasí, žádost je zamítnuta (403).
gen_ai.agent.id All M TargetAgentId (IA, také nejvyšší úroveň AgentId); AgentId (ET, CH) Aplikace pro volání funguje. Musí odpovídat URL a {agentId} ověřené aplikaci. Mismatch vrací 403.
gen_ai.agent.name All M TargetAgentName (IA); AgentName (ET, CH) Defender / admin center zobrazí surové GUID místo jména, pokud chybí.
microsoft.a365.agent.blueprint.id All M TargetAgentBlueprintID (IA); AgentBlueprintId (ET, CH) Plán je aktuální. Pro standardní aplikace Entra bez blueprintu použijte znovu appId agenta. Jinak se shluky blueprintů v administrativním centru rozbijí.
gen_ai.agent.description All O -- Detailní zobrazení v administrativním centru je pro agenta prázdné.
gen_ai.agent.type All O PlatformTargetAgentType (IA); PlatformAgentType (ET); CopilotEventData.PlatformAgentType (CH) Štítek pro váš identifikační systém, který se doplňuje s případy microsoft.a365.agent.platform.id , kdy agent nemá registraci Entra. Volný text; Vyberte hodnotu, která jednoznačně identifikuje váš systém identity. Vynechejte, když má agent registraci Entra – Agent 365 se automaticky klasifikuje. Nepoužívejte hodnoty rezervované Microsoft (viz Výběr hodnot).
microsoft.a365.agent.platform.id All O PlatformTargetAgentId (IA, také nejvyšší úroveň AlternateId); PlatformAgentId (ET, CH) Jedinečné ID agenta ve vašem ne-Entra identitním systému. Free-form text. Sestavme s .gen_ai.agent.type Vynechejte, když má agent registraci Entra. Viz Hodnoty vybírat.
gen_ai.conversation.id All M ConversationId (IA, ET); CopilotEventData.ConversationId / CopilotEventData.ThreadId (CH) Primární klávesa pro spojení běhu. Bez něj se běh neobjevuje v zobrazení aktivity agentů Defender ani v administrativním centru.
microsoft.channel.name All M ChannelName (IA, ET) Povrch, po kterém agent běží. Použijte krátké malé písmeno tokenu; Kanonické hodnoty používané filtry Defender / Admin Center dnes jsou a . Vlastní řetězce (například web, <your-product-name>) jsou akceptovány, ale nepřesnou se v vestavěných kanálových filtrech. Stejná hodnota na každém poli. Viz Hodnoty vybírat.
microsoft.channel.link All O -- Channel deep-link.
microsoft.session.id All O SessionIdentity Přesuny sezení jsou prázdné, pokud chybí.
microsoft.session.description All O -- Session description.
microsoft.conversation.item.link All O -- Hluboký odkaz na zprávu.
correlation.id All O -- Cross-service tracing. Dnes se to v pokročilém lovu neobjevuje.
operation.source All O InvokeSource (IA) Identifikátor pro SDK / službu, která vysílá telemetrii. Může to být atribut Zdroj.
client.address IA, ET, CH M ClientIP (IA, ET) Caller IP. Vyšetřování založené na IP adrese je blokováno, pokud je prázdné.
server.address IA, ET, CH M ServerAddress (IA, ET) Endpoint, který vaše služba volá.
server.port IA, ET, CH M ServerPort (IA) Kódované řetězci (například "443").
user.id IA M UserKey Microsoft Entra ID objektu lidského volajícího. "Kdo vedl tohoto agenta" bez toho je prázdné.
user.email IA O UserId UPN volajícího.
user.name IA O -- Zobrazit jméno volajícího.
gen_ai.input.messages IA, CH M -- Request payload (JSON string). Zachycen pro analýzu po proudu, ale ještě nebyl vynořen při pokročilém lovu.
gen_ai.output.messages IA, CH, OM M -- Payload Response (JSON string).
gen_ai.execution.type IA O -- Jeden z HumanToAgent, Agent2Agent, . EventToAgent
microsoft.a365.agent.thought.process IA, CH O -- Volné textové uvažování / řetězec myšlenek.
gen_ai.author.app.id OM O -- Microsoft Entra ID aplikace aplikace, která agenta vytvořila/vytvořila.
gen_ai.tool.name ET M ToolName Tool name. Zobrazení použití nástrojů v Defender jsou prázdné, pokud chybí.
gen_ai.tool.type ET M ToolType Jeden z , , , , , , function, , Power Platform Connector. MCP ServerAPIKnowledge Sourcebing_groundingcode_interpreterfile_search
gen_ai.tool.call.id ET M ToolId Identifikátor pro toto volání nástroje.
gen_ai.tool.call.arguments ET M -- Argumenty nástrojů (JSON řetězec). Zajat, ale ještě se nevynořil v pokročilém lovu.
gen_ai.tool.call.result ET M -- Výsledek nástroje (JSON řetězec).
gen_ai.tool.description ET O ToolDescription Tool description.
gen_ai.tool.server.name ET O -- Název serveru nástroje. Nastavte tento atribut pro MCP nástroje.
gen_ai.request.model CH M -- Název modelu (například gpt-4o). Zajat, ale ještě se nevynořil v pokročilém lovu.
gen_ai.provider.name CH M -- Název poskytovatele (například openai).
gen_ai.usage.input_tokens CH O -- Počet vstupních tokenů, kódováno řetězcem.
gen_ai.usage.output_tokens CH O -- Počet výstupních tokenů, kódováno řetězcem.
gen_ai.response.finish_reasons CH O -- Finish reason(s).
microsoft.a365.caller.agent.id IA M*2 -- Volám agenta na místě. Vyžadováno pro agent-agent.
microsoft.a365.caller.agent.name IA M*2 -- Volám jméno agenta.
microsoft.a365.caller.agent.blueprint.id IA M*2 AgentBlueprintId Volám agentův plán appId. Vyžadováno pro ztělesněné A2A.
microsoft.a365.caller.agent.user.id IA M*2 -- Volám uživatelské ID agenta.
microsoft.a365.caller.agent.user.email IA M*2 -- Volám agenta UPN.
microsoft.a365.caller.agent.platform.id IA N/A -- Vyhrazeno pro alternativní ID mimo Entra.
gen_ai.caller.agent.type IA N/A -- Agent 365 se automaticky klasifikuje.
microsoft.agent.user.id IA, ET, CH M*1 TargetAgentUserKey (IA); UserKey (ET, CH) Microsoft Entra ID objektu z uživatelského účtu agenta. Povinné pro AI spoluhráče / agenty s tělem.
microsoft.agent.user.email IA, ET, CH O*1 UserId (ET, CH) UPN uživatelského účtu agenta.
span.SpanId All M OpId Jiný SDK to vysílá.
span.ParentSpanId All M*3 ParentId Vyžadováno pouze pro nekořenové obaly; Kořen invoke_agent žádný nemá.
span.StartTimeUnixNano All M nejvyšší úroveň TimeGenerated (také CreationTime v RawEventData) Unixová epocha nanos jako struna.
span.EndTimeUnixNano All M CompletionTime (IA, ET); CopilotEventData.CompletionTime (CH) Trvání nelze vypočítat, pokud chybí.
span.Status.Message All O*4 ErrorMessage (IA, ET); CopilotEventData.ErrorMessage (CH) Příčina neúspěšných pokusů je prázdná, pokud chybí.
span.Status.Code All O*4 ErrorType (IA); CopilotEventData.ErrorType (CH) Pokud chybí, kategorie chyby je prázdná.

Note

Několik atributů, které generujete (například argumenty / výsledky nástrojů, parametry modelu a hluboké odkazy kanálů), je Agentem 365 akceptováno a používáno downstream Microsoft Defender zobrazeními, ale zatím nejsou zobrazeny jako CloudAppEvents.RawEventData JSON klíč. Nastav je podle sloupce Required – mohou být v budoucnu přidány do loveckého payloadu.

Výběr hodnot, když nemáte přirozenou hodnotu

Některé požadované atributy popisují koncepty, které nemusí v architektuře vašeho agenta existovat. Pokud přirozená hodnota není, zde je, co nastavit místo toho. Nenechávejte povinné pole prázdné – i GUID s nulami skryje váš průběh před některými zákaznickými zážitky.

Otázka / scénář Field(s) Co nastavit
Můj agent je standardní registrační aplikace Entra (není postavený na Entra ID agenta blueprintu). gen_ai.agent.id Aplikace Entra je dostupná.
↑ stejný scénář microsoft.a365.agent.blueprint.id Použij stejnou hodnotu jako gen_ai.agent.id (appId agenta). Schéma vyžaduje neprázdnou hodnotu; Opětovné použití agentního appId je bezpečný výchozí režim, když není žádný blueprint.
Můj agent je postavený z Entra ID agenta blueprintu – jedna nebo více agentních identit vytvořených ze stejného blueprintu. gen_ai.agent.id AppId identity agenta ( appIdinstance , ne blueprint).
↑ stejný scénář microsoft.a365.agent.blueprint.id Plán je aktuální. Všechny instance ražené ze stejného blueprintu sdílejí tuto hodnotu.
Volající je lidský uživatel, ne další agent. Vše microsoft.a365.caller.agent.* a atributy gen_ai.caller.agent.* Omit. Jsou povinné pouze v případech agent-agent.
V agent-to-agent: volající agent je standardní aplikace Entra (bez blueprintu). microsoft.a365.caller.agent.blueprint.id Znovu použijte aplikaci volajícího agenta.
Můj agent není AI spoluhráč – nemá vlastní uživatelský účet v tenantu. Všechny microsoft.agent.user.* atributy Omit. Jsou povinné pouze tehdy, když má agent svůj vlastní uživatelský účet Entra ID agenta.
Můj agent nemá pojem o sezení nad rámec jednoho běhu. microsoft.session.id Volitelné – vynechat. Pokud chcete, aby každý běh byl samostatnou relací, nastavte GUID na jeden běh.
Můj agent vůbec nechápe konverzaci (jednorázovka, bez stavu). gen_ai.conversation.id Generujte nový GUID za každý běh. Toto pole je povinné; přeskočení odstraní běh z zobrazení aktivity agentů Defender a z Centrum pro správu Microsoftu 365.
Volající nemá žádnou IP adresu (například autonomní plánovaný spouštěč). client.address Použijte stabilní zástupce, "0.0.0.0"který ovládáte (například ). Toto pole je povinné; prázdná hodnota odstraní běh z IP založených vyšetřovacích pivotů.
Agent běží v procesu; Není volán žádný samostatný "server". server.address / server.port Použijte název hostitele stroje, který spustil agenta (například ) myagent.example.coma port, na kterém váš endpoint poslouchá. Je vyžadováno i tehdy, když není samostatná služba pro downstream.
Můj chat span nemá žádné využití modelových tokenů. gen_ai.usage.input_tokens / gen_ai.usage.output_tokens Volitelné – vynechat. Pokud máte přibližné počty, pošlete je jako .stringValue
Můj rozsah nemá žádnou chybu k hlášení. span.Status.Message, span.Status.Code Nastavte stav OTel na OK (číselný kód 1) a zprávu vynechať. Pipeline tyto pole konzultuje pouze tehdy, když je stav Error.
Můj agent používá ne-Entra identitní systém (agent nemá registraci Entra). microsoft.a365.agent.platform.id a gen_ai.agent.type Nastavte obojí, na každém poli. platform.id je jedinečné ID agenta ve vašem identitním systému; agent.type je krátký štítek, který identifikuje, o jaký identitní systém se jedná. Oba jsou volné texty – vyberte si, co dává smysl vašemu systému. Nepoužívejte hodnoty typu rezervované Microsoft: CustomBuiltAgentsUsingSDK, CopilotStudio, Foundry, DeclarativeAgent, Custom (tyto hodnoty jsou vyhrazeny pro vnitřní Microsoft povrchy). Volající aplikace, kterou autentizujete, stále potřebuje registraci Entra pro použití těchto tras – pár alternate-id popisuje cílového agenta, ne volajícího.
Jakou hodnotu bych měl přiřadit microsoft.channel.name? microsoft.channel.name Povrch, po kterém agent běží. Defender a admin center filtrují klíče z doslovného řetězce, takže použijte krátký, stabilní token malým písmenem. Dnes jsou msteams kanonické hodnoty a ; outlookběžné plochy pro zákazníky také používají web, office, sharepoint, nebo <your-product-name>. Vyberte si jednu hodnotu a držte se jí – nástroje nedokážou sladit msteams a Microsoft Teams jako stejný kanál.
Mám nastavit gen_ai.agent.type? gen_ai.agent.type Pouze pokud zároveň nastavujete ( microsoft.a365.agent.platform.id například váš agent nemá registraci u Entra). Dvojice agentovi 365 řekne, z jakého identifikačního systému agent pochází. Vyberte si krátký štítek, který jedinečně identifikuje váš systém identity. Nepoužívejte CustomBuiltAgentsUsingSDK, CopilotStudio, Foundry, DeclarativeAgent nebo Custom – tyto hodnoty jsou vyhrazeny pro interní Microsoft použití. U agentů registrovaných u Entra vynechte pole; Agent 365 to doplňuje.
Jaký OTLP kind bych měl nastavit na svých spans? span.kind Použijte celočíselnou hodnotu enum, nikoli řetězec proto enum - 1 (),INTERNAL2 (), (SERVER), 3 (CLIENT), 4PRODUCER5CONSUMER(), (). Agent 365 přijímá žádnou z těchto možností a neodvozuje chování viditelné pro zákazníka z kind, takže 1 (INTERNAL) je bezpečný výchozí režim pro každé období. Pokud chcete, INTERNALinvoke_agent / output_messagesaby tvar volání odrážel pro a CLIENT pro chat / execute_tool je rozumné.

Related content

  • Last updated on