React SDK (@asgard-js/react)

インストール​

@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​

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 を自前で組む場合にだけ直接使います。

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

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 デモ

関連ドキュメント​

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