Понятия наблюдаемости Agent 365

В этой статье объясняется модель данных наблюдаемости Agent 365, включая то, какие телеметрические агенты излучают, кто может это излучать, где она приземляется и какие ограничения применяются. Используйте эти концепции для планирования интеграции и понимания телеметрии в дистрибутиве Microsoft OpenTelemetry, Agent 365 SDK и прямом OTel.

Note

Сведения на уровне протокола, включая маршруты URL из раздела Проверка подлинности, коды ошибок HTTP из раздела Ограничения и условия отбрасывания данных, а также ограничения на размер и частоту запросов, применимы только к прямому пути OTel. Пакет SDK и Distro берут эти детали на себя. Остальная часть этой статьи (глоссарий, поток данных, модели удостоверений, области, условия отбрасывания данных, где отображаются данные) применима к каждому пути.

Выбор пути интеграции

Все три пути передают в Agent 365 одну и ту же модель данных трассировки. Выберите:

Path Description
Microsoft OpenTelemetry Distro Рекомендуется для новых интеграций. Единый пакет SDK наблюдаемости в Agent 365, Microsoft Foundry, Azure Monitor и других службах.
Агент 365 SDK (SDK наблюдаемости) Более ранний SDK. Продолжает работать без критических изменений, однако больше не рекомендуется для новых интеграций. Руководство по миграции для существующих пользователей SDK будет опубликовано позже.
Прямой OTel Сырой путь OTLP/HTTP. Используйте этот вариант только в том случае, если у вас уже настроен конвейер OpenTelemetry, используемый фреймворк агента не поддерживает пакет SDK Agent 365 или ваш агент написан на языке, который SDK пока не поддерживает (например, Java).

Какой бы метод интеграции вы ни выбрали, будут применяться описанные ниже модель данных, модели удостоверений, области, лимиты и конечные платформы.

Глоссарий наблюдаемости агента 365

Срок Description
Идентификатор приложения (appId) Идентификатор приложения, выдаваемый при регистрации идентификатора агента Microsoft Entra или Microsoft Entra ID для агентов.
- Равен OAuthclient_id, а не идентификатору объекта Microsoft Entra.
- В этих документах «agent id» и «blueprint id» оба означают appId.
Разговор Логическая цепочка взаимодействия агентов, например, чат в Teams.
- Идентифицировано .gen_ai.conversation.id
- Основной ключ join для запуска.
Channel Поверхность, по которой работает агент: msteams, outlook, web, и так далее.
Беги Одно сообщение пользователя входит, один агент отвечает наружу. Моделируется как дерево OTel, разделяющих .traceId

Как работает наблюдаемость агента 365

Для обзора Agent 365 и того, какую телеметрию он собирает, см. Обзор Microsoft Agent 365.

Вы отправляете телеметрию в виде данных трассировки OpenTelemetry:

  • Дерево элементов трассировки, описывающее одно выполнение (одно входящее сообщение пользователя, один исходящий ответ агента).
  • Каждый элемент трассировки описывает отдельный шаг — вызов агента верхнего уровня, вызов LLM, вызов инструмента или итоговый ответ.

Поток данных о наблюдаемости агента 365

Следующая схема показывает, как телеметрия агента проходит через аутентификацию и поступление наблюдаемости агента 365 к последующим опытам Microsoft 365.

Диаграмма потока данных наблюдаемости агента 365.

Модели идентичности

Для полного объяснения моделей идентичности агента (стандартная регистрация приложений Microsoft Entra против Microsoft Entra Agent ID agent identity blueprint, включая AI-командных партнёров) см. раздел Agent identity. Выбор модели удостоверений определяет, какой поток проверки подлинности и конечную точку вы используете.

Если у вашего агента нет регистрации Microsoft Entra, он не может использовать эти маршруты напрямую. Идентифицируйте агента через альтернативные атрибуты ID (см. ссылку на атрибуты) и свяжитесь с командой агента 365 по поводу соответствующего входного пути.

Authentication

Проверка подлинности зависит от того, выполняет ли служба проверку подлинности от собственного имени или от имени пользователя. Ветвь определяет поток OAuth, утверждение токена, содержащее разрешение, и маршрут URL-адреса.

  • Служба выполняет проверку подлинности от собственного имени: нет вошедшего пользователя — автономный, запланированный или управляемый событиями сценарий.

    • Поток OAuth: служба — служба (S2S) — учетные данные клиента.
    • Утверждение токена: roles.
    • Маршрут URL-адреса: /observabilityService/....

  • Служба выполняет проверку подлинности от имени пользователя: для ИИ-помощников или для собственной учетной записи пользователя агента.

    • Поток OAuth: от имени (OBO).
    • Утверждение токена: scp.
    • Маршрут URL-адреса: /observability/....

Одно и то же приложение агента может участвовать в обоих потоках, например ИИ-помощник, который также выполняет ночной автономный процесс суммирования. Для получения дополнительной информации см. разделы Поток OAuth автономного приложения и Поток On-Behalf-Of.

Полные инструкции по формированию токенов для каждой комбинации модели удостоверений и потока см. в разделе Сценарии проверки подлинности руководства по интеграции.

Удостоверение агента привязано к URL-адресу

Значение {agentId} в URL-адресе должно соответствовать appId вызывающего приложения (утверждение appid или azp в вашем токене). В случае несоответствия возвращается 403 Forbidden. Для удостоверений, созданных на основе схемы, значение {agentId} соответствует appId удостоверения агента, а не appId схемы.

Кроме того, для каждого отправляемого элемента трассировки необходимо задать значение gen_ai.agent.id, равное тому же appId. Сервер проверяет указанное в полезных данных удостоверение агента на соответствие прошедшему проверку подлинности агенту и отклоняет несоответствия. Этот шаг позволяет обнаружить случаи, когда элементы трассировки нескольких агентов случайно смешиваются в одном запросе.

Область (делегированная) или роль приложения (приложение) — это именованное разрешение, которое Microsoft Entra добавляет в маркер доступа. Для телеметрии Agent 365 разрешением является Agent365.Observability.OtelWrite для ресурса наблюдаемости Agent 365 (аудитория 9b975845-388f-4429-889e-eab1ef63949c).

Одно и то же имя разрешения зарегистрировано для обоих типов:

  • Роль приложения для автономного потока (S2S/учетные данные клиента). Попадает в утверждение roles. Выбирается <resource>/.default.
  • Делегированная область для потока OBO. Попадает в утверждение scp. Выбирается <resource>/Agent365.Observability.OtelWrite (или <resource>/.default).

Agent 365 также предоставляет разрешение на чтение, Agent365.Observability.OtelRead, которое используется операторами для запроса телеметрии Agent 365. Большинству партнеров это не требуется — в этой документации описывается только прием данных.

Добавьте разрешение в своё приложение

  • Для стандартной регистрации приложения Microsoft Entra: на портале Azure добавьте Agent365.Observability.OtelWrite (роль приложения для S2S, область разрешений для делегированного доступа) в разделе Разрешения API регистрации приложения агента.
  • Для схемы: агенты, созданные на основе схемы удостоверения агента ИД агента Microsoft Entra, наследуют разрешения OAuth, определенные в схеме, поэтому администратор клиента предварительно настраивает разрешения один раз. Каждый экземпляр агента, созданный на основе этой схемы, автоматически получает эти разрешения. См. раздел Настройка наследуемых разрешений для схем удостоверений агента.

Прежде чем токены будут выполнять роль или область действия, администратор арендатора в арендаторе клиента должен дать согласие. См. Предоставление агентам доступа к ресурсам Microsoft 365.

Без согласия получение токена не заканчивается с AADSTS65001 помощью (The user or administrator has not consented to use the application with ID...) или токен выдаётся без roles претензии или scp , и конечная точка погружения отклоняет запрос с 403.

Согласие предоставляется один раз для каждого клиента, и затем применяется ко всем экземплярам, созданным на основе схемы. Повторное предоставление согласия требуется только в том случае, если в схему добавляется новое разрешение.

Ограничения и условия отбрасывания данных

Знание этих ограничений заранее предотвращает сюрпризы при интеграции. Некоторые сбои возвращают успешный HTTP-статус, хотя в ответе сообщается, что телеметрия не была принята.

Ограничения на уровне передачи данных:

  • Вы должны указывать api-version=1 это в каждом запросе.
  • Максимальный размер тела запроса составляет 1 МБ. Возврат 413 Payload Too Largeбольших запросов.
  • У обоих маршрутов разные лимиты на количество запросов. При получении ответа 429 учитывайте значение Retry-After (установлено значение 1 секунда) и выполняйте повторные попытки с увеличивающейся задержкой и случайным разбросом.

Встроенные сторонние интеграции, использующие аутентификацию S2S, могут вызывать конечную точку права на использование арендатора в качестве опционального предварительного просмотра перед отправкой телеметрии. Когда вы используете конечную точку, полагайтесь на её решение, а не на выводы о пригодности только по согласию или лицензированию. enabled: false Ответ означает, что арендатор в настоящее время не имеет права на участие. Безтело 503 Service Unavailable означает, что нельзя было определить право на участие. Если Retry-After вам всё ещё нужен результат по заголовку.

Отклики в случае ошибки:

  • 403 Forbidden: Токен, в котором отсутствует необходимая роль или область применения, или {agentId} в URL не совпадает с appid или azp вашего токена.
  • 413 Payload Too Large: Объём тела превышает 1 МБ.
  • 429 Too Many Requests: Достигнут лимит скорости; Честь Retry-After: 1 и отступай с дрожью.

Условия отбрасывания данных (HTTP принимает запрос, но данные не доходят до последующих этапов обработки):

# Condition Behavior
1 Элемент трассировки gen_ai.operation.name отсутствует или его значение не входит в список {invoke_agent, execute_tool, chat, output_messages} Отбрасывание на уровне отдельного элемента трассировки. Отображается в partialSuccess.rejectedSpans + errorMessage.
2 Ни одному пользователю в клиенте заказчика не назначена лицензия Microsoft 365 E7 или Microsoft Agent 365. В клиенте как минимум одному пользователю должна быть назначена лицензия (наличия SKU в клиенте недостаточно — именно назначение лицензии запускает внутренний рабочий процесс Defender). Лицензированный пользователь не обязательно должен быть человеком, который вызывает агент. Запрос возвращает 200 OK, но запись каждого пролёта results имеет rejected статус и причину tenant_not_licensed.

А 200 OK не является доказательством проглатывания. Проверьте ответы resultsи используйте поток верификации для подтверждения приземления данных.

Где появляются данные о наблюдаемости агента 365

После принятия ваши элементы трассировки отображаются в трех пользовательских интерфейсах. Все три зависят от наличия допустимого элемента трассировки invoke_agent в корне выполнения. Выполнение, содержащее только элементы трассировки chat / execute_tool / output_messages, доступно для запросов в расширенном поиске Defender (таблица CloudAppEvents), но не отображается ни в одном из остальных интерфейсов ниже.

Experience Description
Microsoft Defender Действие агента (invoke_agent, execute_tool, chat) отображается в представлениях действий агента. Администраторы клиента и аналитики безопасности могут детально изучать отдельные выполнения, инструменты и вызовы вывода. Представления действий агента используют элемент трассировки invoke_agent в качестве ключевого элемента; без него выполнение не отображается в этих представлениях, хотя дочерние элементы трассировки по-прежнему доступны для запросов через расширенный поиск. Представление расширенного поиска — CloudAppEvents — принимает все операции: ActionType указывает операцию (InvokeAgent, InferenceCall, ExecuteToolBySDK, ExecuteToolByGateway, ExecuteToolByMCPServer), а поля каждого элемента трассировки находятся в RawEventData. Имена полей, отображаемых пользователю, напрямую сопоставляются с атрибутами элементов трассировки, которые вы отправили: ConversationId ← gen_ai.conversation.id, SessionIdentity ← microsoft.session.id, AgentId ← gen_ai.agent.id, PlatformTargetAgentId ← microsoft.a365.agent.platform.id и т. д. Полное сопоставление приведено в разделе Справочник по атрибутам.
Центр администрирования Microsoft 365 Действие агента также отображается в представлениях инвентаризации и безопасности агентов, которые администраторы клиента используют для управления агентами в своем клиенте. Административный центр вводит invoke_agent только строки: агенты без invoke_agent телеметрии не появляются в инвентаре и запускаются, которые излучают только chat, execute_toolили output_messages здесь невидимы. Административный центр считывает такие атрибуты, как идентификатор агента, имя агента, идентификатор чертежа, идентификатор вызывающего, идентификатор разговора, канал и статус ошибки из этого invoke_agent диапазона.
Microsoft Purview Активность агентов также проявляется у администраторов комплаенса в Microsoft Purview, где они могут настраивать правила обработки данных и политики при запуске агентов (предотвращение потери данных, удержание, соответствие коммуникации и тому подобное). Атрибуты, которые Purview использует (идентификатор агента, идентификатор чертежа, идентификация абонента, разговор, канал, запрос и сообщения ответа), берутся из invoke_agent span и его потомков.

Дальнейшие действия

  • Last updated on