Skip to main content

🔧 Getting Started: Build Your First AI App!

STEP 1：Add a New AI App and Name It​

完成工作流程（workflow）設計後，接下來將其部署為一個可以對外使用的 AI 機器人。

請依以下步驟新增整合應用（Integration）：

  1. 於左側選單中點選 Apps 分頁，進入整合介面
  2. 點選中央的 「+ New Integration」 按鈕，開始建立新的應用接點

Integration 設定說明：

  • Integration 名稱：暫時命名為 API
  • Description（描述）：暫時命名為 API
  • Environment（環境）：選擇 main
  • Workflow（工作流程）：選擇前面章節中建立的 "Hello" 流程
  • 狀態：請確認 Integration 為「啟用中（Enabled）」
  • API Key 權限：請確認你是此 Bot 的設計者，以確保擁有操作與呼叫該 API 的權限。

在本練習中，你可以自行命名一組 API Key，作為測試用途。後續使用此 Key 即可對剛建立的機器人進行 API 呼叫與驗證。

  • 完成後，請點選 💾 Save（儲存） 按鈕，確保Integration 已成功建立。

這樣你的 Integration 就建立完成了！

請回到 Apps 頁面，找到剛剛建立的 Integration 卡片，點選右上角的「⋯」圖示，並選擇 Integrate。

進入後，你將看到系統自動為你產生的幾個 API Endpoint，包含：

  • SSE（Server-Sent Events）：支援即時串流回應，適用於 Streaming 類型的 Bot。SSE 回應的格式會與你在 **Workflow 預覽模式（Preview）**中看到的回覆行為非常相似。
  • Blob：支援二進位資料傳輸，適合上傳檔案等特殊情境。
  • Message：基本訊息觸發點，適用於標準文字互動。

📌 這些 Endpoint 可供你在不同平台或自訂前端中整合使用，實現與 Bot 的互動。

STEP 3：使用 SSE Endpoint 發送請求​

當你使用 SSE（Server-Sent Events） Endpoint 與 AI Bot 進行串接時，請遵循以下格式發送請求。

HTTP Method​

  • POST

Headers​

名稱說明
X-API-KEY請輸入你在建立 Integration 時所設定的 API Key，用於身份驗證

Request Body 格式​

請以 JSON 格式傳送訊息，內容包含以下三個欄位：

{
  "customChannelId": "1",
  "customMessageId": "msg-1",
  "text": "",
  "action": "RESET_CHANNEL"
}
欄位名稱說明
customChannelId自定義的頻道 ID，用來識別使用者對話上下文
customMessageId當前訊息的唯一識別碼（用於追蹤回應、日誌）
text留空即可，因為 RESET_CHANNEL 不需實際對話文字
action指令動作，設為 "RESET_CHANNEL" 可清除該頻道的上下文與歷史紀錄

📌 應用場景：

  • 使用者點選「重新開始對話」按鈕時觸發
  • 每次開啟新會話時，自動呼叫重置動作
  • 測試 LLM 回應是否在無上下文條件下仍然合理

延伸閱讀

🧼 對話初始化：開始互動前的 Reset Channel 重置​

在每一次機器人對話開始前，系統會先對該使用者的 Channel（頻道）進行初始化，以清空過去的上下文、重設對話狀態，確保此次對話從乾淨的狀態開始。

這個動作通常是透過 API 發送一個包含 action: "RESET_CHANNEL" 的請求來完成。

📌 實際案例說明：Hello Workflow 的初始化動作​

以「Hello」這個 Workflow 為例：

  • 當你觸發機器人開始對話時，會發現回應前會出現一段 微小的停頓時間。
  • 這段時間實際上不是延遲，而是系統正在進行 Channel 初始化 的動作。
  • 初始化完成後，才會執行 Entry → Push Message 的流程，發送歡迎訊息。

📡 SSE 回應格式：由一連串事件組成的串流式資料​

當你呼叫 SSE（Server-Sent Events）Endpoint 時，回應資料不會像傳統 HTTP 一樣一次性傳回，而是以串流（Streaming）方式逐步送出。這種串流式回應是由一系列的 事件（event） 所組成，每個事件都代表對話過程中的一個階段或資料片段。

🧩 事件流程結構（Event Sequence）​

SSE 回應通常包含以下事件順序：

  1. run:init
    • 表示對話流程初始化開始
    • 系統已接收訊息並準備執行流程
  2. run:delta / run:data**（多次）**
    • 主體輸出階段
    • AI 模型回應內容將以逐段訊息送出，每次一小段
  3. （可選）**run:log** / run:debug
    • 若有開啟除錯，可包含流程執行細節或除錯資訊
  4. run:done
    • 串流回應結束
    • 表示本次流程與訊息回覆已完成，可進行下一步處理

🧾 每則訊息的三個組成階段：start、delta、complete​

在使用 Streaming LLM Completion 串接聊天機器人時，每一則回應訊息會被拆分為以下三個階段，依序透過 SSE（Server-Sent Events）回傳給前端：

1. start​

  • 表示回應輸出的起點
  • 常用於初始化回應區塊、顯示「AI 正在輸入中」的提示
  • 不含實際內容，僅代表一段新訊息即將開始

2. delta​

  • 核心回應階段
  • 每段文字會以小片段（token 或字串）逐步送出
  • 前端可即時將內容「逐字顯示」在畫面上，模擬打字效果
  • 此階段可能包含多則 delta 事件，直到訊息輸出完畢為止

3. complete​

  • 表示回應結束，包含完整的結構化資料
  • 通常會附帶如：
    • 最終組合的輸出文字（例如 answer）
    • 流程執行摘要或狀態代碼
  • 前端可藉此階段關閉「輸入中」動畫，或觸發下一步操作

📌 補充說明：

  • 這三個階段會依序透過不同 event 傳送給前端，每一段都可用來更新畫面狀態。
  • 若串流中斷或模型錯誤，可能只收到 start 或部分 delta，此時可由系統觸發 error 或 fallback 機制。