Quickstart
Sign a user token on your server, wrap your app in BaseeraProvider, and render the chat surface.
This quickstart uses Next.js (App Router). It takes four steps: sign a token on the server, wrap your app, define one tool, and render the surface. The same steps work in Vite.
You need an agent in the Baseera console with its publishable key, secret key and runtime URL, and your app's domain in the agent's allowed domains. See Installation for the packages.
Set environment variables
# Browser: safe to expose.
NEXT_PUBLIC_BASEERA_KEY=pk_your_publishable_key
NEXT_PUBLIC_BASEERA_URL=https://runtime.example.com
# Server only: never prefix with NEXT_PUBLIC_.
BASEERA_SECRET_KEY=sk_your_secret_keySign a token on your server
The token tells Baseera which user is in the session. Your server signs it with the secret key, after it has checked who is signed in.
import { signUserToken } from "@baseera/node";
export const dynamic = "force-dynamic";
export async function POST(request: Request) {
const user = await getCurrentUser(request); // your own session check
if (!user) return Response.json({ error: "unauthorized" }, { status: 401 });
const token = await signUserToken(
{ userId: user.id, tenantId: user.orgId, name: user.name, locale: "ar" },
process.env.BASEERA_SECRET_KEY!,
);
return Response.json({ token }, { headers: { "cache-control": "no-store" } });
}getCurrentUser stands for your own authentication. The token lasts 15 minutes by default.
Wrap your app
BaseeraProvider is a client component. Put it in its own file and import it from your layout.
"use client";
import "@baseera/ui/baseera.css";
import { BaseeraProvider } from "@baseera/react";
import { BaseeraSurface } from "@baseera/ui/connected";
import type { ReactNode } from "react";
async function getUserToken(): Promise<string> {
const res = await fetch("/api/baseera-token", { method: "POST" });
if (!res.ok) throw new Error("Could not get a Baseera token");
return ((await res.json()) as { token: string }).token;
}
export function Providers({ children }: { children: ReactNode }) {
return (
<BaseeraProvider
publishableKey={process.env.NEXT_PUBLIC_BASEERA_KEY!}
baseUrl={process.env.NEXT_PUBLIC_BASEERA_URL!}
getUserToken={getUserToken}
theme="system"
>
{children}
<BaseeraSurface locale="ar" />
</BaseeraProvider>
);
}import type { ReactNode } from "react";
import { Providers } from "./providers";
export default function RootLayout({ children }: { children: ReactNode }) {
return (
<html lang="ar" dir="rtl">
<body>
<Providers>{children}</Providers>
</body>
</html>
);
}BaseeraSurface draws a launcher in the corner of the page. Selecting it opens the chat panel.
Give the assistant a tool
A tool is a function in your app that the assistant can call. A read tool runs at once. A draft or write tool waits for the user to approve.
"use client";
import { useBaseeraTool } from "@baseera/react";
import { z } from "zod";
const getInvoiceInput = z.object({ number: z.string().describe("Invoice number, for example INV-1042") });
export function InvoiceTools() {
useBaseeraTool({
name: "getInvoice",
description: "Get an invoice by its number",
kind: "read",
input: getInvoiceInput,
run: ({ number }) => fetch(`/api/invoices/${encodeURIComponent(number)}`).then((r) => r.json()),
});
return null;
}Render <InvoiceTools /> inside Providers, next to BaseeraSurface. The tool is registered while the component is mounted.
Check it works
Start your app, open a page, and open the surface. Ask a question your agent's knowledge answers. You should see the reply stream in, with sources under it when the agent cited documents.
An agent in dev mode can run without a user token, but only from localhost. In production getUserToken is required, and the runtime refuses a request from a domain that is not in the agent's allowed domains.