> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/build/teams/traces.md).

# 團隊執行記錄

查看團隊每一次執行的記錄——屬於哪一段對話、經過哪些 Agent、各自的 Token 用量與耗時，並可依對話篩選出同一段對話的所有執行。

團隊在 Agent 之間自動移交與委派，過程對使用者是無感的。〈**執行記錄**〉讓你回頭檢視每一次對話實際「走過哪些 Agent、各花了多少資源」，用來確認團隊有如預期分工，也方便排查與優化。

## <mark style="color:blue;">一、查看執行記錄</mark> <a href="#view-traces" id="view-traces"></a>

在團隊頁切換到〈**執行記錄**〉檢視，會列出這個團隊的每一次執行。使用者每傳一則訊息給團隊，就會產生一筆記錄。每筆記錄包含：

| 欄位          | 說明                                                                                      |
| ----------- | --------------------------------------------------------------------------------------- |
| **記錄 ID**   | 這次執行的唯一識別碼。                                                                             |
| **對話**      | 這次執行所屬的對話（以對話標題顯示）。點標題可直接開啟〈所有對話〉查看該段對話的完整內容。                                           |
| **狀態**      | 〈執行中〉〈已完成〉〈失敗〉〈逾時〉或〈待回覆〉。〈待回覆〉表示團隊走到開啟「等使用者回覆再繼續」的連線而停下，見下方[待回覆的記錄](#waiting-for-user)。 |
| **迭代數**     | 這次執行中，Agent 之間總共來回了幾次。                                                                  |
| **Token 數** | 這次執行的總 Token 用量（輸入 in／輸出 out）。                                                          |
| **耗時**      | 從收到訊息到完成回覆的總時間。                                                                         |
| **建立時間**    | 這次執行的時間。點欄位標題可切換由舊到新、由新到舊排序；未指定排序時預設由新到舊。                                               |

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-823fb555400af54c89c714cb0a7639da6e51acf8%2Fteams-traces-list.png?alt=media" alt="團隊執行記錄列表，含記錄 ID、對話、狀態、迭代數、Token 數與操作欄"><figcaption><p>執行記錄：每筆記錄顯示所屬對話的標題，可一眼看出哪幾筆來自同一段對話</p></figcaption></figure>

{% hint style="info" %}
**對話標題無法點開？** 需要具備〈對話紀錄〉的存取權限，對話標題才會以連結顯示；沒有權限時只會顯示純文字（滑鼠移到標題上會提示原因）。
{% endhint %}

## <mark style="color:blue;">二、依對話篩選執行記錄</mark> <a href="#filter-by-conversation" id="filter-by-conversation"></a>

一段對話通常有好幾則訊息，每則訊息各自產生一筆執行記錄。想集中檢視某一段對話時，可以只列出屬於這段對話的記錄。

### 1. 以此對話過濾 <a href="#apply-conversation-filter" id="apply-conversation-filter"></a>

在要檢視的那筆記錄右側〈操作〉欄，點漏斗圖示 <mark style="color:blue;">以此對話過濾</mark>。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-af8dbc17a102a15908d4afd228598b5f3c4180e8%2Fteams-traces-filter-by-conversation.png?alt=media" alt="操作欄的漏斗圖示，滑鼠移上顯示「以此對話過濾」"><figcaption><p>點記錄右側的漏斗圖示「以此對話過濾」</p></figcaption></figure>

### 2. 檢視篩選結果 <a href="#filtered-result" id="filtered-result"></a>

列表上方會出現提示列〈**僅顯示對話「…」的執行記錄**〉，下方只剩這段對話的記錄；翻頁與排序時篩選仍會保留。此時這些記錄的漏斗圖示會變成灰色，滑鼠移上會顯示〈已在檢視此對話的記錄〉。

要回到完整列表，點提示列右側的 <mark style="color:blue;">清除</mark> 或關閉（×）即可。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-09594aef5f67452c4713db76671ae7d12e207195%2Fteams-traces-filtered.png?alt=media" alt="提示列顯示僅顯示對話的執行記錄，列表只剩同一段對話的兩筆記錄"><figcaption><p>篩選後：提示列標示目前檢視的對話，列表只剩這段對話的記錄</p></figcaption></figure>

### 使用情境：追查客訴對話是哪個 Agent 回覆的 <a href="#example-complaint-review" id="example-complaint-review"></a>

客服主管收到顧客反映「退貨說明不清楚」，想確認那段對話中每一則回覆分別是由團隊裡的哪個 Agent 處理：

1. 在〈執行記錄〉找到這段對話的任一筆記錄，點 <mark style="color:blue;">以此對話過濾</mark>，列表只剩這段對話的記錄。
2. 逐筆展開，從步驟卡上的 Agent 名稱看出：第一則訊息由〈示範－客服分流助理〉接待後移交給〈示範－退換貨助理〉，之後的追問則由〈示範－退換貨助理〉直接回覆。
3. 點〈對話〉欄的標題開啟原對話，對照實際回覆內容，確認問題出在〈示範－退換貨助理〉後，再回到〈AI 助理〉調整它的設定。

## <mark style="color:blue;">三、展開步驟詳情</mark> <a href="#step-detail" id="step-detail"></a>

點記錄左側的 **+**（或直接點該列）展開，可看到這次執行**依序經過哪些 Agent 節點**。每一步是一張步驟卡：

| 項目           | 說明                                                                                                  |
| ------------ | --------------------------------------------------------------------------------------------------- |
| **步驟序號與名稱**  | 以〈#序號 · 名稱〉顯示，例如〈#1 · 示範－客服分流助理〉，一眼看出這一步由團隊裡的哪個 Agent 處理。                                           |
| **互動類型**     | 接在名稱之後，顯示這個 Agent 這一輪實際是怎麼被叫進來的：〈**移交**〉或〈**委派**〉。這一輪第一個處理的 Agent 不顯示。連線設成〈自動〉時，這裡顯示的是當下實際發生的移交或委派。 |
| **輸入**       | 這個 Agent 拿到的內容，見下方[輸入與輸出的內容](#step-summaries)。                                                      |
| **輸出**       | 這個 Agent 這一輪最後一段回覆，見下方[輸入與輸出的內容](#step-summaries)。                                                  |
| **Token 用量** | 卡片右側顯示這一步的輸入／輸出 Token（`in` / `out`），部分步驟另會附上耗時，讓你看清成本花在哪個 Agent 身上。                                 |

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-e111f5b6779648bae94e72680649237008039af1%2Fteams-trace-step-summaries.png?alt=media" alt="展開的執行記錄有三張步驟卡：#1 · docs-line 示範（虛構）步驟詳情團隊 只有輸入；#2 · docs-line 示範（虛構）退換貨助理 · 移交，輸入為移交原因、輸出為回覆；#3 · docs-line 示範（虛構）訂單查詢助理 · 委派，輸入為委派任務、輸出為交回的結果"><figcaption><p>步驟詳情：名稱後標示移交或委派，卡片下方是這一步的輸入與輸出</p></figcaption></figure>

### 輸入與輸出的內容 <a href="#step-summaries" id="step-summaries"></a>

輸入與輸出的內容，依這個 Agent 這一輪是怎麼進來的而不同：

| 步驟                                            | 輸入                      | 輸出           |
| --------------------------------------------- | ----------------------- | ------------ |
| 這一輪第一個處理的 Agent（通常是入口；前一輪已移交時，是目前接手服務的 Agent） | 使用者這次傳來的訊息              | 它這一輪最後一段回覆   |
| 互動類型為〈移交〉                                     | 移交原因：上一個 Agent 說明為什麼交給它 | 它這一輪最後一段回覆   |
| 互動類型為〈委派〉                                     | 委派的任務內容                 | 它做完交回給委派者的結果 |

* 輸入與輸出各最多 500 字，超過的部分以「…」截斷。
* 沒有內容的欄位不顯示。例如入口只負責把對話移交出去、自己沒有回覆時，它的步驟卡只有〈輸入〉。
* 這些內容在功能上線後才開始記錄，較早的執行記錄不會補上。

{% hint style="warning" %}
**有設定輸出端控制時，步驟卡只留使用者訊息。** 團隊的入口 Agent（名稱與團隊相同）掛了攔截點為〈AI 回應生成後〉的 [Hook](/build/hook.md)，或啟用 AWS Guardrails 時，這些控制只會套用在團隊最後交給使用者的回覆上，不會經過步驟卡。為了不讓未經處理的模型原文留在執行記錄裡，這類團隊的步驟卡只顯示互動類型，以及第一個 Agent 收到的使用者訊息；移交原因、委派任務與所有〈輸出〉都留空。
{% endhint %}

{% hint style="info" %}
**誰看得到步驟內容？** 輸入與輸出含有使用者訊息與 Agent 的回覆，所以執行記錄的列表與單筆內容都需要角色具備〈[團隊權限](/org/roles/role-permission.md)〉才能讀取，組織擁有者不受此限。
{% endhint %}

### 使用情境：找出換貨問題卡在哪一步 <a href="#example-step-summaries" id="example-step-summaries"></a>

一家電商的客服主管發現，顧客問換貨時常被反問客戶編號，想知道是哪個 Agent 要求的：

1. 在〈執行記錄〉展開顧客詢問換貨的那筆記錄，看到三張步驟卡：〈#1 · docs-line 示範（虛構）步驟詳情團隊〉、〈#2 · docs-line 示範（虛構）退換貨助理 · 移交〉、〈#3 · docs-line 示範（虛構）訂單查詢助理 · 委派〉。
2. \#2 的〈輸入〉是入口寫下的移交原因，確認這段對話有交給對的 Agent。
3. \#3 的〈輸入〉是退換貨助理委派的任務「請查詢虛構訂單 A1001 的出貨狀態」，〈輸出〉是訂單查詢助理交回的「請提供客戶編號（userId），我才能查詢訂單 A1001 的出貨狀態」。
4. 主管因此知道是訂單查詢助理缺少客戶編號才查不到，回到〈AI 助理〉調整它的設定，不必逐一比對整段對話。

### 待回覆的記錄 <a href="#waiting-for-user" id="waiting-for-user"></a>

團隊走到開啟[等使用者回覆再繼續](/build/teams/setup.md#wait-for-reply-rules)的連線時，這一輪會在來源 Agent 回覆後停下，記錄的狀態顯示為〈**待回覆**〉。這是正常結束，不是失敗。展開後，步驟卡下方多一張提示卡：

* 〈**等使用者回覆**〉：這一輪停在這裡，等使用者的下一則訊息。
* 〈**回覆後接著交給：○○**〉：使用者回覆後由哪個 Agent 接續。這裡顯示的是停下當時的 Agent 名稱，之後改名也不會變。

使用者回覆後，接續的那一輪會另外產生一筆記錄，步驟卡從目標 Agent 開始。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-9139f96ee3307d293980fe3d180361de3214cc32%2Fteams-traces-waiting-for-user.png?alt=media" alt="展開的執行記錄：狀態為待回覆，步驟卡 #1 · docs-line 示範（虛構）客服分流助理，下方提示卡顯示等使用者回覆與回覆後接著交給：docs-line 示範（虛構）退換貨助理"><figcaption><p>待回覆的記錄：展開後可看到停在哪個 Agent，以及使用者回覆後接著交給誰</p></figcaption></figure>

{% hint style="info" %}
**可以用 API 取得執行記錄嗎？** 目前執行記錄只能在後台的〈**執行記錄**〉檢視查看，尚未列入公開的 [API 文件](https://docs.maiagent.ai/api)。需要匯出分析時，請洽 MaiAgent 窗口。
{% endhint %}

{% hint style="info" %}
**看不到記錄？** 執行記錄只在團隊實際被對話觸發後才會產生。若列表是空的，先透過團隊的對話平台與團隊聊幾句，再回來查看。
{% endhint %}

## <mark style="color:blue;">四、怎麼用這些記錄優化團隊</mark> <a href="#optimize" id="optimize"></a>

* **路由不如預期**：從步驟卡的 Agent 名稱與〈輸入〉裡的移交原因，發現問題被交給了錯誤的 Agent，回到 [畫布編排](/build/teams/setup.md#compose-canvas) 調整連線的〈觸發條件描述〉，把「什麼時候走這條連線」寫得更明確。
* **迭代數或耗時偏高**：可能是 Agent 之間來回移交太多次。檢查是否有多餘的連線，或調整團隊的〈最大迭代數〉與各節點設定。
* **成本集中在某個 Agent**：比對各步驟卡的 Token 用量，找出 Token 花最多的 Agent，考慮為它換用較輕量的模型，或縮小它的知識庫與工具範圍。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/build/teams/traces.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.