React SDK (`@asgard-js/react`)

@asgard-js/react 在 @asgard-js/core 之上提供現成的 React 聊天室 UI 元件與 hooks，讓 React 應用程式能快速整合 Asgard 聊天功能。

建議先看完整指南

模式選型、進階設定、常見問題等完整說明在前端 SDK 使用指南，每個功能都有可實際操作的範例在 SDK Demo。

安裝

@asgard-js/react 以 @asgard-js/core 為 peer dependency，請同時安裝：

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

CSS 樣式引入

import "@asgard-js/react/style";

這一行只需執行一次，否則 chatbot 會沒有樣式。

`<Chatbot>` 元件

import { Chatbot } from "@asgard-js/react";
import "@asgard-js/react/style";

export default function App() {
  return (
    <div style={{ height: "100vh" }}>
      <Chatbot
        title="我的 AI 助理"
        customChannelId="user-123"
        config={{
          botProviderEndpoint:
            "https://api.asgard-ai.com/ns/{namespace}/bot-provider/{botProviderId}",
        }}
      />
    </div>
  );
}

必填 Props

Prop	型別	說明
`config.botProviderEndpoint`	`string`	Bot Provider 的 endpoint URL
`customChannelId`	`string`	對話頻道識別 ID，通常用 user id 或 session id

完整 props 清單見 Props Reference。

SSR 框架（Next.js）

@asgard-js/react 依賴瀏覽器 API（window、SpeechRecognition、ResizeObserver 等），不能在 server 端執行。

Next.js App Router

"use client";

import dynamic from "next/dynamic";
import "@asgard-js/react/style";

const Chatbot = dynamic(
  () => import("@asgard-js/react").then((m) => m.Chatbot),
  { ssr: false },
);

export default function ChatPage() {
  return (
    <div style={{ height: "100vh" }}>
      <Chatbot
        title="我的 AI 助理"
        customChannelId="user-123"
        config={{
          botProviderEndpoint:
            "https://api.asgard-ai.com/ns/{namespace}/bot-provider/{botProviderId}",
        }}
      />
    </div>
  );
}

Next.js Pages Router

import dynamic from "next/dynamic";

const Chatbot = dynamic(
  () => import("@asgard-js/react").then((m) => m.Chatbot),
  { ssr: false },
);

Docusaurus / Gatsby

import BrowserOnly from "@docusaurus/BrowserOnly";

export default function MyPage() {
  return (
    <BrowserOnly>
      {() => {
        const { Chatbot } = require("@asgard-js/react");
        require("@asgard-js/react/style");
        return (
          <Chatbot
            title="..."
            customChannelId="..."
            config={{ botProviderEndpoint: "..." }}
          />
        );
      }}
    </BrowserOnly>
  );
}

自訂 UI（useAsgardContext）

在 renderHeader、renderFooter 等自訂渲染 props 中，可用 useAsgardContext 存取對話狀態：

import { useAsgardContext } from "@asgard-js/react";

function CustomHeader() {
  const { resetChannel, isConnecting } = useAsgardContext();
  return (
    <div>
      <span>My Bot</span>
      <button onClick={resetChannel} disabled={isConnecting}>
        重置對話
      </button>
    </div>
  );
}

Context 與 Provider

@asgard-js/react 匯出四組 context，每組都有 Provider 與對應的 hook。<Chatbot> 內部已經把它們接好，自行組裝 UI 時才需要直接使用。

Context	Provider	Hook	提供什麼
`AsgardServiceContext`	`AsgardServiceContextProvider`	`useAsgardContext`	對話狀態與操作（`resetChannel`、`isConnecting` 等）
`AsgardThemeContext`	`AsgardThemeContextProvider`	`useAsgardThemeContext`	主題設定，預設值為 `defaultAsgardThemeContextValue`
`AsgardTemplateContext`	`AsgardTemplateContextProvider`	`useAsgardTemplateContext`	訊息模板的渲染設定
`AsgardAppInitializationContext`	`AsgardAppInitializationContextProvider`	`useAsgardAppInitializationContext`	應用初始化狀態

另外 FileDropContextProvider 與 useFileDropContext 處理拖放檔案。

ThemeScope 把主題套用在一段子樹上，DEFAULT_CONTENT_MAX_WIDTH 是內容區的預設最大寬度。

Headless 整合

不使用 <Chatbot> 而要自己畫介面時，用這兩個 hook：

import { useAsgardServiceClient, useChannel } from '@asgard-js/react';

const client = useAsgardServiceClient({
  config: { botProviderEndpoint, apiKey },
  keepConnectionOnUnmount: false,
});

const channel = useChannel({ client, customChannelId, initMessages });

useAsgardServiceClient 建立並管理 AsgardServiceClient 的生命週期，回傳 AsgardServiceClient | null。keepConnectionOnUnmount 決定元件卸載時是否保留連線。

useChannel 接收 UseChannelProps（client、customChannelId、initMessages、autoResetChannel、onSseMessage、onAuthError 等），回傳 UseChannelReturn。

檔案總管與 Sandbox

用於顯示 Sandbox 檔案系統的元件與 hook：

匯出	用途
`FileExplorer` / `FileExplorerPanel`	檔案總管本體與面板容器
`FileExplorerProvider` / `useFileExplorer`	檔案總管的 context 與讀取 hook
`useFileExplorerController`	建立檔案總管的控制器，接 `UseFileExplorerControllerOptions`
`FileView`	單一檔案的檢視元件
`createSandboxFsProviders`	把 `AsgardServiceClient` 的 `sandboxFs*` 方法包成檔案總管要的 provider 組
`useSandboxLaunch` / `useLaunchedSandboxes`	啟動 Sandbox、讀取已啟動的清單
`sandboxAsSource` / `sandboxesAsSources`	把 Sandbox 轉成檔案總管的來源
`SourceSetFileExplorer`	SourceSet 的檔案總管，搭配 `@asgard-js/core` 的 `AsgardSourceSetClient`

EMPTY_SOURCE_VIEW 是沒有來源時的空狀態值。

其他元件

ChatHeader 是對話標題列，可用 ChatHeaderAction 加上動作按鈕。TaskList 與 SubagentList 顯示任務與子代理，資料來自 @asgard-js/core 的衍生狀態。

通用 React 工具

以下 hook 沒有 Asgard 專屬語意，是套件內部使用時一併匯出的通用工具，可以直接用，但它們不是整合介面的一部分：useDebounce、useDeepCompareMemo、useResizeObserver、useVisualViewport、useIsAtBottom、useSyncedSpin、usePromptSuggestion。

t 是 i18n 的翻譯函式，Locale 是語系型別。

Sandbox 瀏覽器面板

SandboxBrowserPanel 把 Sandbox 的瀏覽器畫面渲染在你的版面裡，連線、輸入轉送、游標都由它處理。

useSandboxBrowserController({ open?, activeSandboxName? }) 管理它的開關與目標 Sandbox，回傳 open、activeSandboxName、requestedBrowser，以及 openBrowser()、closeBrowser()、toggle()、selectSandbox(name)、requestBrowser(name, { reveal }) 這些動作。requestBrowser 預設會順手把面板打開，傳 reveal: false 可以只切換目標而不展開。

回傳的物件用 useMemo 包過，identity 只隨狀態改變 —— 面板的連線 effect 依賴它，每次 render 都換一個新物件會導致不斷重連。

toRemoteCoords(video, clientX, clientY) 把滑鼠在面板上的座標換算成遠端畫面的座標，fromRemoteCoords(video, x, y) 是反向。兩者都會處理影片的 letterbox 留白，算不出來時回傳 null 而不是硬給一個值。自己做指標疊層或標註時才需要直接呼叫。

互動式 Demo

每個 prop 與功能（訊息模板、主題、客製渲染、認證、tool call 等）都有可操作的範例：sdk-demo.asgard-ai.com

安裝​

CSS 樣式引入​

<Chatbot> 元件​

必填 Props​

SSR 框架（Next.js）​

Next.js App Router​

Next.js Pages Router​

Docusaurus / Gatsby​

自訂 UI（useAsgardContext）​

Context 與 Provider​

Headless 整合​

檔案總管與 Sandbox​

其他元件​

通用 React 工具​

Sandbox 瀏覽器面板​

互動式 Demo​

延伸閱讀​

安裝