> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# Mastra platform 上的 Trace Intelligence

Trace Intelligence 会在 Agent 交互中发现反复出现的模式。它分析 Mastra Observability 捕获的 Trace，为四个维度生成 trace signal，并将相似的 trace signal 聚类为主题。

可以使用 Trace Intelligence 调查以下问题：

- 用户尝试完成什么任务？
- 哪些目标往往能成功，哪些仍未解决或受阻？
- 成功和失败的交互中分别出现哪些 Agent 行为？
- 用户情绪与目标和结果有何关系？

> **Private beta:** Trace Intelligence 仅通过邀请向部分 Mastra platform 项目开放。

## 获取访问权限

1. 提交 [Trace Intelligence private beta 表单](https://mastra.ai/trace-intelligence)申请访问权限。
2. 确认已启用 [Mastra platform Observability](https://mastra.zisheng.pro/docs/mastra-platform/observability)，并且已完成的 Agent Trace 显示在 **Traces** 下。
3. 至少需要 `@mastra/core@1.53.0` 和 `mastra@1.20.2`。升级项目，然后为获准参与的项目部署或重新部署 Studio。Private beta 期间不支持本地 Studio 和仅 Server 部署。
4. 打开已部署的 Studio，在侧边栏中选择 **Intelligence**。
5. 向 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

流程下方的卡片显示每种 trace signal 的主题分布：

- **Trace count**：所选快照中分配到某一主题的不同 Trace 数量。
- **Stage share**：针对该 trace signal 分析的 Trace 中，分配到该主题的百分比。

Studio 会显示每种 trace signal 类型最常见的主题。为了保持总数且避免图表过度拥挤，它可能会将较小主题合并到 **Other** 中。

**Noise** 包含在所选快照中未能持续匹配反复出现主题的摘要。它不一定表示错误或低质量交互。Noise 可能包括少见请求和新出现的模式，也可能包含有歧义的交互或无关案例。Noise 占比过大，可能表明流量差异很大，或数据不足以形成稳定主题。

### 快照

快照是覆盖一组 Trace 的移动分析窗口。快照可能重叠，因此不要将它们的 Trace 数量相加。由于窗口之间的流量可能变化，请结合比较 Trace 数量和 stage share。

同一主题可能在不同快照中持续存在、消失、拆分、合并或再次出现。请将主题名称和说明视为生成的摘要，而不是固定的分类体系。

## 使用 Trace Intelligence 页面

1. 使用 **Agent** 选择器，在有可用分析的 Agent 之间切换。Agent 的首批主题就绪前不会显示在此处。
2. 在流程中选择一个主题，将每一列筛选到包含该主题的 Trace。
3. 选择 **View theme details**，检查其说明、Trace 数量、阶段占比、生成的示例和历史记录。
4. 选择 **Clear filter** 恢复完整流程。

你还可以：

- 在分布卡片中选择主题，打开其详情和生成的示例摘要。
- 在分布卡片中选择 **Noise**，检查其分布和生成的示例摘要。
- 拖动分布卡片，重新排列 trace signal 列，从不同角度查看关系。
- 使用时间线选择快照，或选择 **Play** 观察主题随时间变化。
- 打开主题的历史记录，查看它是否持续存在，以及覆盖范围如何变化。

对于包含超过 2,000 条 Trace 的快照，无法按主题筛选流程。请选择其他快照，或清除活跃筛选器以返回完整流程。仍可从分布卡片查看主题和 Noise 详情。

## 故障排除

### 侧边栏中没有 Intelligence

确认 Mastra 纳入的是正确项目、你使用与 beta 兼容的 Mastra 版本，并且已重新部署 Studio。Private beta 不支持本地 Studio。

### 缺少 Agent

确认该 Agent 已完成的 Trace 列在 **Traces** 下。仅当首批主题就绪后，Agent 才会显示。如果它最近才达到 100 条 Trace，请等待异步处理完成。

### 关系流不可用

关系流至少需要两种 trace signal 类型的主题。请继续发送具有代表性的流量，并等待处理完成。

### 大多数摘要都是 Noise

收集更多具有代表性的流量，并与较晚的快照进行比较。多样或少见的交互更难分组，而重复的测试 prompt 可能产生不具代表性的分布。

## Private beta 限制

- Trace Intelligence 仅可用于已获准参与项目的已部署 Studio。
- 初始分析要求每个 Agent 至少有 100 条已处理 Trace。部分 Agent 可能需要更多。
- 结果取决于已捕获 Trace 的多样性和质量。
- Trace signal 摘要、主题标签、聚类、阈值和 UI 行为可能在 beta 期间发生变化。

报告反馈时，请提供组织 ID、项目 ID、Agent ID、所选快照，以及能够说明问题的主题或 Noise 示例。

## 相关内容

- [Mastra platform 上的 Observability](https://mastra.zisheng.pro/docs/mastra-platform/observability)
- [Mastra platform 上的 Studio](https://mastra.zisheng.pro/docs/mastra-platform/studio)