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

# Mastra platform 上的 Trace Intelligence

Trace Intelligence 會找出 Agent 互動中重複出現的模式。它分析 Mastra Observability 擷取的 Trace、針對四個維度產生 Trace signal，並將相似的 Trace signal 分群為主題。

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

- 使用者想完成什麼？
- 哪些目標通常會成功、尚未解決或受阻？
- 成功與失敗的互動中分別出現哪些 Agent 行為？
- 使用者情緒與目標和結果有何關聯？

> **私人測試:** Trace Intelligence 僅邀請獲選的 Mastra platform 專案使用。

## 取得存取權

1. 提交 [Trace Intelligence 私人測試表單](https://mastra.ai/trace-intelligence)以申請存取權。
2. 確認已啟用 [Mastra platform Observability](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/observability)，且已完成的 Agent Trace 顯示在 **Traces** 下。
3. 需至少使用 `@mastra/core@1.53.0` 與 `mastra@1.20.2`。升級專案，然後為已加入測試的專案部署或重新部署 Studio。私人測試期間不支援本機 Studio 與僅 Server 的部署。
4. 開啟已部署的 Studio，並在側邊欄選取 **Intelligence**。
5. 將具代表性的流量傳送至 Agent，並等候分析完成。

Mastra 將專案加入測試後，無須變更 Agent 定義或呼叫。

### 資料何時可用

Trace Intelligence 需要同一個 Agent 有足夠的已處理 Trace，才能識別重複模式。通常在該 Agent 至少有 **100 個已完成的 Trace** 完成處理後，才會出現初始主題。

由於分析管線以非同步方式執行，**Traces** 下的 Trace 數量可能會先達到 100，而 Trace Intelligence 尚未就緒。達到門檻後，處理可能仍需數分鐘。無法分析的 Trace 不會計入，因此 100 是最低值，而非精確的 UI 觸發條件。

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

請使用具代表性的流量。少量重複測試提示可能產生不具代表性的結果，例如只有一個廣泛主題，或大多被歸為 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 count 與 Stage share。

主題可能在不同快照中持續、消失、分裂、合併或再次出現。請將主題名稱與說明視為產生的摘要，而非固定分類法。

## 使用 Trace Intelligence 頁面

1. 使用 **Agent** 選擇器切換至已有分析結果的 Agent。Agent 要到第一批主題就緒後才會出現。
2. 在流程圖中選取主題，將所有欄位篩選為包含該主題的 Trace。
3. 選取 **View theme details**，檢查說明、Trace 數、Stage share、產生的範例與歷程。
4. 選取 **Clear filter**，還原完整流程圖。

你也可以：

- 在分布卡片中選取主題，開啟其詳細資料與產生的範例摘要。
- 在分布卡片中選取 **Noise**，檢查其分布與產生的範例摘要。
- 拖曳分布卡片以重新排列 Trace signal 欄，從不同角度查看關係。
- 使用時間軸選取快照，或選取 **Play**，觀察主題隨時間變化。
- 開啟主題歷程，查看主題是否持續存在，以及涵蓋範圍如何變化。

若快照超過 2,000 個 Trace，就無法依主題篩選流程圖。請選擇其他快照，或清除作用中的篩選條件以返回完整流程圖。仍可從分布卡片查看主題與 Noise 詳細資料。

## 疑難排解

### 側邊欄中沒有 Intelligence

請確認 Mastra 已將正確專案加入測試、使用與測試相容的 Mastra 版本，且已重新部署 Studio。私人測試不支援本機 Studio。

### 缺少某個 Agent

確認其已完成的 Trace 列於 **Traces** 下。Agent 只會在第一批主題就緒後列出。若最近才達到 100 個 Trace，請等候非同步處理。

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

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

### 大多數摘要都是 Noise

收集更多具代表性的流量，並比較較晚的快照。多變或罕見的互動較難分組，而重複的測試提示可能產生不具代表性的分布。

## 私人測試限制

- Trace Intelligence 僅適用於已加入測試專案中部署的 Studio。
- 初始分析要求每個 Agent 至少有 100 個已處理 Trace；部分 Agent 可能需要更多。
- 結果取決於擷取 Trace 的多樣性與品質。
- Trace signal 摘要、主題標籤、分群、門檻與 UI 行為在測試期間可能變更。

回報意見時，請附上組織 ID、專案 ID、Agent ID、所選快照，以及可說明問題的主題或 Noise 範例。

## 相關內容

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