Integración de la observabilidad del agente mediante OTel directo

Esta guía te orienta de principio a fin para enviar la telemetría del agente directamente a Agent 365 utilizando OpenTelemetry (OTLP/HTTP+JSON). Antes de comenzar, lea los conceptos de observabilidad de Agent 365 para entender el modelo, los flujos de autenticación y los destinos donde llegan sus datos.

Requisitos previos

Asegúrese de que las siguientes configuraciones se hayan realizado antes de que fluya cualquier telemetría.

Recetas de autenticación

Las cuatro recetas utilizan el punto de conexión estándar de tokens de Microsoft Entra:

Las siguientes recetas muestran HTTP sin procesar para mayor claridad. En producción, prefiera Microsoft.Identity.Web u otra biblioteca MSAL, que gestione la actualización de tokens y el almacenamiento en caché.

¿Qué receta necesito?

S2S, aplicación estándar de Microsoft Entra

Un POST al punto de conexión de token del inquilino con grant_type=client_credentials. Autentique la aplicación mediante un secreto de cliente, un certificado (aserción JWT firmada), o una identidad administrada o credencial federada.

POST https://login.microsoftonline.com/{your-tenant-id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id={your-app-id}
&scope=9b975845-388f-4429-889e-eab1ef63949c%2F.default
&client_secret={secret}
&grant_type=client_credentials

El token devuelto tiene appid/azp = {your-app-id}, roles que contiene Agent365.Observability.OtelWrite y aud = 9b975845-.... Úselo en la ruta /observabilityService/.../traces.

Para la autenticación basada en certificados, reemplace client_secret={secret} por client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={signed-jwt}.

S2S,, identidad del agente derivado del plano técnico

Las identidades de los agentes no tienen credenciales propias. La plantilla de identidad del agente contiene las credenciales (FIC de identidad administrada, certificado o secreto de cliente) y emite tokens en nombre de sus identidades de agente secundarias mediante un intercambio de dos pasos. Para más información, consulte flujo OAuth de la aplicación independiente.

1. La plantilla se autentica y obtiene un token T1 de intercambio de identidad federada:

   • {blueprint-credential} es el token MSI del plano técnico JWT firmado por certificado o la aserción de token de intercambio secreto, según la configuración del plano técnico.

   POST https://login.microsoftonline.com/{your-tenant-id}/oauth2/v2.0/token
   Content-Type: application/x-www-form-urlencoded
   
   client_id={blueprint-app-id}
   &scope=api%3A%2F%2FAzureADTokenExchange%2F.default
   &fmi_path={agent-identity-app-id}
   &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
   &client_assertion={blueprint-credential}
   &grant_type=client_credentials
   

2. La identidad del agente intercambia T1 por el token de recurso de observabilidad de Agent 365:

   POST https://login.microsoftonline.com/{your-tenant-id}/oauth2/v2.0/token
   Content-Type: application/x-www-form-urlencoded
   
   client_id={agent-identity-app-id}
   &scope=9b975845-388f-4429-889e-eab1ef63949c%2F.default
   &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
   &client_assertion={T1}
   &grant_type=client_credentials
   

   • El token devuelto tiene appid/azp = {agent-identity-app-id}, roles que contiene Agent365.Observability.OtelWrite y aud = 9b975845-....
   • Utilice este token en la ruta /observabilityService/.../traces.
   • La URL {agentId} es el appId de identidad de agente, no el appId de plano técnico.

OBO, aplicación estándar de Microsoft Entra

Reciba el token entrante del usuario Tc de quien realiza la llamada ascendente (Bearer o PFAT) y, a continuación, intercámbielo:

POST https://login.microsoftonline.com/{your-tenant-id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id={your-app-id}
&scope=9b975845-388f-4429-889e-eab1ef63949c%2FAgent365.Observability.OtelWrite
&client_secret={secret}
&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&assertion={Tc}
&requested_token_use=on_behalf_of

Para la autenticación mediante certificado, reemplace client_secret={secret} por el mismo par client_assertion_type + client_assertion que en S2S.

El token devuelto tiene appid/azp = {your-app-id}, scp que contiene Agent365.Observability.OtelWrite y aud = 9b975845-.... Úselo en la ruta /observability/.../traces. Se devuelve un token de actualización adicional; guárdelo y reutilícelo en lugar de volver a ejecutar el intercambio en cada llamada.

OBO, identidad de agente derivada de plano técnico (incluyendo compañero de equipo con IA)

Hay tres pasos principales del flujo con derechos delegados. Para más información, consulte Flujos de OAuth del agente: flujo con derechos delegados.

1. Reciba el token de usuario Tc. Para un compañero de equipo de IA, este token representa la cuenta de usuario del agente; de lo contrario, representa al usuario humano que llama.

2. El plano técnico autentica y obtiene T1, igual que el flujo de identidad del agente derivado del plano técnico S2S.

3. La identidad del agente intercambia T1 y Tc por un token de recurso delegado:

   POST https://login.microsoftonline.com/{your-tenant-id}/oauth2/v2.0/token
   Content-Type: application/x-www-form-urlencoded
   
   client_id={agent-identity-app-id}
   &scope=9b975845-388f-4429-889e-eab1ef63949c%2FAgent365.Observability.OtelWrite
   &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
   &client_assertion={T1}
   &grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
   &assertion={Tc}
   &requested_token_use=on_behalf_of
   

El token devuelto tiene appid/azp = {agent-identity-app-id}, scp que contiene Agent365.Observability.OtelWrite, y representa al usuario del agente. Úselo en la ruta /observability/.../traces. La URL {agentId} es el appId de identidad de agente, no el appId de plano técnico. Se devuelve un token de actualización junto a él; almacénelo en caché y reutilícelo.

Notificaciones obligatorias sobre el token devuelto

Ruta S2S (/observabilityService/...): token exclusivo de aplicación:

Ruta delegada (/observability/...) - token delegado por el usuario (portador o PFAT):

La ruta delegada acepta tanto Bearer como MSAuth1.0 PFAT tokens. Los que llaman directamente deben usar Bearer. Si no sabe cuál tienes, use Bearer.

Puntos de conexión

Dos rutas; elija en función de cómo su servicio autentica, no según lo que hace el usuario:

POST https://agent365.svc.cloud.microsoft/observabilityService/tenants/{tenantId}/otlp/agents/{agentId}/traces?api-version=1   # S2S
POST https://agent365.svc.cloud.microsoft/observability/tenants/{tenantId}/otlp/agents/{agentId}/traces?api-version=1          # OBO

Encabezados:

Authorization: Bearer <token>      # or MSAuth1.0 ... for delegated PFAT
Content-Type: application/json

Parámetros de URL

• {tenantId} - el GUID de inquilino de cliente. El servidor lo trata como autoritativo; si los intervalos se establecen en microsoft.tenant.id y no están de acuerdo, se rechaza la solicitud.
• {agentId} - el appId de la aplicación que llama (también el OAuth client_id). Para las identidades derivadas de plantillas, este es el appId de la identidad del agente, no el appId de la plantilla. Debe ser igual a la notificación appid / azp de su token.
• api-version=1: obligatorio.

Solicitar codificación de cuerpo

El cuerpo tiene el formato estándar OTLP/HTTP+JSON: un ExportTraceServiceRequest con resourceSpans → scopeSpans → spans. Tenga en cuenta los siguientes detalles:

• traceId (16 bytes) y spanId (8 bytes) se envían como cadenas hexadecimales minúsculas.
• startTimeUnixNano / endTimeUnixNano son cadenas que contienen nanosegundos de la época Unix.
• kind es el valor entero de enumeración OTLP (por ejemplo, 1 para INTERNAL); status.code es el valor entero de enumeración (por ejemplo, 1 para OK, 2 para ERROR).
• Todos los valores de atributos se envían como stringValue.

Estructura de la respuesta

Una llamada correcta devuelve 200 OK:

{ "partialSuccess": null }

Si el filtro por intervalo rechazó algunos intervalos:

{
  "partialSuccess": {
    "rejectedSpans": 2,
    "errorMessage": "Dropped 2 non-A365 span(s) ..."
  }
}

Los nombres de campo se escriben en camelCase en la transmisión. Comprobar siempre partialSuccess: un 200 con todos los segmentos rechazados es un resultado real que se debe mostrar. Los límites y condiciones de descarte enumeran los casos de descarte silencioso donde un 200 devuelve partialSuccess: null a pesar de que no aparecen datos posteriores.

La solicitud más pequeña posible

La prueba más sencilla de un extremo a otro envía un solo tramo invoke_agent. Este intervalo es el cuerpo más pequeño que llega a Microsoft Defender.

Paso 1. Obtenga un token de portador. Para S2S, utilice las credenciales de cliente con ámbito 9b975845-388f-4429-889e-eab1ef63949c/.default (consulte Recetas de autenticación para la receta completa).

Paso 2. POST un solo intervalo:

TOKEN="$(./get-token.sh)"
TENANT_ID="<customer-tenant-guid>"
AGENT_ID="<your-agent-app-id>"

curl -i -X POST \
  "https://agent365.svc.cloud.microsoft/observabilityService/tenants/${TENANT_ID}/otlp/agents/${AGENT_ID}/traces?api-version=1" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  --data @- <<EOF
{
  "resourceSpans": [{
    "scopeSpans": [{
      "scope": { "name": "my-instrumentation", "version": "1.0.0" },
      "spans": [{
        "traceId": "0102030405060708090a0b0c0d0e0f10",
        "spanId":  "1111111111111111",
        "parentSpanId": "",
        "name": "invoke_agent",
        "kind": 1,
        "startTimeUnixNano": "1736175600000000000",
        "endTimeUnixNano":   "1736175601500000000",
        "status": { "code": 1 },
        "attributes": [
          { "key": "gen_ai.operation.name", "value": { "stringValue": "invoke_agent" } },
          { "key": "gen_ai.agent.id",       "value": { "stringValue": "${AGENT_ID}" } },
          { "key": "gen_ai.agent.name",     "value": { "stringValue": "MyAgent" } },
          { "key": "microsoft.a365.agent.blueprint.id", "value": { "stringValue": "${AGENT_ID}" } },
          { "key": "gen_ai.conversation.id","value": { "stringValue": "conv-001" } },
          { "key": "microsoft.channel.name","value": { "stringValue": "web" } },
          { "key": "user.id",               "value": { "stringValue": "<entra-user-objectid>" } },
          { "key": "client.address",        "value": { "stringValue": "10.1.2.80" } },
          { "key": "server.address",        "value": { "stringValue": "myagent.example.com" } },
          { "key": "server.port",           "value": { "stringValue": "443" } },
          { "key": "gen_ai.input.messages", "value": { "stringValue": "[{\"role\":\"user\",\"content\":\"hi\"}]" } },
          { "key": "gen_ai.output.messages","value": { "stringValue": "[{\"role\":\"assistant\",\"content\":\"hello\"}]" } }
        ]
      }]
    }]
  }]
}
EOF

Paso 3. Se espera 200 OK con el siguiente cuerpo:

{ "partialSuccess": null }

Paso 4. Confirme que los datos se han recibido correctamente. Un estado 200 OK no prueba que se haya realizado la ingesta; Verificar la ingesta explica el proceso de verificación. Para hacer un POST con un archivo de cuerpo guardado en su lugar, sustituya --data @- <<EOF ... EOF por --data @./otlp-request.json.

Ejemplo de ejecución de agente

Un usuario de Microsoft Teams pregunta: "¿Qué tiempo hace en Seattle?". Su agente llama a la función GetWeather, pide a un LLM que formatee la respuesta y envía la respuesta. Esa ejecución única es de cuatro intervalos:

graph TD
    A["<b>invoke_agent</b> · spanId=A · parentSpanId=∅<br/><i>root - the run itself</i>"]
    B["<b>chat</b> · spanId=B · parentSpanId=A<br/><i>LLM picks the tool / formats reply</i>"]
    C["<b>execute_tool</b> · spanId=C · parentSpanId=A<br/><i>the GetWeather call</i>"]
    D["<b>output_messages</b> · spanId=D · parentSpanId=A<br/><i>final reply emitted to the user</i>"]
    A --> B
    A --> C
    A --> D

Atributos de todo el tramo establecidos para cada tramo:

Tramo A: invoke_agent (raíz)

{
  "traceId": "0102030405060708090a0b0c0d0e0f10",
  "spanId": "1111111111111111",
  "parentSpanId": "",
  "name": "invoke_agent",
  "kind": 1,
  "startTimeUnixNano": "1736175600000000000",
  "endTimeUnixNano":   "1736175601500000000",
  "status": { "code": 1 },
  "attributes": [
    { "key": "gen_ai.operation.name",   "value": { "stringValue": "invoke_agent" } },
    { "key": "gen_ai.execution.type",   "value": { "stringValue": "HumanToAgent" } },
    { "key": "gen_ai.input.messages",   "value": { "stringValue": "[{\"role\":\"user\",\"content\":\"What's the weather in Seattle?\"}]" } },
    { "key": "gen_ai.output.messages",  "value": { "stringValue": "[{\"role\":\"assistant\",\"content\":\"It's 65F and partly cloudy in Seattle.\"}]" } },
    { "key": "user.email",              "value": { "stringValue": "alice@contoso.com" } }
    /* plus all the run-wide attributes listed above */
  ]
}

Tramo B: chat (llamada al LLM)

{
  "traceId": "0102030405060708090a0b0c0d0e0f10",
  "spanId": "2222222222222222",
  "parentSpanId": "1111111111111111",
  "name": "chat",
  "kind": 1,
  "startTimeUnixNano": "1736175600200000000",
  "endTimeUnixNano":   "1736175600900000000",
  "status": { "code": 1 },
  "attributes": [
    { "key": "gen_ai.operation.name",      "value": { "stringValue": "chat" } },
    { "key": "gen_ai.request.model",       "value": { "stringValue": "gpt-4o" } },
    { "key": "gen_ai.provider.name",       "value": { "stringValue": "openai" } },
    { "key": "gen_ai.usage.input_tokens",  "value": { "stringValue": "42" } },
    { "key": "gen_ai.usage.output_tokens", "value": { "stringValue": "23" } }
    /* plus all the run-wide attributes */
  ]
}

Tramo C: execute_tool

{
  "traceId": "0102030405060708090a0b0c0d0e0f10",
  "spanId": "3333333333333333",
  "parentSpanId": "1111111111111111",
  "name": "execute_tool",
  "kind": 1,
  "startTimeUnixNano": "1736175600950000000",
  "endTimeUnixNano":   "1736175601200000000",
  "status": { "code": 1 },
  "attributes": [
    { "key": "gen_ai.operation.name",      "value": { "stringValue": "execute_tool" } },
    { "key": "gen_ai.tool.name",           "value": { "stringValue": "GetWeather" } },
    { "key": "gen_ai.tool.type",           "value": { "stringValue": "function" } },
    { "key": "gen_ai.tool.call.id",        "value": { "stringValue": "call-001" } },
    { "key": "gen_ai.tool.call.arguments", "value": { "stringValue": "{\"location\":\"Seattle\"}" } },
    { "key": "gen_ai.tool.call.result",    "value": { "stringValue": "{\"tempF\":65,\"condition\":\"partly cloudy\"}" } }
    /* plus all the run-wide attributes */
  ]
}

Tramo D: output_messages

{
  "traceId": "0102030405060708090a0b0c0d0e0f10",
  "spanId": "4444444444444444",
  "parentSpanId": "1111111111111111",
  "name": "output_messages",
  "kind": 1,
  "startTimeUnixNano": "1736175601400000000",
  "endTimeUnixNano":   "1736175601500000000",
  "status": { "code": 1 },
  "attributes": [
    { "key": "gen_ai.operation.name",  "value": { "stringValue": "output_messages" } },
    { "key": "gen_ai.output.messages", "value": { "stringValue": "[{\"role\":\"assistant\",\"content\":\"It's 65F and partly cloudy in Seattle.\"}]" } }
    /* plus all the run-wide attributes */
  ]
}

Envío de telemetría

Usar un SDK de OTel

La mayoría de los socios envía trazas a través de un SDK de OTel en lugar de HTTP implementado manualmente. El SDK gestiona automáticamente el procesamiento por lotes, los reintentos y la codificación OTLP/HTTP+JSON. Configure el punto de conexión exportador e inserte el encabezado Authorization.

El punto de conexión exportador es la URL de la propia ruta, incluyendo la cadena de consulta:

https://agent365.svc.cloud.microsoft/observabilityService/tenants/{tenantId}/otlp/agents/{agentId}/traces?api-version=1

(Use /observability/... en lugar de /observabilityService/... para la ruta delegada.)

Python

from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

exporter = OTLPSpanExporter(
    endpoint="https://agent365.svc.cloud.microsoft/observabilityService/tenants/{tenantId}/otlp/agents/{agentId}/traces?api-version=1",
    headers={"Authorization": f"Bearer {token}"},
)

Paquete: opentelemetry-exporter-otlp-proto-http.

Node.js / TypeScript

import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";

const exporter = new OTLPTraceExporter({
  url: "https://agent365.svc.cloud.microsoft/observabilityService/tenants/{tenantId}/otlp/agents/{agentId}/traces?api-version=1",
  headers: { Authorization: `Bearer ${token}` },
});

Paquete: @opentelemetry/exporter-trace-otlp-http.

.NET

using OpenTelemetry.Exporter;

services.AddOpenTelemetry().WithTracing(b => b
    .AddOtlpExporter(o =>
    {
        o.Endpoint = new Uri("https://agent365.svc.cloud.microsoft/observabilityService/tenants/{tenantId}/otlp/agents/{agentId}/traces?api-version=1");
        o.Headers = $"Authorization=Bearer {token}";
        o.Protocol = OtlpExportProtocol.HttpJson;
    }));

Paquete: OpenTelemetry.Exporter.OpenTelemetryProtocol.

HTTP manual

Si no puede o no quieres usar un SDK de OTel, cree usted mismo la solicitud OTLP/HTTP+JSON y envíela mediante POST. La forma del cuerpo se define por la especificación OTLP/HTTP+JSON de OpenTelemetry:

{
  "resourceSpans": [{
    "resource":  { "attributes": [ ... ] },          // optional
    "scopeSpans": [{
      "scope":  { "name": "<your-instrumentation>", "version": "1.0.0" },
      "spans":  [ <span>, <span>, ... ]
    }]
  }]
}

Cada <span> es un objeto cuyos campos requeridos son traceId, spanId, name, kind, startTimeUnixNano, endTimeUnixNano, attributes y (para tramos que no son raíz) parentSpanId. Consulte Puntos de conexión y Solicitar codificación de cuerpo para las reglas de codificación (tiempos codificados como cadenas, hexadecimal traceId / spanId, entero kind / status.code, todos los valores de atributo como stringValue).

El conjunto de atributos que se debe establecer en cada tramo está definido en Contratos de mensaje. Consulte Referencia de entidad para ver una lista completa de atributos. Consulte el Ejemplo de ejecución del agente para ver un ejemplo funcional integral con el token de portador en el encabezado y el cuerpo en línea.

Puede enviar todos los intervalos de una ejecución en un único cuerpo POST (preferido: una solicitud, un seguimiento) o en varios POST. El servidor reconstruye la ejecución a partir de traceId + parentSpanId + gen_ai.conversation.id, por lo que cada tramo transporta suficiente como para estar correlacionado en ambos sentidos.

Contratos de mensajes

Esta sección define qué intervalos puede emitir y qué atributos van en cada uno. Para la especificación completa atributo por atributo, consulte la Referencia de atributo.

Tipos de operación

Cada intervalo que envíe debe tener gen_ai.operation.name configurado con uno de estos cuatro valores (sin distinción entre mayúsculas y minúsculas). Cualquier tramo con un valor que falta o no es reconocido se descarta silenciosamente y se cuenta en partialSuccess.rejectedSpans.

Jerarquía de intervalos y agrupación de ejecución

Agent 365 reconstruye una ejecución a partir de la gráfica estándar de intervalos de OTLP (traceId, spanId, parentSpanId), junto con los atributos globales de la ejecución de la Referencia de atributos.

Seis reglas:

1. Establezca siempre parentSpanId en cada tramo que no sea raíz. Sin ella, la estructura de árbol de la ejecución no se puede reconstruir.
2. Reutiliza el mismo traceId en cada tramo de una ejecución.
3. Establezca gen_ai.conversation.id en cada tramo con el mismo valor. Esta es la clave de combinación principal para "todos los intervalos de esta ejecución". No se propaga automáticamente.
4. Establezca microsoft.channel.name en cada tramo con el mismo valor. Los intervalos de herramientas a los que les faltan el canal o la conversación pueden heredarlos de su intervalo principal invoke_agentsolo si el intervalo principal está en la misma solicitud OTLP, así que configúrelos usted mismo en cada intervalo.
5. Establezca microsoft.session.id en cada intervalo cuando tenga una sesión lógica.
6. En las llamadas de agente a agente en las que el agente secundario está en una solicitud independiente, reutilice el mismo gen_ai.conversation.id y use los atributos microsoft.a365.caller.agent.* (consulte Referencia de atributos) para capturar el contexto del agente que llama.

El árbol de cuatro intervalos del ejemplo de ejecución del Agente es la forma canónica.

Formas comunes de ejecución

Lista de verificación de incorporación

Revise esta lista de verificación antes de pasar a producción.

Pasos siguientes

• Referencia de atributos: especificación por atributo y guía para seleccionar valores.
• Solución de problemas: verificación de la ingestión, errores comunes y respuestas de error.