Conceptos de observabilidad de Agent 365

En este artículo se explica el modelo de datos detrás de la observabilidad del Agente 365: qué agentes de telemetría emiten, quién puede emitirlo, dónde llega y los límites que se aplican. Estos conceptos se aplican a cada vía de integración: Microsoft OpenTelemetry Distro, Agent 365 SDK y direct OTel.

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:

  • Distribución de Microsoft para OpenTelemetry - recomendada para nuevas integraciones. SDK de observabilidad unificada en el Agente 365, Microsoft Foundry, Azure Monitor, etc.
  • SDK del Agente 365 (SDK de observabilidad): el SDK anterior. Sigue funcionando sin cambios importantes, pero ya no la ruta recomendada para las nuevas integraciones; La guía de migración para los usuarios del SDK existentes estará disponible.
  • Direct OTel - la ruta OTLP/HTTP directa. Úselo solo si ya tiene una canalización de OpenTelemetry en su lugar, el marco de trabajo del agente no puede usar el SDK de Agent 365 o el agente está en un lenguaje que el SDK todavía no admite (por ejemplo, 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.

Glossary

  • Id. de aplicación (appId): El identificador de aplicación emitido cuando se ha registrado una aplicación de Microsoft Entra o la identidad de agente de Agente de Microsoft Entra ID.
    • Igual al OAuth client_id, no al identificador de objeto de Microsoft Entra.
    • En toda esta documentación, "ID de agente" e "ID de blueprint" se refieren ambos a un appId.
  • Conversación: Un hilo lógico de interacciones de un agente, como un hilo de chat de Teams.
    • Identificado por gen_ai.conversation.id.
    • La clave de unión principal de una ejecución.
  • Canal: la superficie en la que se ejecuta el agente: msteams, outlook, web, etc.
  • Ejecución: entra un mensaje de usuario y sale una respuesta del agente. Se modela como un árbol de spans de OTel que comparten un traceId.

Cómo funciona

Para obtener información general sobre el Agente 365 y las fuentes de telemetría, consulte Overview of 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

   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 obtener una explicación completa de los modelos de identidad del agente (registro de aplicaciones Microsoft Entra estándar frente a Agente de Microsoft Entra ID plano técnico de identidad del agente, incluidos los compañeros de equipo de IA), consulte Get started with Agent 365 development. La elección del modelo de identidad determina el flujo de autenticación y el punto de conexión que usa.

Si el agente no tiene ningún registro Microsoft Entra, no puede usar estas rutas directamente. Identifique el agente a través de los atributos de identificador alternativos (consulte Referencia de atributos) y póngase en contacto con el equipo del Agente 365 sobre la ruta de acceso de entrada adecuada.

Autenticación

La autenticación se bifurca en 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 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.
    • 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).
    • Reclamación de 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 span que envíes 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 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 la aplicación para el flujo autónomo (S2S / client-credentials). Tierras incluidas en la roles reclamación. Seleccionado por <resource>/.default.
  • Ámbito delegado para el flujo de OBO. Tierras en la scp reclamación. Seleccionado por <resource>/Agent365.Observability.OtelWrite (o <resource>/.default).

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.

Adición del permiso a la aplicación

  • Para un registro de aplicaciones estándar de Microsoft Entra: en el portal de Azure, agregue Agent365.Observability.OtelWrite (rol de aplicación para S2S, ámbito para acceso delegado) en Permisos de API del registro de aplicaciones del agente.
  • Para un plano: 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 creada a partir de ese plano técnico las 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, se produce un error en la obtención del token con AADSTS65001 ("el usuario o el administrador no ha dado su consentimiento") o el token se emite sin el claim roles / scp y el punto de conexión de ingesta rechaza la solicitud con 403.

El consentimiento se concede una vez por inquilino y se aplica a cada instancia compilada a partir de un plano técnico a partir de ese momento. 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 por adelantado evita sorpresas durante la integración: la mayoría son silenciosas (la API acepta la solicitud, pero los datos nunca aparecen de bajada).

Límites a nivel de cable:

  • api-version=1 se requiere en cada solicitud.
  • El tamaño máximo del cuerpo de la solicitud es de 1 MB. Las solicitudes más grandes obtienen 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.

Respuestas de error:

  • 403 Forbidden--al token le falta el rol de la aplicación o el ámbito requeridos, o {agentId} en la URL no coincide con el appid / azp de tu token.
  • 413 Payload Too Large--body 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 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. Se descartó la solicitud completa sin notificación. Devuelve 200 { "partialSuccess": null }.

Un 200 OK no es prueba de ingesta. Utiliza el flujo de verificación para confirmar que los datos llegan correctamente.

Dónde se muestran tus datos

Una vez aceptados, tus spans aparecen en tres experiencias de cara al cliente. Los tres dependen de un elemento span válido invoke_agent en la raíz de la ejecución. Una ejecución que solo contiene spans 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 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 incorpora solo las filas invoke_agent: los agentes sin invoke_agent telemetría no aparecen en el inventario, y las ejecuciones que emiten solo chat / execute_tool / output_messages son invisibles aquí. Los atributos que lee el centro de administración (id. de agente, nombre del agente, id. de blueprint, identidad de la persona que llama, id. de conversación, canal, estado de error) proceden del elemento invoke_agent span.

Microsoft Purview. La actividad del agente también se muestra a los administradores de cumplimiento en Microsoft Purview, donde pueden configurar reglas de directiva y control de datos a través de ejecuciones de agente (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 blueprint, identidad del llamante, conversación / canal, mensajes de solicitud y de respuesta) proceden todos del span invoke_agent y de sus elementos descendientes.

Pasos siguientes

  • Last updated on