Integrar a observabilidade do agente usando o OTel direto

Este guia orienta você em todo o processo de envio da telemetria do agente diretamente para o Agent 365 via OpenTelemetry (OTLP/HTTP+JSON). Antes de começar, leia os conceitos de observabilidade do Agent 365 para entender o modelo, os fluxos de autenticação e os pontos de destino dos seus dados.

Pré-requisitos

Garanta que as seguintes configurações sejam definidas antes de qualquer fluxo de telemetria.

Métodos de autenticação

Os quatro fluxos utilizam o ponto de extremidade de token padrão do Microsoft Entra:

Os métodos abaixo mostram HTTP bruto para maior clareza. Em produção, prefira Microsoft.Identity.Web ou outra biblioteca MSAL, que gerencie a atualização de tokens e o cache.

De qual método eu preciso?

S2S, aplicativo padrão do Microsoft Entra

Um POST para o ponto de extremidade do token do locatário com grant_type=client_credentials. Autentique o aplicativo usando um segredo do cliente, um certificado (declaração JWT assinada), uma identidade gerenciada ou uma 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

O token retornado possui appid/azp = {your-app-id}, roles que contém Agent365.Observability.OtelWrite e aud = 9b975845-.... Use-o na rota /observabilityService/.../traces.

Para autenticação baseada em certificado, substitua client_secret={secret} por client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={signed-jwt}.

S2S, identidade de agente derivada do Blueprint

As identidades dos agentes não têm credenciais próprias. O blueprint de identidade do agente mantém as credenciais (FIC de identidade gerenciada, certificado ou segredo do cliente) e emite tokens em nome das suas identidades de agentes filhos por meio de uma troca em duas etapas. Para obter mais informações, consulte fluxo OAuth do aplicativo autônomo.

1. O blueprint se autentica e obtém um token de troca de identidade federada T1:

   • {blueprint-credential} é o token MSI do blueprint, JWT assinado por certificado ou declaração secreta de token de troca – conforme a configuração do blueprint.

   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. A identidade do agente troca T1 pelo token do recurso Observabilidade do 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
   

   • O token retornado possui appid/azp = {agent-identity-app-id}, roles que contém Agent365.Observability.OtelWrite e aud = 9b975845-....
   • Use este token na rota /observabilityService/.../traces.
   • A URL {agentId} é o appId da identidade do agente, não o appId do blueprint.

OBO, aplicativo padrão do Microsoft Entra

Receba o token de entrada Tc do usuário, enviado pelo chamador upstream (Portador ou PFAT) e troque-o:

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 autenticação por certificado, substitua client_secret={secret} pelo mesmo par client_assertion_type + client_assertion usado no S2S.

O token retornado possui appid/azp = {your-app-id}, scp que contém Agent365.Observability.OtelWrite e aud = 9b975845-.... Use-o na rota /observability/.../traces. Um token de atualização é retornado junto; armazene-o em cache e reutilize-o, em vez de executar nova troca em cada chamada.

OBO, identidade de agente derivada do Blueprint (incluindo assistente de IA)

Existem três etapas principais para o fluxo On-Behalf-Of. Para obter mais informações, consulte Fluxos OAuth do agente: fluxo On-Behalf-Of.

1. Receba o token de usuário Tc. Para um assistente de IA, esse token representa a própria conta de usuário do agente; caso contrário, representa o chamador humano.

2. O blueprint autentica e obtém T1, assim como no fluxo de identidade do agente derivado do blueprint S2S.

3. A identidade do agente troca T1 e Tc por um 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
   

O token retornado tem appid/azp = {agent-identity-app-id}, scp contendo Agent365.Observability.OtelWrite e representa o usuário do agente. Use-o na rota /observability/.../traces. A URL {agentId} é o appId da identidade do agente, não o appId do blueprint. Um token de atualização é retornado junto; armazene-o em cache e reutilize-o.

Declarações obrigatórias no token devolvido

Rota S2S (/observabilityService/...) - token somente para aplicativo:

Rota delegada (/observability/...) - token delegado pelo usuário (Portador ou PFAT):

A rota delegada aceita os tokens Bearer e MSAuth1.0 PFAT. Chamadores diretos devem usar Bearer. Se você não sabe qual deles possui, use Bearer.

Pontos de extremidade

Duas rotas; escolha com base em como seu serviço se autentica, não pelo que o usuário está fazendo:

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

Cabeçalhos:

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

Parâmetros de URL

• {tenantId} – GUID do locatário do cliente. O servidor trata esse valor como autoritativo; se seus spans definirem microsoft.tenant.id e não corresponderem, a solicitação será rejeitada.
• {agentId} – o appId do aplicativo de chamada (também conhecido como client_id do OAuth). Para identidades derivadas de blueprint, trata-se do appId da identidade do agente, não do appId do blueprint. Deve ser igual à declaração appid / azp do seu token.
• api-version=1 - obrigatório.

Codificação do corpo da solicitação

O corpo segue o formato padrão OTLP/HTTP+JSON: um ExportTraceServiceRequest com resourceSpans → scopeSpans → spans. Lembre-se dos seguintes detalhes:

• traceId (16 bytes) e spanId (8 bytes) são enviados como cadeias de caracteres hexadecimais em minúsculas.
• startTimeUnixNano / endTimeUnixNano são cadeias de caracteres que contêm nanossegundos da época Unix.
• kind representa o valor inteiro da enumeração OTLP (por exemplo, 1 para INTERNAL); status.code representa o valor inteiro da enumeração (por exemplo, 1 para OK, 2 para ERROR).
• Todos os valores de atributo são enviados como stringValue.

Estrutura da resposta

Uma chamada bem-sucedida retorna 200 OK:

{ "partialSuccess": null }

Se alguns spans forem rejeitados pelo filtro por span:

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

Os nomes dos campos usarão camelCase na transmissão. Sempre verifique partialSuccess: um código 200 com todos os seus spans rejeitados é um resultado real que precisa ser reportado. Limites e condições de remoção lista os casos de remoção silenciosa em que uma resposta 200 é retornada com partialSuccess: null, mesmo que nenhum dado apareça nos sistemas downstream.

A menor solicitação possível

O teste mais simples de ponta a ponta envia um único span invoke_agent. Esse span é o menor corpo de dados que chega ao Microsoft Defender.

Etapa 1. Obtenha um token de portador. Para S2S, use credenciais de cliente com escopo 9b975845-388f-4429-889e-eab1ef63949c/.default (veja Métodos de autenticação para ver as instruções completas).

Etapa 2. Envie um único span via POST:

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

Etapa 3. Espere 200 OK com este corpo:

{ "partialSuccess": null }

Etapa 4. Confirme que os dados foram realmente recebidos. Uma resposta 200 OK não é prova de ingestão; Verificando a ingestão explica o fluxo de verificação. Para enviar um arquivo de corpo já salvo via POST, substitua --data @- <<EOF ... EOF por --data @./otlp-request.json.

Exemplo de execução do agente

Um usuário do Microsoft Teams pergunta: "Como está o clima em Seattle?". Seu agente chama uma função GetWeather, pede a um LLM para formatar a resposta e responde. Essa única execução consiste em quatro spans:

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 definidos para toda a execução, aplicados em todos os spans:

Span A: invoke_agent (raiz)

{
  "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 */
  ]
}

Span B: chat (chamada de 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 */
  ]
}

Span 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 */
  ]
}

Span 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 */
  ]
}

Enviando telemetria

Usando um SDK do OTel

A maioria dos parceiros envia rastreamento por meio de um SDK do OTel, em vez de construir chamadas HTTP manualmente. O SDK cuida do envio em lote, das tentativas de reenvio e da codificação OTLP/HTTP+JSON para você. Defina o ponto de extremidade exportador e injete o cabeçalho Authorization.

O ponto de extremidade do exportador é a própria URL da rota, incluindo a cadeia de consulta:

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

(Use /observability/... em vez de /observabilityService/... para a rota 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}"},
)

Pacote: 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}` },
});

Pacote: @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;
    }));

Pacote: OpenTelemetry.Exporter.OpenTelemetryProtocol.

HTTP manual

Se você não puder ou não quiser usar um SDK do OTel, crie a solicitação OTLP/HTTP+JSON manualmente e envie-a via POST. O formato do corpo é definido pela especificação OTLP/HTTP+JSON do OpenTelemetry:

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

Cada <span> é um objeto cujos campos obrigatórios são traceId, spanId, name, kind, startTimeUnixNano, endTimeUnixNano, attributes e, para spans não raiz, parentSpanId. Veja Pontos de extremidade e Codificação do corpo da solicitação para ver as regras de codificação (tempos codificados como cadeias de caracteres, valores em hexadecimal traceId / spanId, valores inteiros kind / status.code, todos os valores de atributos como stringValue).

O conjunto de atributos a ser definido em cada span é especificado em Contratos de mensagem. Consulte Referência de atributo para ver a lista completa de atributos. Consulte o Exemplo de execução do agente para ver um exemplo funcional de ponta a ponta com o token de portador no cabeçalho e o corpo em linha.

Você pode enviar todos os spans de uma execução em um único corpo de POST (preferido - uma solicitação, um rastreamento) ou em vários POSTs. O servidor reconstrói a execução a partir de traceId + parentSpanId + gen_ai.conversation.id, de modo que cada span carregue informações suficientes para ser correlacionado de qualquer forma.

Contratos de mensagem

Esta seção define quais spans você pode emitir e quais atributos vão em cada um. Para a especificação detalhada de cada atributo, consulte a Referência de atributo.

Tipos de operação

Cada span que você enviar deve ter gen_ai.operation.name definido como um destes quatro valores (não diferencia maiúsculas de minúsculas). Qualquer span com um valor ausente ou não reconhecido é removido silenciosamente e contabilizado em partialSuccess.rejectedSpans.

Hierarquia de span e agrupamento de execução

O Agent 365 reconstrói uma execução a partir do grafo padrão do span OTLP (traceId, spanId, parentSpanId) mais os atributos de toda a execução provenientes da Referência de atributo.

Seis regras:

1. Sempre defina parentSpanId em cada span que não seja raiz. Sem isso, a estrutura em árvore da execução não pode ser reconstruída.
2. Mantenha o mesmo traceId em todos os spans da execução.
3. Defina gen_ai.conversation.id em cada span com o mesmo valor. Esta é a chave primária de junção para "todos os spans nesta execução". Ela não é propagada automaticamente.
4. Defina microsoft.channel.name em cada span com o mesmo valor. Spans de ferramentas que não possuem canal/conversa podem herdá-los do span pai invoke_agentsomente se o pai estiver na mesma solicitação OTLP; portanto, atribua-os manualmente em cada span.
5. Defina microsoft.session.id em cada span quando tiver uma sessão lógica.
6. Para chamadas entre agentes em que o agente filho está em uma solicitação separada, reutilize o mesmo gen_ai.conversation.id e use os atributos microsoft.a365.caller.agent.* (veja Referência de atributo) para capturar o contexto do agente chamador.

A árvore de quatro spans no Exemplo de execução do agente é o formato canônico.

Formatos comuns de execução

Lista de verificação de integração

Revise esta lista de verificação antes de entrar em produção.

Próximas etapas

• Referência de atributo - especificações por atributo e orientações para seleção de valores.
• Solução de problemas - verificando a ingestão, armadilhas comuns e respostas a erros.