本文解释了Agent 365可观测性数据模型，包括代理发出哪些遥测数据、谁可以发射、落点以及适用的限制。 利用这些概念规划你的集成，并了解Microsoft OpenTelemetry 发行版、已弃用的 Agent 365 Observability SDK以及直接 OTel中的遥测数据。
Note
线路级别详细信息 - 身份验证中的 URL 路由、 限制和删除条件中的 HTTP 错误代码，以及每个请求的大小和速率限制 - 具体适用于直接 OTel 路径。 SDK 和发行版为你抽象这些内容。 本文的其余部分（术语表、数据流、身份模型、作用域、丢弃条件以及数据显示的位置）适用于所有路径。
选择集成路径
三个路径向 Agent 365 发出相同的跨度数据模型。 选择一个：
| Path | Description |
|---|---|
| Microsoft OpenTelemetry 发行版 | 推荐用于新集成。 适用于 Agent 365、Microsoft Foundry、Azure Monitor 等的统一可观测性 SDK。 |
| 已弃用的 Agent 365 可观测性 SDK | 遗留的SDK。 现有的集成依然有效，但不要用它来做新的集成。 文章包含迁移指南。 |
| 直接使用 OTel | 原始的OTLP/HTTP路径。 只有在你已经有 OpenTelemetry 流水线、你的代理框架无法使用 Microsoft OpenTelemetry 发行版，或者你的代理是用发行版尚未支持的语言编写的（比如 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 体验。
标识模型
关于代理身份模型的完整说明（标准 Microsoft Entra 应用注册与 Microsoft Entra 智能体 ID 代理身份蓝图，包括 AI 团队成员），请参见代理身份。 你选择的标识模型决定了使用的身份验证流和终结点。
蓝图派生的代理身份只有在代理365注册完成后（例如通过 a365 setup all 完成注册），才会成为代理365注册代理实例。 仅仅创建 Microsoft Entra 身份并不会注册该实例。 标准的 Microsoft Entra 应用注册，比如自定义引擎代理使用的，不是已注册的代理实例。
如果代理没有Microsoft Entra注册，则无法直接使用这些路由。 通过备用ID属性识别代理（参见 属性参考），并联系代理365团队了解合适的入口路径。
Authentication
认证取决于你的服务是自我认证还是代表用户认证。 这一区分决定了OAuth流、携带权限的令牌声明以及URL路由。
服务本身进行身份验证：无登录用户 - 自治、计划或事件驱动。
- OAuth 流： 服务到服务（S2S） 客户端凭据。
- 令牌声明：
roles. 未注册身份需要Agent365.Observability.OtelWrite应用角色。 一个注册为Agent 365的代理实例可以使用仅应用的令牌，而无需该角色。 - 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）选择。
在 S2S 路径中，已注册到 Agent 365 的代理实例可以使用不含 Agent365.Observability.OtelWrite 角色的纯应用令牌进行导出。 它不需要可观测性权限或管理员同意即可导出遥测数据。 未注册身份仍然需要应用角色，委派路由仍需委派权限范围和管理员同意。
Agent 365 还提供一项读取端权限 Agent365.Observability.OtelRead，供查询Agent 365遥测数据的操作员使用。 大多数合作伙伴不需要它 - 这些文档仅介绍引入。
给你的应用添加权限
- 对于标准的 Microsoft Entra 应用注册：在 Azure 门户中，在代理应用注册的
Agent365.Observability.OtelWrite下添加。 S2S用应用角色，OBO用委派范围。 - 对于 S2S 路由的蓝图衍生代理实例：完成代理实例的 Agent 365 注册。 注册实例不需要Observability API权限或管理员同意即可在S2S路由上导出遥测数据。
- 对于 委托路由中的蓝图派生代理实例：将委托
Agent365.Observability.OtelWrite范围添加到蓝图中，使代理实例继承该范围。 请参阅 配置代理标识蓝图的可继承权限。 要使用 Agent 365 CLI 添加它，请参见 可观测性权限。
租户同意
在令牌具有所需的角色或范围之前，必须由客户租户中的租户管理员授予同意。 请参阅 授予代理访问 Microsoft 365 资源的权限。
未经同意，令牌获取会失败，并显示 AADSTS65001（The user or administrator has not consented to use the application with ID...）；或者，颁发的令牌不包含 roles 或 scp 声明，而引入终结点会以 403 拒绝该请求。
一个通过 S2S 路由导出的已在 Agent 365 注册的代理实例不需要 Observability 管理员同意。 使用应用角色的未注册S2S身份以及所有使用委派范围的委派路由导出仍需获得同意。
当需要同意时，同意按 租户 仅需授予一次，之后根据蓝图构建的每个实例都适用。 仅当向蓝图添加新权限时，才需要重新确认。
限制和删除条件
事先了解这些限制，可以避免集成过程中出现意外。 某些失败情况即使返回了成功的 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可观测性数据出现在哪里
接受 span 后，它们会出现在三个面向客户的体验中。 这三种体验都依赖于该 run 的根节点处的有效 invoke_agent span。 只有包含 chat、execute_tool 或 output_messages 跨度的运行记录可在 Defender 高级搜寻（CloudAppEvents 表）中查询，但在所有其他界面中均不可见。
| 体验 | 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 区间及其后代。 |