React SDK (@asgard-js/react)

@asgard-js/react は @asgard-js/core の上に、すぐ使える React 製のチャット UI とフックを提供します。React アプリケーションに Asgard のチャット機能を素早く組み込めます。

まず全体ガイドを

統合パターンの選択、詳細な設定、よくある問題は フロントエンド SDK ガイドにまとまっています。 各機能の実際に動かせる例は SDK Demo にあります。

インストール

@asgard-js/react は @asgard-js/core を peer dependency とするため、両方をインストールしてください。

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

スタイルシートの読み込み

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

この 1 行は一度だけ必要です。読み込まないとチャットボットにスタイルが当たりません。

<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 のエンドポイント URL
customChannelId	string	対話チャネルの識別子。通常はユーザー ID かセッション ID

props の一覧は Props Reference にあります。

SSR フレームワーク（Next.js）

@asgard-js/react はブラウザ API（window、SpeechRecognition、ResizeObserver など）に依存するため、サーバー側では実行できません。

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 は 4 組の context を公開しており、それぞれに Provider と対応するフックがあります。<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> を使わず自前で画面を作る場合は、次の 2 つのフックから始めます。

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 のファイルシステムを表示するためのコンポーネントとフックです。

公開 API	用途
FileExplorer / FileExplorerPanel	エクスプローラー本体とパネルのコンテナ
FileExplorerProvider / useFileExplorer	エクスプローラーの context と、それを読むフック
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 ユーティリティ

以下のフックには 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 を渡すと、開かずに対象だけ切り替えられます。

返るオブジェクトは memo 化されており、identity は状態にのみ従って変わります。パネルの接続 effect がこのオブジェクトに依存しているため、毎レンダーで新しいオブジェクトを返すと再接続が繰り返されます。

toRemoteCoords(video, clientX, clientY) はパネル上のポインター位置をリモート画面の座標に変換し、fromRemoteCoords(video, x, y) はその逆です。どちらも映像のレターボックスを考慮し、計算できない場合は値をでっち上げずに null を返します。独自のポインターオーバーレイや注釈を作るときだけ直接呼びます。

インタラクティブなデモ

各 prop と機能（メッセージテンプレート、テーマ、カスタム描画、認証、tool call など）に動かせる例があります: sdk-demo.asgard-ai.com

関連ドキュメント

• フロントエンド SDK ガイド — パターンの選択、props、よくある問題
• JavaScript SDK リファレンス — 低レベルの @asgard-js/core API