Quickstart
Go from a new account to an embedded assistant that asks for approval before it changes anything.
In about ten minutes you will add Baseera to a Next.js app, give the agent two tools, and watch it ask for approval before it changes data:
getInvoiceis a read tool. It runs straight away.markInvoicePaidis a write tool. It waits until the user presses Approve.
The finished app is examples/quickstart-next in the repository. Every code block below is a file of that app, and CI builds it and checks it against these steps.
You need a Next.js 15 App Router app (or start one with npx create-next-app@latest), Node 22 or newer, and an API key from a model provider: Anthropic, OpenAI, Google or OpenRouter.
The SDK is not on npm yet
The packages are MIT licensed and ready to publish, but the first release has not happened. Until it does, put your app inside the repository workspace (as examples/quickstart-next does, with "@baseera/react": "workspace:*" and the same for the other three packages), or run the finished example as it is. The pnpm add command in step 4 works once they are published.
Build it
1. Create an account and add your model key
Open the dashboard at baseera.dev, create an account at /auth/signup (or sign in at /auth/login), and confirm your email. If this is your first sign-in you are asked to name your organization. Everything you create belongs to it.
Open Provider keys, press Add a provider key, choose the provider, paste the key into API key and press Check and save. Baseera checks the key with the provider, stores it encrypted and never shows it again.
2. Create an agent
Open All agents, press Create agent, and give it a name such as "Invoices assistant". Choose the provider key you just added and a model, then press Create agent.
Creating an agent publishes version 1 for you, so you can chat with it straight away. Later edits go to a draft until you publish them. Without a key and a model, the agent answers with an "agent not configured" error instead of a reply.
3. Get your keys
Open the agent, then Deploy. The page is called Deploy & access.
- Under Allowed domains, add
localhost:3300and press Save domains. Only these domains can start a session. Add your real domain before you go live. - Under Publishable keys, press Create publishable key and copy it (
pk_...). It is safe in the browser and only works from the allowed domains. - Under Secret keys, press Create secret key. Copy it now, because it is shown only once, then press I have saved it. The secret key (
sk_...) belongs on your server only.
4. Install the SDK and set the environment
pnpm add @baseera/core @baseera/react @baseera/node @baseera/ui zod lucide-reactOnly the publishable key may start with NEXT_PUBLIC_:
NEXT_PUBLIC_BASEERA_KEY=pk_xxx
BASEERA_SECRET_KEY=sk_xxx
NEXT_PUBLIC_BASEERA_URL=http://localhost:3100NEXT_PUBLIC_BASEERA_URL is the runtime's address. There is no hosted runtime yet, so use the one you run from the repository: pnpm --filter @baseera/runtime dev (port 3100).
5. Add the provider and the chat surface
BaseeraProvider connects your app to the agent. BaseeraSurface from @baseera/ui/connected is the launcher and chat panel, and it draws the approval cards. Both are client components, so put them in a client file and use it from your server layout.
"use client";
import "@baseera/ui/baseera.css";
import { BaseeraProvider } from "@baseera/react";
import { BaseeraSurface } from "@baseera/ui/connected";
import type { ReactNode } from "react";
import { InvoiceTools } from "@/components/invoice-tools";
import { LANG } from "@/lib/lang";
/** Asks your own server for a user token. The secret key never reaches the browser. */
async function getUserToken(): Promise<string> {
const res = await fetch("/api/baseera/token", { method: "POST" });
if (!res.ok) throw new Error(`The token route answered ${res.status}.`);
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}
>
<InvoiceTools />
{children}
<BaseeraSurface locale={LANG} />
</BaseeraProvider>
);
}/** "ar" gives right-to-left pages and Arabic approval cards; "en" gives English ones. */
export const LANG: "ar" | "en" = "ar";Render <Providers> around {children} in src/app/layout.tsx, and set lang and dir on <html> from LANG.
6. Sign the user token on your server
The browser must prove who the user is. Your server signs a short-lived token (15 minutes by default) with the secret key, and BaseeraProvider asks for a new one before it expires.
import { signUserToken } from "@baseera/node";
export const dynamic = "force-dynamic";
const NO_STORE = { "cache-control": "no-store" } as const;
export async function POST(request: Request): Promise<Response> {
// Only a same-origin POST is accepted, so another site cannot ask a visitor's browser for a token.
const origin = request.headers.get("origin");
const host = request.headers.get("host");
if (!origin || !host || new URL(origin).host !== host) {
return Response.json({ error: "Cross-origin requests are not allowed." }, { status: 403, headers: NO_STORE });
}
const secretKey = process.env.BASEERA_SECRET_KEY;
if (!secretKey) {
return Response.json({ error: "BASEERA_SECRET_KEY is not set." }, { status: 500, headers: NO_STORE });
}
// Replace this with your own session: the signed-in user and the customer (tenant) they belong to.
const user = { id: "user-1", name: "Layla", organizationId: "org-1" };
const token = await signUserToken(
{ userId: user.id, tenantId: user.organizationId, name: user.name, locale: "ar" },
secretKey,
);
return Response.json({ token }, { headers: NO_STORE });
}7. Register a read tool and a write tool
Tools live in your app and call your app's own API, so the agent can only do what your code allows. useBaseeraTool registers a tool while its component is mounted.
"use client";
import { useBaseeraTool } from "@baseera/react";
import { isolate } from "@baseera/ui";
import { useRouter } from "next/navigation";
import { z } from "zod";
import { LANG } from "@/lib/lang";
// Define schemas outside the component so they keep their identity between renders.
const invoiceId = z.string().regex(/^INV-\d{1,10}$/).describe("Invoice number, for example INV-1042");
const getInvoiceInput = z.object({ id: invoiceId });
const markPaidInput = z.object({ id: invoiceId, paidOn: z.iso.date().optional().describe("YYYY-MM-DD, default today") });
/** Calls your own API, like any code in your app would. */
async function api(path: string, init?: RequestInit): Promise<unknown> {
const res = await fetch(path, { ...init, headers: { "content-type": "application/json" } });
const body = (await res.json().catch(() => ({}))) as { error?: { message?: string } };
if (!res.ok) throw new Error(body.error?.message ?? `The API answered ${res.status}.`);
return body;
}
export function InvoiceTools() {
const router = useRouter();
const ar = LANG === "ar";
// A read tool runs at once. The user is not asked.
useBaseeraTool({
name: "getInvoice",
description: "Get an invoice by its number: customer, total, currency and status.",
kind: "read",
input: getInvoiceInput,
run: ({ id }) => api(`/api/invoices/${encodeURIComponent(id)}`),
});
// A write tool waits for approval. `describe` is the sentence the approval card shows.
useBaseeraTool({
name: "markInvoicePaid",
description: "Mark an unpaid invoice as paid, on the given date (default today).",
kind: "write",
input: markPaidInput,
describe: ({ id, paidOn }) =>
ar
? `تسجيل الفاتورة ${isolate(id)} كمدفوعة${paidOn ? ` بتاريخ ${isolate(paidOn)}` : ""}`
: `Mark invoice ${isolate(id)} as paid${paidOn ? ` on ${isolate(paidOn)}` : ""}`,
run: async ({ id, paidOn }) => {
const result = await api(`/api/invoices/${encodeURIComponent(id)}/pay`, {
method: "POST",
body: JSON.stringify(paidOn ? { paidOn } : {}),
});
router.refresh(); // show the new status on the page
return result;
},
});
return null;
}inputis a Zod object. Baseera validates what the model sends against it before anything runs, and sends it to the model as JSON Schema.kind: "read"runs at once.kind: "write"(and"draft") waits for the user.describeis the sentence on the approval card. Write it for the person who clicks.- A tool can also take
undo; the card then shows an undo button after it runs.
The example app also holds a one-invoice stand-in for your database, two API routes and a page. Copy them from examples/quickstart-next/src to run it as it is.
8. Run it and approve a call
pnpm devOpen http://localhost:3300 and press the launcher.
- Type "What is the status of invoice INV-1042?". The agent calls
getInvoicewithout asking, because it only reads, and answers from the result. - Type "Mark invoice INV-1042 as paid". An approval card appears with your
describesentence and the values of the call, with Approve and Reject. Nothing has changed yet. - Press Approve. The card shows that it is working, then done, and the page behind it now says the invoice is paid.
Press Reject instead and you can add a reason. The tool does not run, and the agent is told it was rejected, with your reason.
How approval works
Approval happens in the user's browser, inside the SDK, not on Baseera's servers. The model asks for a write tool, the runtime relays the call to the browser, and @baseera/react holds it until the user decides. Only an approved call reaches your run. A rejection goes back to the model as the result.
Your own API must still check permissions, because run calls it as the signed-in user.
To see what happened, open the agent's Sessions page: every message, tool call, approval and timing is in the trace. The Tools page lists the tools Baseera has seen from your app.
Troubleshooting
| What you see | Check |
|---|---|
| "The assistant has not been set up yet." | The agent has no provider key or model (step 2). |
| The panel cannot reach the assistant | NEXT_PUBLIC_BASEERA_URL points at a running runtime, and localhost:3300 is in the allowed domains (step 3). |
| The token route answers 500 | BASEERA_SECRET_KEY is missing. Restart pnpm dev after editing .env.local. |
| Build fails with "needs a publishable key" | NEXT_PUBLIC_BASEERA_KEY is not set at build time. |