Mastra platform 上的 Trace Intelligence
Trace Intelligence 会在 Agent 交互中发现反复出现的模式。它分析 Mastra Observability 捕获的 Trace，为四个维度生成 trace signal，并将相似的 trace signal 聚类为主题。
可以使用 Trace Intelligence 调查以下问题：
- 用户尝试完成什么任务？
- 哪些目标往往能成功，哪些仍未解决或受阻？
- 成功和失败的交互中分别出现哪些 Agent 行为？
- 用户情绪与目标和结果有何关系？
Trace Intelligence 仅通过邀请向部分 Mastra platform 项目开放。
获取访问权限获取访问权限的直接链接
- 提交 Trace Intelligence private beta 表单申请访问权限。
- 确认已启用 Mastra platform Observability，并且已完成的 Agent Trace 显示在 Traces 下。
- 至少需要
@mastra/core@1.53.0和mastra@1.20.2。升级项目，然后为获准参与的项目部署或重新部署 Studio。Private beta 期间不支持本地 Studio 和仅 Server 部署。 - 打开已部署的 Studio，在侧边栏中选择 Intelligence。
- 向 Agent 发送具有代表性的流量，并留出分析时间。
Mastra 将项目纳入测试后，无需更改 Agent 定义或调用。
数据何时可用数据何时可用的直接链接
Trace Intelligence 需要来自一个 Agent 的足量已处理 Trace，才能识别反复出现的模式。通常，该 Agent 至少有 100 条已完成 Trace 得到处理后，初始主题才可用。
由于分析管道异步运行，Traces 下的 Trace 数量可能在 Trace Intelligence 就绪前达到 100。达到阈值后，处理可能还需要几分钟。无法分析的 Trace 不计入其中，因此 100 是最低数量，而不是准确的 UI 触发点。
随着更多 Trace 到达，Trace Intelligence 会自动更新。Studio 需要至少两种 trace signal 类型的主题，才能显示关系流。
请使用具有代表性的流量。少量重复的测试 prompt 可能产生不具代表性的结果，例如只有一个宽泛主题或大部分内容都是 Noise。
理解分析结果理解分析结果的直接链接
每条可分析的已完成 Trace 都会产生四种 trace signal：
| Trace signal | 含义 |
|---|---|
| Goal | 用户尝试实现或完成的任务。 |
| Outcome | 最终处于完成、部分完成、受阻、失败、未解决或不明确状态。 |
| Behavior | 可观察到的 Agent 操作和模式，包括 Tool 使用、遗漏、重试、失败和恢复。 |
| Sentiment | 用户的情绪状态或态度。 |
主题是从相似 trace signal 生成的聚类。每种 trace signal 类型都会单独进行聚类。一条 Trace 可以在 Goal、Outcome、Behavior 和 Sentiment 各个维度中分别属于不同主题。
主题和关系主题和关系的直接链接
流程图连接相邻 trace signal 列中的主题：
- 节点表示一个主题。其数量是所选快照中分配到该主题的不同 Trace 数量。
- 带状连接用于连接在两个相邻列中均分配到主题的 Trace。其宽度表示共享的 Trace 数量。
- 将鼠标悬停在节点或带状连接上，或聚焦它们，即可单独查看其关系。
流程显示的是关联，而不是因果关系或执行顺序。例如，Goal 与 Outcome 之间的带状连接表示两个主题出现在同一批 Trace 中，并不表示目标导致了结果。
分布、Other 和 Noise分布、Other 和 Noise的直接链接
流程下方的卡片显示每种 trace signal 的主题分布：
- Trace count：所选快照中分配到某一主题的不同 Trace 数量。
- Stage share：针对该 trace signal 分析的 Trace 中，分配到该主题的百分比。
Studio 会显示每种 trace signal 类型最常见的主题。为了保持总数且避免图表过度拥挤，它可能会将较小主题合并到 Other 中。
Noise 包含在所选快照中未能持续匹配反复出现主题的摘要。它不一定表示错误或低质量交互。Noise 可能包括少见请求和新出现的模式，也可能包含有歧义的交互或无关案例。Noise 占比过大，可能表明流量差异很大，或数据不足以形成稳定主题。
快照快照的直接链接
快照是覆盖一组 Trace 的移动分析窗口。快照可能重叠，因此不要将它们的 Trace 数量相加。由于窗口之间的流量可能变化，请结合比较 Trace 数量和 stage share。
同一主题可能在不同快照中持续存在、消失、拆分、合并或再次出现。请将主题名称和说明视为生成的摘要，而不是固定的分类体系。
使用 Trace Intelligence 页面使用 Trace Intelligence 页面的直接链接
- 使用 Agent 选择器，在有可用分析的 Agent 之间切换。Agent 的首批主题就绪前不会显示在此处。
- 在流程中选择一个主题，将每一列筛选到包含该主题的 Trace。
- 选择 View theme details，检查其说明、Trace 数量、阶段占比、生成的示例和历史记录。
- 选择 Clear filter 恢复完整流程。
你还可以：
- 在分布卡片中选择主题，打开其详情和生成的示例摘要。
- 在分布卡片中选择 Noise，检查其分布和生成的示例摘要。
- 拖动分布卡片，重新排列 trace signal 列，从不同角度查看关系。
- 使用时间线选择快照，或选择 Play 观察主题随时间变化。
- 打开主题的历史记录，查看它是否持续存在，以及覆盖范围如何变化。
对于包含超过 2,000 条 Trace 的快照，无法按主题筛选流程。请选择其他快照，或清除活跃筛选器以返回完整流程。仍可从分布卡片查看主题和 Noise 详情。
故障排除故障排除的直接链接
侧边栏中没有 Intelligence侧边栏中没有 Intelligence的直接链接
确认 Mastra 纳入的是正确项目、你使用与 beta 兼容的 Mastra 版本，并且已重新部署 Studio。Private beta 不支持本地 Studio。
缺少 Agent缺少 Agent的直接链接
确认该 Agent 已完成的 Trace 列在 Traces 下。仅当首批主题就绪后，Agent 才会显示。如果它最近才达到 100 条 Trace，请等待异步处理完成。
关系流不可用关系流不可用的直接链接
关系流至少需要两种 trace signal 类型的主题。请继续发送具有代表性的流量，并等待处理完成。
大多数摘要都是 Noise大多数摘要都是 Noise的直接链接
收集更多具有代表性的流量，并与较晚的快照进行比较。多样或少见的交互更难分组，而重复的测试 prompt 可能产生不具代表性的分布。
Private beta 限制Private beta 限制的直接链接
- Trace Intelligence 仅可用于已获准参与项目的已部署 Studio。
- 初始分析要求每个 Agent 至少有 100 条已处理 Trace。部分 Agent 可能需要更多。
- 结果取决于已捕获 Trace 的多样性和质量。
- Trace signal 摘要、主题标签、聚类、阈值和 UI 行为可能在 beta 期间发生变化。
报告反馈时，请提供组织 ID、项目 ID、Agent ID、所选快照，以及能够说明问题的主题或 Noise 示例。