Conceptos de observabilidad de Agent 365

Este artículo explica el modelo de datos de observabilidad del Agente 365, incluyendo qué emiten los agentes de telemetría, quién puede emitirlo, dónde cae y los límites que se aplican. Utiliza estos conceptos para planificar tu integración y entender la telemetría entre la Distribución OpenTelemetry de Microsoft, el obsoleto SDK de Observabilidad Agent 365 y OTel directo.

Note

Detalles a nivel de protocolo: las rutas URL en Authentication, los códigos de error HTTP en Limits and drop conditions y los límites de tamaño y de frecuencia por solicitud se aplican específicamente a la ruta directa de OTel. El SDK y la distro se encargan de abstraer esto para ti. El resto de este artículo (glosario, flujo de datos, modelos de identidad, alcances, condiciones de descarte, dónde se muestran los datos) se aplica a cada ruta.

Elige tu ruta de integración

Tres vías emiten el mismo modelo de datos de span a Agent 365. Elija uno:

Path Description
Distribución de Microsoft OpenTelemetry Recomendado para nuevas integraciones. SDK de observabilidad unificada en el Agente 365, Microsoft Foundry, Azure Monitor, etc.
SDK de observabilidad del Agente 365 obsoleto El SDK legado. Las integraciones existentes siguen funcionando, pero no se debe usar para nuevas integraciones. El artículo incluye guías de migración.
Directo OTel La ruta OTLP/HTTP en bruto. Úsalo solo si ya tienes una canalización OpenTelemetry implementada, si tu framework de agentes no puede usar la distribución Microsoft OpenTelemetry o si tu agente está en un lenguaje que la distribución aún no soporta (como Java).

Sea cual sea la opción que elija, el modelo de datos, los modelos de identidad, los alcances, los límites y las superficies de nivel inferior que se describen a continuación se aplican en todos los casos.

Glosario de observabilidad del Agente 365

Término Description
ID de la aplicación (appId) El identificador de aplicación emitido cuando se registra una aplicación Microsoft Entra o la identidad de agente de Agente de Microsoft Entra ID.
- Equivale al OAuth client_id, no al identificador de objeto de Microsoft Entra.
- En toda esta documentación, «id de agente» e «id de plantilla» se refieren a un appId.
Conversación Un hilo lógico de interacciones con los agentes, como un hilo de chat en Teams.
- Identificado por gen_ai.conversation.id.
- La clave principal de unión de una ejecución.
Channel La superficie en la que corre el agente: msteams, outlook, web, y así sucesivamente.
Ejecutar Un mensaje de usuario de entrada, una respuesta del agente de salida. Se modela como un árbol de OTel spans que comparten un traceId.

Cómo funciona la observabilidad del Agente 365

Para una visión general del Agente 365 y la telemetría que recoge, véase Resumen de Microsoft Agent 365.

La telemetría se envía como datos de seguimiento de OpenTelemetry:

  • Un árbol de tramos que describen una ejecución (entra un mensaje de usuario y sale una respuesta del agente).
  • Cada intervalo describe un solo paso: la invocación del agente de nivel superior, una llamada LLM, una llamada a herramienta o la respuesta final.

Flujo de datos de observabilidad del Agente 365

El siguiente diagrama muestra cómo la telemetría de agentes fluye a través de la autenticación y la ingesta de observabilidad del Agente 365 hacia las experiencias posteriores de Microsoft 365.

Diagrama de flujo de datos de observabilidad del Agente 365.

Modelos de identidad

Para una explicación completa de los modelos de identidad de agente (registro estándar de la app Microsoft Entra vs. blueprint de identidad de agente de Agente de Microsoft Entra ID, incluyendo compañeros de equipo con IA), véase Identidad de agente. La elección del modelo de identidad determina el flujo de autenticación y el punto de conexión que usa.

Una identidad de agente derivada del blueprint se convierte en una instancia de agente registrada en el Agente 365 solo después de completar el registro del Agente 365, como a través de a365 setup all. Crear una identidad Microsoft Entra por sí sola no registra la instancia. Los registros estándar de la app de Microsoft Entra, como los que usan los agentes de custom engine, no son instancias de agentes registrados.

Si el agente no tiene ningún registro Microsoft Entra, no puede usar estas rutas directamente. Identifica al agente mediante los atributos de ID alternativo (véase referencia de atributo) y contacta con el equipo del Agente 365 sobre la ruta de entrada adecuada.

Authentication

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

  • El servicio se autentica a sí mismo: ningún usuario que haya iniciado sesión: autónomo, programado o controlado por eventos.

    • Flujo de OAuth: credenciales de cliente servicio a servicio (S2S).
    • Declaración del token: roles. Una identidad no registrada necesita el Agent365.Observability.OtelWrite rol de app. Una instancia de agente registrada en Agent 365 puede usar un token solo de aplicación sin ese rol.
    • Ruta de dirección URL: /observabilityService/....

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

    • Flujo de OAuth: en nombre de (OBO).
    • Declaración del token: scp.
    • Ruta de dirección 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 obtener más información, consulte flujo OAuth de aplicación autónoma y flujo en nombre del usuario.

Para obtener las recetas de token completas 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á enlazada a la dirección URL

El {agentId} de la URL debe coincidir con el appId de la aplicación que realiza la llamada (el claim appid o azp de tu token). Los errores de coincidencia devuelven 403 Forbidden. Para las identidades derivadas de la plantilla, {agentId} es el appId de la identidad del agente, no el appId de la plantilla.

Además, cada tramo que envíes debe establecer gen_ai.agent.id con el mismo appId. El servidor valida la identidad del agente dentro de la carga contra el agente autenticado y rechaza las discrepancias. Este paso detecta la mezcla accidental de tramos de varios agentes dentro de una misma solicitud.

Un scope (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 está registrado en ambos tipos:

  • Rol de aplicación para identidades no registradas en el flujo autónomo (S2S / credenciales de cliente). Tierras incluidas en la roles reclamación. Seleccionado por <resource>/.default.
  • Ámbito delegado para el flujo de OBO. Tierras incluidas en la scp reclamación. Seleccionado por <resource>/Agent365.Observability.OtelWrite (o <resource>/.default).

En la ruta S2S, una instancia registrada en Agent 365 puede exportar con un token solo de aplicación que no tiene ningún Agent365.Observability.OtelWrite rol. No necesita un permiso de observabilidad ni el consentimiento del administrador para exportar telemetría. Una identidad no registrada sigue necesitando el rol de la app, y la ruta delegada sigue necesitando el alcance delegado más el consentimiento del administrador.

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

Añade el permiso a tu app

  • Para un registro estándar de la app Microsoft Entra: en el portal de Azure, añade Agent365.Observability.OtelWrite bajo Permisos de API en el registro de la aplicación del agente. Usa el rol de aplicación para S2S y el alcance delegado para OBO.
  • Para una instancia de agente derivada de blueprint en la ruta S2S: completa el registro del Agente 365 para la instancia del agente. Una instancia registrada no necesita el permiso de la API de Observabilidad ni el consentimiento del administrador para exportar telemetría en la ruta S2S.
  • Para una instancia de agente derivada de un blueprint en la ruta delegada: añade el alcance delegado Agent365.Observability.OtelWrite al blueprint para que las instancias de agente lo hereden. Consulte Configuración de permisos heredables para planos técnicos de identidad del agente. Para añadirlo con la CLI del Agente 365, véase permisos de observabilidad.

Antes de que los tokens tengan un papel o alcance requerido, un administrador del tenant en el tenant del cliente debe conceder su consentimiento. Consulte Conceder a los agentes acceso a los recursos de Microsoft 365.

Sin consentimiento, la adquisición de tokens falla con AADSTS65001 (The user or administrator has not consented to use the application with ID...) o el token se emite sin la declaración roles o scp, y el punto de conexión de ingesta rechaza la solicitud con 403.

Una instancia de agente registrada en Agent 365 que exporta en la ruta S2S no necesita el consentimiento del administrador de Observabilidad. El consentimiento sigue siendo necesario para identidades S2S no registradas que usan el rol de la app y para todas las exportaciones de rutas delegadas que usan el ámbito delegado.

Cuando se requiere consentimiento, se concede una vez por tenant y se aplica a todas las instancias construidas a partir de una plantilla a partir de entonces. La reconsentencia solo es necesaria cuando se agrega un nuevo permiso al plano técnico.

Límites y condiciones de eliminación

Conocer estos límites de antemano evita sorpresas durante la integración. Algunos fallos devolven un estado HTTP exitoso aunque la respuesta informe que la telemetría no fue aceptada.

Límites a nivel de cable:

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

Las integraciones de terceros incorporadas que usan autenticación S2S pueden llamar al punto de conexión de elegibilidad del inquilino como comprobación previa opcional antes de enviar la telemetría. Cuando uses el endpoint, confía en su decisión en lugar de inferir la elegibilidad a partir únicamente del consentimiento o de la licencia. Una enabled: false respuesta significa que el inquilino no es elegible en ese momento. Un 503 Service Unavailable sin cuerpo significa que no se pudo determinar la elegibilidad. Vuelve a intentarlo según su Retry-After encabezado si aún necesitas un resultado de elegibilidad.

Respuestas de error:

  • 403 Forbidden: Al token le falta el rol de aplicación o el ámbito requeridos, o el valor de {agentId} en la URL no coincide con el appid o el azp de tu token.
  • 413 Payload Too Large: El cuerpo supera los 1 MB.
  • 429 Too Many Requests: Límite de velocidad alcanzado; Honra Retry-After: 1 y retrocede con nerviosismo.

Condiciones de descarte (solicitud aceptada mediante HTTP, pero los datos no aparecen aguas abajo):

# Condition Comportamiento
1 Falta el intervalo gen_ai.operation.name o no está en {invoke_agent, execute_tool, chat, output_messages} Caída por tramo. Aparece en partialSuccess.rejectedSpans + errorMessage.
2 Ningún usuario del tenant del cliente tiene asignada una licencia de Microsoft 365 E7 o Microsoft Agent 365. Al menos un usuario del inquilino debe tener la licencia asignada (no basta con que la SKU esté presente en el inquilino; la asignación pone en marcha el flujo de trabajo del back-end de Defender). El usuario con licencia no tiene por qué ser la persona que llama al agente. La solicitud devuelve 200 OK, pero la entrada results de cada tramo tiene el estado rejected y el motivo tenant_not_licensed.

200 OK no constituye una prueba de ingestión. Inspecciona la respuesta resultsde , y utiliza el flujo de verificación para confirmar que los datos llegan.

Donde aparecen los datos de observabilidad del Agente 365

Después de aceptar los segmentos, aparecen en tres experiencias de cara al cliente. Las tres experiencias dependen de un span válido invoke_agent en la raíz de la ejecución. Una ejecución con solo chat, execute_tool o output_messages spans es consultable en Defender advanced hunting (la tabla CloudAppEvents), pero es invisible para todas las demás interfaces.

Experience Description
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 invoke_agent span; sin él, la ejecución no aparece en ellas, aunque los spans secundarios siguen pudiéndose consultar mediante búsqueda avanzada. La vista de búsqueda avanzada - CloudAppEvents - admite todas las operaciones: ActionType refleja la operación (InvokeAgent, InferenceCall, ExecuteToolBySDK, ExecuteToolByGateway, ExecuteToolByMCPServer) y los campos por tramo están dentro de RawEventData. Los nombres de campo visibles para el cliente se asignan directamente a los atributos span enviados: ConversationId ← gen_ai.conversation.id, SessionIdentity ← microsoft.session.id, AgentId ← gen_ai.agent.id, PlatformTargetAgentId ← microsoft.a365.agent.platform.id, etc. Consulte Referencia de atributos para obtener 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 solo incorpora filas de invoke_agent: los agentes sin telemetría de invoke_agent no aparecen en el inventario, y las ejecuciones que solo emiten chat, execute_tool o output_messages no son visibles aquí. El centro de administración lee atributos como el ID del agente, el nombre del agente, el ID del plano, la identidad de la persona que llama, el ID de la conversación, el canal y el estado de error del elemento invoke_agent span.
Microsoft Purview La actividad de los agentes también llega a los administradores de cumplimiento en Microsoft Purview, donde pueden configurar las reglas de manejo de datos y políticas sobre las ejecuciones de agentes (prevención de pérdida de datos, retención, cumplimiento de comunicaciones, y similares). Los atributos que las políticas de Purview activan (ID del agente, ID del blueprint, identidad de llamante, conversación, canal, solicitud y mensajes de respuesta) provienen del invoke_agent span y sus descendientes.

Pasos siguientes

  • Last updated on