Agent 365 可观测性概念

本文介绍了 Agent 365 可观测性背后的数据模型，包括遥测代理会发送哪些遥测数据、哪些主体可以发送这些数据、这些数据会发送到哪里，以及适用的限制。 这些概念适用于 every 集成路径：Microsoft OpenTelemetry DistroAgent 365 SDK 和 direct OTel。

注释

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

选择集成路径

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

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

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

Glossary

  • App id （appId）：注册Microsoft Entra应用或Microsoft Entra 智能体 ID代理标识时颁发的应用程序标识符。
    • 等同于 OAuth client_id，而不是 Microsoft Entra 对象 ID。
    • 在这些文档中，“代理 ID”和“蓝图 ID”均指 appId。
  • 对话：代理交互的逻辑线程，例如 Teams 聊天线程。
    • 使用 gen_ai.conversation.id 标识。
    • 某次运行的主联接键。
  • 渠道：代理运行所在的载体：msteams、outlook、web等等。
  • 运行：输入一条用户消息，输出一条智能体回复。其被建模为一棵由 OTel span 构成的树，共享同一个 traceId。

工作原理

有关 Agent 365 以及遥测数据流向的概述，请参阅 Microsoft Agent 365 概述。

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

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

数据流

   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)                  |
  +-------------------------------------+

标识模型

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

如果代理没有Microsoft Entra注册，则无法直接使用这些路由。 通过备用 ID 属性（请参阅 “属性参考”）标识代理，并联系 Agent 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；服务器会根据已通过身份验证的代理来验证负载中的代理标识，并拒绝任何不匹配的情况。 此步骤用于检测是否意外将来自多个代理的跨度数据混入同一个请求中。

scope（委托）或 app role（应用程序）是 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（“用户或管理员尚未授予同意”）；或者签发的令牌中不包含 roles / scp 声明，引入端点会返回 403 并拒绝该请求。

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

限制和删除条件

提前了解这些限制可防止集成期间出现意外 - 大多数是无提示的（API 接受请求，但数据从未出现在下游）。

线路级限制：

  • 每个请求都需要 api-version=1。
  • 最大请求正文大小为 1 MB。 较大的请求会得到 413 Payload Too Large。
  • 这两个路由具有 单独的速率限制。 启用 429 时，遵循 Retry-After（设为 1 秒），并采用抖动退避。

错误响应：

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

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

# 条件 行为
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 { "partialSuccess": null }。

200 OK 并不能证明已摄取成功。 使用 验证流程 来确认数据已落地。

您的数据显示位置

一经接受，你的 span 将出现在三个面向客户的使用场景中。 这三者都依赖于运行根处的有效 invoke_agent 范围。 仅包含 chat / execute_tool / output_messages spans 的一次运行可在 Defender 高级搜寻中查询到（位于 CloudAppEvents 表中），但在下面的所有其他界面中都不可见。

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的运行在此处也不会显示。 管理中心读取的属性（代理 ID、代理名称、蓝图 ID、调用方标识、聊天 ID、通道、错误状态）都来自 invoke_agent 范围。

Microsoft Purview。 代理活动也会在 Microsoft Purview 中呈现给合规管理员，管理员可在其中针对代理运行配置数据处理和策略规则（如数据丢失防护、保留、通信合规性等）。 Purview 策略所依据的属性（代理 ID/蓝图 ID、调用方标识、对话/通道、请求和响应消息）都来自 invoke_agent span 及其后代元素。

后续步骤

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