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

# Mastra 平台上的 Trace Intelligence

Trace Intelligence 會從 Agent 的互動中找出反覆出現的模式。它會分析 Mastra Observability 擷取的 Trace，從四個維度產生 Trace 訊號，再將相似的 Trace 訊號聚類成主題。

你可以使用 Trace Intelligence 探究以下問題：

- 用戶想完成甚麼？
- 哪些目標通常能夠成功、仍未解決，或受到阻礙？
- 成功及未能成功的互動中分別出現哪些 Agent 行為？
- 用戶情緒與目標及結果有何關係？

> **私人測試版:** Trace Intelligence 僅以邀請形式向獲選的 Mastra 平台項目提供。

## 取得存取權

1. 提交 [Trace Intelligence 私人測試版表格](https://mastra.ai/trace-intelligence)以申請存取權。
2. 確認已啟用 [Mastra 平台 Observability](https://mastra.zisheng.pro/zh-HK/docs/mastra-platform/observability)，而且已完成的 Agent Trace 會顯示於 **Traces** 下。
3. 必須至少使用 `@mastra/core@1.53.0` 及 `mastra@1.20.2`。升級項目後，為已登記的項目部署或重新部署 Studio。私人測試期間不支援本機 Studio 及純伺服器部署。
4. 開啟已部署的 Studio，然後在側邊欄選擇 **Intelligence**。
5. 將具代表性的流量傳送至 Agent，並預留時間進行分析。

Mastra 為項目完成登記後，你毋須更改 Agent 定義或呼叫方式。

### 何時會有數據

Trace Intelligence 需要同一 Agent 有足夠數量且已處理的 Trace，才能識別反覆出現的模式。通常該 Agent 至少有 **100 個已完成的 Trace** 經過處理後，才會出現首批主題。

由於分析管線以非同步方式運作，**Traces** 下的 Trace 數目可能已達 100，但 Trace Intelligence 仍未準備好。達到門檻後，處理可能仍需數分鐘。無法分析的 Trace 不會計入，因此 100 是最低數目，而非觸發介面的確切數字。

收到更多 Trace 後，Trace Intelligence 會自動更新。Studio 至少需要兩種 Trace 訊號類型各自有主題，才能顯示關係流程圖。

請使用具代表性的流量。少量而重複的測試提示可能會產生不具代表性的結果，例如只得一個籠統主題，或大部分內容都屬於 Noise。

## 了解分析方式

每個可分析且已完成的 Trace 都會產生四種 Trace 訊號：

| Trace 訊號      | 含義                                         |
| ------------- | ------------------------------------------ |
| **Goal**      | 用戶嘗試達成或完成的事項。                              |
| **Outcome**   | 最終狀態：已完成、部分完成、受阻、失敗、未解決或不明確。               |
| **Behavior**  | 可觀察的 Agent 操作及模式，包括 Tool 使用情況、遺漏、重試、失敗及復原。 |
| **Sentiment** | 用戶的情緒狀態或態度。                                |

主題是由相似 Trace 訊號產生的聚類。每種 Trace 訊號類型都會獨立進行聚類。同一個 Trace 在 Goal、Outcome、Behavior 及 Sentiment 各個維度中，可以分別屬於不同主題。

### 主題與關係

流程圖會連接相鄰 Trace 訊號欄中的主題：

- 一個**節點**代表一個主題。其數目是所選快照中，歸入該主題的不重複 Trace 數量。
- 一條**色帶**會連接在兩個相鄰欄位中都歸入相應主題的 Trace。色帶寬度代表兩者共有的 Trace 數量。
- 將游標移至節點或色帶上，或將焦點移至其中，即可獨立顯示其關係。

流程圖顯示的是關聯，而非因果關係或執行次序。例如，Goal 與 Outcome 之間的色帶表示兩個主題在同一批 Trace 中出現，並不表示該目標導致該結果。

### 分佈、Other 與 Noise

流程圖下方的卡片會顯示每種 Trace 訊號的主題分佈：

- **Trace count**：所選快照中，歸入某個主題的不重複 Trace 數量。
- **Stage share**：就該 Trace 訊號而言，歸入該主題的已分析 Trace 百分比。

Studio 會顯示每種 Trace 訊號類型最常見的主題。為了在避免圖表過於擠迫的同時維持總數，它可能會將較小的主題合併至 **Other**。

**Noise** 包含在所選快照中，未能持續符合某個重複主題的摘要。這不一定表示發生錯誤或互動質素欠佳。Noise 可以包括罕見請求及剛開始出現的模式，亦可以包含語意不明的互動或互不相關的個案。Noise 佔比較高，可能表示流量非常多樣化，或數據不足以形成穩定主題。

### 快照

快照是涵蓋一組 Trace 且會移動的分析時段。各個快照可能重疊，因此不要將它們的 Trace 數目相加。由於不同時段的流量可能會改變，請同時比較 Trace 數目及階段佔比。

同一主題在不同快照之間可能持續存在、消失、拆分、合併或再次出現。主題名稱及描述是系統產生的摘要，不應視為固定分類法。

## 使用 Trace Intelligence 頁面

1. 使用 **Agent** 選擇器切換至已有分析結果的 Agent。Agent 要到首批主題準備好後才會顯示。
2. 在流程圖中選擇一個主題，以篩選所有欄位，只顯示包含該主題的 Trace。
3. 選擇 **View theme details**，查看其描述、Trace 數目、階段佔比、系統產生的例子及歷史記錄。
4. 選擇 **Clear filter**，還原完整流程圖。

你亦可以：

- 在分佈卡片中選擇主題，以開啟其詳細資料及系統產生的例子摘要。
- 在分佈卡片中選擇 **Noise**，查看其分佈及系統產生的例子摘要。
- 拖曳分佈卡片，重新排列 Trace 訊號欄，從不同角度查看關係。
- 使用時間軸選擇快照，或選擇 **Play**，觀看主題如何隨時間轉變。
- 開啟主題的歷史記錄，查看它是否持續存在，以及涵蓋範圍如何改變。

若快照包含超過 2,000 個 Trace，便無法按主題篩選流程圖。請選擇另一個快照，或清除使用中的篩選條件，以返回完整流程圖。你仍可從分佈卡片查看主題及 Noise 的詳細資料。

## 疑難排解

### 側邊欄中沒有 Intelligence

確認 Mastra 已登記正確的項目、你使用與測試版相容的 Mastra 版本，而且已重新部署 Studio。私人測試版不支援本機 Studio。

### 找不到某個 Agent

確認其已完成的 Trace 已列於 **Traces** 下。Agent 要到首批主題準備好後才會列出。如果最近才達到 100 個 Trace，請預留時間讓系統進行非同步處理。

### 無法使用關係流程圖

流程圖至少需要兩種 Trace 訊號類型各自有主題。請繼續傳送具代表性的流量，並等候處理完成。

### 大部分摘要都是 Noise

收集更多具代表性的流量，再與較後的快照比較。多樣化或罕見的互動較難分組，而重複的測試提示亦可能產生不具代表性的分佈。

## 私人測試版限制

- Trace Intelligence 只適用於已登記項目的已部署 Studio。
- 每個 Agent 至少需要 100 個已處理的 Trace 才能開始分析，部分 Agent 可能需要更多。
- 結果取決於已擷取 Trace 的多樣性及質素。
- Trace 訊號摘要、主題標籤、聚類、門檻及介面行為可能會在測試期間改變。

提交意見時，請附上機構 ID、項目 ID、Agent ID、所選快照，以及可說明問題的主題或 Noise 例子。

## 相關內容

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