Web Apps

Use Agentuity services from framework routes, server functions, and browser-facing apps

Build the UI with the framework you already chose. Put Agentuity service clients in server-only code, then call those routes from the browser with normal fetch.

Server Route

This example uses a Next.js route handler, but the boundary is the same in other frameworks: validate the request, call the service from server code, and return a Web Response.

typescriptapp/api/preferences/route.ts
import { KeyValueClient } from '@agentuity/keyvalue';
 
interface Preference {
  readonly theme: 'light' | 'dark';
}
 
const kv = new KeyValueClient();
 
function isPreference(value: unknown): value is Preference {
  return (
    typeof value === 'object' &&
    value !== null &&
    'theme' in value &&
    (value.theme === 'light' || value.theme === 'dark')
  );
}
 
export async function POST(request: Request): Promise<Response> {
  const body: unknown = await request.json();
 
  if (!isPreference(body)) {
    return Response.json({ error: 'theme must be light or dark' }, { status: 400 });
  }
 
  await kv.set('preferences', 'current-user', body, {
    ttl: 60 * 60 * 24 * 30,
  });
 
  return Response.json({ saved: true });
}
 
export async function GET(): Promise<Response> {
  const result = await kv.get<Preference>('preferences', 'current-user');
 
  return Response.json({
    preference: result.exists ? result.data : { theme: 'light' },
  });
}

KeyValueClient reads project credentials from the environment that agentuity dev and agentuity deploy provide. Keep that client out of browser components and browser bundles.

Browser Call

Call the route through the same origin. The browser never receives AGENTUITY_SDK_KEY.

typescriptsrc/preferences.ts
export async function saveTheme(theme: 'light' | 'dark'): Promise<void> {
  const response = await fetch('/api/preferences', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ theme }),
  });
 
  if (!response.ok) {
    throw new Error(`Preference save failed: ${response.status}`);
  }
}

Framework-Specific Setup

FrameworkServer boundary
Next.jsapp/api/**/route.ts
Nuxtserver/api/*.ts
React Routerresource routes with loader and action
SvelteKit+server.ts routes and server actions
Astrosrc/pages/api/*.ts endpoints
TanStack Startserver routes and server functions
Vite + Reacta server boundary such as server.ts

See Frameworks: choose the route shape for your framework before adding service clients.

Related Docs

  • Backend APIs: deploy an API without a browser UI
  • Static Sites: deploy static output and add a server boundary only when secrets are needed
  • Services: choose the client package for app state, files, queues, AI Gateway, sandbox, and observability