承接： Copilot Agent 会话流式审计实战：从 48 小时补数到脱敏告警闭环
调研日期：2026-08-08
本文目标：基于 GitHub Copilot Usage Metrics 新增的 Agent App 字段，建立可复查的多 Agent 采用度口径；清楚区分 Job 启动、Session、Prompt 与结果质量，避免把可计数活动误写成生产率结论。
2026-08-07，GitHub 为 Copilot Usage Metrics API 增加了 Agent App 活动的按 Agent 拆分。企业、组织及其用户级的 1 日和 28 日报告中，新增可选的 totals_by_3rd_party_agent 数组；已识别的 Agent App 会按稳定的 agent_id 聚合。官方公告给出的直接价值是：团队终于可以把不同 Agent 的采用情况拆开观察，而不是把所有工作都塞进一个模糊的活动桶。
这是一个很容易被误读的进展。看到活动数量上升，不代表代码质量上升；看到 Session 变少，也不一定代表效率变差；更不能把 Agent 的 Job 启动次数与人类在 IDE 中发出的 Prompt 相加后，宣布“总工作量”。正确的起点是先建立数据字典、时间窗口和失败解释，再决定指标能支持哪些治理动作。
适用前提：你的企业或组织已启用 Copilot usage metrics policy，且负责人员拥有相应的 Metrics 查看权限。示例只展示读取报告的最小流程，不应把下载链接、原始 NDJSON、用户标识或访问令牌提交到代码库。
一、先把四类计数拆开：它们不是同一个单位
新增字段关注的是“已识别 Agent App 的服务端作业活动”，并不是所有 Copilot 或所有 Agent 的统一工时表。先把最重要的字段放在一张表中：
字段或概念 | 它实际计数什么 | 适用范围 | 不能据此断言什么 |
totals_by_3rd_party_agent | 每个已识别 Agent 的活动条目 | 无相关活动时整个字段会省略 | 未识别 Agent 完全不存在 |
agent_id | Agent 的稳定标识 | 跨报表周期用于分组和关联 | Agent 的展示名称或厂商策略永不变化 |
agent_name | Agent 的显示名称 | 适合仪表盘显示 | 跨周期主键 |
嵌套 user_initiated_interaction_count | 用户发起的 Agent App Job 启动数 | 每次 Job 开始计一次 | 人类发出的所有 Copilot Prompt 数 |
session_count | Agent App Session 数 | 仅企业或组织聚合报告提供；用户级条目省略 | 每个用户的会话次数 |
顶层 user_initiated_interaction_count | 其他受支持遥测中的显式 Prompt 总数 | 报告顶层 | Agent App Job 启动数 |
两个约束尤其值得写进数据模型：
- 用 agent_id 分组，而不是 agent_name。显示名称可能变化；同一 Agent 的多个 App 集成也会被合并到一个 Agent 条目。
- 不要把两个同名交互计数相加。嵌套字段是 Agent App Job start，顶层字段是其他遥测里的显式 Prompt；它们的触发路径不同，官方明确说不能互换或求和。
所以，“本周某 Agent 有 150 次 Job”只能说明这个受管范围内出现了 150 次用户发起的作业启动。它不能单独证明 150 个任务完成、150 次代码变更正确，或 150 次调用都比人工更快。
二、先选对报告粒度，再谈仪表盘
Usage Metrics 同时提供 1 日和 28 日报告。1 日报告适合发现刚上线的策略或集成是否产生可见活动；28 日报告适合查看一个完整窗口内的聚合总量。要判断“是否在多个日期持续出现”，不能只看一份 28 日用户报告：它是该窗口的一条聚合记录，必须保留连续的 1 日用户报告再按日期计算。
目标问题 | 推荐报告 | 为什么 |
新 Agent 是否真的被试点成员启动 | 用户级 1 日报告 | 可以按用户级记录检查是否出现对应 Agent 条目 |
一个 Agent 是否有稳定使用而非偶发点击 | 连续 28 份用户级 1 日报告 | 逐日记录目标 Agent 是否出现，才能计算活跃天数分布 |
某个周期的总采用量 | 28 日用户级报告 | 一条记录汇总窗口内的活动，适合期间比较，不能还原每日出现情况 |
企业或组织层面有多少 Agent Session | 聚合 1 日或 28 日报告 | session_count 只在聚合条目中提供 |
新旧 Agent 是否同时被采用 | 用户级报告按 agent_id 汇总 | 避免按可变显示名称比较 |
是否应该扩大、暂停或训练试点 | 28 日量化趋势加人工样本 | 指标提供信号，任务质量仍需人审 |
读取前先核对权限与开关。官方 REST 文档要求开启 Copilot usage metrics policy；企业端通常需要企业所有者、账单经理或已授予 View Enterprise Copilot Metrics 的角色，组织端也需要相应的组织权限。细粒度令牌应仅授予读取 Copilot metrics 的最小权限，且专用于报告拉取。
不要把组织级与企业级的返回形状想当然视为完全相同。当前文档对具体字段、用户级与聚合级的可用性有区别；尤其是在组织级聚合视图中，应以你当天实际拿到的 schema 为准，而不是只依赖早期公告或他人的截图。
三、用最小权限取回 1 日报告
下面以组织的用户级 1 日报告为例。GitHub CLI 会使用本机已有的安全登录状态，因此命令中不出现令牌。请在受控终端中运行，并将 ORG 与 DAY 替换为真实值。
ORG=your-organization DAY=2026-08-07 gh api \ --method GET \ -H "Accept: application/vnd.github+json" \ -H "X-GitHub-Api-Version: 2026-03-10" \ "/orgs/$ORG/copilot/metrics/reports/users-1-day?day=$DAY"该请求返回的是报告下载链接和报告日期，不是整份指标内容本身。下载链接为限时签名链接，适合在受控的采集作业中短暂使用，不适合写入 Git、Issue、聊天记录或长期日志。只处理 API 返回的完整已处理报告日；不要因为当天报告尚未生成、链接过期或采集作业失败就填充零值。对于 28 日窗口，可改用 users-28-day/latest 端点取得期间聚合；企业范围则使用 enterprises 下对应的 reports 路径。若要计算每日持续采用度，则连续拉取并留存 28 份 users-1-day 报告。完整端点、权限与响应定义应以 GitHub REST API 文档为准。
报告拉取后，先把字段规范化为只含聚合分析所需列的临时数据集。下例假定 report.ndjson 是已经在受控存储中下载的报告文件：
jq -c ' (.totals_by_3rd_party_agent // [])[] | { agent_id: .agent_id, agent_name: .agent_name, job_starts: .user_initiated_interaction_count, session_count: (.session_count // null) } ' report.ndjson这里的空数组有明确含义：某条记录没有已识别的 Agent App 活动时，字段可能被省略。不要强行填成“所有 Agent 都是 0”，更不要把“未识别或未上报”解释为“团队完全没有使用任何 Agent”。
为了让报表审阅者一眼看出计数边界，可保留如下的示意记录。数值仅用于说明字段层级，不代表真实组织数据：
{ "user_initiated_interaction_count": 137, "totals_by_3rd_party_agent": [ { "agent_name": "Example Coding Agent", "agent_id": "example-coding-agent", "user_initiated_interaction_count": 12 } ] }上面的 137 与 12 没有加法关系。第一项是顶层显式 Prompt 计数，第二项是特定 Agent App 的 Job start。只有在数据字典明确了不同事件的来源、去重方式和业务问题后，才可以把它们放在同一张分析图中比较趋势。
四、为多 Agent 试点建立“可回答问题”的指标契约
先确定你要用数据做什么，再写公式。一个适合早期试点的最小契约可以只回答四个问题：
决策问题 | 建议指标 | 计算口径 | 需要配套的人类证据 |
试点是否真的开始使用 | 活跃采用者数 | 出现目标 agent_id 的去重成员数 | 成员是否完成接入与培训 |
使用是否持续 | 28 日活跃天数分布 | 从连续 28 份 1 日报告中，计算每个 agent_id 出现的报告日数量 | 是否只是一次演示或临时故障处置 |
用户启动后是否形成会话 | 聚合 Job start 与 Session 的趋势 | 同一报告粒度内分别查看，不强行一一对应 | 代表性任务是否需要多轮协作 |
是否应扩大范围 | 增长趋势加任务样本 | 仅比较相同人群、相同时间窗口 | 代码审阅、测试、返工与安全事件复盘 |
最后一行最重要。采用度指标可以帮助发现“谁在用什么”，但无法替代质量证据。若要讨论实际工程价值，至少还要从独立系统取证，例如：PR 是否被人工合并、测试是否通过、故障是否减少、审阅返工是否下降，以及用户是否明确反馈某类任务更适合或不适合交给 Agent。
建议将个人数据最小化：
- 对组织级决策，默认输出按 agent_id、团队或已批准的最小群组聚合后的趋势，而不是公开个人排名。
- 对用户级报告设置明确用途、访问期限和审计记录；它应服务于接入障碍排查和培训改进，不应成为单一绩效指标。
- 将原始 NDJSON、下载链接和转换后的分析数据分开存放；前两者只保留在受控存储中，仓库只保存查询定义与无敏感的聚合结果。
五、用“1 日健康检查 + 每日留样 + 28 日聚合”做渐进决策
一套低噪声的运行节奏可以分为三段：
阶段 | 看什么 | 允许的动作 | 不该做什么 |
上线后第 1 天 | 目标 agent_id 是否出现、字段是否按预期省略或返回 | 修复权限、策略、采集脚本与培训入口 | 用一天数据评价人或采购效果 |
第一周 | 每日已处理报告中的 Job start 异常尖峰或完全缺失 | 排查重复触发、集成故障、报告延迟或试点覆盖问题 | 把峰值直接当作效率提升 |
第一个完整 28 日窗口 | 连续 1 日报告计算的采用持续性，加上 28 日聚合、不同 Agent 重叠和代表性任务样本 | 决定扩展试点、补培训、收紧范围或下线集成 | 用活动数替代质量、成本或风险评审 |
如果多个 Agent 在同一团队并行试点，比较时必须固定人群和时间窗口。不要用“新 Agent 的前三天”对比“旧 Agent 的全部历史”，也不要因为一个 Agent 被用于更长、更复杂的任务就把更高 Job 数判成更差体验。指标是提出问题的入口，不是自动裁决。
当报表出现异常时，按下面顺序排查通常更快：
- 确认 Copilot usage metrics policy、角色权限与报告日期是否正确。
- 确认目标 Agent 是否属于已识别 Agent App；无法识别的活动不会出现在该数组中。
- 确认报告日已经处理完成且采集作业没有漏跑；缺失报告不是零活动。
- 确认当前查看的是用户级还是聚合级报表，避免把缺失的 session_count 当作零。
- 核对 agent_id 是否稳定，避免因显示名称变化导致同一 Agent 被拆成两条趋势。
- 再结合任务样本与人类反馈判断这是集成问题、培训问题还是实际不适配。
六、六个常见误区
1）按 agent_name 做长期分组
显示名称可以变化。仪表盘展示用名称，数据仓库关联、趋势比较和告警规则都应该使用 agent_id。
2）把嵌套 Job start 与顶层 Prompt 相加
它们名称相似，事件来源不同。相加会制造一个没有清晰业务含义的“总互动数”，也会误导后续预算或采用判断。
3）把用户级缺少的 session_count 填成 0
用户级 Agent App 条目本来就不提供这个字段。缺失意味着“该层级不可用”，不是“用户没有 Session”。
4）把字段省略理解为绝对没有 Agent 使用
该数组只覆盖已识别 Agent App。没有数组可能表示没有已识别活动，也可能意味着某类集成不在这一统计范围内；需要结合产品配置和其他审计来源解释。
5）把 Job 数量当成开发质量或个人绩效
一个高质量的长任务可能只启动一次，一个调试失败的任务也可能反复启动很多次。活动指标不包含正确性、审阅结果、安全影响或业务价值。
6）把签名下载链接和原始报告塞进仓库
限时链接仍可能暴露受控数据访问路径；原始报告也可能包含用户级活动。代码库应保存采集说明、字段定义和脱敏聚合，而不是敏感原始材料。
结语
按 Agent 拆分 Usage Metrics 的意义，在于让多 Agent 治理终于拥有一条可复查的采用度证据链：用稳定 agent_id 观察不同 Agent，用 Job start 解释用户是否启动任务，用聚合 Session 观察会话形态，再把这些信号与人工审阅、测试和风险复盘连接起来。
正确的下一步不是立刻排名“哪个 Agent 最好”，而是先为一个小试点写清数据契约：看哪些字段、按什么窗口、由谁读取、缺失如何解释、什么额外证据才允许扩大范围。这样得到的报表才能服务于技术决策，而不是把一串活动数字伪装成生产率结论。
来源与延伸阅读
- Copilot usage metrics API adds agent app activity：GitHub 官方公告，发布于 2026-08-07；说明按 Agent 聚合、字段含义、报告范围与重要限制。
- Data available in Copilot usage metrics：当前字段定义，包含 Agent App、CLI、Copilot app 与活动维度的口径。
- REST API endpoints for Copilot usage metrics：1 日与 28 日报告端点、权限、时间窗口与下载链接行为。
CSDN 标题：
标签：AI Agent · GitHub Copilot · 多智能体 · 可观测性 · 数据治理 · 工程效能