使用直接 OTel 集成智能体可观测性

本指南将端到端演练通过 OpenTelemetry (OTLP/HTTP+JSON) 直接将智能体遥测数据发送到 Agent 365。 开始前，请阅读 Agent 365 可观测性概念，以了解模型、身份验证流以及数据所进入的平台。

必备条件

请确保在任何遥测数据流动之前，已完成以下配置。

身份验证方案

全部四种方案都使用标准的 Microsoft Entra 令牌终结点：

下面的方案显示原始 HTTP 以获取清晰度。 在生产中，建议使用 Microsoft.Identity.Web 或其他 MSAL 库，以处理库刷新和缓存。

我需要哪个方案？

S2S，标准 Microsoft Entra 应用

使用 grant_type=client_credentials 向租户的令牌终结点发送一次 POST。 使用客户端密码、证书（签名的 JWT 断言）、托管标识或联合凭据对应用进行身份验证。

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

返回的令牌具有 appid/azp = {your-app-id}，roles 包含 Agent365.Observability.OtelWrite 且 aud = 9b975845-...。 在 /observabilityService/.../traces 路由上使用它。

对于基于证书的身份验证，将 client_secret={secret} 替换为 client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={signed-jwt}。

S2S，蓝图派生的智能体标识

智能体身份本身不具备凭据。 智能体身份蓝图 持有凭据（托管身份 FIC、证书或客户端密钥），并通过两步交换流程代表其子智能体身份生成令牌。 有关详细信息，请参阅自主应用 OAuth 流。

1. 蓝图获取联合标识交换令牌 T1 并进行身份验证：

   • {blueprint-credential} 是蓝图的 MSI 令牌、证书签名的 JWT 或密钥交换令牌断言 - 具体取决于蓝图配置。

   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. 智能体身份将 T1 交换为 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
   

   • 返回的令牌具有 appid/azp = {agent-identity-app-id}，roles 包含 Agent365.Observability.OtelWrite 且 aud = 9b975845-...。
   • 在 /observabilityService/.../traces 路由上使用该令牌。
   • URL {agentId} 是智能体身份 appId，而非蓝图 appId。

OBO，标准 Microsoft Entra 应用

从上游调用方接收用户的传入令牌 Tc（Bearer 或 PFAT），然后进行交换：

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

对于证书身份验证，将 client_secret={secret} 替换为与 S2S 中相同的 client_assertion_type + client_assertion 对。

返回的令牌具有 appid/azp = {your-app-id}，scp 包含 Agent365.Observability.OtelWrite 且 aud = 9b975845-...。 在 /observability/.../traces 路由上使用它。 同时返回一个刷新令牌；将其缓存并重用，而不是每次调用时都重新运行交换。

OBO，蓝图派生的智能体标识（包括 AI 队友）

“代表”流主要包括三个步骤。 有关更多信息，请参阅智能体 OAuth 流：代表流。

1. 接收用户令牌 Tc。 对于 AI 团队成员，此令牌代表智能体自身用户账户；否则，它代表人类调用者。

2. 蓝图获取 T1 并进行身份验证，与 S2S 蓝图派生的智能体标识流相同。

3. 智能体标识针对委派的资源令牌交换 T1 和 Tc：

   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
   

返回的令牌具有 appid/azp = {agent-identity-app-id}，scp 包含 Agent365.Observability.OtelWrite，并表示智能体的用户。 在 /observability/.../traces 路由上使用它。 URL {agentId} 是智能体身份 appId，而非蓝图 appId。 同时返回一个刷新令牌；将其缓存并重用。

返回令牌上的必需声明

S2S 路由 (/observabilityService/...) - 仅限应用令牌：

委托路径 (/observability/...) - 用户委托令牌（Bearer 或 PFAT）：

委派的路由接受 Bearer 和 MSAuth1.0 PFAT 令牌。 直接调用方应使用 Bearer。 如果您不知道自己拥有哪种，请使用 Bearer。

终结点

有两种路由；请根据您的服务 进行身份验证的方式（而不是用户正在执行的操作）进行选取：

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

标题：

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

URL 参数

• {tenantId} - 客户租户 GUID。 服务器将此视为权威值；如果您的数据段设置 microsoft.tenant.id，但它不同意，请求将遭到拒绝。
• {agentId} - 调用应用程序的 appId（也称为 OAuth client_id）。 对于蓝图派生的标识，这是智能体标识 appId，而不是蓝图 appId。 必须与令牌的 appid / azp 声明相等。
• api-version=1 - 必需。

请求正文编码

正文采用标准 OTLP/HTTP+JSON 格式：一个 ExportTraceServiceRequest 包含 resourceSpans → scopeSpans → spans。 牢记以下详细信息：

• traceId（16 个字节）和 spanId（8 个字节）以小写的十六进制字符串形式发送。
• startTimeUnixNano / endTimeUnixNano 是包含 Unix epoch 纳秒的字符串。
• kind 是整数 OTLP 枚举值（例如对于 INTERNAL 为 1）；status.code 是整数枚举（例如对于 OK 为 1，对于 ERROR 为 2）。
• 所有属性值都以 stringValue 形式发送。

回复结构

成功的调用返回 200 OK：

{ "partialSuccess": null }

如果某些数据段被按数据段过滤器拒绝：

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

传输中的字段名称采用驼峰命名法。 务必检查 partialSuccess：所有数据段均被拒绝但返回 200 状态码是真实可能的结果，必须予以显示。 限制与丢弃条件列出了无声丢弃的情况，即尽管下游未出现数据，但仍返回 200 状态码并包含 partialSuccess: null。

可能的最小请求

最简单的端到端测试发送单个 invoke_agent 数据段。 此数据段是最终进入 Microsoft Defender 的最小数据主体。

第 1 步。 获取持有者令牌。 对于 S2S，使用带有范围 9b975845-388f-4429-889e-eab1ef63949c/.default 的客户端凭据（有关完整方案，请参阅身份验证方案）。

步骤 2. 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

第 3 步。 预期 200 OK 返回此数据主体：

{ "partialSuccess": null }

第 4 步。 确认数据确实已接收。 200 OK 状态码不代表已成功摄入；验证摄入详细说明了验证流程。 若要 POST 已保存的数据主体文件，请将 --data @- <<EOF ... EOF 替换为 --data @./otlp-request.json。

智能体运行示例

Microsoft Teams 上的用户询问：“西雅图的天气如何？” 您的智能体调用 GetWeather 函数，要求 LLM 生成答案，然后回复。 本次运行有四个数据段：

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

在每个数据段上设置全局属性：

数据段 A：invoke_agent（根）

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

数据段 B：chat（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 */
  ]
}

数据段 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 */
  ]
}

数据段 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 */
  ]
}

发送遥测数据

使用 OTel SDK

大多数合作伙伴通过 OTel SDK 发送跟踪，而不是手写 HTTP。 SDK 为您处理批处理、重试和 OTLP/HTTP+JSON 编码。 设置导出程序终结点并引入 Authorization 标头。

导出程序终结点是路由 URL 本身，包括查询字符串：

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

（为委派的路由使用 /observability/...，而非 /observabilityService/...。）

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}"},
)

数据包：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}` },
});

数据包：@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;
    }));

数据包：OpenTelemetry.Exporter.OpenTelemetryProtocol。

手动 HTTP

如果您不能或不想要使用 OTel SDK，自行生成 OTLP/HTTP+JSON 请求并对其执行 POST 操作。 正文结构由 OpenTelemetry OTLP/HTTP+JSON 规范定义：

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

每个 <span> 都是一个对象，其必填字段包括 traceId、spanId、name、kind、startTimeUnixNano、endTimeUnixNano、attributes 和（对于非根数据段）parentSpanId。 有关编码规则（字符串编码的时间、十六进制 traceId / spanId、整数 kind / status.code 以及作为 stringValue 的所有属性值），请参阅终结点和请求正文编码。

要在每个数据段上设置的属性集均在消息合同中定义。 有关完整的属性列表，请参阅属性引用。 请参阅 智能体运行示例，获取包含标头中 Bearer 令牌和内联正文的端到端工作示例。

您可以在一个 POST 正文（首选 - 一个请求、一个跟踪）中或跨多个 POST 发送一次运行的所有数据段。 服务器从 traceId + parentSpanId + gen_ai.conversation.id 重新构建运行，因此每个数据的都具有足够的信息以实现关联，无论采用哪种方式。

消息合同

本部分定义可以发送哪些数据段，以及每个数据段应包含哪些属性。 有关完整的按属性规范，请参阅属性引用。

操作类型

您发送的每个数据段都必须将 gen_ai.operation.name 设置为以下四个值之一（不区分大小写）。 任何缺少值或值无法识别的数据段将被静默丢弃，并计入 partialSuccess.rejectedSpans。

数据段层次结构与运行分组

Agent 365 通过标准 OTLP 数据段图 (traceId, spanId, parentSpanId) 以及属性参考中全运行范围的属性来重建运行。

六个规则：

1. 在每个非根数据段上始终设置 parentSpanId。 若缺少此信息，则无法重建运行的树形结构。
2. 在一次运行的所有数据段中重用相同的 traceId。
3. 使用相同值在每个数据段上设置 gen_ai.conversation.id。 这是“此运行中的所有数据段”的主要连接键。 它不会自动传播。
4. 使用相同值在每个数据段上设置 microsoft.channel.name。 缺少通道/对话的工具数据段invoke_agent仅当其父节点位于同一 OTLP 请求中时，才可从父节点继承这些信息，因此请务必在每个数据段上自行设置这些属性。
5. 在有逻辑会话时，在每个数据段上设置 microsoft.session.id。
6. 对于子智能体位于单独请求中的智能体到智能体调用，请重用相同的 gen_ai.conversation.id 并使用 microsoft.a365.caller.agent.* 属性（请参阅属性引用）以捕获呼叫方智能体上下文。

智能体运行示例中的四个数据段树是规范的结构。

常见运行结构

入职检查清单

在进入生产之前检查此清单。

后续步骤

• 属性引用 - 每个属性规范和取值指导。
• 故障排除 - 验证引入、常见陷阱和错误回复。