Agent 365 可观测性概念

本文阐述了 Agent 365 可观测性背后的数据模型——遥测智能体会发送哪些数据、哪些主体可以发送这些数据、数据会发送到何处，以及适用的限制。 这些概念适用于所有集成路径：Microsoft OpenTelemetry Distro、Agent 365 SDK 以及直接 OTel。

备注

网络层面的细节——身份验证中的 URL 路由、限制与丢弃条件中的 HTTP 错误代码，以及每条请求的大小和速率限制——专门适用于直接 OTel 路径。 SDK 和 Distro 会为您抽象这些细节。 本文其余内容（术语表、数据流、身份模型、作用域、丢弃条件、数据显示位置）适用于所有路径。

选择您的集成路径

三种路径都会将相同的跨度数据模型发送到 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）时才使用此 SDK。

无论您选择哪种路径，下文所述的数据模型、身份模型、作用域、限制以及下游接口均适用。

术语表

  • 应用 ID (appId)：在注册 Microsoft Entra 应用或 Microsoft Entra 智能体 ID 智能体身份 时生成的应用程序标识符。
    • 等同于 OAuth client_id，不是 Microsoft Entra 对象 ID。
    • 在本文档中，“智能体 ID”和“蓝图 ID”均指 appId。
  • 对话：智能体交互的逻辑线程，例如 Teams 聊天线程。
    • 使用 gen_ai.conversation.id 标识。
    • 运行的主要联接键。
  • 频道：智能体运行的界面：msteams、outlook、web等。
  • 运行：一条用户消息进入，一个智能体回复输出。建模为共享 traceId 的 OTel 跨度树。

工作原理

有关 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 团队了解合适的入口路径。

身份验证

身份验证流程取决于您的服务是自行进行身份验证，还是代表用户进行身份验证。 该分支决定了 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。

此外，您发送的每个跨度都必须将 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 错误（“用户或管理员未同意”）而失败，或者令牌将不包含 roles / scp 声明，此时数据摄取端点会以 403 状态码拒绝该请求。

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

限制和删除条件

提前了解这些限制可避免集成过程中的意外情况——大多数情况是无提示的（API 接受请求，但数据从未出现在下游）。

网络层限制：

  • 每个请求都必须包含 api-version=1。
  • 请求正文的最大大小为 1 MB。 超过此大小的请求将返回 413 Payload Too Large。
  • 这两条路由有各自的速率限制。 在 429 上，接受 Retry-After（设置为 1 秒），然后抖动退出。

错误响应：

  • 403 Forbidden--令牌缺少必需的应用角色/作用域，或 URL 中的 {agentId} 与令牌的 appid / azp 不匹配。
  • 413 Payload Too Large--请求正文超过 1 MB。
  • 429 Too Many Requests--到达速率限制；接受 Retry-After: 1 并抖动退出。

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

# 条件 行为
1 跨度 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 正常”不能证明已经引入。 使用验证流确认数据登陆。

您的数据的显示位置

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

Microsoft Defender。 智能体活动 (invoke_agent, execute_tool, chat) 会显示在智能体活动视图中。 租户管理员和安全分析师可以深入分析单个运行、工具和推理调用。 智能体活动视图以 invoke_agent 跨度为依据；如果没有该跨度，运行将不会显示在那里，即使子跨度仍可通过高级搜寻进行查询。 高级搜索视图 - CloudAppEvents - 接受所有操作：ActionType 反映了操作 (InvokeAgent, InferenceCall, ExecuteToolBySDK, ExecuteToolByGateway, ExecuteToolByMCPServer) ，而每个跨度字段位于 RawEventData 内。 客户可见的字段名称与您发送的跨度属性直接映射：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 跨度及其后代。

后续步骤

  • 属性参考 - 各属性的规范、要求及值选择指南。
  • 故障排除 - 验证引入、常见陷阱和错误回复。
  • Last updated on