Mastra platform 上的 Trace Intelligence

Trace Intelligence 会在 agent 交互中发现反复出现的模式。它会分析 Mastra Observability 捕获的 traces，并针对四个内置维度以及为项目启用的任何自定义信号生成 trace signals。然后它会将相似的 trace signals 聚类为 themes。

使用 Trace Intelligence 调查以下问题：

• 用户试图完成什么？
• 哪些目标通常会成功、保持未解决或被阻塞？
• 哪些 agent 行为出现在成功和不成功的交互中？
• 用户情绪与目标和结果有何关联？

Private beta

Trace Intelligence 以邀请方式提供给选定的 Mastra platform 项目。

获取访问权限

1. 提交 Trace Intelligence 私有 beta 表单以请求访问权限。
2. 确认已启用 Mastra platform Observability，并且已完成的 agent traces 显示在 Traces 下。
3. 需要至少 @mastra/core@1.53.0 和 mastra@1.20.2。升级项目，然后为已加入的项目部署或重新部署 Studio。私有 beta 期间不支持本地 Studio 和仅 server 的部署。
4. 打开已部署的 Studio，并在侧边栏中选择 Intelligence。
5. 向 agent 发送具有代表性的流量，并留出分析时间。

Mastra 将项目加入后，你无需更改 agent 定义或调用。

数据何时可用

Trace Intelligence 需要来自一个 agent 的足够多已处理 traces 才能识别反复出现的模式。初始 themes 通常在该 agent 至少 100 个已完成 traces 被处理后可用。

由于分析管线异步运行，Traces 下的 trace 计数可能在 Trace Intelligence 就绪之前就达到 100。达到阈值后，处理可能需要几分钟。无法分析的 traces 不会计入。因此，100 是最小值，而不是精确的 UI 触发条件。

随着更多 traces 到达，Trace Intelligence 会自动更新。Studio 需要至少两种 trace signal 类型的 themes 才能显示关系流。

请使用具有代表性的流量。少量重复的测试提示可能产生不具代表性的结果，例如一个宽泛的 theme 或大部分为 Noise。

理解分析

每个可分析的已完成 trace 都会产生四个内置 trace signals，以及为项目启用的任何自定义信号：

Trace signal	含义
Goal	用户试图实现或完成的内容。
Outcome	最终完成、部分完成、阻塞、失败、未解决或不明确的状态。
Behavior	可观察的 agent 操作和模式，包括工具使用、遗漏、重试、失败和恢复。
Sentiment	用户的情绪状态或态度。

Themes 是由相似 trace signals 生成的聚类。聚类会按每种 trace signal 类型独立进行。一个 trace 可以在每个维度（Goal、Outcome、Behavior 和 Sentiment）中属于不同的 theme。

Themes 和关系

流程图连接相邻 trace signal 列中的 themes：

• 节点代表一个 theme。其计数是所选快照中分配给该 theme 的不同 traces 数量。
• ribbon 连接相邻两列中分配给 themes 的 traces。其宽度代表共享的 trace 数量。
• 悬停或聚焦节点或 ribbon 可隔离其关系。

该流显示的是关联，而不是因果关系或执行顺序。例如，Goal 和 Outcome 之间的 ribbon 表示两个 themes 出现在相同的 traces 中。它并不表示该 goal 导致了该 outcome。

Other 和 Noise

每个节点显示其 trace 计数：所选快照中分配给该 theme 的不同 traces 数量。theme 的详情还会说明其占比，例如“此快照中 70 个 traces 中的 28 个（40%）”。

Studio 会为每种 trace signal 类型显示最常见的 themes。它可能会将较小的 themes 合并到 Other 中，以保留总数而避免图表过于拥挤。

Noise 包含在所选快照中未能稳定匹配某个反复出现的 theme 的摘要。它不一定表示错误或低质量交互。Noise 可以包含罕见请求和新兴模式，也可以包含模糊交互或无关案例。较大的 Noise 占比可能表示流量高度多样，或数据不足以形成稳定 themes。

快照

快照是覆盖一组 traces 的移动分析窗口。快照可以重叠，因此不要将它们的 trace 计数相加。请同时比较 theme 的 trace 计数及其在快照中的占比，因为不同窗口之间的流量可能变化。

一个 theme 可以在快照之间持续、消失、拆分、合并或重新出现。请将 theme 名称和描述视为生成的摘要，而不是固定的分类法。

使用 Trace Intelligence 页面

1. 打开 Intelligence 查看实体索引。搜索或排序索引，然后选择一个实体以打开其分析。
2. 在流中选择一个 theme 以打开其详情，并将每一列筛选为包含该 theme 的 traces。
3. 详情面板显示 theme 的描述、其在快照中的占比、分页的示例摘要，以及其 trace 计数随时间变化的趋势。
4. 选择 Clear filter 以恢复完整流。

实体在其信号仍在收集或处理时就会显示。索引会显示每个实体的已分析 trace 计数、就绪和已启用信号计数、生命周期状态以及最后更新时间。

配置自定义信号

组织 admin 可以无需离开 Intelligence 即可配置自定义信号：

1. 返回实体索引并选择 Signal settings。
2. 选择 Create signal，提供稳定的信号名称、显示标签、描述和信号指令，然后保存。定义及其版本会跨组织共享。
3. 在 Current project 下启用该信号。项目启用仅影响当前项目，并应用于新处理的 traces。
4. 从索引打开一个实体，并在其信号状态从 collecting 变为 processing 再到 ready 时跟踪它。

你可以编辑自定义信号的标签、描述或指令。指令更改会创建新版本，并且仅应用于新 traces。你还可以归档不应再可用的定义，或稍后恢复已归档的定义。

你还可以：

• 在流中选择 Noise 以检查其占比和生成的示例摘要。
• 拖动图表上方的列标题以重新排列 trace signal 列，查看不同的关系视角。
• 使用时间轴选择快照，或选择 Play 观看 themes 随时间变化。
• 切换到 Compare 查看两个时间点之间哪些 themes 增长、缩小、进入范围或离开范围，或切换到 Lifelines 跟踪每个 theme 在所选整个范围内占比的变化。

对于超过 2,000 个 traces 的快照，无法按 theme 筛选流。在那里选择 theme 仍会打开其详情，但不会筛选流。

故障排除

侧边栏中没有 Intelligence

请确认 Mastra 加入了正确的项目、你使用了与 beta 兼容的 Mastra 版本，并且重新部署了 Studio，因为私有 beta 不支持本地 Studio。

缺少某个 agent

请确认其已完成的 traces 列在 Traces 下，并且项目已加入。Trace Intelligence 会在信号生成开始后、首批 themes 就绪前列出实体。如果它最近才达到 100 个 traces，请留出异步处理时间。

关系流不可用

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

大多数摘要都是 Noise

请收集更多具有代表性的流量，并比较稍后的快照。多样或罕见的交互更难分组，而重复的测试提示可能产生不具代表性的分布。

私有 beta 限制

• Trace Intelligence 仅适用于已部署 Studio 中已加入的项目。
• 初始分析需要每个 agent 至少 100 个已处理 traces。某些 agents 可能需要更多。
• 结果取决于所捕获 traces 的多样性和质量。
• Trace signal 摘要、theme 标签、聚类、阈值和 UI 行为可能在 beta 期间发生变化。

报告 feedback 时，请包含组织 ID、项目 ID、agent ID、所选快照，以及能说明该问题的 theme 或 Noise 示例。

相关内容

• Mastra platform 上的 Observability
• Mastra platform 上的 Studio