> ## Documentation Index
> Fetch the complete documentation index at: https://datagen.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 觸發方式與自動化

> 啟用 Agent、立即執行，並用自動化以排程或 Webhook 觸發 Agent

Agent 啟用後，不需要有人按按鈕也能執行。使用者透過聊天、頻道與 Agent API 使用它；**自動化**則依排程，或在其他系統呼叫 Webhook 時執行它。

| 觸發方式 | 如何開始一次執行 | 在哪裡設定 |
| - | - | - |
| **聊天** | 在「聊天」中傳送訊息 | 不需設定 |
| **測試執行** | 執行尚未發布的草稿 | Agent Builder |
| **立即執行** | 隨時觸發一次已儲存的自動化 | 「自動化」分頁 |
| **排程** | 在指定時間觸發自動化一次，或重複觸發 | 「自動化」分頁 |
| **Webhook** | 其他系統 POST 到自動化的網址時觸發 | 「自動化」分頁 |
| **頻道** | Slack、Teams 或 Discord 的提及、電子郵件、Linear issue、公開聊天連結 | [頻道](/zh/agents/channels) |
| **Agent API** | 你的程式碼傳訊息給 Agent | [Agent API](/zh/api-reference/agent-api/overview) |

***

## 啟用或停用 Agent

Agent 只有在**已啟用**時才會執行。Agent 頁面頂端的狀態按鈕會顯示「已啟用」或「已停用」，點選即可切換。

* 從 Agent Builder **發布**會啟用 Agent。
* **停用**會讓 Agent 在所有地方停止回應：聊天、API 呼叫、公開連結、電子郵件、聊天應用、聊天室與自動化。Builder 中的建構與「測試執行」仍可使用。重新開啟即可恢復。

只有 Admin 與 Builder 角色可以啟用或停用 Agent。

***

## 自動化

自動化是 Agent 的一次已儲存呼叫：包含提示詞、觸發它的條件，以及結果要送到哪裡。每次觸發都是 Agent 的一次真實執行，而且每次執行都會開啟一段新對話。

<Frame>
  <img src="https://mintcdn.com/datagen/rusBmwP8bd_Srmdm/images/browser-guide/zh/automation-editor.jpg?fit=max&auto=format&n=rusBmwP8bd_Srmdm&q=85&s=f4c5577e2d124fae69e2d1d36d0210e3" alt="尚未儲存的自動化：工作日 09:00 排程與 America/Chicago 時區" width="838" height="863" data-path="images/browser-guide/zh/automation-editor.jpg" />
</Frame>

### 建立自動化

<Steps>
  <Step title="開啟「自動化」分頁">
    在 Agent 頁面開啟「自動化」，點選「新增自動化」。
  </Step>

  <Step title="命名並撰寫提示詞">
    填寫「名稱」（例如「Morning digest」），並在「要做什麼？」中描述任務，例如：「彙整上週的新名單，並標出任何異常。」
  </Step>

  <Step title="加入觸發條件">
    在「觸發條件」下點選「新增觸發條件」，選擇「定時排程」或「Webhook」。排程可以加入任意多個，Webhook 最多一個。沒有任何觸發條件時，自動化只會在有人按下「立即執行」時執行。
  </Step>

  <Step title="選擇結果的去向">
    展開「進階設定」選擇「目的地」，並可選擇設定「模型」、「執行身分」與「最大並行執行數」。編輯器會把選擇摘要為「結果傳送至：...」。
  </Step>

  <Step title="儲存">
    點選「建立」。自動化儲存後才會出現 Webhook 網址。
  </Step>
</Steps>

| 設定 | 作用 |
| - | - |
| **目的地** | 每次執行結果要發布到哪裡：「網頁聊天」（在你的聊天清單中開啟一段以該自動化命名的私人對話），以及 Agent 聊天應用所運作的 Teams 或 Discord 頻道。請參閱 [頻道](/zh/agents/channels)。 |
| **模型** | 為此自動化覆寫 Agent 的預設模型。留白則依序使用 Agent 的預設模型、系統預設值。API 呼叫指定的模型或 Harness 固定的模型仍然優先。 |
| **執行身分** | 用來驗證此次執行回呼 DataGen 的 API 金鑰。金鑰擁有者就是這次執行的身分。「使用帳戶預設（派發時自動選取）」會在派發執行時選用你的預設金鑰。 |
| **最大並行執行數** | 此自動化同時可執行的次數上限。 |
| **自動化使用中** | 關閉時，不論各觸發條件本身的狀態為何，都不會觸發。 |

### 立即執行

「自動化」分頁上的每一列自動化都有「立即執行」按鈕，可立即觸發一次。Operator、Builder 與 Admin 角色都可以使用「立即執行」。

***

## 排程

「定時排程」觸發條件會在你選擇的「時區」中，於指定時間執行自動化。

| 頻率 | 執行時間 |
| - | - |
| **只執行一次** | 在你選擇的「日期與時間」執行一次 |
| **每小時** | 每小時的指定分鐘 |
| **每天** | 每天的指定時間 |
| **每個工作日** | 星期一到星期五的指定時間 |
| **每週** | 每週的指定星期與時間 |
| **自訂（cron）** | 任何 cron 運算式 |

自訂 cron 範例：

| 排程 | Cron 運算式 |
| - | - |
| 每天上午 9 點 | `0 9 * * *` |
| 每週一下午 2 點 | `0 14 * * 1` |
| 工作日上午 8 點 | `0 8 * * 1-5` |
| 每 6 小時 | `0 */6 * * *` |

暫停中的排程會顯示「此排程已暫停。」以及「恢復」按鈕。

***

## Webhook

「Webhook」觸發條件會給自動化一個專屬網址。任何能發送 HTTP POST 的系統都能執行 Agent：n8n、Make、Zapier、GitHub、會議記錄工具，或你自己的應用程式。

網址格式如下，編輯器會在「如何呼叫此自動化」中顯示它，並提供「複製網址」按鈕：

```text theme={null}
https://api.datagen.dev/api/agents/<agent-name>/automations/<automation-id>/trigger
```

### 保護 Webhook

在「API 金鑰（Bearer 權杖）」下點選「產生」，即可要求呼叫端傳送 `Authorization: Bearer <key>`。金鑰只會顯示一次；DataGen 只保存其雜湊值，因此請立即保存。「輪替」會發出新金鑰，並立即讓舊金鑰失效。沒有金鑰時，任何知道網址的人都能觸發 Webhook。

「每小時最多呼叫次數」限制 Webhook 的觸發頻率。

### 在提示詞中使用 payload

你 POST 的 JSON 內容可以在提示詞中使用。在「要做什麼？」中寫 `{{ payload.foo }}`，即可插入請求中的 `foo` 欄位：

```text theme={null}
Enrich the company {{ payload.domain }} and post a summary.
```

### 呼叫並取得結果

<Steps>
  <Step title="觸發執行">
    ```bash theme={null}
    curl -X POST 'https://api.datagen.dev/api/agents/<agent-name>/automations/<automation-id>/trigger' \
      -H 'Authorization: Bearer <your-token>' \
      -H 'Content-Type: application/json' \
      -d '{"domain": "example.com"}'
    ```

    回應為 `202 Accepted`，內容是 `{ executionId, statusUrl }`。執行會以非同步方式開始。
  </Step>

  <Step title="輪詢結果">
    ```bash theme={null}
    curl 'https://api.datagen.dev/api/agent/execution/<executionId>'
    ```

    每 1–2 秒輪詢一次，直到 `status` 為最終狀態。Agent 的答案在 `result.content` 中：

    ```json theme={null}
    {
      "executionId": "...",
      "status": "completed",
      "result": { "content": "<the agent's final answer>" },
      "startedAt": "...",
      "completedAt": "...",
      "durationMs": 10180
    }
    ```
  </Step>
</Steps>

在編輯器中點選「測試觸發」，會對網址 POST `{}`，確認它已進入佇列。

<Tip>
  若要從你自己的程式碼與 Agent 進行一問一答的對話，請使用 [Agent API](/zh/api-reference/agent-api/overview)，而不是 Webhook。
</Tip>

***

<AccordionGroup>
  <Accordion title="舊版的儲存庫執行自動化">
    部分較舊的自動化使用一次性的儲存庫執行，這種執行可以提交並開啟 Pull Request（「PR 模式」：「建立 PR」、「自動合併」或「略過」）。編輯器會在這類自動化上顯示提示與「改用對話方式」按鈕。新建立的自動化一律以對話方式執行。
  </Accordion>

  <Accordion title="排程沒有觸發">
    1. 確認 Agent 為「已啟用」。
    2. 確認「自動化使用中」已開啟，且排程沒有暫停。
    3. 檢查觸發條件上的「時區」。
    4. 在 [AI 代理人日誌](/zh/agents/versions-and-logs) 中以 **Scheduled (Cron)** 觸發來源篩選，尋找該次執行。
  </Accordion>

  <Accordion title="Webhook 回傳錯誤">
    * **401**：Webhook 設有 API 金鑰。請傳送 `Authorization: Bearer <key>`；若遺失金鑰，請「輪替」取得新金鑰。
    * **404**：檢查網址中的 Agent 名稱與自動化 ID、「自動化使用中」是否開啟，以及自動化是否有啟用中的 Webhook 觸發條件。
    * **429**：Webhook 超過「每小時最多呼叫次數」，或你排隊中與執行中的工作太多。請在回應指示的時間後重試。
  </Accordion>
</AccordionGroup>

## 下一步

<CardGroup cols={2}>
  <Card title="頻道" icon="comments" href="/zh/agents/channels">
    從 Slack、Teams、Discord、電子郵件、網頁聊天與公開連結使用 Agent
  </Card>

  <Card title="版本與紀錄" icon="clock-rotate-left" href="/zh/agents/versions-and-logs">
    回溯版本並檢視每一次執行
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.