🔧 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 就建立完成了！

STEP 2：View the information related to 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 機制。