REFERENCE

開發者參考

認證、API、SDK、Flow Agent 處理節點與參數取值的完整參考。

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

@asgard-js/react React SDK 參考文件

@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 範例
延伸閱讀
- 前端 SDK 使用指南 — 完整模式選型、props、常見問題
- JavaScript SDK 參考文件 — @asgard-js/core 底層 API

準備好開始了嗎？

想知道 Asgard 怎麼用在你的團隊？跟我們聊聊。

聯絡我們

安裝​

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​

延伸閱讀​

準備好開始了嗎？

安裝

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

延伸閱讀