JavaScript SDK (@asgard-js/core)

インストール​

npm install @asgard-js/core

中心となる概念​

基本的な使い方​

import { AsgardServiceClient, Channel, Conversation } from '@asgard-js/core';
 
const client = new AsgardServiceClient({
  botProviderEndpoint:
    'https://api.asgard-ai.com/ns/{namespace}/bot-provider/{botProviderId}',
});
 
const conversation = new Conversation({ messages: new Map() });
 
const channel = await Channel.reset({
  client,
  customChannelId: 'channel-123',
  conversation,
  statesObserver: (states) => {
    console.log('isConnecting:', states.isConnecting);
    console.log(
      'Messages:',
      Array.from(states.conversation.messages.values()),
    );
  },
});
 
await channel.sendMessage({ text: 'こんにちは！' });

AsgardServiceClient の設定​

チャネルとファイルの操作​

接続の確立以外に、AsgardServiceClient は次のメソッドを提供します。

detach と close の違いは実行中のリクエストの扱いです。close はすぐに閉じます。detach は新規受付を止め、実行中のものがなければ即座に閉じ、あれば終わるまで待ちます。ページを離れる前の後始末に向いています。

いずれも botProviderEndpoint の設定が必要です。各エンドポイントはそこから導出されるためで、未設定の場合はどのエンドポイントの導出に失敗したかを示すエラーが発生します。

メッセージへのフィードバック​

ユーザーが一つの返信を評価したら、sendMessageFeedback で送信します。

import {
  FEEDBACK_COMMENT_MAX_BYTES,
  feedbackCommentByteLength,
  composeFeedbackMessage,
} from '@asgard-js/core';
 
await client.sendMessageFeedback({
  customChannelId,
  messageId,          // 評価対象の返信の messageId
  verdict: 'BAD',     // 'GOOD' | 'BAD'
  comment: '質問した内容とは別のことに答えています',
});

返る messageId はこのフィードバック自身の id で、評価された返信のものとは異なります。あわせて transcript の seq が返り、チャネルに再参加した際にその位置で asgard.message.feedback イベントとして再生されます。

コメントの上限は 8192 文字ではなく 8 KiB​

FEEDBACK_COMMENT_MAX_BYTES は 8 * 1024 で、単位は UTF-8 のバイト数です。日本語や中国語の文字は 3 バイトを占めるため、文字数で検査するとサーバーが 400 で拒否するコメントを通してしまいます。feedbackCommentByteLength(comment) で測ってください。

if (feedbackCommentByteLength(comment) > FEEDBACK_COMMENT_MAX_BYTES) {
  // 短くするようユーザーに促す
}

フィードバックを AI にも伝える​

composeFeedbackMessage(verdict, comment?) は対話に送る後続メッセージを組み立てます。先頭はその verdict に対応する接頭辞、ユーザーがコメントを書いた場合のみ空行を挟んで原文が続きます。

composeFeedbackMessage('BAD', '質問した内容とは別のことに答えています');
// "[Response Feedback: Bad]\n\n質問した内容とは別のことに答えています"

RESPONSE_FEEDBACK_PREFIX はその 2 つの接頭辞文字列（[Response Feedback: Good] / [Response Feedback: Bad]）です。これらはバイト単位のプラットフォーム規約で、バックエンドの system prompt がこの文字列そのものを認識し、直前の返信についての差し込みとして扱います。接頭辞を書き換えないでください。

エラー処理​

@asgard-js/core は 3 つのエラークラスと、それぞれの type guard を公開しています。いずれも Error のサブクラスなので、instanceof でも guard でも判定できます。

import {
  isHttpError,
  isChannelBusyError,
  isChannelAwaitingConsentError,
} from '@asgard-js/core';
 
try {
  await channel.sendMessage({ text: input });
} catch (error) {
  if (isChannelAwaitingConsentError(error)) {
    // 先に同意プロンプトへ回答しないと、このターンは送信できません
  } else if (isChannelBusyError(error)) {
    // 前のターンが未完了。送信ボタンを無効のままにするなど
  } else if (isHttpError(error) && error.status === 429) {
    // error.body で残高切れかレート制限かを判別します
  }
}

HttpError​

status、statusText、body の 3 つの読み取り専用プロパティを持ちます。body は解析済みのエラー内容で、実務では同じステータスコードの中で原因を見分ける手掛かりになります。たとえば 429 のとき reason_code を読んで、残高切れか単なるレート制限かを区別します。

body は undefined になり得ます。レスポンスが必ず JSON を伴うとは限らず、解析の失敗は呼び出し側の誤りではなく通常の結果なので、読む前に確認してください。

ChannelBusyError​

Channel.sendMessage() は、そのチャネルで既に run が実行中のときこのエラーで reject します。runKind プロパティがどの種類の run が占有しているかを示します。

run はサーバー側でバックグラウンド実行されるため、もう一つ送ると同じ対話記録に 2 つの run が書き込むことになります。黙って破棄せず明確に拒否することで、呼び出し側はメッセージが送られていないと分かります。

SDK 内蔵の入力欄は既にこの状況を防いでいるため、実際にこのエラーが出るのはプログラムからメッセージを送る経路だけです。

ChannelAwaitingConsentError​

Channel.sendMessage() と Channel.nudge() は、チャネルがツール呼び出しの同意プロンプトで停止しているときこのエラーで reject します。サーバーはそのチャネルを一時停止状態に保ち、同意への回答だけが再開させます。それ以外のターンは nudge も含めて拒否されます。

この一時停止は「run 実行中」の判定では検出できません。同意のフレームは run の終了後に届くため、プロンプトが画面に出た時点で run は既に終わっており、チャネルはアイドルに見えます。まず Channel.replyToolCallConsents() で回答し、その後に次のターンを送ってください。

processId プロパティは停止中のバッチの process id ですが、既存チャネルへの再参加時は空文字列になります。リロード後に復元されたプロンプトはバックエンドが永続化された停止状態から再構築し、その経路では process id を意図的に空にしています。同意による停止かどうかはプロンプトの有無で判断するためです。診断の手掛かりとして扱い、キーには使わないでください。

Sandbox のファイルシステム​

Agent の実行時にマウントされる Sandbox にはファイル操作 API があり、いずれも sandboxName とパスで対象を指定します。

sandboxFsWatch は Promise ではなく RxJS の Observable を返します。購読するとそのパスの変更イベントを受け取り続けるので、不要になったら unsubscribe してください。

generateSandboxBrowserOpenUrl(sandboxName) はブラウザでその Sandbox を開く URL を生成します。

resolveSandboxUri(uri) は Sandbox URI を SandboxUriIntent に解析し、解析できない場合は null を返します。reconcileLaunched(metadata) は起動済み Sandbox の一覧を整理します。

React 側でこれらを直接呼ぶ必要はありません。createSandboxFsProviders がファイルエクスプローラーの求める形にまとめます。React SDK を参照してください。

SourceSet​

AsgardSourceSetClient は SourceSet の内容にアクセスします。関連する定数は次のとおりです。

assertVolumePath(path, options?) はパスの妥当性を検証し、不正な場合はエラーを送出します。ルートが空文字列である点は誤りやすいので、自前で比較せずこの関数を使ってください。

イベントと派生データ​

fetchSse(payload, options?) は SSE 接続を確立し、RxJS の Subscription を返します。rejoinSse(customChannelId, options?) は既存チャネルに再参加し transcript を再生します。handleEvent(response) は単一の SSE イベントを client の内部状態に取り込みます。通常は SDK 自身が呼び出します。

イベントからタスクとサブエージェントを導出するための関数です。

Headless の派生状態（タスク / サブエージェント / タイトル）​

0.3.x 以降、@asgard-js/core はフレームワーク非依存の派生状態 API も提供します。headless、Vue、Svelte などの利用者が <Chatbot> の外でタスク一覧、サブエージェント一覧、対話タイトルを描画できます。

• Channel 上のリアクティブな store: channel.tasks$、channel.subagents$、channel.channelTitle$（該当部分が変化したときだけ発行する RxJS の Observable）と、対応するスナップショット取得の getTasks() / getSubagents() / getChannelTitle()。
• conversation$ から自分で構築する: createDerivedStores(conversation$) は { tasks$, subagents$, getTasks, getSubagents, teardown } を返します。一度きりの導出には deriveTasks(conversation) / deriveSubagents(conversation) を使います。
• 履歴を消さずに既存チャネルへ参加する: Channel.restore(config, options?) はまず client.channelMetadata()（GET /channel/metadata）でチャネルの存在を確認し、存在すれば RESET_CHANNEL を送らずに client.rejoinSse() でサーバーの transcript を再生します。

Sandbox ブラウザー​

Sandbox 内で動くブラウザーは、新しいタブを開かずに自分の画面へ埋め込んで操作できます。

createSandboxBrowserSession(sandboxName) は POST {botProviderEndpoint}/sandbox/{sandbox_name}/browser/session からストリーミング用の資格情報を取得し、{ wsUrl, token } を返します。それを createSandboxBrowserTransport に渡して接続すると、画面も入力もその WebSocket を通ります。

これは既存の generateSandboxBrowserOpenUrl(sandboxName) の置き換えではなく、もう 1 つの経路です。あちらは新しいタブで開くための一度きりの URL を返し、フォールバックとして残っています。こちらは SDK がページ内で描画するためのソケットを返します。

リモートデスクトップのプロトコルはブラウザーの KeyboardEvent.key ではなく X11 keysym を使うため、core は変換ユーティリティも公開しています。

ホイールイベントは単位がブラウザーごとに違うので normalizeWheel(event) で正規化します。WHEEL_MAX は 1 回のスクロール量の上限、WHEEL_THROTTLE_MS は送信の間隔です。リモートカーソルのフレームは decodeCursorFrame でデコードします。

React SDK の SandboxBrowserPanel を使う場合、これらの低レベルユーティリティに直接触れる必要はありません。React SDK を参照してください。

インタラクティブなデモ​

@asgard-js/core の headless での使い方とイベント処理の例: SDK Demo — Headless

関連ドキュメント​

• フロントエンド SDK ガイド — 統合パターンの選択と全体の手順
• React SDK リファレンス — @asgard-js/react のコンポーネント