Примечание.
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
Это каноническая спецификация по атрибутам, используемая в конвейере введения Agent 365. Каждый диапазон, поглощённый Агентом 365 — будь то Microsoft OpenTelemetry Distro, Agent 365 SDK или отправленный через direct 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*¹: обязательно только для воплощённых агентов (у агента есть собственная Entra ID для агентов учетная запись пользователя).
- M*²: обязательно только для звонков между агентами.
-
M*³: обязательно только для некорневых отсеков. Корень
invoke_agentне имеет родителя. - O*⁴: необязательно, значимо только тогда, когда статус span — Ошибка.
- O: optional.
- N/A: не излучайте. Агент 365 автоматически заполняется.
Столбец «RawEventData field » называет JSON-ключ внутри CloudAppEvents.RawEventData , в котором канонический продвинутый запрос в Verifying ingestion парсирует. Пустая ячейка означает, что атрибут not выставлен в CloudAppEvents сегодня — вы всё равно должны излучать его (согласно столбце Required), потому что Agent 365 использует его для погружения, разрешения родителей и просмотров активности агента Microsoft Defender, но сегодня он не подлежит прямому запросу Microsoft Defender Advanced Hunt.
Note
Агент 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уровень); 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. file_searchcode_interpreter |
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 reason(s). |
microsoft.a365.caller.agent.id |
IA | M*² | -- | Звоню агенту appId. Требуется для взаимодействия агента с агентом. |
microsoft.a365.caller.agent.name |
IA | M*² | -- | Вызываю агента с указанием имени. |
microsoft.a365.caller.agent.blueprint.id |
IA | M*² | AgentBlueprintId |
Приложение Blueprint агента для звонка. Требуется для воплощённого A2A. |
microsoft.a365.caller.agent.user.id |
IA | M*² | -- | Идентификатор пользователя звонящего агента. |
microsoft.a365.caller.agent.user.email |
IA | M*² | -- | Звоню агенту 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*¹ |
TargetAgentUserKey (IA); UserKey (ET, CH) |
Microsoft Entra — идентификатор объекта собственной учетной записи агента. Обязательно для ИИ-товарищей по команде / воплощённых агентов. |
microsoft.agent.user.email |
IA, ET, CH | O*¹ |
UserId (ET, CH) |
UPN пользовательского аккаунта агента. |
span.SpanId |
All | M | OpId |
OTel SDK излучает это. |
span.ParentSpanId |
All | M*³ | 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*⁴ |
ErrorMessage (IA, ET); CopilotEventData.ErrorMessage (CH) |
Коренная причина неудачных прохождений пуста, если отсутствует. |
span.Status.Code |
All | O*⁴ |
ErrorType (IA); CopilotEventData.ErrorType (CH) |
Категория ошибки пустая, если отсутствует. |
Note
Несколько атрибутов, которые вы используете (например, аргументы / результаты инструмента, параметры модели и глубокие каналы), принимаются агентом 365 и используются в следующих Microsoft Defender представлениях, но пока не отображаются как CloudAppEvents.RawEventData JSON-ключ. Всё равно устанавливайте их по столбцу Required — возможно, они появятся в охотничьей нагрузке в будущем выпуске.
Выбирать значения, когда у тебя нет естественного
Некоторые обязательные атрибуты описывают концепции, которые могут отсутствовать в архитектуре вашего агента. Если естественного значения нет, вот что стоит установить вместо этого. Не оставляйте обязательное поле пустым — даже полностью нулевой GUID скроет ваш забег от некоторых взаимодействий с клиентами.
| Вопрос / сценарий | 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. Они обязательны только в ситуациях между агентами. |
| В агенте-агенте: вызывающий агент — это стандартное приложение 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), (CONSUMER). 5 Agent 365 принимает любой из этих параметров и не выводит поведение, видимое для клиента, из kind, поэтому 1 (INTERNAL) является безопасным стандартом для каждого диапазона. Если вы хотите, чтобы форма отражала форму вызова, INTERNAL то для / output_messagesinvoke_agentи CLIENT для chat / execute_tool — это разумно. |