Conceptos de observabilidad de Agent 365

Este artículo explica el modelo de datos detrás de la observabilidad de Agent 365: qué emiten los agentes de telemetría, quiénes pueden emitirlo, dónde se recibe y los límites que se aplican. Estos conceptos se aplican a todas las rutas de integración: Microsoft OpenTelemetry Distro, Agent 365 SDK y direct OTel.

Nota

Los detalles en el nivel de red —las rutas URL en Autenticación, los códigos de error HTTP en Límites y condiciones de descarte y los límites de tamaño y velocidad por solicitud— se aplican específicamente a la ruta directa de OTel. El SDK y Distro se encargan de abstraer estos aspectos por usted. El resto de este artículo (glosario, flujo de datos, modelos de identidad, ámbitos, condiciones de eliminación y dónde aparecen los datos) se aplica a todas las rutas.

Elija su ruta de integración

Tres rutas emiten el mismo modelo de datos de ámbito a Agent 365. Elija uno:

  • Distribución de Microsoft para OpenTelemetry - recomendada para nuevas integraciones. Kit de desarrollo de software (SDK) de observabilidad unificado para Agent 365, Microsoft Foundry, Azure Monitor y otras plataformas.
  • SDK de Agent 365 (SDK de observabilidad) - el SDK anterior. Sigue funcionando sin cambios que afecten a la compatibilidad, pero ya no es la opción recomendada para nuevas integraciones; próximamente se publicarán las directrices de migración para los usuarios actuales del SDK.
  • Direct OTel - la ruta OTLP/HTTP en bruto. Utilícelo únicamente si ya dispone de una canalización de OpenTelemetry, si su marco de trabajo de agente no puede utilizar el SDK de Agent 365 o si su agente está escrito en un lenguaje que el SDK aún no admite (como Java).

Sea cual sea la ruta que elija, se aplicarán el modelo de datos, los modelos de identidad, los ámbitos, los límites y las superficies de acceso posteriores que se describen a continuación.

Glosario

  • Id. de aplicación (appId): el identificador de aplicación asignado cuando se registra una aplicación de Microsoft Entra o una identidad de agente Agente de Microsoft Entra ID.
    • Igual al OAuth client_id, no el identificador de objeto de Microsoft Entra.
    • En toda esta documentación, "ID de agente" e "ID de plano técnico" se refieren ambos a una appId.
  • Conversación: un hilo lógico de interacciones de agente, como un hilo de chat en Teams.
    • Identificado por gen_ai.conversation.id.
    • La clave de unión principal de una ejecución.
  • Canal: el entorno en el que se ejecuta el agente: msteams, outlook, web y así sucesivamente.
  • Ejecución: un mensaje de usuario entra y sale una respuesta del agente. Se modela como un árbol de ámbitos de OTel que comparten una traceId.

Cómo funciona

Para obtener una visión general de Agent 365 y de los destinos de la telemetría, consulte Información general sobre Microsoft Agent 365.

La telemetría se envía como datos de trazas de OpenTelemetry.

  • Un árbol de intervalos que describe una ejecución (un mensaje de usuario entrante, una respuesta de agente saliente).
  • Cada intervalo describe un solo paso: la invocación principal del agente, una llamada LLM, una llamada a una herramienta o la respuesta final.

Flujo de datos

   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)                  |
  +-------------------------------------+

Modelos de identidad

Para una explicación completa de los modelos de identidad de agente (registro estándar de la aplicación Microsoft Entra frente a Plano de identidad de agente de Agente de Microsoft Entra ID, incluyendo compañeros de equipo con IA), consulte Comenzar con el desarrollo de Agent 365. La elección del modelo de identidad determina qué flujo de autenticación y qué punto de conexión se utilizarán.

Si su agente no está registrado en Microsoft Entra, no podrá utilizar estas rutas directamente. Identifique al agente mediante los atributos de identificación alternativos (consulte Referencia de atributos) y contacte al equipo de Agent 365 sobre la vía de ingreso adecuada.

Autenticación

La autenticación depende de si el servicio se autentica a sí mismo o en nombre de un usuario. La bifurcación determina el flujo de OAuth, la declaración del token que contiene el permiso y la ruta URL.

  • El servicio se autentica por sí mismo: sin usuario autenticado; autónomo, programado o basado en eventos.

    • Flujo OAuth: Service-to-service (S2S) credenciales de cliente.
    • Notificación del token: roles.
    • Ruta de URL: /observabilityService/....

  • El servicio se autentica en nombre de un usuario: Para compañeros de equipo de IA, o para la propia cuenta de usuario del agente.

    • Flujo de OAuth: Flujo con derechos delegados (OBO).
    • Notificación del token: scp.
    • Ruta de URL: /observability/....

La misma aplicación del agente puede participar en ambos flujos, como un compañero de equipo de IA que también ejecuta un proceso autónomo nocturno de generación de resúmenes. Para más información, consulte flujo OAuth de aplicación autónoma y flujo con derechos delegados.

Para las recetas completas de tokens para cada combinación de modelo de identidad y flujo, consulte Recetas de autenticación en la guía de integración.

La identidad del agente está vinculada a la URL

El {agentId} en la URL debe coincidir con el appId de la aplicación que llama (la reclamación appid o azp en su token). Los errores de coincidencia devuelven 403 Forbidden. Para las identidades derivadas de plantillas, {agentId} es la appId de identidad del agente, no la appId del plano técnico.

Además, cada ámbito que envíe debe establecer gen_ai.agent.id con el mismo appId; el servidor valida la identidad del agente incluida en la carga útil con la del agente autenticado y rechaza las discrepancias. Este paso detecta la mezcla accidental de tramos de varios agentes dentro de una misma solicitud.

Un ámbito (delegado) o un rol de aplicación (aplicación) es el permiso con nombre que Microsoft Entra emite en el token de acceso. Para la telemetría de Agent 365, el permiso es Agent365.Observability.OtelWrite en el recurso de observabilidad de Agent 365 (audiencia 9b975845-388f-4429-889e-eab1ef63949c).

El mismo nombre de permiso se registra como ambos tipos:

  • Rol de la aplicación para el flujo autónomo (S2S / client-credentials). Aparece en la notificación roles. Seleccionado por <resource>/.default.
  • Ámbito delegado para el flujo OBO. Aparece en la notificación scp. Seleccionado por <resource>/Agent365.Observability.OtelWrite (o <resource>/.default).

Agent 365 también expone un permiso de lado de lectura, Agent365.Observability.OtelRead, utilizado por operadores que consultan la telemetría de Agent 365. La mayoría de los socios no lo necesitan: estos documentos solo cubren la ingesta.

Agregar el permiso a la aplicación

  • Para un registro estándar de una aplicación Microsoft Entra: en Azure Portal, agregue Agent365.Observability.OtelWrite (rol de aplicación para S2S, ámbito para delegados) dentro de Permisos de la API en el registro de la aplicación del agente.
  • Para un plano técnico: los agentes creados a partir de un plano de identidad de agente de Agente de Microsoft Entra ID heredan los permisos de OAuth definidos en el plano, por lo que un administrador del inquilino aprovisiona previamente los permisos una sola vez. Cada instancia de agente construida a partir de ese plano técnico los recibe automáticamente. Consulte Configuración de permisos heredables para planos técnicos de identidad del agente.

Antes de que los tokens lleven el rol o ámbito, un administrador de inquilinos, del inquilino del cliente debe conceder consentimiento. Consulte Conceder a los agentes acceso a los recursos de Microsoft 365.

Sin consentimiento, la adquisición del token devuelve el error AADSTS65001 ("el usuario o el administrador no ha dado su consentimiento") o el token se emite sin la declaración roles / scp y el punto de conexión de ingesta rechaza la solicitud con 403.

El consentimiento se otorga una vez por inquilino y se aplica a cada instancia construida a partir de un plano técnico en adelante. Solo se necesita volver a otorgar el consentimiento cuando se agrega un nuevo permiso al plano técnico.

Límites y condiciones de descarte

Conocer estos límites desde el principio evita sorpresas durante la integración; la mayoría de ellas son silenciosas (la API acepta la solicitud, pero los datos nunca llegan a los sistemas posteriores).

Límites en el nivel de protocolo:

  • api-version=1 es obligatorio en cada solicitud.
  • El tamaño máximo del cuerpo de la solicitud es de 1 MB. Las solicitudes más grandes reciben 413 Payload Too Large.
  • Las dos rutas tienen límites de tasa separados. En 429, honor Retry-After (establecido en 1 segundo) y retroceder con vibración.

Respuestas de error:

  • 403 Forbidden--token al que le falta el rol o alcance de aplicación requerido, o {agentId} en la URL no coincide con el appid / azp de su token.
  • 413 Payload Too Large--el cuerpo supera los 1 MB.
  • 429 Too Many Requests--rate limit hit; honor Retry-After: 1 y volver atrás con vibración.

Condiciones de descarte (solicitud aceptada por HTTP pero los datos no aparecen en sistemas posteriores):

# Condición Comportamiento
1 Falta el intervalo gen_ai.operation.name o no está en {invoke_agent, execute_tool, chat, output_messages} Anular por tramo. Se muestra en partialSuccess.rejectedSpans + errorMessage.
2 Ningún usuario en el inquilino del cliente tiene una licencia Microsoft 365 E7 o Microsoft Agent 365 asignada. Debe haber al menos un usuario en el inquilino con la licencia asignada (la presencia del SKU en el inquilino no es suficiente; la asignación inicia el flujo de trabajo back-end de Defender). No es necesario que el usuario con licencia sea la persona que llama al agente. Toda la petición se descarta silenciosamente. Devuelve 200 { "partialSuccess": null }.

Un 200 OK no es prueba de ingesta. Utilice el flujo de verificación para confirmar que los datos se reciban.

Dónde aparecen los datos

Una vez aceptados, sus tramos aparecen en tres experiencias de cara al cliente. Los tres dependen de un elemento de tramo válido invoke_agent en la raíz de la ejecución. Una ejecución que solo contiene tramos chat / execute_tool / output_messages se puede consultar en la búsqueda avanzada de Defender (la tabla CloudAppEvents), pero no es visible en ninguna de las demás superficies que aparecen a continuación.

Microsoft Defender. La actividad del agente (invoke_agent, execute_tool, chat) aparece en las vistas de actividad del agente. Los administradores del inquilino y los analistas de seguridad pueden examinar en detalle las ejecuciones, las herramientas y las llamadas de inferencia individuales. Las vistas de actividad del agente dependen del tramo invoke_agent; sin él, la ejecución no aparece en ellas, aunque los tramos secundarios siguen pudiéndose consultar mediante búsqueda avanzada. La vista de búsqueda avanzada - CloudAppEvents - acepta todas las operaciones: ActionType refleja la operación (InvokeAgent, InferenceCall, ExecuteToolBySDK, ExecuteToolByGateway, ExecuteToolByMCPServer) y los campos por intervalo están dentro de RawEventData. Los nombres de los campos visibles para el cliente se asignan directamente a los atributos de intervalo que usted envió: ConversationId ← gen_ai.conversation.id, SessionIdentity ← microsoft.session.id, AgentId ← gen_ai.agent.id, PlatformTargetAgentId ← microsoft.a365.agent.platform.id, y así sucesivamente. Consulte la referencia de atributos para la asignación completa.

Centro de administración de Microsoft 365. La actividad del agente también se muestra en las vistas de inventario y seguridad del agente que usan los administradores de inquilinos para controlar los agentes de su inquilino. El centro de administración incorpora solo las filas invoke_agent: los agentes sin telemetría invoke_agent no aparecen en el inventario, y las ejecuciones que emiten solo chat / execute_tool / output_messages son invisibles aquí. Todos los atributos que lee el centro de administración (Id. del agente, nombre del agente, Id. del modelo, identidad de la persona que llama, Id. de la conversación, canal y estado de error) proceden del intervalo invoke_agent.

Microsoft Purview. La actividad del agente también se muestra a los administradores de cumplimiento en Microsoft Purview, donde pueden configurar reglas y políticas de control de datos sobre las ejecuciones de agentes (prevención de pérdida de datos, retención, cumplimiento de comunicaciones y similares). Los atributos en los que se basan las directivas de Purview (id. de agente / id. de plano técnico, identidad del llamante, conversación / canal, mensajes de solicitud y de respuesta) proceden todos del tramo invoke_agent y de sus elementos descendientes.

Pasos siguientes

  • Last updated on