Ссылка атрибута наблюдаемости агента 365

Эта статья представляет собой каноническую спецификацию по атрибуту, используемую в конвейере введения Агента 365. Каждый диапазон, поглощённый Агентом 365 — будь то от Microsoft OpenTelemetry Distro, устаревшего Agent 365 Observability SDK или отправленный через прямой OTel — должен соответствовать ему. В каждой записи перечислены типы операций, к которым применяется атрибут, является ли это обязательным, имя поля, в которое попадает ваше значение для запросов на продвинутую охоту (если оно есть), и влияние при пропущенном доступе.

Если вы используете SDK или дистрибутив, SDK излучает эти атрибуты за вас. Раздел «Выбор значений» применяется только тогда, когда нужно отменить стандартный параметр. Если вы используете прямой путь OTel, вы излучаете все атрибуты вручную. Чтобы узнать, как собрать их в запрос, смотрите руководство по интеграции.

Attribute table

Все значения передаются как stringValue - количество токенов должно быть "42" (не 42); порты должны быть "443" (не 443).

Операция Легенда.IA, = invoke_agentET = execute_tool, CH = chat, OM = output_messages, All = применяется к каждой операции.

Required legend.

  • M: mandatory.
  • M*1: обязательно только для вооружённых агентов (у агента есть собственная учетная запись Entra ID для агентов).
  • M*2: обязательно только для звонков между агентами.
  • M*3: обязательно только для некорневых отсеков. Корень invoke_agent не имеет родителя.
  • O*4: необязательно, имеет значение только если статус span — Ошибка.
  • O: optional.
  • N/A: не излучайте. Агент 365 автоматически заполняется.

Столбец «RawEventData field » называет JSON-ключ внутри CloudAppEvents.RawEventData , в котором канонический продвинутый запрос в Verifying ingestion парсирует. Пустая ячейка означает, что атрибут сегодня не отображается CloudAppEvents . Вы всё равно должны излучать его (согласно столбцу «Требуется»), потому что Agent 365 использует его для загрузки, разрешения родителей и просмотров активности агента в Microsoft Defender. Однако сегодня нельзя напрямую запросить его из Microsoft Defender Advanced Hunting.

Note

Agent 365 автоматически заполняет статические поля записи (Id, RecordType, , WorkloadUserTypeVersion, ) и сгенерированные идентификаторы запросов и ответов.

Attribute Applies to Required RawEventData field Примечания / влияние при отсутствии
gen_ai.operation.name All M Operation Один из invoke_agent, execute_tool, chat, output_messages. Пролёт опускается, если отсутствует или не распознается.
microsoft.tenant.id All M OrganizationId {tenantId} URL является авторитетным. Если вы установите это значение и он не согласен, запрос отклоняется (403).
gen_ai.agent.id All M TargetAgentId (IA); AgentId (ET, CH) Приложение для звонков — приложение для звонков. Должно совпадать URL {agentId} и аутентифицированное приложение. Несоответствие возвращает 403.
gen_ai.agent.name All M TargetAgentName (IA); AgentName (ET, CH) Defender и Admin Center показывают исходный GUID вместо имени, если его нет.
microsoft.a365.agent.blueprint.id All M TargetAgentBlueprintID (IA); AgentBlueprintId (ET, CH) Чертеж в приложении. Для стандартных приложений Entra без чертежа используйте повторно appId агента. Сводки чертежей в административном центре в противном случае ломаются.
gen_ai.agent.description All O -- Подробный просмотр в административном центре пуст для агента.
gen_ai.agent.type All O PlatformTargetAgentType (IA); PlatformAgentType (ET); CopilotEventData.PlatformAgentType (CH) Ярлык для вашей системы идентификации, в сочетании с microsoft.a365.agent.platform.id тем, когда у агента нет регистрации Entra. Текст в свободной форме; Выберите значение, которое уникально определяет вашу систему идентичности. Опускайте, если у агента есть регистрация Entra. Агент 365 автоматически классифицируется. Не используйте значения, зарезервированные Microsoft (см. Значения выбора).
microsoft.a365.agent.platform.id All O PlatformTargetAgentId (IA, также высший AlternateIdуровень); PlatformAgentId (ET, CH) Уникальный идентификатор агента в вашей системе идентификации, не связанной с Entra. Free-form text. Вместе с gen_ai.agent.type. Опускайте, если у агента есть регистрация Entra. См. раздел «Выбор значений».
gen_ai.conversation.id All M ConversationId (IA, ET); CopilotEventData.ConversationId / CopilotEventData.ThreadId (CH) Основной ключ join для забега. Без него запуск не отображается в просмотре активности агента Defender или в административном центре.
microsoft.channel.name All M ChannelName (IA, ET) Поверхность, по которой работает агент. Используйте короткий токен с строчной буквы. Канонические значения, используемые сегодня фильтрами Defender и админ-центров, — это msteams и outlook. Пользовательские строки (например web, <your-product-name>) принимаются, но не вращаются в встроенных фильтрах каналов. Используйте одно и то же значение на каждом пролёте. См. раздел «Выбор значений».
microsoft.channel.link All O -- Channel deep-link.
microsoft.session.id All O SessionIdentity Поворот сессии пусты, если отсутствует.
microsoft.session.description All O -- Session description.
microsoft.conversation.item.link All O -- Глубокая ссылка на сообщение.
correlation.id All O -- Cross-service tracing. Сегодня его не всплывали в продвинутой охоте.
operation.source All O InvokeSource (IA) Идентификатор SDK или сервиса, излучающего телеметрию. Возможно, это атрибут Ресурса.
client.address IA, ET, CH M ClientIP (IA, ET) Caller IP. Расследование по IP-адресу заблокировано, если пусто.
server.address IA, ET, CH M ServerAddress (IA, ET) Конечная точка, которую зовёт ваша служба.
server.port IA, ET, CH M ServerPort (IA) Строковое кодирование (например "443").
user.id IA M UserKey Microsoft Entra — идентификатор объекта вызывающего человека. «Кто управлял этим агентом» пусто без него.
user.email IA O UserId UPN звонящего.
user.name IA O -- Покажите имя звонящего.
gen_ai.input.messages IA, CH M -- Запрос полезной нагрузки (строка JSON). Пойман для анализа ниже по течению, но ещё не всплыл в продвинутой охоте.
gen_ai.output.messages IA, CH, OM M -- Полезная нагрузка отклика (строка JSON).
gen_ai.execution.type IA O -- Один из HumanToAgent, Agent2Agent, EventToAgent.
microsoft.a365.agent.thought.process IA, CH O -- Свободное рассуждение или цепочка мыслей.
gen_ai.author.app.id OM O -- Microsoft Entra — идентификатор приложения приложения, которое создало или создало агента.
gen_ai.tool.name ET M ToolName Tool name. Просмотры использования инструментов Defender пусты, если отсутствуют.
gen_ai.tool.type ET M ToolType Один из function, Power Platform Connector, MCP Server, APIKnowledge Source, bing_grounding. code_interpreterfile_search
gen_ai.tool.call.id ET M ToolId Идентификатор для этого вызова инструмента.
gen_ai.tool.call.arguments ET M -- Аргументы инструментов (строка JSON). Пойманные, но ещё не всплыли в продвинутой охоте.
gen_ai.tool.call.result ET M -- Результат инструмента (строка JSON).
gen_ai.tool.description ET O ToolDescription Tool description.
gen_ai.tool.server.name ET O -- Имя сервера инструмента. Задайте этот атрибут для инструментов MCP.
gen_ai.request.model CH M -- Название модели (например, gpt-4o). Пойманные, но ещё не всплыли в продвинутой охоте.
gen_ai.provider.name CH M -- Имя поставщика (например, openai).
gen_ai.usage.input_tokens CH O -- Количество входных токенов, закодировано строками.
gen_ai.usage.output_tokens CH O -- Количество токенов вывода, закодировано строками.
gen_ai.response.finish_reasons CH O -- Finish reasons.
microsoft.a365.caller.agent.id IA M*2 AgentId (IA) Звоню агенту appId. Требуется для взаимодействия агента с агентом.
microsoft.a365.caller.agent.name IA M*2 AgentName (IA) Вызываю агента с указанием имени.
microsoft.a365.caller.agent.blueprint.id IA M*2 AgentBlueprintId Приложение Blueprint агента для звонка. Требуется для воплощённого A2A.
microsoft.a365.caller.agent.user.id IA M*2 -- Идентификатор пользователя звонящего агента.
microsoft.a365.caller.agent.user.email IA M*2 -- Звоню агенту UPN.
microsoft.a365.caller.agent.platform.id IA N/A -- Зарезервировано для альтернативных удостоверений, не относящихся к Entra.
gen_ai.caller.agent.type IA N/A -- Агент 365 автоматически классифицируется.
microsoft.agent.user.id IA, ET, CH M*1 TargetAgentUserKey (IA); UserKey (ET, CH) Microsoft Entra — идентификатор объекта собственной учетной записи агента. Требуется для ИИ-товарищей по команде и воплощённых агентов.
microsoft.agent.user.email IA, ET, CH O*1 UserId (ET, CH) UPN пользовательского аккаунта агента.
span.SpanId All M OpId OTel SDK излучает это.
span.ParentSpanId All M*3 ParentId Требуется только для некорневых развязок; корень invoke_agent их не имеет.
span.StartTimeUnixNano All M Высший уровень TimeGenerated (также CreationTime в RawEventData) Unix эпохальные nanos в виде строки.
span.EndTimeUnixNano All M CompletionTime (IA, ET); CopilotEventData.CompletionTime (CH) Длительность нельзя вычислить, если отсутствует.
span.Status.Message All O*4 ErrorMessage (IA, ET); CopilotEventData.ErrorMessage (CH) Коренная причина неудачных прохождений пуста, если отсутствует.
span.Status.Code All O*4 ErrorType (IA); CopilotEventData.ErrorType (CH) Категория ошибки пустая, если отсутствует.

Note

Агент 365 принимает несколько используемых вами атрибутов, таких как аргументы и результаты инструмента, параметры модели и глубокие каналы. Нижние версии Microsoft Defender используют эти атрибуты, но Agent 365 пока не показывает их как CloudAppEvents.RawEventData JSON-ключ. Настройте их по столбцу «Обязательно». Возможно, их добавят в охотничью нагрузку в будущем выпуске.

Important

В invoke_agent записях (IA) AgentIdполя , AgentNameи AgentBlueprintId описывают вызывающего агента, а не вызываемого агента. Агент 365 наполняет их по microsoft.a365.caller.agent.* атрибутам. Когда человек вызывает вашего агента, опустите эти атрибуты so AgentId и AgentBlueprintId появятся как полностью нулевый GUID (00000000-0000-0000-0000-000000000000) и AgentName пустой в аудитских записях и Microsoft Purview. Значение всех нулей ожидается для забегов, инициированных человеком. Для идентификации вызываемого агента используйте TargetAgentId, TargetAgentName, и TargetAgentBlueprintID.

Выбирать значения, когда у тебя нет естественного

Некоторые обязательные атрибуты описывают концепции, которые могут отсутствовать в архитектуре вашего агента. Если естественное значение недоступно, установите следующие значения. Не оставляйте обязательное поле пустым. Даже полностью нулевый GUID скрывает ваш забег от некоторых взаимодействий с клиентами. Это правило применяется только к обязательным атрибутам. Это не относится к атрибутам звонящего-агента при запусках, инициированных человеком, где ожидается полный нулевой AgentId уровень в invoke_agent записях.

Вопрос / сценарий Field(s) Что поставить
Мой агент — стандартное приложение Entra для регистрации (не построен по Entra ID для агентов чертежу). gen_ai.agent.id Приложение Entra appId.
↑ Та же ситуация microsoft.a365.agent.blueprint.id Используйте то же значение, что и gen_ai.agent.id (appId агента). Схема требует непустого значения; Повторное использование Agent AppId по умолчанию является безопасным вариантом, если нет чертежа.
Мой агент построен по Entra ID для агентов чертежу — один или несколько идентификаторов агентов, созданных по одному и тому же чертежу. gen_ai.agent.id AppId идентичности агента (instance appId, а не blueprint).
↑ Та же ситуация microsoft.a365.agent.blueprint.id Чертеж в приложении. Все экземпляры, отчеканенные по одному и тому же чертежу, имеют это значение.
Звонящий — это человек, а не другой агент. Все microsoft.a365.caller.agent.* и gen_ai.caller.agent.* атрибуты Omit. Они обязательны только в ситуациях между агентами. В invoke_agent записях звонящий вводит AgentId и AgentBlueprintId показывает GUID с нулями. Используйте TargetAgentId для идентификации вашего агента.
В агенте-агенте: вызывающий агент — это стандартное приложение Entra (без чертежа). microsoft.a365.caller.agent.blueprint.id Повторно используйте приложение агента по вызову.
Мой агент не является коллегой по ИИ — у него нет собственной учетной записи в арендаторе. Все microsoft.agent.user.* атрибуты Omit. Они обязательны только если у агента есть собственная учетная запись пользователя Entra ID для агентов.
Мой агент не понимает, что такое сессия, кроме одного запуска. microsoft.session.id Опционально — опустить. Если хотите, чтобы каждый забег был отдельной сессией, установите GUID для каждого запуска.
Мой агент не понимает, что такое разговор (одноразовый разговор, без гражданства). gen_ai.conversation.id Генерируйте новый GUID за каждую пробежку. Поле обязательно; пропуск убирает запуск из видов активности агентов Defender и Центр администрирования Microsoft 365.
У звонящего нет IP (например, автономного запланированного триггера). client.address Используйте стабильный заполняющий элемент, который вы контролируете (например, "0.0.0.0"). Поле обязательно; пустое значение убирает поток из IP-ориентированных опорных элементов расследования.
Агент работает в процессе; Отдельного «сервера» не вызывается. server.address / server.port Используйте имя хоста машины, на которой запускался агент (например), myagent.example.comи порт, на котором слушает ваш конечный пункт. Это обязательно даже если нет отдельного сервиса по низу.
В моём chat span нет использования токенов модели. gen_ai.usage.input_tokens / gen_ai.usage.output_tokens Опционально — опустить. Если у вас есть приблизительное количество счёта, отправьте их как stringValue.
В моём Span нет ошибки, которую можно было бы сообщить. span.Status.Message, span.Status.Code Установите статус OTel на OK (числовой код 1) и опустите сообщение. Конвейер обращается к этим полям только при статусе .Error
Мой агент использует систему идентификации, не принадлежащую Entra (у агента нет регистрации Entra). microsoft.a365.agent.platform.id и gen_ai.agent.type. Поставьте оба на каждый пролёт. platform.id — уникальный идентификатор агента в вашей системе идентификации; agent.type — короткая метка, которая определяет, какая именно система идентичности является. Оба текста свободной формы — выбирайте то, что подходит вашей системе. Не используйте значения типа Microsoft зарезервированных: CustomBuiltAgentsUsingSDK, CopilotStudio, Foundry, DeclarativeAgent, Custom (эти значения зарезервированы для внутренних Microsoft поверхностей). Вызывающее приложение, с которым вы аутентифицируетесь, всё равно требует регистрации Entra для использования этих маршрутов — пара альтернативных идентификаторов описывает целевого агента, а не вызывающего.
Какую ценность стоит ввести microsoft.channel.name? microsoft.channel.name Поверхность, по которой работает агент. Фильтры Defender и Admin Center зависят от буквальной строки, поэтому используйте короткий, стабильный токен с маленькой буквы. Сегодня канонические значения — и msteamsoutlook; распространённые поверхности, ориентированные на клиента, также используют web, office, sharepoint, или <your-product-name>. Выберите одно значение и придерживайтесь его — инструменты не могут согласовать msteams и Microsoft Teams с одним каналом.
Стоит ли ставить gen_ai.agent.type? gen_ai.agent.type Только если вы также устанавливаете microsoft.a365.agent.platform.id (например, у вашего агента нет регистрации Entra). Пара сообщает агенту 365, из какой системы идентичности происходит агент. Выберите короткий ярлык, который уникально идентифицирует вашу систему идентичности. Не используйте CustomBuiltAgentsUsingSDK, CopilotStudio, Foundry, DeclarativeAgent или Custom — эти значения зарезервированы для внутреннего Microsoft. Для агентов, зарегистрированных в Entra, исключите это поле; Агент 365 заполняет её.
Какой OTLP kind мне стоит установить на свои пролёты? span.kind Используйте целое значение enum, а не прото-строку enum - 1 (INTERNAL), 2 (SERVER), 3 (), (CLIENT), 4 (), (PRODUCER), (5). CONSUMER Agent 365 принимает любой из этих параметров и не выводит поведение, видимое для клиента, из kind, поэтому 1 (INTERNAL) является безопасным стандартом для каждого диапазона. Если вы хотите, чтобы форма отражала форму вызова, INTERNAL то дляinvoke_agent / output_messagesи CLIENT для chat / execute_tool — это разумно.

Related content

  • Последнее обновление: