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
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 underbasePath (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:
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).