Pattern 2: Direct Connect

你的前端使用 SDK 直接連線到 Edge Server, 完整客製化聊天 UI, 但仍維持「無自架後端」的簡潔架構。

適用場景

這個模式適合以下情境:

• 🎨 需要客製化聊天 UI: 想完全掌控聊天視窗的外觀、訊息呈現、互動元件
• 🧩 客製化訊息渲染: 需要把某些訊息呈現成圖表、卡片、表格、或自訂 UI 元件(Custom Renderer)
• 🔌 嵌入到現有 App / Web: 已經有自己的 React / Vue / 其他前端應用, 要把聊天功能融入其中
• 💰 可接受 API Key 暴露在前端: Agent 本身是公開的, 或你已經有外部 Gateway 限制存取
• 🚀 沒有後端開發資源: 不想為了整合而額外建一個後端服務

如果你需要 per-user 身份驗證、保護 API Key、或實作稽核, 請看 Workflow Auth 或 Backend Relay。

---

架構圖

此模式下, 程式碼執行於你的前端(畫面層 + 瀏覽器層)。你能寫 UI 元件、攔截訊息事件、實作客製化邏輯。不熟悉執行層的概念? → 架構深入解析

---

能力邊界

✅ 你能做的

• 完整客製化聊天視窗外觀(Theme、字體、版型、響應式)
• 自訂訊息渲染(把訊息渲染成圖表、表格、Vega 視覺化、卡片等)
• 訊息送出前/後攔截(Pre-send / Post-send Hook)
• 客戶端 History 維持(用 localStorage 保留 customChannelId)
• 客戶端 analytics 埋點、A/B test 分群
• 從前端注入 Payload 影響 Workflow 行為

❌ 你不能做的

做不到的事	為什麼
把 API Key 藏起來	API Key 必須寫進前端程式碼, 使用者打開 DevTools 就能看到
Per-user 身份驗證 / 細粒度 ACL	伺服器層 (Server Plane) 不開放, 無法在可信端做驗證
跨裝置同步 History	只有 localStorage, 換裝置就沒了
Audit Log	客戶端 log 可被使用者竄改, 稽核需要伺服器層
從後端動態組裝 Memory 注入 Payload	沒有伺服器層

想完整理解這些限制背後的「為什麼」? → 架構深入解析

---

快速起步

步驟 1: 取得 Bot Provider 連線資訊

在 Odin Studio 上對應的 App 設定頁取得:

• Bot Provider Endpoint: 格式為 https://api.asgard-ai.com/ns/{namespace}/bot-provider/{botProviderName}
• Message API Key(若有設定 Auth)

步驟 2: 安裝 SDK

如果你用 React:

npm install @asgard-js/core @asgard-js/react

如果你用其他框架(Vue、Vanilla JS、Next.js 自訂渲染):

npm install @asgard-js/core

兩個 SDK 的選型差異請見 前端 SDK 使用指南。

步驟 3: 渲染 Chatbot 元件

最小可運行範例(React):

import { Chatbot } from '@asgard-js/react';
import '@asgard-js/react/style';
import { v4 as uuidv4 } from 'uuid';
import { useRef } from 'react';

export default function App() {
  // 簡單策略:每次掛載 Component 用一個隨機 channelId
  const channelIdRef = useRef(uuidv4());

  return (
    <Chatbot
      title="我的 AI 助理"
      config={{
        botProviderEndpoint: 'https://api.asgard-ai.com/ns/your-namespace/bot-provider/your-bot',
        apiKey: 'your-api-key',
      }}
      customChannelId={channelIdRef.current}
    />
  );
}

打開頁面就可以對話。

完整 Props 與 Method 參考:前端 SDK 使用指南 或外部 SDK Demo。

---

常用實作模式

1. Channel ID 管理策略

customChannelId 是「對話延續性」的唯一識別。不同策略對應不同產品體驗:

策略	行為	適用場景
每次掛載產生新 UUID	每次重新整理就重置對話	一次性 Demo、Stateless 客服小幫手
localStorage 保留	同瀏覽器持續同一對話(直到清快取)	個人助理、長期客服歷史
URL Query 帶入	可分享某個對話的連結(僅同 channel 才能看)	分享對話 Snapshot
Server-side 同步	跨裝置同步	需要 Backend Relay

範例: 用 localStorage 維持同一對話

const channelIdRef = useRef(
  localStorage.getItem('chat:channelId') ??
    (() => {
      const id = uuidv4();
      localStorage.setItem('chat:channelId', id);
      return id;
    })()
);

2. 訊息送出前攔截(Pre-send Hook)

利用 onBeforeSendMessage 在訊息送出前改寫:

<Chatbot
  // ...其他 props
  onBeforeSendMessage={(params) => {
    // 例如:在 payload 裡塞入頁面上下文
    return {
      ...params,
      payload: {
        ...params.payload,
        page_url: window.location.href,
        user_locale: navigator.language,
      },
    };
  }}
/>

Workflow 內可透過 prevPayload.page_url 取得這些值。

3. 監聽 SSE 事件流

<Chatbot
  // ...其他 props
  onSseMessage={(response) => {
    if (response.eventType === 'asgard.tool_call.complete') {
      // 例如:Bot 呼叫了某個工具,你可以在這裡做客戶端的 side effect
      console.log('Tool called:', response.fact);
    }
  }}
  onSseError={(error) => {
    // 集中錯誤處理
  }}
/>

4. 自訂訊息渲染(Custom Renderer)

如果預設訊息呈現方式不夠, 你可以註冊自訂 Renderer 把訊息渲染成圖表、卡片、表格等。詳見 Custom Renderer 互動範例。

---

限制與注意事項

1. API Key 等於公開於前端: 使用者打開 DevTools 就能看到, 無法隱藏。如果你的場景無法接受這點, 請回到總覽與選型重新評估。

2. History 只在當前裝置: 換瀏覽器、清快取就沒了。

3. 稽核紀錄不可信: 任何客戶端紀錄都能被使用者改, 不能當作 Audit 用途。

4. Payload 注入內容會暴露: 你從前端送出的 Payload(例如 Memory 內容)會被使用者看到、甚至能改。敏感資料不應放在前端注入的 Payload 裡。

5. CORS 設定: 你的網域必須被 Asgard Edge Server 允許跨域存取(預設多數網域已開放, 如有疑問請聯絡 Asgard)。

---

延伸閱讀

• SDK 全貌與 Props 參考:前端 SDK 使用指南
• 客製化訊息渲染:Custom Renderer 互動範例
• 想保護 API Key 但不建後端?:Pattern 3: Workflow Auth
• 想要伺服器端 History、稽核、ACL?:Pattern 4: Backend Relay
• 想理解這個模式的能力邊界本質:架構深入解析
• 更多前端 SDK 互動範例:SDK Demo