> 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/agent/usage.md).

# Agent 使用分析

提供後台監測數據內容，了解使用者的資訊。

## 如何查看 <a href="#how-to-view" id="how-to-view"></a>

從左側選單進入 <mark style="color:blue;">AI 功能</mark> → <mark style="color:blue;">AI 助理</mark>，點選要查看的 Agent 進入設定頁，切換到上方的 <mark style="color:blue;">使用分析</mark> 分頁。這一頁有兩個子分頁：

| 子分頁                                   | 內容                                                                                                                                                                          | 誰看得到                                                             |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| <mark style="color:blue;">監控指標</mark> | 與 AgentOps 的 <mark style="color:blue;">AI 助理監控</mark> 儀表板相同的指標與圖表（對話數、回應時間、錯誤率、串流效能、回答品質分數等），但固定只看這一個 Agent；圖表說明見 [儀表板圖表](/build/agent-ops/evaluations.md#dashboard-charts) | 角色具備 <mark style="color:blue;">AI 助理監控權限</mark> 的成員；沒有權限時只顯示使用統計 |
| <mark style="color:blue;">使用統計</mark> | 這個 Agent 的對話量與 Token 用量（本頁以下說明）                                                                                                                                             | 能看到這個 Agent 的成員                                                  |

<mark style="color:blue;">使用統計</mark> 的圖表包含：

* <mark style="color:blue;">Token 用量</mark>：這個 Agent 每個 LLM 模型各一條線，另加一條 <mark style="color:blue;">Token 總用量</mark>，呈現 LLM 實際消耗，可對照 [Credits 計費制度](/others/credits.md) 估算成本
* <mark style="color:blue;">對話字數</mark>：同樣是每個 LLM 模型各一條線，另加一條 <mark style="color:blue;">對話總字數</mark>
* 對話次數
* 訊息次數
* 平均對話互動次數
* 使用者滿意度

圖表上方可選時間範圍（今天、昨天、本週、上週、本月、上月、近 7 天、近 30 天、本季度、上季度、今年、去年，或自訂區間），並切換統計粒度為 <mark style="color:blue;">時</mark>、<mark style="color:blue;">天</mark> 或 <mark style="color:blue;">月</mark>。

透過這些指標，您可以從多角度了解 Agent 的使用情形。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-365a7f2570428c98ef11ea2ae079c88048511794%2Fagent-usage-token-per-model.png?alt=media" alt="使用統計分頁的 Token 用量與對話字數圖，滑鼠停在 Token 用量圖上顯示各模型與 Token 總用量的數值"><figcaption><p>Token 用量與對話字數圖：每個模型一條線，另加一條總量線</p></figcaption></figure>

### 依模型查看 Token 用量 <a href="#token-usage-by-model" id="token-usage-by-model"></a>

<mark style="color:blue;">Token 用量</mark> 圖的每個模型線，是該模型的 Token 總數（輸入、輸出與 Prompt Cache 合計）；<mark style="color:blue;">Token 總用量</mark> 是所有模型加總。圖上不顯示圖例，把滑鼠移到圖上任一日期，會列出當天各模型（格式為「模型名稱 | 供應商」）與總量的數值。

{% hint style="info" %}

* 某個模型在所選區間內只有 Token、沒有字數（例如用來解析圖片或檔案的模型），它只會出現在 <mark style="color:blue;">Token 用量</mark> 圖，不會在 <mark style="color:blue;">對話字數</mark> 圖畫出一條 0 的線；反之亦然。總量線則一定會顯示，沒有用量時是一條貼在 0 的線。
* 統計粒度選 <mark style="color:blue;">時</mark> 時，不顯示 <mark style="color:blue;">Token 用量</mark> 與 <mark style="color:blue;">對話字數</mark> 圖，請切換為 <mark style="color:blue;">天</mark> 或 <mark style="color:blue;">月</mark>。
  {% endhint %}

**情境範例**：客服主管想知道「訂單查詢助理」換用另一個模型測試後，各模型分別用了多少 Token。她進入這個 Agent 的 <mark style="color:blue;">使用分析</mark> → <mark style="color:blue;">使用統計</mark>，時間範圍選近 7 天、粒度選 <mark style="color:blue;">天</mark>，把滑鼠移到 <mark style="color:blue;">Token 用量</mark> 圖上測試當天的位置，就看到兩個模型各自的 Token 數與 <mark style="color:blue;">Token 總用量</mark>，不必另外到組織的用量統計頁篩選。

## 統計數據詳細說明 <a href="#statistics-details" id="statistics-details"></a>

### 1. 對話字數 (Words Count) <a href="#words-count" id="words-count"></a>

**計算方式：**

* **文字字數**：計算訊息內容的字元數量
* **圖片成本**：每張圖片依照設定的圖片字數成本來計算
* **總字數** = 訊息內容字數 + (圖片數量 × 圖片字數成本)

**統計範圍：** 包含使用者輸入訊息和 Agent 回覆訊息，支援日、月時間粒度統計

***

### 2. 對話次數 (Conversations Count) <a href="#conversations-count" id="conversations-count"></a>

**計算方式：**

* 每當建立一個新的對話時，計數器 +1
* 當對話中的第一則訊息建立時，會觸發對話統計更新

**更新時機：** 用戶開始新對話時（第一則訊息）

{% hint style="info" %}
「對話次數」與 AgentOps「AI 助理監控」儀表板的「對話數」定義不同：這裡是每個對話計 1 次；儀表板的「對話數」是 Agent 回覆的次數，同一個對話回覆幾輪就計幾次。詳見 [自動評估與 Agent 監控](/build/agent-ops/evaluations.md#conversation-count-definition)。
{% endhint %}

**統計範圍：** 支援小時、日、月時間粒度統計

***

### 3. 訊息次數 (Messages Count) <a href="#messages-count" id="messages-count"></a>

**計算方式：**

* 每當建立一則新訊息時，計數器 +1
* 包含使用者輸入訊息和 Agent 回覆訊息

**更新時機：** 每則訊息建立時都會觸發統計更新

**統計範圍：** 支援小時、日、月時間粒度統計

***

### 4. 平均對話互動次數 (Average Messages per Conversation) <a href="#average-messages-per-conversation" id="average-messages-per-conversation"></a>

**計算公式：**

```
平均對話互動次數 = 訊息次數 ÷ 對話次數（若對話次數為0則顯示0）
```

**含義說明：**

* 表示每個對話平均包含多少則訊息
* 反映使用者與 Agent 的互動深度
* 數值越高表示對話越深入、互動越頻繁

**統計範圍：** 支援小時、日、月時間粒度統計

***

### 5. 使用者滿意度 (User Satisfaction Rate) <a href="#user-satisfaction-rate" id="user-satisfaction-rate"></a>

**計算公式：**

```
使用者滿意度 = 按讚數 ÷ 總回饋數（若總回饋數為0則顯示0）
總回饋數 = 按讚數 + 按倒讚數
```

**含義說明：**

* 表示獲得正面回饋的比例（按讚率）
* 數值範圍：0% \~ 100%
* 數值越高表示使用者對 Agent 回覆越滿意

**回饋機制：**

* 使用者可對 Agent 的回覆給予「讚」或「倒讚」
* 支援即時更新統計數據

**更新時機：** 使用者給予回饋時（建立、更新、刪除）

**讚／倒讚怎麼計數：**

* 每則回覆最多算一次回饋：由讚改成倒讚，讚數減 1、倒讚數加 1；取消回饋，就從統計中扣掉
* 回饋算在「被評價的那則回覆」建立的時段，不是按讚的時間。例如訪客隔天才對前一天的回覆按讚，這個讚會加在前一天
* **Web Chat 開場白的回饋不計入**：開場白是固定文案、不是 AI 回答，Web Chat 上開場白只有 <mark style="color:blue;">複製</mark> 按鈕，沒有讚／倒讚。若自行串接 API 或舊版嵌入程式仍對開場白送出回饋，回饋會保存在該則訊息上，但不會算進讚數、倒讚數與使用者滿意度

{% hint style="info" %}
**為什麼滿意度有數字，對話紀錄卻找不到那個讚？** 過去開場白的讚／倒讚會被算進滿意度：訪客打開 Web Chat、對開場白按讚就離開，滿意度出現 100%，對話紀錄裡卻沒有任何問答。現在開場白的回饋不再計入，滿意度只反映訪客對實際回覆的評價。
{% endhint %}

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-6cda82815c0a1348a03c234ed46e428cbfaf7c75%2Fweb-chat-greeting-no-feedback.png?alt=media" alt="Web Chat 對話畫面：開場白下方只有複製按鈕，Agent 回答下方有複製、讚、倒讚三個按鈕"><figcaption><p>開場白下方只有複製按鈕；Agent 回答才有讚／倒讚</p></figcaption></figure>

**情境範例**：客服主管發現「訂單查詢助理」某天滿意度是 100%，想確認這個數字是不是只來自訪客對開場白的回饋。她打開這個 Agent 的 Web Chat，看到開場白下方只有 <mark style="color:blue;">複製</mark>，Agent 回答下方才有讚／倒讚；接著回到後台 <mark style="color:blue;">使用分析</mark> → <mark style="color:blue;">使用統計</mark>，粒度選 <mark style="color:blue;">天</mark>，把滑鼠移到 <mark style="color:blue;">使用者滿意度</mark> 圖上那一天，看到的比例只由訪客對 Agent 回答的讚／倒讚算出，開場白的回饋沒有算進去。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-1f87e409d2ad280bd69755512a5afef091a268dd%2Fusage-satisfaction-chart.png?alt=media" alt="使用統計分頁的使用者滿意度圖，滑鼠停在 2026-10-12 顯示比例 1"><figcaption><p>使用者滿意度圖：滑鼠停在某一天顯示當天的讚數比例</p></figcaption></figure>

**統計範圍：** 支援小時、日、月時間粒度統計

***

## 統計數據更新機制 <a href="#statistics-update-mechanism" id="statistics-update-mechanism"></a>

**即時更新：** 當相關事件發生時（新訊息、新對話、回饋變更），會立即觸發統計更新

**時間粒度支援：**

* **小時級**：適合即時監控
* **日級**：適合日報分析
* **月級**：適合月報和趨勢分析

## 可以匯出或定期寄送報表嗎？ <a href="#export-and-reports" id="export-and-reports"></a>

使用分析的圖表只能在畫面上查看，沒有匯出按鈕，也沒有定期寄送報表的設定。需要把資料帶出平台時，改用下列有匯出功能的頁面：

| 需要的資料                          | 從哪裡匯出                                                                                                                                                                                                                  |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 各 Agent、角色、成員、對話平台的用量與 Credits | 用量統計的各分頁可 <mark style="color:blue;">匯出 Excel</mark>，見 [用量統計](/others/usage-statistics.md)                                                                                                                              |
| 工具呼叫的明細                        | AgentOps 的工具執行紀錄，可匯出 CSV 或 Excel，見 [工具執行紀錄](/build/agent-ops/tool-execution-records.md#step-export-execution-records)                                                                                                  |
| AI 問答紀錄                        | 在 <mark style="color:blue;">AgentOps</mark> → <mark style="color:blue;">AI 助理監控</mark> 篩選後匯出 Excel，或用問答紀錄 API 由內部系統定期同步，見 [取得對話問答紀錄](/serve/daily-operations/reply/conversation-viewer.md#export-conversation-history) |

## 應用場景：使用成效評估 <a href="#use-case-effectiveness-evaluation" id="use-case-effectiveness-evaluation"></a>

觀察「使用者滿意度」與互動次數的變化趨勢，可評估 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/agent/usage.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.