@baguette-studios/kernl-react

React 18 and 19 bindings for embedding Kernl agents in an existing application.

npm install @baguette-studios/kernl-react @baguette-studios/kernl-ui

import { AgentProvider } from "@baguette-studios/kernl-react";
import { AgentBubbleLauncher } from "@baguette-studios/kernl-ui";
import "@baguette-studios/kernl-ui/styles.css";

export function App() {
  return (
    <AgentProvider
      client={{
        projectId: "your-project",
        clientKey: "kernlpk_...",
        url: "https://your-kernl-endpoint.example",
        auth: {
          getSessionToken: async ({ sessionId, forceRefresh, signal }) => {
            const response = await fetch("/api/kernl/session-token", {
              method: "POST",
              credentials: "include",
              headers: { "content-type": "application/json" },
              body: JSON.stringify({ sessionId, forceRefresh }),
              signal
            });
            if (!response.ok) throw new Error("Unable to create Kernl session token");
            return (await response.json()).token;
          }
        }
      }}
      user={{ id: "current-user-id" }}
      session={{ id: "current-session-id" }}
      ui={{ launcherDraggable: true }}
    >
      <YourApplication />
      <AgentBubbleLauncher />
    </AgentProvider>
  );
}

Register context, tools, prompts, instructions, and navigation near the UI that owns those capabilities. Application tools continue to use the application's authenticated APIs and backend authorization.

For production, client.auth.getSessionToken should call your backend using the signed-in user's normal app session. The backend authenticates and authorizes that user, then signs a short-lived, session-bound JWT; signing keys must never be shipped to the browser. The underlying client caches the token in memory per session, refreshes from its JWT exp, deduplicates concurrent requests, and retries once with forceRefresh: true after a 401. Its bearer token covers message and browser tool-result appends plus event replay and transcript reads, and token values are redacted from client-visible failures.

With a configured client, AgentProvider restores the server-visible transcript by default when neither initial messages nor sessionPersistence is supplied. Use client={{ ..., restoreTranscript: false }} only when the host deliberately wants a fresh UI. Kernl server persistence remains the default source of truth.

The Kernl server verifies the JWT and is authoritative for hosted identity, tenant, budget, and restriction claims. Browser user data and metadata are not authorization inputs. Tools continue to call the app's normal APIs, and the app backend remains the final authority for permissions and side effects.

Static client.session.token remains supported for compatibility, but the token-provider form is recommended for production rotation. See the client authentication documentation for cache clearing and refresh details.

Set ui.launcherDraggable to true to let users drag the collapsed launcher around the viewport. When released, it snaps to the closest edge. The option defaults to false.

See the repository quickstart for a complete example.