JavaScript SDK (@asgard-js/core)

@asgard-js/core 是框架無關的 JavaScript SDK，處理 SSE 串流連線、Channel 管理與 Conversation 狀態。適用於 Node.js、瀏覽器，以及不使用 @asgard-js/react 元件的場景（Headless、Vue、Svelte 等）。

使用 React？

若你用 React，通常不需要直接使用 @asgard-js/core。改用 @asgard-js/react 的 <Chatbot> 元件即可，詳見 React SDK 參考文件。

安裝

npm install @asgard-js/core

核心概念

類別	說明
AsgardServiceClient	連線設定（botProviderEndpoint、apiKey、customHeaders）
Channel	一個對話頻道，透過 SSE 與 Bot Provider 通訊
Conversation	儲存訊息狀態的容器

基本使用

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 設定

參數	型別	必填	說明
botProviderEndpoint	string	是	Bot Provider 的 base URL
apiKey	string	否	API 金鑰（Direct Connect 模式）
customHeaders	Record<string, string>	否	自訂 HTTP header

Headless 衍生狀態（Task / Subagent / 標題）

0.3.x 起，@asgard-js/core 額外提供一組框架無關的衍生狀態 API，讓 Headless / Vue / Svelte 等消費端能在 <Chatbot> 之外自行渲染任務清單、子代理清單與對話標題：

• Channel 上的響應式 store：channel.tasks$、channel.subagents$、channel.channelTitle$（RxJS Observable，只在該切片變動時發射），以及對應的快照 getter getTasks() / getSubagents() / getChannelTitle()。
• 從 conversation$ 自行建立：createDerivedStores(conversation$) 回傳 { tasks$, subagents$, getTasks, getSubagents, teardown }；或用 deriveTasks(conversation) / deriveSubagents(conversation) 做一次性推導。
• 加入既有 channel（不清空歷史）：Channel.restore(config, options?) 會先透過 client.channelMetadata()（GET /channel/metadata）判斷 channel 是否存在，存在則重播 server transcript（client.rejoinSse()）而非送出 RESET_CHANNEL。

React 消費端

使用 React 時，直接用 @asgard-js/react 的 useTaskList / useSubagents / useChannelTitle hooks，它們已把上述 store 橋接進 useSyncExternalStore。

互動式 Demo

@asgard-js/core 的 Headless 用法與事件處理範例：SDK Demo — Headless

延伸閱讀

• 前端 SDK 使用指南 — 模式選型與完整整合說明
• React SDK 參考文件 — @asgard-js/react 元件說明