# 如何設定代理排程

{% hint style="info" %}
本頁示範如何實際建立一個代理排程。如果你還不了解代理排程的用途，建議先閱讀 [代理排程](/agent-builder/schedule.md)。
{% endhint %}

## 前置條件 <a href="#prerequisites" id="prerequisites"></a>

在建立排程前，請先確認：

1. **已建立 Agent 模式的 AI 助理** — 代理排程僅支援 Agent 模式的 AI 助理，非 Agent 模式的助理不會出現在選單中
2. **AI 助理已連結至少一個對話平台** — 排程執行時會以對話平台為容器跑 Agent
3. **具備代理排程存取權限** — 若看不到「代理排程」選單，請聯絡組織管理員確認權限設定

## 進入代理排程 <a href="#navigate-to-schedule" id="navigate-to-schedule"></a>

從左側選單點選 <mark style="color:blue;">AI 功能</mark> → <mark style="color:blue;">代理排程</mark>。進入後會看到排程列表：

<figure><img src="/files/LlXowrd3L6zkf7h9JzKr" alt="代理排程列表頁"><figcaption><p>代理排程列表頁，顯示所有排程的狀態、類型、傳遞方式與上次執行時間</p></figcaption></figure>

列表欄位說明：

| 欄位        | 說明                                          |
| --------- | ------------------------------------------- |
| **名稱**    | 排程的識別名稱                                     |
| **AI 助理** | 此排程使用的 AI 助理                                |
| **執行模式**  | 上下文模式或獨立模式                                  |
| **排程**    | 排程類型（Cron、interval、one\_shot）與時間            |
| **傳遞方式**  | 💬 代表傳送到對話、🔗 代表 Webhook，`auto` 表示自動建立的專屬對話 |
| **上次執行**  | 最近一次執行的時間                                   |
| **狀態**    | 啟用中 / 已暫停                                   |

## 建立排程 <a href="#create-schedule" id="create-schedule"></a>

### 1. 點選新增排程 <a href="#step-new-schedule" id="step-new-schedule"></a>

點右上角的 <mark style="color:blue;">新增排程</mark> 按鈕開啟表單。表單分為四個分頁：**基本資訊**、**提示詞**、**排程設定**、**傳遞設定**。

### 2. 填寫基本資訊 <a href="#step-basic-info" id="step-basic-info"></a>

<figure><img src="/files/McPisYFxgvMyo6DBt4IP" alt="基本資訊分頁"><figcaption><p>基本資訊分頁：選擇 AI 助理、命名、決定執行模式與對話平台</p></figcaption></figure>

| 欄位           | 必填 | 說明                                                   |
| ------------ | -- | ---------------------------------------------------- |
| **AI 助理**    | ✅  | 選擇已建立的 AI 助理（僅顯示 Agent 模式的助理）                        |
| **名稱**       | ✅  | 排程的識別名稱，例如「每日客服摘要」                                   |
| **執行模式**     | ✅  | 選擇上下文模式或獨立模式                                         |
| **對話平台**     | ✅  | 排程執行時的對話平台容器；上下文模式會用它累積 Agent 記憶（後端使用，不會在客服對話列表出現）   |
| **儲存結果至上下文** | —  | 僅上下文模式顯示。**只影響下次執行的記憶**（不影響你能否看到結果——所有歷次回覆都保留在執行紀錄頁） |

**執行模式如何選擇？**

* **上下文模式**：跨次執行保留記憶。適合需要累積資訊的任務，例如持續追蹤客訴處理進度、監控數據變化趨勢。
* **獨立模式**：每次從頭開始，不帶前次記憶。適合獨立的重複性任務，例如每日報告、定期統計。

{% hint style="warning" %}
**AI 助理、執行模式、對話平台三個欄位在建立後無法修改。** 如果需要變更，必須刪除排程後重新建立。其他欄位（名稱、提示詞、排程時間、傳遞方式）可隨時編輯。
{% endhint %}

### 3. 撰寫提示詞 <a href="#step-prompt" id="step-prompt"></a>

<figure><img src="/files/n6uNGcUq9FQ8QlKT48Ys" alt="提示詞分頁"><figcaption><p>提示詞分頁：描述 Agent 每次執行要完成的任務</p></figcaption></figure>

在提示詞欄位描述 Agent **每次執行**要做的事情。提示詞會傳給 Agent 作為指令，Agent 會運用它掛載的工具和技能完成任務。

**提示詞範例：**

```
請查詢過去 24 小時內所有未解決的客訴案件，
依優先級排序後，整理成條列式摘要。
若有「高」優先級的案件，請額外標注「⚠️ 緊急」。
```

撰寫提示詞的建議：

* 明確描述任務目標與輸出格式
* 若需要 Agent 使用特定工具，可在提示詞中引導（例如「請查詢資料庫中的 orders 表」）
* 避免依賴當前時間以外的外部狀態，每次執行應為獨立任務（除非使用上下文模式）

### 4. 設定排程時間 <a href="#step-schedule-config" id="step-schedule-config"></a>

<figure><img src="/files/jJer6iQhgDxb7HQWXE51" alt="排程設定：Cron"><figcaption><p>Cron 模式：使用標準 5 欄位 Cron 表達式精確設定時間</p></figcaption></figure>

排程類型分為三種：

{% tabs %}
{% tab title="Cron" %}
用標準 5 欄位 Cron 表達式設定精確時間：`分 時 日 月 週`。

| 表達式           | 意義            |
| ------------- | ------------- |
| `0 9 * * 1-5` | 每週一到週五早上 9:00 |
| `0 */2 * * *` | 每 2 小時整點執行    |
| `30 8 * * *`  | 每天早上 8:30     |
| `0 0 1 * *`   | 每月 1 號凌晨      |

需搭配「時區」欄位，預設為 `Asia/Taipei`（台北時間）。
{% endtab %}

{% tab title="間隔" %}
每隔固定時間執行一次，以天／時／分／秒四個欄位組合設定：

<figure><img src="/files/Yv7PPg1TxXLiizcsEwCc" alt="排程設定：間隔"><figcaption><p>間隔模式：天、時、分、秒四欄位組合</p></figcaption></figure>

* 間隔時間**至少 1 秒**
* 例如要設定「每 30 分鐘執行一次」，在「分」欄位填 `30`，其他欄位填 `0`
* 間隔模式不使用時區欄位（因為是相對時間而非絕對時間）
  {% endtab %}

{% tab title="單次執行" %}
在指定時間執行一次，之後排程自動結束：

<figure><img src="/files/iyzBQFGzkhkHIPBUIg9d" alt="排程設定：單次執行"><figcaption><p>單次執行：選擇特定日期時間，執行完畢後排程結束</p></figcaption></figure>

* 選擇精確到秒的日期時間
* 需搭配「時區」欄位
* 執行完成後，排程會保留在列表中以供查看紀錄，但不會再次執行
  {% endtab %}
  {% endtabs %}

**其他欄位：**

| 欄位         | 說明                           |
| ---------- | ---------------------------- |
| **啟用**     | 是否立即啟動排程。關閉時排程為「已暫停」狀態，不會觸發  |
| **最大執行次數** | 限制排程最多執行幾次；達到次數後自動暫停。留空表示無限制 |

### 5. 設定傳遞方式 <a href="#step-delivery" id="step-delivery"></a>

執行完成後的結果要送到哪裡？在此分頁設定。

<figure><img src="/files/qRlK4UQ9U53GIXCzPyDN" alt="傳遞設定分頁"><figcaption><p>傳遞設定：可設定多個對話目標與多個 Webhook URL</p></figcaption></figure>

{% hint style="info" %}
本頁設定的是**結果要主動推送到哪裡**（指定的對話、Webhook 接收端）。即使不設任何傳遞目標，每次執行的完整結果還是會保留在<mark style="color:blue;">執行紀錄</mark>頁，只是不會主動 push 到別的地方。
{% endhint %}

#### 對話 <a href="#delivery-conversation" id="delivery-conversation"></a>

點 <mark style="color:blue;">新增對話</mark> 從選單中挑選對話，結果會以機器人訊息的形式送出。可加入多個對話。

#### Webhook <a href="#delivery-webhook" id="delivery-webhook"></a>

點 <mark style="color:blue;">新增 Webhook URL</mark>，結果會以 POST 請求送到你的外部 URL（需以 `http://` 或 `https://` 開頭）。常用於：

* 串接 Slack / Discord / LINE
* 寫入自家系統做進一步處理
* 觸發其他自動化流程

{% hint style="warning" %}
沒設傳遞目標也沒關係，執行結果一定會留在<mark style="color:blue;">執行紀錄</mark>頁。但如果想讓團隊／同事被動收到結果（例如推到 Slack），就要至少設定一個對話或 Webhook，否則沒人會被通知。
{% endhint %}

### 6. 儲存並啟用 <a href="#step-save" id="step-save"></a>

點 <mark style="color:blue;">確認</mark> 儲存。若「啟用」開關為開啟狀態，排程會立即開始依設定的時間觸發。

## 儲存後會發生什麼？ <a href="#after-save" id="after-save"></a>

排程儲存成功後，你會立刻看到以下變化：

1. **Modal 關閉，排程出現在列表中**
   * 狀態顯示為「啟用中」（綠色 Tag），或「已暫停」（若關閉了啟用開關）
   * 「上次執行」欄位為空，直到首次觸發後更新為執行時間
2. **系統在背景做了兩件事**（你不會看到 UI 變化，但幕後發生）
   * 把排程註冊到後台排程器，到設定的時間就會自動觸發
   * 上下文模式還會額外建立一個系統內部的對話容器來累積 Agent 記憶（這個容器不會出現在<mark style="color:blue;">客服對話</mark>列表）
3. **等排程觸發**
   * **Cron / 間隔**：依設定的時間自動執行，例如 Cron `0 9 * * 1-5` 會在下一個週一至週五的 9:00 觸發
   * **單次執行**：到設定的那個時間點執行一次
   * 不想等？點列表中的 ▶️ <mark style="color:blue;">立即執行</mark> 按鈕，可以立刻觸發一次做測試
4. **執行過程**
   * 列表中的狀態會保持「啟用中」，「上次執行」欄位會隨每次執行更新時間
   * 每一次執行都會在<mark style="color:blue;">執行紀錄</mark>頁產生一筆紀錄（含完整 Agent 回覆）
   * 若你在「傳遞設定」加了對話或 Webhook，結果同時會送到那些目標
   * 詳細查看方式請見下方〈[結果會跑到哪裡？](#where-results-go)〉
5. **任務結束時**
   * 達到「最大執行次數」上限 → 自動切換為「已暫停」，不再觸發
   * 單次執行完成 → 排程保留在列表中但不再觸發

## 結果會跑到哪裡？ <a href="#where-results-go" id="where-results-go"></a>

排程跑完後，Agent 的回覆會出現在以下位置。**執行紀錄頁是查看歷史的主要入口**——不管哪種執行模式，每一次跑完都會在這裡留下完整內容。其他位置取決於你的傳遞設定。

### 1. 執行紀錄頁（主要查看入口） <a href="#result-execution-log" id="result-execution-log"></a>

每一次執行都會產生一筆紀錄。這是查看歷次結果最可靠的方式。

**怎麼進去：**

<mark style="color:blue;">代理排程</mark>列表 → 在該排程那一列點 🕘 <mark style="color:blue;">查看執行紀錄</mark> → 進入執行歷史頁 → 點某筆紀錄右側的 👁 <mark style="color:blue;">查看詳情</mark>

**會看到：**

* 執行狀態（成功 / 失敗 / 部分成功）
* 開始時間、完成時間
* Agent 完整回覆內容（即使後續傳遞失敗，內容仍保留在這）
* 失敗時的錯誤訊息

### 2. 你指定的對話（傳遞設定中加入的對話） <a href="#result-target-conversations" id="result-target-conversations"></a>

執行結果會以 Agent 的訊息身份送進這些對話中，跟客戶／同事看到的訊息一樣。

**怎麼找到：**

<mark style="color:blue;">客服對話</mark> → 進入你在傳遞設定中加入的那個對話 → 訊息會在最新位置。

### 3. Webhook URL（傳遞設定中加入的 URL） <a href="#result-webhooks" id="result-webhooks"></a>

執行結果會以 HTTP POST 送到你的外部 URL，**Body 為 JSON**：

```json
{
  "content": "Agent 產生的完整回覆內容"
}
```

**技術細節：**

* Content-Type：`application/json`
* 逾時：30 秒（Webhook 端要在 30 秒內回應 2xx，否則視為失敗）
* 失敗會記錄在執行紀錄的「錯誤訊息」中（執行紀錄狀態變「部分成功」），但不會重試

### 「儲存結果至上下文」開關有什麼效果？ <a href="#save-context-effect" id="save-context-effect"></a>

這個開關**只影響上下文模式下次執行的記憶**，不影響你能不能看到結果。

| 設定         | 對下次執行的影響                                    |
| ---------- | ------------------------------------------- |
| **開啟**（預設） | 上一次的提示詞與 Agent 回覆會被當成歷史對話帶入下一次，Agent 能延續上下文 |
| **關閉**     | 每次執行雖然走上下文模式但不留訊息，效果接近獨立模式                  |

不論開關狀態，**執行紀錄頁都會保留每次的完整回覆**——這個開關不影響你查歷史。

### 摘要：結果可見性對照表 <a href="#result-summary" id="result-summary"></a>

| 執行模式 / 設定            | 執行紀錄頁 | 指定對話   | Webhook | Agent 跨次記憶 |
| -------------------- | ----- | ------ | ------- | ---------- |
| 上下文模式 + 儲存結果至上下文（預設） | ✅     | ✅ 若有設定 | ✅ 若有設定  | ✅ 帶記憶      |
| 上下文模式 + 不儲存結果        | ✅     | ✅ 若有設定 | ✅ 若有設定  | ❌ 無記憶      |
| 獨立模式                 | ✅     | ✅ 若有設定 | ✅ 若有設定  | ❌ 無記憶      |

{% hint style="info" %}
**為什麼沒有「專屬對話」入口？** 上下文模式會在後端建立一個專屬對話累積記憶，但這個對話**目前不會出現在**<mark style="color:blue;">**客服對話**</mark>**列表中**——它是系統內部使用的容器，不是給人類客服處理的對話。要看歷史結果請走<mark style="color:blue;">執行紀錄</mark>。
{% endhint %}

## 完整範例：每日客服摘要 <a href="#example-daily-summary" id="example-daily-summary"></a>

以下是一個端到端範例，示範如何建立一個每天早上 9:00 自動彙整前一日客服摘要、並把結果送到 Slack 的排程。

### 情境 <a href="#example-scenario" id="example-scenario"></a>

每天早上上班前，你希望 AI 助理先彙整昨天所有未解決的客訴，整理成摘要送到團隊的 Slack #customer-support 頻道，讓客服主管一打開 Slack 就能看到。

### 前置準備 <a href="#example-prerequisites" id="example-prerequisites"></a>

* 一個 Agent 模式的 AI 助理，已掛載可查詢客訴資料的工具（例如資料庫工具或客服系統 API 工具）
* 一個已串接的對話平台（作為排程執行的容器）
* 一個 Slack incoming webhook URL（用來接收結果）

### 設定內容 <a href="#example-config" id="example-config"></a>

**基本資訊：**

| 欄位    | 填入內容                  |
| ----- | --------------------- |
| AI 助理 | `客服 AI 主管`            |
| 名稱    | `每日客訴摘要 - 9:00`       |
| 執行模式  | 獨立模式（每天獨立彙整，不需要記憶前一天） |
| 對話平台  | `內部客服`                |

**提示詞：**

```
請查詢過去 24 小時內（以今天凌晨為終點）
所有狀態為「未解決」或「處理中」的客訴案件，
按照優先級排序（高 → 中 → 低）並整理成摘要：

## 格式
### 🔴 高優先級（X 筆）
- [#案件編號] 客戶名稱 — 一句話描述

### 🟡 中優先級（X 筆）
...

### 🟢 低優先級（X 筆）
...

最後加一行總結：「共 X 筆待處理，其中高優先級 X 筆需今日處理」。
```

**排程設定：**

* 排程類型：`Cron`
* Cron 表達式：`0 9 * * 1-5`（週一至週五早上 9:00）
* 時區：`Asia/Taipei`
* 啟用：開啟
* 最大執行次數：留空（持續執行）

**傳遞設定：**

* 對話：不加入額外對話（執行紀錄頁本來就會保留 Agent 完整輸出，沒必要再傳到客服對話佔空間）
* Webhook URL：`https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXX`

### 儲存後 <a href="#example-after-save" id="example-after-save"></a>

1. **週一早上 9:00（首次觸發）**：排程自動觸發，Agent 開始查詢與彙整
2. **約 30 秒內（視 Agent 處理速度）**：
   * 團隊的 Slack #customer-support 頻道收到 Webhook 推送的摘要訊息（POST body 為 `{"content": "..."}`）
   * 排程列表中的「上次執行」更新為 `2026-04-20 09:00:12`
3. **想回頭看 Agent 產生了什麼？** 兩個地方：
   * **執行紀錄頁**（主要入口）：<mark style="color:blue;">代理排程</mark> → 點該排程的 🕘 → 點 👁 → 看完整機器人回覆與 token 使用量
   * **Slack**：直接到 #customer-support 頻道（這是你設定的 Webhook 接收端）
4. **週二、週三… 持續執行**：每個工作日早上 9:00 自動觸發，不再需要人為介入

### 如果有問題要怎麼排查？ <a href="#example-troubleshooting" id="example-troubleshooting"></a>

* **Slack 沒收到訊息** → 先到執行紀錄頁確認那次執行的狀態，若是「失敗」看錯誤訊息；若是「成功」但 Slack 沒收到，檢查 Webhook URL 是否正確、Slack 端是否有 rate limit
* **摘要內容不符預期** → 到執行紀錄詳情看 Agent 實際輸出，再回頭調整提示詞
* **排程沒觸發** → 參考本頁下方「常見問題」

## 管理既有排程 <a href="#manage-schedules" id="manage-schedules"></a>

回到排程列表，每一列右側的操作區提供以下功能：

| 圖示     | 功能          | 說明                        |
| ------ | ----------- | ------------------------- |
| ✏️     | **編輯**      | 修改排程內容（AI 助理、執行模式、對話平台除外） |
| 🕘     | **查看執行紀錄**  | 進入該排程的歷次執行紀錄頁             |
| ▶️     | **立即執行**    | 不等排程時間，立刻觸發一次執行           |
| ⏸️ / ⏻ | **暫停 / 啟用** | 切換排程啟用狀態                  |
| 🗑     | **刪除**      | 刪除排程。刪除後執行紀錄一併清除          |

### 立即執行 <a href="#run-now" id="run-now"></a>

「立即執行」是測試排程是否設定正確的最快方式。按下後：

1. 系統會立刻觸發一次執行，不會影響原本的排程時間
2. 畫面出現「排程已觸發」提示
3. 可到「查看執行紀錄」觀察執行結果

### 暫停與啟用 <a href="#pause-resume" id="pause-resume"></a>

暫停後排程不會再觸發，但保留設定與執行紀錄。隨時可再次啟用。

## 查看執行紀錄 <a href="#view-executions" id="view-executions"></a>

在列表點 🕘 圖示進入執行紀錄頁：

<figure><img src="/files/wz3uQizsPeiTdVWBeA0l" alt="執行紀錄列表"><figcaption><p>執行紀錄頁：依狀態、日期範圍篩選，並查看每次執行的結果</p></figcaption></figure>

### 篩選 <a href="#filter-executions" id="filter-executions"></a>

* **狀態**：等待中 / 執行中 / 成功 / 失敗
* **日期範圍**：指定開始與結束日期

### 欄位說明 <a href="#execution-fields" id="execution-fields"></a>

| 欄位        | 說明                        |
| --------- | ------------------------- |
| **狀態**    | 等待中（排隊）、執行中、成功、失敗         |
| **開始時間**  | Agent 開始執行的時間             |
| **完成時間**  | 執行結束的時間                   |
| **錯誤訊息**  | 若執行失敗，顯示錯誤原因              |
| **機器人回覆** | Agent 產生的回應內容（完整內容可在詳情查看） |

### 查看執行詳情 <a href="#execution-detail" id="execution-detail"></a>

點每列右側的 👁 圖示開啟詳情彈窗，可查看完整的機器人回覆與錯誤訊息：

<figure><img src="/files/Al02U833zsQdyLrAFNDV" alt="執行詳情"><figcaption><p>執行詳情：狀態、開始/完成時間、完整機器人回覆與錯誤訊息</p></figcaption></figure>

## 常見問題 <a href="#faq" id="faq"></a>

<details>

<summary>排程為什麼沒有觸發？</summary>

可能原因：

1. 排程狀態為「已暫停」——到列表確認狀態欄
2. 已達「最大執行次數」上限——會自動暫停
3. Cron 表達式或時區設定錯誤——到編輯頁檢查
4. 單次執行模式已執行過——單次執行只會觸發一次

建議先用「立即執行」測試，確認排程本身可正確執行，再排查時間設定。

</details>

<details>

<summary>為什麼選不到我的 AI 助理？</summary>

代理排程**只支援 Agent 模式**的 AI 助理。若你的助理是 Chatbot 模式或其他模式，不會出現在選單中。請到 AI 助理設定頁確認模式後再來建立排程。

</details>

<details>

<summary>排程跑完，要去哪裡看 Agent 產生了什麼？</summary>

主要入口是<mark style="color:blue;">代理排程</mark> → 點該排程的 🕘 <mark style="color:blue;">查看執行紀錄</mark> → 點某筆紀錄的 👁。詳情會顯示 Agent 完整回覆。

如果有設定傳遞目標（對話／Webhook），也會送一份過去：

* 指定的對話：直接進那個對話看訊息
* Webhook：到你的外部接收端看 POST body

</details>

<details>

<summary>「儲存結果至上下文」開了之後，我去哪看那個對話？</summary>

**這個開關不影響你能不能看到結果**——所有歷次回覆永遠保留在執行紀錄頁。

它只影響「Agent 下次執行時記不記得上次發生什麼」：

* 開啟（預設）：Agent 在後端會用同一個對話容器累積記憶，下次執行能延續上下文
* 關閉：每次都不留訊息，效果類似獨立模式

這個後端對話容器目前不會出現在<mark style="color:blue;">客服對話</mark>列表，是系統內部使用的，不是給人類客服處理的。

</details>

<details>

<summary>Webhook 收到的資料格式是什麼？</summary>

POST 請求，Content-Type 為 `application/json`，body 結構：

```json
{
  "content": "Agent 產生的完整回覆內容（純文字）"
}
```

逾時 30 秒，不重試。Webhook 端應在 30 秒內回應 2xx 狀態碼，否則該次傳遞會記錄為失敗（但執行紀錄頁仍會保留 Agent 完整回覆）。

</details>

<details>

<summary>獨立模式 vs 上下文模式，差別到底在哪？</summary>

兩者最大差別在 **Agent 執行時看不看得到上次的對話歷史**：

* **上下文模式**：用同一個後端對話累積訊息。Agent 下次執行時，能看到歷次的提示詞與回覆，可以延續判斷（適合需要追蹤趨勢、避免重複、累積上下文的任務）
* **獨立模式**：每次建臨時對話，執行完立即刪除。Agent 每次都從零開始，不知道之前發生過什麼（適合每天獨立輸出的任務，例如每日報告）

兩種模式的執行結果**都會保存在執行紀錄頁**——差別不在「能不能查歷史」，而在「Agent 工作時帶不帶記憶」。

</details>

## 延伸閱讀 <a href="#related" id="related"></a>

* [代理排程](/agent-builder/schedule.md) — 代理排程的概念介紹
* [Agent（AI 助理）](/agent-builder/agent.md) — 建立 Agent 模式的 AI 助理
* [串接對話平台：網站](/conversations/web-chat/website.md) — 設定對話平台（以網站為例）


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.maiagent.ai/agent-builder/schedule/schedule-setup.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.