Agent 365 可观测性概念

本文解释了Agent 365可观测性数据模型，包括代理发出哪些遥测数据、谁可以发射、落点以及适用的限制。 使用这些概念来规划集成，并了解 Microsoft OpenTelemetry 发行版、Agent 365 SDK 和 直接使用 OTel 中的遥测。

注释

线路级别详细信息 - 身份验证中的 URL 路由、 限制和删除条件中的 HTTP 错误代码，以及每个请求的大小和速率限制 - 具体适用于直接 OTel 路径。 SDK 和发行版为你抽象这些内容。 本文的其余部分（术语表、数据流、身份模型、作用域、丢弃条件以及数据显示的位置）适用于所有路径。

选择集成路径

三个路径向 Agent 365 发出相同的跨度数据模型。 选择一个：

路径 Description
Microsoft OpenTelemetry 发行版 推荐用于新集成。 适用于 Agent 365、Microsoft Foundry、Azure Monitor 等的统一可观测性 SDK。
Agent 365 SDK （Observability SDK） 早期的SDK版本。 继续运行，没有中断性变更，但不再是新集成的推荐路径；面向现有 SDK 用户的迁移指南即将发布。
直接使用 OTel 原始的OTLP/HTTP路径。 仅在以下情况下才使用它：你已经部署了 OpenTelemetry 管道、你的代理框架无法使用 Agent 365 SDK，或者你的代理使用的是 SDK 尚未支持的语言（如 Java）。

无论选择哪种路径，数据模型、标识模型、范围、限制和下游图面都适用。

Agent 365 可观测性术语表

条款 Description
应用ID （appId） 当注册 Microsoft Entra 应用或 Microsoft Entra 智能体 ID 代理身份时，应用标识符会发出。
- 等同于 OAuth client_id，而非 Microsoft Entra 对象 ID。
- 在这些文档中，“agent id”和“blueprint id”都指一个 appId。
对话 代理交互的逻辑会话线程，例如 Teams 聊天线程。
- 由gen_ai.conversation.id识别。
- 某次运行的主连接键。
Channel 代理运行所在的界面：msteams、outlook、web 等等。
运行 输入一条用户消息，输出一条代理回复。被建模为一棵共享同一个 的 OTel traceId 树。

Agent 365 可观测性的工作原理

有关Agent 365及其收集的遥测数据概述，请参见Microsoft Agent 365概述。

将遥测数据作为 OpenTelemetry 跟踪数据发送：

  • 描述一次运行（一条用户消息进入，一个智能体回复输出）的跨度树。
  • 每个范围描述了一个步骤 - 顶级代理调用、LLM 调用、工具调用或最终答复。

Agent 365 可观测性数据流

下图展示了代理遥测数据如何流经身份验证和 Agent 365 可观测性数据引入流程，并最终流向下游 Microsoft 365 体验。

Agent 365 可观测性数据流图。

标识模型

关于代理身份模型的完整说明（标准 Microsoft Entra 应用注册与 Microsoft Entra 智能体 ID 代理身份蓝图，包括 AI 团队成员），请参见代理身份。 你选择的标识模型决定了使用的身份验证流和终结点。

如果代理没有Microsoft Entra注册，则无法直接使用这些路由。 通过备用ID属性识别代理（参见 属性参考），并联系代理365团队了解合适的入口路径。

Authentication

身份验证取决于您的服务是验证自身身份，还是代表用户进行身份验证。 分支确定 OAuth 流、携带权限的令牌声明和 URL 路由。

  • 服务本身进行身份验证：无登录用户 - 自治、计划或事件驱动。

    • OAuth 流：服务到服务 (S2S) 客户端凭据。
    • 令牌声明：roles。
    • URL 路由： /observabilityService/....

  • 服务代表用户进行身份验证：对于 AI 团队成员或代理自己的用户帐户。

    • OAuth 流：代理 (OBO)。
    • 令牌声明：scp。
    • URL 路由： /observability/....

同一智能体应用可以参与两个流，如也会在每晚运行自主摘要传递的 AI 队友。 有关详细信息，请参阅自主应用 OAuth 流和智能体流。

有关身份模型和流程各组合的完整令牌配置方案，请参阅《集成指南》中的 身份验证方案。

代理身份与 URL 绑定

URL 中的 {agentId} 必须等于调用应用程序的 appId（即令牌中的 appid 或 azp 声明）。 不匹配时返回 403 Forbidden。 对于蓝图派生的身份，{agentId} 是智能体身份 appId，不是蓝图 appId。

此外，你发送的每个 span 都必须将 gen_ai.agent.id 设置为相同的 appId；服务器会根据已通过身份验证的代理来验证负载中的代理标识，并拒绝任何不匹配的情况。 此步骤用于检测是否意外将来自多个代理的跨度数据混入同一个请求中。

范围（委托）或应用角色（应用程序）是 Microsoft Entra 在访问令牌中创建的命名权限。 对于 Agent 365 遥测，权限是 Agent 365 可观测性资源上的 Agent365.Observability.OtelWrite（访问群体 9b975845-388f-4429-889e-eab1ef63949c）。

相同的权限名称被注册为 两种 类型：

  • 自主（S2S/客户端凭据）流的应用角色。 登陆 roles 声明。 由 <resource>/.default 选择。
  • 用于 OBO 流的委托作用域。 登陆 scp 声明。 由 <resource>/Agent365.Observability.OtelWrite（或 <resource>/.default）选择。

Agent 365 还提供一项读取端权限 Agent365.Observability.OtelRead，供查询Agent 365遥测数据的操作员使用。 大多数合作伙伴不需要它 - 这些文档仅介绍引入。

给你的应用添加权限

  • 对于标准 Microsoft Entra 应用注册：在 Azure 门户中，在智能体的应用注册的 API 权限下添加 Agent365.Observability.OtelWrite（对于 S2S 为应用角色，对于委托为范围）。
  • 对于蓝图：从 Microsoft Entra 智能体 ID 智能体身份蓝图创建的智能体会继承蓝图中定义的 OAuth 权限，因此租户管理员只需预先配置一次权限。 从该蓝图生成的每个代理实例都会自动接收它们。 请参阅 配置代理标识蓝图的可继承权限。

在令牌携带角色或范围之前，客户租户中的租户管理员必须授予同意。 请参阅 授予代理访问 Microsoft 365 资源的权限。

未经同意，令牌获取会失败，并显示 AADSTS65001（The user or administrator has not consented to use the application with ID...）；或者，颁发的令牌不包含 roles 或 scp 声明，而引入终结点会以 403 拒绝该请求。

每个租户授予一次同意，授予后将应用于此后从蓝图生成的每个实例。 仅当向蓝图添加新权限时，才需要重新确认。

限制和删除条件

事先了解这些限制，可以避免集成过程中出现意外。 某些失败情况即使返回了成功的 HTTP 状态码，响应也会表明遥测数据未被接受。

线路级限制：

  • 你必须在每个请求中包含 api-version=1 。
  • 最大请求主体大小为 1 MB。 较大的请求返回 413 Payload Too Large。
  • 这两个路由具有 单独的速率限制。 在 429 上，接受 Retry-After（设置为 1 秒），然后抖动退出。

已接入的、使用 S2S 身份验证的第三方集成可在发送遥测数据前，选择先调用 租户资格终结点 进行预检。 使用该端点时，应依赖其判定，而不是仅根据同意或许可来推断是否符合条件。 回复 enabled: false 意味着租户目前不符合资格。 无正文的 503 Service Unavailable 表示无法确定资格。 如果你仍需要资格判定结果，请根据其 Retry-After 标头指示重试。

错误响应：

  • 403 Forbidden：令牌缺少所需的应用角色或作用域，或者 URL 中的 {agentId} 与你的令牌的 azp 或 appid 不匹配。
  • 413 Payload Too Large：正文超过 1 MB。
  • 429 Too Many Requests：已触发速率限制；请遵循 Retry-After: 1 并采用抖动退避。

数据丢弃条件（HTTP 已接受请求，但数据未出现在下游）：

# 条件 Behavior
1 span gen_ai.operation.name 缺失或不在 {invoke_agent, execute_tool, chat, output_messages} 中 每跨度删除。 在 partialSuccess.rejectedSpans + errorMessage 中显示。
2 客户租户中没有任何用户分配有 Microsoft 365 E7 或 Microsoft Agent 365 许可证。 租户中至少有一个用户必须分配有许可证（仅租户中存在 SKU 还不够 - 分配会触发 Defender 后端工作流）。 许可用户不必是智能体的人工调用方。 请求返回 200 OK，但每个 span results 的条目都有一个 rejected 状态和原因 tenant_not_licensed。

一个200 OK并不能证明已发生摄入。 检查响应的 results，并使用 验证流程 确认数据已成功落地。

Agent 365可观测性数据出现在哪里

接受后，您的跨度将出现在三个面向客户的体验中。 三个都依赖于运行根处的有效 invoke_agent 跨度。 仅包含 chat / execute_tool / output_messages 跨度的运行可在 Defender 高级搜寻中查询（CloudAppEvents 表），但在下面的所有其他界面都不可见。

Experience Description
Microsoft Defender 代理活动 （invoke_agent， ， execute_toolchat） 显示在代理活动视图中。 租户管理员和安全分析师可以深入查看单个运行记录、工具和推理调用。 智能体活动视图以 invoke_agent 跨度为依据；如果没有该跨度，运行将不会显示在那里，即使子跨度仍可通过高级搜寻进行查询。 高级搜寻视图 - CloudAppEvents - 接受所有操作：ActionType 反映该操作（InvokeAgent、InferenceCall、ExecuteToolBySDK、ExecuteToolByGateway、ExecuteToolByMCPServer），而每个 span 的字段位于 RawEventData 中。 客户可见的字段名称直接映射到你发送的 span 属性： ConversationId ← gen_ai.conversation.id、 SessionIdentity ← microsoft.session.id、 AgentId ← gen_ai.agent.id、 PlatformTargetAgentId ← microsoft.a365.agent.platform.id等。 请参阅属性参考以了解完整映射。
Microsoft 365 管理中心 智能体活动也会显示在租户管理员用于管理其租户内智能体的智能体清单和安全视图中。 管理中心仅导入 invoke_agent 行数据：没有 invoke_agent 遥测数据的智能体不会出现在库存中，且仅发出 chat、execute_tool 或 output_messages 的运行在此处不可见。 管理中心从 invoke_agent span 元素中读取属性，例如代理 ID、代理名称、蓝图 ID、呼叫者身份、会话 ID、渠道和错误状态。
Microsoft Purview 代理活动还会显示给 Microsoft Purview 中的合规管理员，他们可以在代理运行时配置数据处理和策略规则（数据丢失预防、保留、通信合规等）。 Purview 策略所识别的属性（代理 ID、蓝图 ID、呼叫者身份、对话、信道、请求和响应消息）来自该 invoke_agent 区间及其后代。

后续步骤

  • 属性参考 - 每个属性规范、要求和值选取指南。
  • 故障排除 - 验证引入、常见陷阱和错误响应。
  • Last updated on