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

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

Note

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

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

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

  • Microsoft OpenTelemetry Distro - рекомендовано для новых интеграций. Унифицированный SDK наблюдаемости в Agent 365, Microsoft Foundry, Azure Monitor и других.
  • Agent 365 SDK (Observability SDK) — более ранний SDK. Продолжает работать без нарушений изменений, но больше не является рекомендованным путём для новых интеграций; Руководство по миграции для существующих пользователей SDK скоро будет.
  • Прямой OTel — сырой путь OTLP/HTTP. Используйте его только если у вас уже есть конвейер OpenTelemetry, ваш фреймворк агента не может использовать SDK Agent 365 или если ваш агент находится на языке, который SDK пока не поддерживает (например, Java).

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

Glossary

  • идентификатор приложения (appId): Идентификатор приложения, выдающийся при регистрации Microsoft Entra приложения или Microsoft Entra ID для агентов агента.
    • Равно OAuth client_id, not идентификатору объекта Microsoft Entra.
    • В этих документах «agent id» и «blueprint id» оба означают appId.
  • Разговор: логическая нить взаимодействия агентов, например, чат в Teams.
    • Идентифицируется по gen_ai.conversation.id.
    • Основной ключ join для забега.
  • Канал: поверхность, по которой проходит агент: msteams, outlook, web, и так далее.
  • Запуск: Одно сообщение пользователя, один ответ агента вышел. Моделируется как дерево OTel , разделяющееtraceId.

Принцип работы

Для обзора Агента 365 и того, на что влияет телеметрия, см. Обзор Microsoft Агента 365.

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

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

Поток данных

   Your agent code

        |
        v

   +---------------+
   | OTel SDK or   |
   | raw HTTP      |
   +---------------+

        |
        v

   POST /traces  agent365.svc.cloud.microsoft

        |
        v

  +-------------------------------------+
  | Microsoft Defender                  |
  |   (CloudAppEvents table             |
  |    in advanced hunting)             |
  |                                     |
  | Microsoft Purview                   |
  |                                     |
  | Microsoft 365 admin center          |
  |   (agent inventory and              |
  |    security views)                  |
  +-------------------------------------+

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

Для полного объяснения моделей идентичности агента (стандартная регистрация Microsoft Entra приложения против Microsoft Entra ID для агентов план идентичности агента, включая AI-товарищей) см. Начните с разработки агента 365. Выбор модели идентичности определяет, какой процесс аутентификации и конечную точку вы используете.

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

Authentication

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

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

    • OAuth flow: Учетные данные клиента Service-to-Service (S2S ).
    • Претензия на символы: roles.
    • URL-маршрут: /observabilityService/....

  • Сервис аутентифицируется от имени пользователя: для AI-коллег или для собственной учетной записи агента.

    • OAuth flow: от имени (OBO).
    • Претензия на символы: scp.
    • URL-маршрут: /observability/....

Одно и то же приложение агента может участвовать в обоих потоках, например, AI-напарник, который также запускает ночной автономный проезд на суммирование. Для получения дополнительной информации см. автономное приложение OAuth flow и on-beafter-of.

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

Идентификатор агента привязан к URL

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

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

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

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

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

Агент 365 также предоставляет разрешение на сторону чтения, Agent365.Observability.OtelReadиспользуемое операторами, запрашивающими телеметрию Агента 365. Большинству партнёров это не нужно — эти документы покрывают только глотание.

Добавление разрешения в ваше приложение

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

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

Без согласия получение токена неуспешно происходит («AADSTS65001пользователь или администратор не дали согласия»), либо токен выдаётся безscproles / претензии, и конечная точка введения отклоняет запрос с .403

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

Пределы и условия сброса

Заранее знание этих ограничений предотвращает сюрпризы при интеграции — большинство из них молчатся (API принимает запрос, но данные не появляются дальше).

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

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

Ответы на ошибки:

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

Условия выброса (запрос принимается HTTP, но данные не отображаются дальше):

# Состояние Behavior
1 Пролёт gen_ai.operation.name отсутствует или не входит {invoke_agent, execute_tool, chat, output_messages} Перепад на пролёт. Всплыл в partialSuccess.rejectedSpans + errorMessage.
2 Ни один пользователь в арендаторе-клиенте не имеет лицензии Microsoft 365 E7 или Microsoft Agent 365. Хотя бы один пользователь в арендаторе должен иметь лицензию assigned (наличие SKU в арендаторе недостаточно — присваивание запускает Defender бэкенд). Лицензированный пользователь не обязательно должен быть человеком-звонящим агента. Вся просьба была отложена молча. Возвращает 200 { "partialSuccess": null }.

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

Где отображаются ваши данные

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

Microsoft Defender. Активность агента (invoke_agent, execute_tool, chat) появляется в представлениях агент-активность. Администраторы арендаторов и аналитики безопасности могут подробно анализировать индивидуальные запуски, инструменты и выводы. Просмотры активности агента зависят от invoke_agent span-а; без него запуск там не отображается, хотя дочерние споведы всё ещё можно запросить через расширенную охоту. Продвинутый подход — CloudAppEvents принимает каждую операцию: ActionType отражает операцию (InvokeAgent, InferenceCall, ExecuteToolBySDK, ExecuteToolByMCPServerExecuteToolByGateway, ), а поля по пролёту находятся внутри RawEventData. Имена полей, видимые клиентам, напрямую соответствуют атрибутам span, которые вы отправили: 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 телеметрии не отображаются в инвентаре, а запуски, которые толькоoutput_messageschat / execute_tool / излучают, здесь невидимы. Атрибуты, которые читает админ-центр (идентификатор агента, имя агента, идентификатор чертежа, идентификатор вызывающего, идентификатор разговора, канал, статус ошибки), все они берутся из этого invoke_agent спада.

Microsoft Purview. Активность агентов также раскрывается администраторам комплаенса в Microsoft Purview, где они могут настраивать правила обработки данных и политики при запусках агентов (предотвращение потери данных, удержание, соответствие коммуникации и тому подобное). Атрибуты, от которых зависят политики Purview (идентификатор агента / идентификатор чертежа, идентификация абонента, разговор / канал, запросы и сообщения ответа), все они берутся из invoke_agent span и его потомков.

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

  • Last updated on