Reference atributu pozorovatelnosti agenta 365

Tento článek je kanonická specifikace podle atributů používaná v pipeline Agenta 365. Každý rozsah přijatý Agentem 365 – ať už emitovaný distribucí Microsoft OpenTelemetry, zastaralým Agent 365 Observability SDK, nebo odeslaný přímo OTel – musí s ním odpovídat. 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 vygeneruje. Sekce Výběr hodnot se uplatní pouze tehdy, když potřebujete přepsat výchozí nastavení. Pokud použijete přímou OTel cestu, každý atribut vydáváte ručně. 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 není v Today CloudAppEvents vystaven. Stále byste ji měli emitovat (dle sloupce Required), protože Agent 365 ji používá pro ingester, parent-resolution a zobrazení aktivity agentů v Microsoft Defender. Dnes však nelze přímo dotazovat 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ů a 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 tuto hodnotu nastavíte a ta nesouhlasí, žádost je zamítnuta (403).
gen_ai.agent.id All M TargetAgentId (IA); 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 a administrativní centrum zobrazují 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, které dnes používají filtry Defender a administrativních center, jsou msteams a outlook. Vlastní řetězce (například web, <your-product-name>) jsou akceptovány, ale neotáčejí se ve vestavěných kanálových filtrech. Používejte stejnou hodnotu 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 nebo službu, která vysílá telemetrii. Může to být atribut zdroje.
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í nebo řetězec myšlenek.
gen_ai.author.app.id OM O -- Microsoft Entra ID aplikace aplikace, která agenta vytvořila nebo 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 reasons.
microsoft.a365.caller.agent.id IA M*2 AgentId (IA) Volám agenta na místě. Vyžadováno pro agent-agent.
microsoft.a365.caller.agent.name IA M*2 AgentName (IA) 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 a 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

Agent 365 přijímá několik atributů, které vydáváte, jako jsou argumenty a výsledky nástrojů, parametry modelu a deep-linky kanálů. Downstream pohledy Microsoft Defender tyto atributy používají, ale Agent 365 je zatím nezpřístupňuje jako CloudAppEvents.RawEventData klíč JSON. Nastavte je podle sloupce Požadované. Mohou být přidány do loveckého nákladu v budoucím vydání.

Important

Na záznamech (IA) popisují AgentIdpole , AgentName, a AgentBlueprintId označují volajícího agenta, nikoli volaného agenta.invoke_agent Agent 365 je vyplní z atributů microsoft.a365.caller.agent.* . Když člověk vyvolá vašeho agenta, vynechte tyto atributy, a AgentIdAgentBlueprintId zobrazí se jako GUID s nulami (00000000-0000-0000-0000-000000000000) a AgentName je prázdný v auditních záznamech a Microsoft Purview. Hodnota všech nul se očekává u běhů iniciovaných člověkem. Pro identifikaci vyvolávaného agenta použijte TargetAgentId, TargetAgentName, a TargetAgentBlueprintID.

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í dostupná, nastavte místo toho následující hodnoty. Nenechávejte povinné pole prázdné. I GUID s nulami skrývá váš průběh před některými zákaznickými zážitky. Toto pravidlo platí pouze pro povinné atributy. Nevztahuje se to na atributy volajícího-agenta při běžcích iniciovaných člověkem, kde se očekává úplná nula AgentId na invoke_agent záznamech.

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. Na invoke_agent záznamech volající AgentIdAgentBlueprintId zobrazí GUID pouze s nulami. Použijte TargetAgentId k identifikaci svého agenta.
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; je krátký štítek, agent.type který identifikuje, o který identifikační 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

  • Poslední aktualizace v