This article is auto-synced from its in-app version in Tai.

Not yet generally available. The TAI Chat SDK currently powers Nezasa's own TripBuilder integration and isn't open for general use yet. This reference is published for Nezasa and TripBuilder developers; the public surface may still change before general availability.

The TAI Chat SDK is a reusable, embeddable chat experience backed by TAI's Streaming API — the same chat the Admin Console's TAI Terminal uses (SSE streaming, session management, thinking / tool-step display, markdown and mermaid / draw.io rendering, file upload, export). It ships in two delivery forms from one codebase:

The Web Component wraps the React package in native custom elements (React, ReactDOM, and TanStack Query are bundled in), so the two share behaviour, config, theming, and localization. This page documents both: shared concepts once, then a per-form reference for the parts that differ.

Related documents:

Your host app supplies the bearer token the SDK sends; the SDK never issues or stores credentials. The SDK talks to TAI's Streaming API; you don't call it directly when embedding.

Both packages publish to GitHub Packages under the @nezasa scope. Point the scope at the GitHub registry in your project's .npmrc (or ~/.npmrc):

Then install the form you need:

React Query is a peer dep on purpose: most hosts already use it, so a shared QueryClient avoids duplicate caches. Axios, marked, DOMPurify, highlight.js, mermaid, vega / vega-lite (polished data charts), and Lucide are bundled — you don't install them.

npm install 401s on @nezasa packages until you create a Personal Access Token that is (a) scoped to read packages and (b) SSO-authorized for the nezasa org. The token alone works on personal projects but fails on org-scoped packages with a 401 that looks like the package doesn't exist.

The React package's main entry is ~115 KB gzipped; mermaid, vega / vega-lite (the heaviest — ~270 KB gzipped, fetched only when a message renders a polished chart), highlight.js, and @tanstack/react-table are lazy-loaded on first use, so plain-text conversations don't pay for them. CI enforces a 150 KB gzipped budget on the main entry. The Web Component bundle is larger because React + ReactDOM + TanStack Query ship inside; its gzipped ceiling is also CI-enforced, and the same deps stay lazy. Lazy-load the element module (await import("@nezasa/tai-chat-element")) if you want it off the critical path.

Polished charts render without unsafe-eval: the Vega runtime is evaluated through an AST interpreter, not the Function constructor, so a strict host Content-Security-Policy (script-src with no unsafe-eval) doesn't need loosening for charts to work.

Both packages publish on three dist-tags:

npm v7+ note: snapshot versions are semver prereleases, so they don't satisfy plain caret ranges — install by exact version or dist-tag, and don't commit the lockfile change downstream unless you intend to ship that snapshot.

Every snapshot runs the full build-and-verify pipeline (bundle-size budget, API-surface snapshot, test suite, a pack-install-and-mount smoke test) before publish, so regressions are caught before they reach a dist-tag.

The SDK follows semver. Bump levels:

A provider plus the chat component:

The SDK is stateless about auth and routing — your app owns the bearer token (the SDK reads config.authToken on every request; pass a fresh value when you rotate), handles onAuthError (the SDK calls it on a 401 — refresh, redirect, or show an error), and mounts the provider at the right level. Before mounting: create an agent (Agents), ensure the principal behind the token can run that agent (Agent access), and configure CORS if you embed cross-origin.

The custom elements (<tai-chat>, <tai-chat-drawer>, <tai-chat-widget>) self-register the moment the bundle is parsed. The only host-specific question is how the bundle reaches the browser.

Bundler hosts (Ember ≥ 3.13, Vue, Webpack, Vite, …) — import the package once from your app entry; the elements self-register and the tags work in every template:

For Vue 3, tell the compiler the tag is a custom element so it doesn't strip attributes: isCustomElement: (tag) => tag.startsWith("tai-chat") in the @vitejs/plugin-vue options.

Raw HTML / AngularJS / no bundler — npm install, copy the single bundled ESM file into your public assets, and reference it with a module script (most production servers don't expose node_modules/ to the browser):

Legacy Ember 2.18. Auto-import 1.x can't resolve modern ESM packages. Skip it: pull dist/tai-chat-element.js into assets/ with a broccoli-funnel in ember-cli-build.js, reference it as a <script type="module"> in app/index.html, and use the tag in any .hbs (the dash tells the template compiler it's a custom element). Set function callbacks and array-valued agent as JS properties in a didInsertElement hook — see JS properties.

Three surfaces, same conversation engine:

The React modes render inside your app's React tree (portal modes included), so context, theme, and the React Query cache work transparently — no iframe. The element modes render inside an open shadow root per instance.

Live showroom: Inline, Drawer, and Widget rendered side-by-side, with a prop-toggle panel and copy-ready snippets, at Docs → SDKs → Showroom in the Workbench.

Inline fills its parent's height — give it an ancestor with an explicit height (h-screen, h-[600px], a flex parent with flex-1).

Drawer is host-controlled open/closed:

Widget is a self-managed FAB + popup:

The two forms expose the same options under their native idioms: React props / provider config, or HTML attributes / JS properties. r2wc maps a camelCase prop to a kebab-case attribute automatically (apiBaseUrl → api-base-url).

<TaiChatProvider> — supplies config, theme, and an internal React Query client; must wrap every <TaiChat* />.

<TaiChat> (inline):

agent has three modes: fixed (agent="id" — no selector, opens against that agent), allow-list (agent={["a","b"]} — selector limited to those), all (omit — selector lists every accessible agent). A fixed or allow-list id is the agent's UUID, shown as a copyable value on the agent's page in the Workbench. Built-in agents also have a Reference — a stable nezasa/… name you can use in place of the UUID.

<TaiChatDrawer> extends all <TaiChat> props, adds:

Defaults sessionsLayout to "accordion".

<TaiChatWidget> extends all <TaiChat> props, adds:

Defaults sessionsLayout to "hidden".

All elements take the shared config + display attributes; drawer and widget add their own. Boolean attributes follow HTML convention — presence is truthy (show-sessions or show-sessions=""), absence is falsy.

<tai-chat-drawer> adds: open (boolean), width (string), show-backdrop (boolean). <tai-chat-widget> adds: position, label, width, height, offset-bottom (all strings).

JS properties (HTML attributes are strings, so callbacks, arrays, and objects are set on the element instance):

r2wc re-renders the inner React tree whenever a property or attribute changes, so every property is reactive. Property-only props: onAuthError, onClose, onSessionChange, onAgentChange, onRequestExpand, onRequestCollapse, onLinkClick, agent (array form), context, initSuggestions, strings. @nezasa/tai-chat-element augments HTMLElementTagNameMap, so document.querySelector("tai-chat-drawer") returns a typed element with autocomplete on these properties.

Three layouts trade real-estate for discoverability:

Legacy showSessions={true} / show-sessions maps to "sidebar"; false maps to "hidden".

sendButtonPosition (send-button-position) controls which side of the message textarea the send (and stop, while streaming) button sits on:

The widget FAB sits 24px from the bottom-right corner by default, which can collide with another fixed corner element (a support launcher, a cookie banner). Raise offsetBottom (offset-bottom) — any CSS length — to stack the FAB and its popup above it:

Every surface accepts sessionId / session-id plus an onSessionChange callback. Together they let a host move a running conversation between surfaces — typically a drawer in your app shell and a full-page route — without re-creating the session, refetching messages, or losing the agent's context. The host owns the value; the SDK never decides where the conversation lives.

onSessionChange fires on SDK-driven transitions: auto-create, the user picking a session, or deletion of the active session (with null). It does not fire when the host writes session-id itself. If session-id references a session whose agent doesn't match agent, the SDK surfaces a visible error rather than swapping agents silently — omit agent to let the SDK derive it from the session.

Seed once vs. control. sessionId / session-id is controlled — the host owns the id for the surface's lifetime, so in-SDK switching only sticks if the host writes the new id back. To resume one conversation at mount and then let the surface own switching, use defaultSessionId / default-session-id: read once at mount, ignored while the controlled id is set, never echoed through onSessionChange. In free-agent mode it loads history but leaves the agent header blank; pass agent when you also need the agent strip to resolve.

onAgentChange (onAgentChange?: (agentId: string | null) => void) mirrors onSessionChange for the active agent — it fires when the user picks an agent from the picker / switcher (the agent's UUID) or clears back to the picker (null). Combine the two to keep ?agent= and ?session= in the URL so the surface survives a refresh. Clear ?session= whenever the agent changes — session IDs are agent-scoped, so a stale one triggers a mismatch error on reload.

React — drive both from your router state:

Web Component — set the callbacks as JS properties:

On load, read the params and pass them in once — set agent only at mount:

Capture agent once at mount. Don't re-assign agent when onAgentChange later writes ?agent= to the URL — passing a string agent back in switches the surface into fixed-agent mode and hides the picker / switcher for the rest of the session. Read it from the URL at mount only.

The SDK draws a "switch surface" icon inside the chat chrome; the host opts in by setting a callback and owns where to navigate (the SDK doesn't unmount, close a drawer, or touch routing). The icon shows only when its callback is set.

onRequestCollapse exists only on the inline surface — it makes no sense from a surface that's already a side panel. Pair handoff with sessionId so the target surface resumes the same chat (history and any in-flight stream both carry over — streams are shared per session across all surfaces under one provider).

Links in an agent answer open in a new tab. That's the right default for a chat the user must not lose — following a link in place would navigate the host page away and take the conversation with it.

It's the wrong default in one case: a chat embedded in the very app its links point at. A Customer Care drawer sitting inside cockpit, answering with cockpit deep links, opens a second copy of an app the user is already running — and triaging three bookings leaves three tabs behind.

onLinkClick lets you claim the click instead. Return true and the SDK suppresses its own navigation; return anything else (or nothing) and the link behaves normally.

Worth knowing:

Tell the agent what the user is looking at. Pass a ChatContext envelope — via the context prop (React) or the context JS property (element) — and the SDK forwards it to the backend on session creation; the agent receives it as a ## Page context block in its system prompt.

description is the one-line prose framing an LLM benefits from — only the host can write it well. context is object-only (nested objects don't round-trip through HTML attributes). Locked at session creation: changing it on a live session has no effect — start a new session (clear session-id) to apply new context.

Override the selected agent's greeting and starter chips, or leave them unset to use the agent's defaults:

initSuggestions is property-only because arrays can't survive HTML attribute serialisation. Clicking a chip uses the same handler as Enter-to-send.

The execution engine (harness) is chosen per session. Use showHarnessSwitch / show-harness-switch to let the user pick from the agent's supported engines, or harness to pre-select one. Only engines in the agent's available_harnesses are offered. The chosen harness is locked for the session's lifetime — switching it after a session starts has no effect.

The SDK ships English plus built-in packs and resolves missing keys to English, so a partial override is always a safe drop-in. Per-UI strings are controlled client-side (below); per-agent content (welcome_message, init_suggestions) is localized server-side from the request's Accept-Language — see What's not in strings.

React — pass a pack (or a Partial<TaiChatStrings>) to the provider's strings prop. Hoist the value to a module constant (or useMemo keyed on host state): the provider memoises its context on the strings reference, so an inline literal re-renders every consumer on each keystroke.

Web Component — declarative language="de" picks a built-in pack with no script; the strings property overrides individual keys (and wins per-key over language). Unknown language codes warn and fall back to English.

Switching at runtime. Mirror your host's language (URL locale, profile, i18next, …) into strings and the chat re-renders in place — no remount, no session loss. Pre-import the packs into a lookup keyed by code with an en fallback, and reassign on change. Built-in packs (en, de, fr, pt, it, es, nl, fi, sv, no, da, pl, cs, tr) have stable module identity; inline literals don't.

Custom packs — type your pack against TaiChatStrings (TypeScript enforces full coverage) or Partial<TaiChatStrings> to fill in incrementally. Keys with interpolated values (counts, dates) are functions so you control plural rules and word order without a template parser — e.g. showMore: (n) => string, messageCount: (n) => string, sessionTimeToday: (date) => string. The TaiChatStrings type ships with the package — import it for the full ~80-key list with editor autocomplete and full type-checking.

Date strings caveat. sessionTimeToday / sessionTimeWeek / sessionTimeOlder use date-fns's English weekday/month names across every shipped pack (intentional). Override those three function-valued keys with your own formatter if you need locale-aware date text.

Per-agent content — welcome_message and init_suggestions — is localized server-side, not via strings. The backend reads the request's Accept-Language (browsers send it automatically), picks the best match from the agent's per-locale map, and serves the flat fields the SDK already consumes. Hosts in a non-browser runtime (or integration tests) can force a locale with ?locale=de on agent API calls; unsupported codes fall back to en. See Agents for how per-agent content is configured.

The SDK's CSS is scoped under the [data-tai-chat] attribute the root writes on its own container, so host styles don't bleed into the chat and vice versa. Theme via the theme prop (React) or by targeting the CSS variables directly.

Important: color values are space-separated HSL triplets ("221 83% 53%"), not hex or rgb(). The SDK composes colors with opacity via hsl(var(--primary) / 0.4), which needs the raw triplet — hex silently breaks theming.

Raw-CSS equivalent: [data-tai-chat] { --primary: 221 83% 53%; --radius: 0.75rem; }.

Dark mode is picked up from prefers-color-scheme. Force it with theme={{ colorScheme: "dark" }} (writes data-tai-chat-theme="dark", overriding the OS) — this matters for Mermaid diagrams and Vega charts alike, whose palette is baked into the SVG from the resolved colorScheme.

Web Component theming. Each element renders in an open shadow root, so host resets (button { margin: 0 }, * { box-sizing }) can't collide with the SDK's utilities. The compiled CSS is parsed once into a shared CSSStyleSheet adopted via adoptedStyleSheets (nothing is appended to document.head). CSS custom properties inherit through shadow roots, so the theme tokens still cross the boundary — set them at a scope covering the element (e.g. :root), or pass theme to override.

To render custom UI alongside chat (a dashboard tile, a "recent conversations" list), the React package exports its React Query hooks — all using the provider's QueryClient:

Exported: useRecentSessions, useChatSessions(agentId), useChatSession(sessionId), useChatMessages(sessionId), useCreateSession, useDeleteSession, useRenameSession, useStarSession, useUnstarSession, useStarredSessions.

npm install fails with 401 Unauthorized. Most common cause: the PAT isn't SSO-authorized for nezasa. Open the token at https://github.com/settings/tokens → Configure SSO → Authorize next to nezasa, and re-run. Other causes: missing read:packages, expired token, $NPM_TOKEN not set in the shell. See GitHub PAT + SSO authorization.

The chat renders blank / unstyled (React). You likely forgot import "@nezasa/tai-chat/style.css" once in your app, or your bundler isn't honoring the SDK's "sideEffects" entry.

Tailwind classes like max-w-3xl do nothing (React, Tailwind 4). Tailwind's auto-content detector skips node_modules — add @source "../../node_modules/@nezasa/tai-chat/dist/**/*.js"; to your Tailwind entry.

401 loops. onAuthError should refresh the token and let the SDK retry on the next user action — don't remount <TaiChat> on every error.

Session doesn't persist across reloads. Sessions are server-side; the SDK picks the most recent on mount. To re-open a specific one, pass its id down via sessionId / session-id.

The SDK follows semantic versioning. Pin a caret range ("^1.0.0") for safe patch + minor updates; read the changelog before a major. Only the documented components, props, attributes, hooks, and CSS variables are public — don't rely on internal exports or the shape of dist/.

For questions, bug reports, or feature requests about the SDK, contact your Nezasa representative.