メインコンテンツまでスキップ

架構深入解析

進階選讀

這頁給想完整理解 Asgard 整合架構的進階讀者。如果你只想快速完成整合, 請直接從 總覽與選型 進入對應的 Pattern 頁, 不必讀本頁也能成功完成整合。

本頁涵蓋: 各模式的選型依據、功能在不同模式下的能力邊界、以及如何設計延展性更佳的整合架構。

詞彙定義​

本頁會反覆使用以下名詞, 如果你是第一次接觸 Asgard, 建議先讀 總覽與選型 的開場與名詞速覽:

詞一句話定義
Bot Provider你在 Odin 完成 Agent 後對外發布的端點
Edge ServerAsgard 雲端中對外服務 Bot Provider API 的後端服務(由 Asgard 托管)
Workflow你在 Odin Studio 設計的 Agent 工作流程, 由若干 Processor 串接而成, 於 Edge Server 內部執行
Channel一段對話的識別單位, 具備 customChannelId
Payload隨訊息一起送出的自訂資料, Workflow 可透過 prevPayload 讀取

為什麼要有這個框架​

整合 Asgard Bot Provider 時, 常見的疑問是「Audit Log 為什麼只有某些模式才能做?」「Memory 注入要在哪一層處理?」「Per-user Auth 為什麼一定要建後端服務?」

這些問題如果一一回答, 會得到一份散亂的「功能對照表」。但如果你回到本質問一個更根本的問題:

「我的程式碼能在哪些位置執行?」

你會發現所有的能力差異, 都來自這個根本問題的答案。Asgard 整合架構在訊息流動的鏈路上有 4 個天然的執行層 (Execution Planes), 每個位置是否開放/封閉, 直接決定了該位置上的衍生能力是否可用。

理解了這 4 個執行層(Execution Planes), 你就能在面對任何新需求時, 自行推導出「應該採用哪個 Pattern」、「該在哪一層實作」、「為什麼某些方案做不到」。

4 個 Execution Planes​

訊息流動鏈路​

Plane 的核心定義​

Plane物理位置執行什麼
① UI Plane (畫面層)使用者裝置視覺渲染、互動元件
② Client Plane (瀏覽器層)使用者瀏覽器JavaScript / TypeScript 邏輯
③ Server Plane (伺服器層)你自己的機房你的後端應用邏輯
④ Agent Plane (Agent 內部層)Asgard 雲端 Workflow 執行階段Workflow Processor 邏輯
為什麼這 4 個是「天然」的位置?

任何 Web 應用程式都自然地會跨越這 4 個位置: 使用者看到畫面 → 瀏覽器跑 JS → 過你的伺服器(可選) → 過 SaaS 後端內部邏輯。Asgard 整合的架構, 只是把這 4 個天然位置全部納入可程式化範圍。

各 Plane 提供的衍生能力​

以下列出各 Plane 的能力清單。找到你需要的能力後, 可從所需 Plane 推導出應採用的 Pattern。

在使用者裝置上, 你能畫出什麼

視覺與品牌

  • 完整客製 Theme(顏色、字體、邊框、陰影、圓角)
  • 暗黑/亮色模式切換、動態主題
  • 響應式版型(手機 / 平板 / Desktop)
  • 自訂 Avatar、品牌標誌、聊天視窗外框

訊息呈現

  • Custom Renderer 自訂訊息類型(圖表、卡片、表格、Vega 視覺化)
  • Markdown 渲染客製化(連結處理、代碼塊高亮、數學公式)
  • Streaming 文字逐字動畫呈現
  • 訊息群組化、時間戳分組、已讀指示
  • 工具呼叫過程的視覺化(例:「正在搜尋資料庫…」、進度條)
  • 圖片預覽 Lightbox、影音播放器、檔案下載

互動元件

  • 自訂輸入元件(多行編輯器、語音輸入按鈕、檔案拖放)
  • Quick Reply / Carousel / 內嵌表單元件 / 內嵌按鈕
  • 訊息操作選單(複製、轉發、引用回覆、reactions)
  • Onboarding 引導浮層、提示氣泡、空狀態畫面
  • 對話搜尋介面、歷史分頁瀏覽

整合形態

  • iframe vs 內嵌渲染、浮動聊天按鈕 (FAB)、全螢幕 / 小視窗切換
  • 多 Bot 切換 UI、Workspace 內多會話並列

Pattern × Plane 能力矩陣​

每個 Pattern 開放的 Plane 組合決定了它的能力範圍:

Pattern① UI Plane② Client Plane③ Server Plane④ Agent Plane
Hosted Embed△ 僅 URL 參數❌❌△ 僅 design-time
Direct Connect✅ 完整✅ 完整❌△ 透過 FE 注入 payload
Workflow Auth✅ 完整✅ 完整❌✅ 完整(含 runtime HTTP)
Backend Relay✅ 完整✅ 完整✅ 完整✅ 完整(含 runtime HTTP + BE 注入 payload)

圖例:

  • ✅ 完整開放, 你的程式碼可在此 Plane 自由執行
  • △ 部分開放, 通常僅限 design-time(設計時)或受限管道
  • ❌ 不開放, 此 Plane 不屬於你的控制範圍

從 Plane 推導衍生能力​

理解每種整合模式 (Pattern) 有開放客製的 Plane 後, 你就可以自己回答「為什麼某些功能只有某些整合模式才能做」。以下列幾個經典問題:

例 1: 為什麼 Audit Log 必須採用 Backend Relay?​

Audit Log 的本質需求: 可信賴、不可被使用者竄改的事件紀錄。

該紀錄發生在哪個 Plane?

  • 不能在 ① UI Plane(使用者看到的)
  • 不能在 ② Client Plane(使用者可改 JS、攔截網路請求)
  • 必須在 ③ Server Plane(使用者無法觸及)
  • 不適合在 ④ Agent Plane(Workflow 主要是業務邏輯位置, 且 log 能力受限)

結論: Audit Log 需要 Server Plane, 因此只有 Backend Relay(唯一開放 Server Plane 的 Pattern)才能做。

例 2: 為什麼 Memory 注入「最好」放在 Backend Relay?​

Memory 注入的本質需求: 把使用者偏好、歷史脈絡注入到 Workflow, 影響 AI 回應。

注入點選擇:

  • ② Client Plane 注入: 可行, 但 Memory 內容暴露在前端, 使用者可竄改
  • ③ Server Plane 注入: 可信, 使用者無法竄改 Memory 內容
  • ④ Agent Plane 內部組裝: 可行, 但 Workflow 內查資料庫的能力有限

結論: 理論上 Direct Connect 和 Workflow Auth 都能注入 Memory, 但內容易遭竄改。Backend Relay 提供最安全且彈性最高的注入點。

例 3: 為什麼 Hosted Embed 無法做 per-user Auth?​

per-user Auth 的本質需求: 依使用者身份決定能否使用、能用什麼功能。

需要的 Plane:

  • ② Client Plane: 取得使用者 token(瀏覽器拿 cookie / session)
  • ③ Server Plane 或 ④ Agent Plane: 驗證 token

Hosted Embed 的 Plane 狀態:

  • ① UI Plane:△(只能透過 URL 參數)
  • ② Client Plane:❌(你不能寫 JS, 使用者只看到 Asgard 托管的 UI)
  • ③ Server Plane:❌
  • ④ Agent Plane:△(無 runtime hook)

結論: Hosted Embed 連 token 都無法在客戶端取得, 自然無法做 per-user Auth, 最多只能用「pre-shared API Key 統一密碼」。

Plane 與具體技術組件的對應​

Plane主要技術組件你寫的程式碼放在哪
① UI Plane前端 SDK你的 FE 專案
② Client Plane前端 SDK你的 FE 專案
③ Server Plane後端 SDK你的後端服務專案
④ Agent PlaneWorkflowOdin Studio 上設計的 Workflow

接下來​