Referencja atrybutu obserwowalności agenta 365

Ten artykuł to kanoniczna specyfikacja atrybutów po atributach używana przez pipeline Agent 365. Każdy pakiet pobierany przez Agenta 365 – czy to emitowany przez dystrybucję Microsoft OpenTelemetry, przestarzały Agent 365 Observability SDK, czy przesyłany bezpośrednio przez OTel – musi być zgodny z tym rozwiązaniem. 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. Sekcja Wybieranie wartości dotyczy tylko wtedy, gdy musisz nadpisać domyślne ustawienie. Jeśli używasz bezpośredniej ścieżki OTel, emitujesz wszystkie atrybuty ręcznie. Aby dowiedzieć się, jak je złożyć w żądanie, zobacz przewodnik integracyjny.

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*1: obowiązkowe tylko dla agentów emboed (agent ma własne konto użytkownika Identyfikator agenta Entra).
  • M*2: obowiązkowe tylko dla rozmów agent-agent.
  • M*3: obowiązkowe tylko dla rozpięć niebędących pierwiastkami. Korzeń invoke_agent nie ma rodzica.
  • O*4: opcjonalne, istotne tylko wtedy, gdy status span 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 nie jest widoczny w dzisiejszym terminie CloudAppEvents . Powinieneś je nadal emitować (zgodnie z kolumną Wymagane), ponieważ Agent 365 używa ich do pobierania, rozdzielczości nadrzędnej oraz widoków aktywności agenta w Microsoft Defender. Jednak dziś nie możesz bezpośrednio zapytać o to z zaawansowanego poszukiwania Microsoft Defender.

Note

Agent 365 automatycznie wypełnia pola statycznego rekordu (Id, RecordType, , WorkloadUserType, Version) oraz wygenerowane ID żądań i 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 tę wartość i się nie zgadza, wniosek zostaje odrzucony (403).
gen_ai.agent.id All M TargetAgentId (IA); 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 i 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. Pomij, gdy agent ma rejestrację Entra. Agent 365 automatycznie się 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) Unikalny identyfikator 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żyj krótkiego tokena z małą literą. Kanoniczne wartości używane dziś przez filtry Defender i centrum administracyjnego 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. Używaj tej samej wartości 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 lub usługi emitującej telemetrię. Może to cecha 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 formie wolnego tekstu lub ł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 , , , , , , function, , Power Platform Connector. MCP ServerAPIKnowledge Sourcebing_groundingcode_interpreterfile_search
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 reasons.
microsoft.a365.caller.agent.id IA M*2 AgentId (IA) Dzwonię do agenta na szybko. Wymagane dla agent-agent.
microsoft.a365.caller.agent.name IA M*2 AgentName (IA) Dzwonię do nazwy agenta.
microsoft.a365.caller.agent.blueprint.id IA M*2 AgentBlueprintId Dzwonię do planu agenta. Wymagane dla wbudowanego A2A.
microsoft.a365.caller.agent.user.id IA M*2 -- Dzwonię do identyfikatora użytkownika agenta.
microsoft.a365.caller.agent.user.email IA M*2 -- 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*1 TargetAgentUserKey (IA); UserKey (ET, CH) Microsoft Entra ID obiektu własnego konta użytkownika agenta. Wymagane dla sojuszników AI i agentów z ucieleśnieniami.
microsoft.agent.user.email IA, ET, CH O*1 UserId (ET, CH) UPN konta użytkownika agenta.
span.SpanId All M OpId OTel SDK emituje to.
span.ParentSpanId All M*3 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*4 ErrorMessage (IA, ET); CopilotEventData.ErrorMessage (CH) Przyczyna nieudanych prób jest pusta, jeśli brakuje.
span.Status.Code All O*4 ErrorType (IA); CopilotEventData.ErrorType (CH) Kategoria błędu pusta, jeśli brakuje.

Note

Agent 365 akceptuje kilka atrybutów, które emitujesz, takich jak argumenty i wyniki narzędzi, parametry modelu oraz głębokie linki kanałowe. Widoki Microsoft Defender korzystają z tych atrybutów, ale Agent 365 nie udostępnia ich jeszcze jako klucza CloudAppEvents.RawEventData JSON. Ustaw je zgodnie z kolumną Wymagane. Mogą zostać dodane do ładunku polowań w przyszłej wersji.

Important

W rekordach (IA) pola AgentId, AgentName, i opisują invoke_agentAgentBlueprintId agenta wywołującego, a nie wywołanego agenta. Agent 365 zasypuje je z atrybutów microsoft.a365.caller.agent.* . Gdy człowiek wywoła agenta, pomiń te atrybuty, które AgentId pojawiają się AgentBlueprintId jako GUID z samymi zerami (00000000-0000-0000-0000-000000000000) i AgentName są puste w rejestrach audytu oraz Microsoft Purview. Wartość "zero" jest oczekiwana dla biegów inicjowanych przez człowieka. Aby zidentyfikować wywołanego agenta, użyj TargetAgentId, TargetAgentName, oraz TargetAgentBlueprintID.

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 jest dostępna, ustaw następujące wartości. Nie zostawiaj obowiązkowego pola pustego. Nawet GUID z zerami ukrywa Twój bieg przed niektórymi doświadczeniami z klientem. Ta zasada dotyczy tylko atrybutów obowiązkowych. Nie dotyczy atrybutów agenta wywołującego w ruchach inicjowanych przez człowieka, gdzie AgentId oczekuje się zer w invoke_agent rekordach.

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. Na rekordach invoke_agent dzwoniący AgentIdAgentBlueprintId wyświetla GUID składający się wyłącznie z zer. Użyj TargetAgentId do identyfikacji swojego agenta.
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 to unikalny identyfikator agenta w twoim systemie tożsamości; agent.type jest krótką etykietą identyfikującą, o który 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 ; msteamspowszechne powierzchnie skoncentrowane na kliencie również używają outlook, web, office, lub sharepoint.<your-product-name> 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 (), INTERNAL2(SERVER), (), 3 (CLIENT), 4PRODUCER5(), ().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_agent / output_messagesi CLIENT za chat / execute_tool jest rozsądne.

Related content

  • Ostatnia aktualizacja o