Skip to main content
createRouteHandler(agent, options?) serves an agent from a route file of any framework whose handlers take a Web Request and return a Response: the Next.js App Router, SvelteKit, Remix / React Router, Hono, Bun.serve. It is a thin wrapper over the same session API as lousho dev and the deployed server (Deployment), so the React, Vue and Svelte bindings work against it unchanged. It imports no framework and no node:* module. The vendor/ model prefix chooses the provider; with OpenRouter use openrouter/<vendor>/<model> (e.g. openrouter/openai/gpt-4o-mini).

Next.js App Router

A route with no auth is public: anyone who can reach it can run your agent and spend your model budget. Pass a bearer token, or a function that checks your own session or cookie:

Routes

All paths are under basePath (default /api/agent; a trailing slash is accepted, and a request outside the base path is a 404). Sessions are kept by the agent’s store (createAgent({ store })), so give the agent one that outlives a serverless invocation when you use sessions. With auth, a session id is bound to the first principal that sends it a turn (reading an id claims nothing), and a different principal gets 403 (LOUSHO_SESSION_FORBIDDEN). That binding is kept in memory, so a new serverless instance forgets it, and then refuses the stored session to every user, its owner too: for an app with more than one user, pass authorizeSession as well, e.g. with ids derived from the caller (${userId}-<suffix without '-'>, as below). See Who may use a session. POST routes take JSON only (Content-Type: application/json, which useLoushoAgent and useChat send) and refuse a browser request from another origin unless you list it in allowedOrigins: see Cross-site requests. Who may approve a call. createRouteHandler has no approvers option; approvals are decided by authorizeApproval({ principal, sessionId, approval }). By default (callerOwnsApproval) the user a gated call runs for may approve it, and cannot decide another user’s call, so a single-user app that prompts its own user needs nothing. That also means a user can approve their own refund. If an approval must come from someone else, pass authorizeApproval. This is a two-person rule: a supervisor decides, and never on a call that runs for themselves. The supervisor also needs authorizeSession to read the customer’s session (GET /chat/:id, to show what they are approving) and to decide in it; by default the session belongs to the customer alone:
An error reaches the client as its name and code with a generic message; exposeErrors: true sends the raw text. See Who may decide an approval for the 403 it answers with and the supervisor-in-any-session variant. If the client goes away while a session turn streams (a closed tab, a dropped connection), the turn still runs to its end on the server and is saved to the session, so a tool that already ran (a refund, an email) is in the transcript and the user’s next message can ask about it. Nothing more is written to the closed stream. On a serverless host, pass the platform’s waitUntil (for example waitUntil from @vercel/functions) so the function is kept alive until the turn is saved. onDisconnect: 'abort' aborts the turn instead, as before; tool results it already has are still kept. auth also takes an ordered list of jwt(), oidc(), basic() and apiToken() entries, and the caller it accepts reaches the run as principal: see Route auth and principals.

Client: useLoushoAgent

Client: useChat

With uiMessageStream: true, point useChat at the ui route. The chat id names the session, so only the newest user message is sent to the agent (AI SDK UI).

Other frameworks

The same handler, mounted where the framework wants it: