Referencja atrybutu obserwowalności agenta 365

To jest kanoniczna specyfikacja atrybut po atributie używana przez pipeline ingestion Agenta 365. Każdy pakiet pobierany przez Agenta 365 – niezależnie od tego, czy emitowany przez dystrybucję OpenTelemetry Microsoft OpenTelemetry, Agent 365 SDK czy przesyłany przez direct OTel musi być zgodny z tym przepisem. Każdy wpis wymienia typy operacji, do których przypisuje się atrybut, czy jest to obowiązkowe, nazwę pola, w której trafia wartość dla zapytań zaawansowanych poszukiwań (jeśli takie istnieje), oraz wpływ na pominięcie tej funkcji.

Jeśli używasz SDK lub dystrybucji, SDK generuje te atrybuty za ciebie, a sekcja Wybieranie wartości działa tylko wtedy, gdy musisz nadpisać domyślne atrybuty. Jeśli jesteś na bezpośredniej ścieżce OTel, emitujesz wszystkie atrybuty ręcznie; aby dowiedzieć się, jak je złożyć w żądanie, zobacz Przewodnik Integracji.

Attribute table

Wszystkie wartości są wysyłane jako stringValue - liczba tokenów musi być ( "42" nie 42); porty muszą być "443" (nie 443).

Operacja legenda.IA = invoke_agent, ET = execute_tool, CH = chat, OM = output_messages, All = dotyczy każdej operacji.

Required legend.

  • M: mandatory.
  • M*¹: obowiązkowy tylko dla agentów empersonowanych (agent ma własne konto użytkownika Identyfikator agenta Entra).
  • M*²: obowiązkowe tylko dla rozmów agent-agent.
  • M*³: obowiązkowe tylko dla rozpięć nie-pierwiastkowych. Korzeń invoke_agent nie ma rodzica.
  • O*⁴: opcjonalne, istotne tylko wtedy, gdy status rozpoczęcia to Błąd.
  • O: optional.
  • N/A: nie emituj. Agent 365 automatycznie się zapełnia.

Kolumna "RawEventData field" wymienia klucz JSON wewnątrz CloudAppEvents.RawEventData , który kanoniczne zapytanie zaawansowanego poszukiwania w Verifying ingestion parsuje. Pusta komórka oznacza, że atrybut jest nie obecnie widoczny w CloudAppEvents – nadal powinieneś go emitować (zgodnie z kolumną Wymagane), ponieważ Agent 365 używa go do pobierania, rozdzielczości rodzica oraz widoków aktywności agenta Microsoft Defender, ale nie jest bezpośrednio zapytywalny z Microsoft Defender zaawansowanego poszukiwania.

Note

Agent 365 automatycznie wypełnia pola statycznego rekordu (Id, RecordType, , Workload, UserType) Versionoraz wygenerowane identyfikatory żądań / odpowiedzi.

Attribute Applies to Required RawEventData field Uwagi / wpływ w przypadku braku
gen_ai.operation.name All M Operation Jeden z invoke_agent, execute_tool, chat, output_messages. Zakres spadł, jeśli był zaginiony lub nierozpoznany.
microsoft.tenant.id All M OrganizationId URL {tenantId} jest autorytatywny. Jeśli ustawisz to i to się nie zgadza, wniosek zostaje odrzucony (403).
gen_ai.agent.id All M TargetAgentId (IA, również najwyższy poziom AgentId); AgentId (ET, CH) Aplikacja do dzwonienia jest dostępna. Musi się zgadzać z adresem URL {agentId} i uwierzytelnioną aplikacją. Mismatch daje 403.
gen_ai.agent.name All M TargetAgentName (IA); AgentName (ET, CH) Defender / centrum administracyjne pokazują czysty GUID zamiast nazwy, jeśli brakuje.
microsoft.a365.agent.blueprint.id All M TargetAgentBlueprintID (IA); AgentBlueprintId (ET, CH) Plan jest odpowiedni. W przypadku standardowych aplikacji Entra bez blueprintu ponownie użyj appID agenta. W przeciwnym razie zwiększanie blueprintów w centrum administracyjnym się psuje.
gen_ai.agent.description All O -- Widok szczegółów w centrum administracyjnym jest pusty dla agenta.
gen_ai.agent.type All O PlatformTargetAgentType (IA); PlatformAgentType (ET); CopilotEventData.PlatformAgentType (CH) Etykieta dla systemu tożsamości, połączona z microsoft.a365.agent.platform.id sytuacjami, gdy agent nie ma rejestracji Entra. Tekst swobodny; Wybierz wartość, która jednoznacznie identyfikuje Twój system tożsamości. Pomiń, gdy agent ma rejestrację Entra – Agent 365 automatycznie klasyfikuje. Nie używaj wartości zarezerwowanych Microsoft (zobacz Wybieranie wartości).
microsoft.a365.agent.platform.id All O PlatformTargetAgentId (IA, również najwyższy poziom AlternateId); PlatformAgentId (ET, CH) Unikalne ID agenta w twoim systemie tożsamości nie-Entra. Free-form text. Ułóż razem z .gen_ai.agent.type Pomij, gdy agent ma rejestrację Entra. Zobacz wartości wybierania.
gen_ai.conversation.id All M ConversationId (IA, ET); CopilotEventData.ConversationId / CopilotEventData.ThreadId (CH) Główny klawisz łączenia dla przebiegu. Bez niego run nie pojawia się w widokach aktywności agenta Defender ani w centrum administracyjnym.
microsoft.channel.name All M ChannelName (IA, ET) Powierzchnia, po której agent biegnie. Używaj krótkiego tokena z małymi literami; Obecnie kanoniczne wartości używane przez filtry Defender / Admin Center to msteams oraz outlook. Niestandardowe ciągi (na przykład web, <your-product-name>) są akceptowane, ale nie przesuwają się w wbudowanych filtrach kanałowych. Ta sama wartość na każdym przęsły. Zobacz wartości wybierania.
microsoft.channel.link All O -- Channel deep-link.
microsoft.session.id All O SessionIdentity Sesja przewraca się pusto, jeśli jej brakuje.
microsoft.session.description All O -- Session description.
microsoft.conversation.item.link All O -- Głęboki link do wiadomości.
correlation.id All O -- Cross-service tracing. Dziś nie pojawia się w zaawansowanych polowaniach.
operation.source All O InvokeSource (IA) Identyfikator SDK / usługi emitującej telemetrię. Może to atrybut Zasobów.
client.address IA, ET, CH M ClientIP (IA, ET) Caller IP. Śledztwo oparte na IP zablokowane, jeśli puste.
server.address IA, ET, CH M ServerAddress (IA, ET) Endpoint, który twoja usługa wzywa.
server.port IA, ET, CH M ServerPort (IA) Zakodowane w ciągu (na przykład "443").
user.id IA M UserKey Microsoft Entra ID obiektu ludzkiego dzwoniącego. "Kto prowadził tego agenta" bez tego jest puste.
user.email IA O UserId UPN rozmówcy.
user.name IA O -- Wyświetlaj nazwę dzwoniącego.
gen_ai.input.messages IA, CH M -- Żądaj ładunku (ciąg JSON). Złapane do analizy dalej, ale jeszcze nie wynurzone podczas zaawansowanych polowań.
gen_ai.output.messages IA, CH, OM M -- Ładunek odpowiedzi (ciąg JSON).
gen_ai.execution.type IA O -- Jeden z HumanToAgent, Agent2Agent, EventToAgent.
microsoft.a365.agent.thought.process IA, CH O -- Rozumowanie w swobodnym tekście / łańcuch myślenia.
gen_ai.author.app.id OM O -- Microsoft Entra ID aplikacji aplikacji, która utworzyła lub utworzyła agenta.
gen_ai.tool.name ET M ToolName Tool name. Widoki korzystania z narzędzi Defender są puste, jeśli ich brakuje.
gen_ai.tool.type ET M ToolType Jeden z , , , , , , bing_grounding, , code_interpreter. file_searchAPIKnowledge SourceMCP ServerPower Platform Connectorfunction
gen_ai.tool.call.id ET M ToolId Identyfikator tego wywołania narzędzia.
gen_ai.tool.call.arguments ET M -- Argumenty narzędzi (ciąg JSON). Schwytany, ale jeszcze nie wynurzony podczas zaawansowanych polowań.
gen_ai.tool.call.result ET M -- Wynik narzędzia (ciąg JSON).
gen_ai.tool.description ET O ToolDescription Tool description.
gen_ai.tool.server.name ET O -- Nazwa hosta serwera narzędzi. Ustaw ten atrybut dla narzędzi MCP.
gen_ai.request.model CH M -- Nazwa modelu (na przykład ). gpt-4o Schwytany, ale jeszcze nie wynurzony podczas zaawansowanych polowań.
gen_ai.provider.name CH M -- Nazwa dostawcy (na przykład ). openai
gen_ai.usage.input_tokens CH O -- Liczba tokenów wejściowych, zakodowana łańcuchowo.
gen_ai.usage.output_tokens CH O -- Liczba tokenów wyjściowych, zakodowana łańcuchem znaków.
gen_ai.response.finish_reasons CH O -- Finish reason(s).
microsoft.a365.caller.agent.id IA M*² -- Dzwonię do agenta na szybko. Wymagane dla agent-agent.
microsoft.a365.caller.agent.name IA M*² -- Dzwonię do nazwy agenta.
microsoft.a365.caller.agent.blueprint.id IA M*² AgentBlueprintId Dzwonię do planu agenta. Wymagane dla wbudowanego A2A.
microsoft.a365.caller.agent.user.id IA M*² -- Dzwonię do identyfikatora użytkownika agenta.
microsoft.a365.caller.agent.user.email IA M*² -- Dzwonię do agenta UPN.
microsoft.a365.caller.agent.platform.id IA N/A -- Zarezerwowane dla alternatywnych identyfikatorów nie-Entra.
gen_ai.caller.agent.type IA N/A -- Agent 365 automatycznie się klasyfikuje.
microsoft.agent.user.id IA, ET, CH M*¹ TargetAgentUserKey (IA); UserKey (ET, CH) Microsoft Entra ID obiektu własnego konta użytkownika agenta. Wymagane dla sojuszników AI / agentów z ucieleśnieniami.
microsoft.agent.user.email IA, ET, CH O*¹ UserId (ET, CH) UPN konta użytkownika agenta.
span.SpanId All M OpId OTel SDK emituje to.
span.ParentSpanId All M*³ ParentId Wymagane tylko dla rozpięć niebędących pierwiastkiem; korzeń invoke_agent nie ma żadnego.
span.StartTimeUnixNano All M najwyższy poziom TimeGenerated (również CreationTime w RawEventData) Nanos epoki uniksa jako struna.
span.EndTimeUnixNano All M CompletionTime (IA, ET); CopilotEventData.CompletionTime (CH) Nie da się obliczyć czasu trwania, jeśli brakuje.
span.Status.Message All O*⁴ ErrorMessage (IA, ET); CopilotEventData.ErrorMessage (CH) Przyczyna nieudanych prób jest pusta, jeśli brakuje.
span.Status.Code All O*⁴ ErrorType (IA); CopilotEventData.ErrorType (CH) Kategoria błędu pusta, jeśli brakuje.

Note

Kilka atrybutów, które generujesz (takich jak argumenty narzędzi / wyniki, parametry modelu i głębokie linki kanałowe), jest akceptowanych przez Agenta 365 i wykorzystywanych przez widoki Microsoft Defender w dalszej fazie, ale nie są jeszcze widoczne jako klucz JSON CloudAppEvents.RawEventData. Ustaw je zgodnie z kolumną Wymagane – mogą zostać dodane do ładunku poszukiwań w przyszłej wersji.

Wybieranie wartości, gdy nie masz naturalnej

Niektóre wymagane atrybuty opisują koncepcje, które mogą nie istnieć w architekturze Twojego agenta. Jeśli naturalna wartość nie istnieje, oto co warto ustawić zamiast tego. Nie zostawiaj obowiązkowego pola pustego – nawet GUID z zerami ukryje Twój bieg przed niektórymi doświadczeniami z klientem.

Pytanie / scenariusz Field(s) Co ustawić
Mój agent to standardowa rejestracja aplikacji Entra (nie zbudowany na podstawie Identyfikator agenta Entra blueprint). gen_ai.agent.id Aplikacja Entra jest dostępna.
↑ ten sam scenariusz microsoft.a365.agent.blueprint.id Wykorzystaj tę samą wartość co gen_ai.agent.id (appId agenta). Schemat wymaga wartości niepustej; ponowne użycie appId agenta jest bezpiecznym domyślnym rozwiązaniem, gdy nie ma blueprintu.
Mój agent jest zbudowany na podstawie Identyfikator agenta Entra blueprintu – jednej lub wielu tożsamości agentów wybitych z tego samego blueprintu. gen_ai.agent.id Identyfikator tożsamości agenta ( appIdinstancji , nie blueprint).
↑ ten sam scenariusz microsoft.a365.agent.blueprint.id Plan jest odpowiedni. Wszystkie instancje wybite z tego samego blueprintu mają tę wartość.
Dzwoniący to użytkownik ludzki, a nie inny agent. Wszystko microsoft.a365.caller.agent.* i atrybuty gen_ai.caller.agent.* Omit. Są obowiązkowe tylko w sytuacjach agent-agent.
W relacji agent-to-agent: agent dzwoniący to standardowa aplikacja Entra (bez blueprintu). microsoft.a365.caller.agent.blueprint.id Ponownie wykorzystaj aplikację agenta dzwoniącego.
Mój agent nie jest współpracownikiem AI – nie ma własnego konta użytkownika w tenantze. Wszystkie microsoft.agent.user.* atrybuty Omit. Są obowiązkowe tylko wtedy, gdy agent ma własne konto użytkownika Identyfikator agenta Entra.
Mój agent nie ma pojęcia o sesji poza jednym przejściem. microsoft.session.id Opcjonalnie – pomij. Jeśli chcesz, aby każdy przebieg był osobną sesją, ustaw rozliczenie GUID na każdy run.
Mój agent nie ma pojęcia o rozmowie (jednorazowe, bezpaństwowe). gen_ai.conversation.id Generuj świeży GUID na każdy przebieg. Pole jest obowiązkowe; pominięcie tego usuwa uruchomienie z widoków aktywności agenta Defender oraz z Centrum administracyjne platformy Microsoft 365.
Dzwoniący nie ma adresu IP (na przykład autonomicznego zaplanowanego wyzwalacza). client.address Użyj stabilnego zastępczego zastępcy, który kontrolujesz (na przykład ). "0.0.0.0" Pole jest obowiązkowe; wartość pusta usuwa przebieg z pivotów badań opartych na IP.
Agent jest w trakcie procesu; nie ma osobnego "serwera" wywoływanego. server.address / server.port Użyj nazwy hosta maszyny, która uruchomiła agenta (na przykład ) oraz portu, myagent.example.comna którym nasłuchuje Twój punkt końcowy. Wymagane nawet wtedy, gdy nie ma osobnej usługi w dół łańcucha.
Mój chat span nie ma użycia tokenów modelowych. gen_ai.usage.input_tokens / gen_ai.usage.output_tokens Opcjonalnie – pomij. Jeśli masz przybliżone liczby, wyślij je jako .stringValue
Mój zakres nie ma żadnego błędu do zgłoszenia. span.Status.Message, span.Status.Code Ustaw status OTel na OK (kod numeryczny 1) i pomiń tę wiadomość. Potok konsultuje te pola tylko wtedy, gdy status wynosi .Error
Mój agent używa systemu tożsamości nie-Entra (agent nie ma rejestracji Entra). microsoft.a365.agent.platform.id i gen_ai.agent.type Ustaw oba na każdym przęsły. platform.id jest unikalnym identyfikatorem agenta w twoim systemie tożsamości; agent.type to krótka etykieta identyfikująca, o jaki system tożsamości chodzi. Oba są tekstem swobodnym – wybierz to, co pasuje do twojego systemu. Nie używaj wartości typów zarezerwowanych Microsoft: CustomBuiltAgentsUsingSDK, CopilotStudio, Foundry, DeclarativeAgent, Custom (wartości te są zarezerwowane dla powierzchni wewnętrznych Microsoft). Aplikacja do dzwonienia, którą uwierzytelniasz, nadal wymaga rejestracji Entra, aby korzystać z tych tras – para alternate-id opisuje agenta docelowego , nie dzwoniącego.
Jaką wartość powinienem położyć microsoft.channel.name? microsoft.channel.name Powierzchnia, po której agent biegnie. Defender i centrum administracyjne filtrują klucz z literalnego ciągu, więc używaj krótkiego, stabilnego tokena z małymi literami. Obecnie wartości kanoniczne to i ; outlookpowszechne powierzchnie skoncentrowane na kliencie również używają web, office, sharepoint, lub <your-product-name>.msteams Wybierz jedną wartość i trzymaj się jej – narzędzia nie potrafią pogodzić msteams i Microsoft Teams jako ten sam kanał.
Czy powinienem ustawić gen_ai.agent.type? gen_ai.agent.type Tylko jeśli też zakładasz ( microsoft.a365.agent.platform.id na przykład Twój agent nie ma rejestracji Entra). Para informuje agenta 365, z którego systemu tożsamości pochodzi agent. Wybierz krótką etykietę, która jednoznacznie identyfikuje Twój system tożsamości. Nie używaj CustomBuiltAgentsUsingSDK, CopilotStudio, Foundry, DeclarativeAgent ani Custom – te wartości są zarezerwowane dla użytku wewnętrznego Microsoft. Dla agentów zarejestrowanych w Entra pominąć pole; Agent 365 ją uzupełnia.
Jakie OTLP kind powinienem ustawić na moich spanach? span.kind Użyj wartości enum całkowitej, a nie proto-enum łańcucha - 1 (), 2INTERNAL(SERVER), (), 3 (CLIENT), 54PRODUCER(), ().CONSUMER Agent 365 akceptuje którykolwiek z tych elementów i nie wyprowadza zachowań widocznych dla klienta z , kindwięc 1 (INTERNAL) jest bezpiecznym domyślnym dla każdego okresu. Jeśli chcesz, aby kształt połączenia odzwierciedlał, INTERNAL to za invoke_agentoutput_messages / i CLIENT za chat / execute_tool jest rozsądne.

Related content

  • Last updated on