| name | agentuity-frontend |
| description | When building website or app frontends that connect to Agentuity agents and services. Covers @agentuity/react hooks, @agentuity/auth for login flows, @agentuity/frontend for WebRTC and real-time communication. |
| version | 2.0.0 |
Agentuity Frontend Reference
Package Overview
| Package | Purpose |
|---|
@agentuity/react | React hooks for context, auth, WebRTC, and analytics |
@agentuity/frontend | Framework-agnostic web utilities |
@agentuity/auth | Authentication (server + client) |
Key Concepts
- Use
hc<AppRouter>() from hono/client for type-safe API calls — useAPI and createClient were removed in v2
- Chained Hono methods (
.get().post()) are required for type inference with hc()
useAuth() for authentication state, useAnalytics() for tracking- Wrap app with
<AgentuityProvider> (and <AuthProvider> if using auth)
- Auth tokens from
useAuth() must be passed to hc() calls manually
baseUrl prop only needed if frontend is hosted separately from Agentuity- Server auth via
createAuth(), createSessionMiddleware(), mountAuthRoutes() from @agentuity/auth
AuthProvider is exported from @agentuity/auth/react (not @agentuity/react)- Build config goes in standard
vite.config.ts (not agentuity.config.ts)
Type-Safe API Calls (v2)
v2 removed useAPI, createClient, and RPCRouteRegistry. Use Hono's hc() client for fully typed API calls:
import { hc } from 'hono/client';
import type { AppRouter } from '../api';
const client = hc<AppRouter>('/api');
const res = await client.hello.$get();
const data = await res.json();
For richer data fetching (caching, background updates), pair with TanStack Query, SWR, or any library you prefer — v2 doesn't prescribe a data fetching approach.
Authentication
Server Setup
import { createAuth, createSessionMiddleware, mountAuthRoutes } from '@agentuity/auth';
import { Hono } from 'hono';
import type { Env } from '@agentuity/runtime';
const auth = createAuth({
connectionString: process.env.DATABASE_URL,
});
const router = new Hono<Env>()
.on(['GET', 'POST'], '/api/auth/*', mountAuthRoutes(auth))
.use('/api/*', createSessionMiddleware(auth));
Client Setup
import { AgentuityProvider, useAuth } from '@agentuity/react';
import { AuthProvider } from '@agentuity/auth/react';
function App() {
return (
<AuthProvider>
<AgentuityProvider>
<MyApp />
</AgentuityProvider>
</AuthProvider>
);
}
Using Auth in Agent Handlers
When auth middleware is active, ctx.auth is available:
handler: async (ctx, input) => {
if (!ctx.auth) return { error: 'Please sign in' };
const user = await ctx.auth.getUser();
return { message: `Hello ${user.name}` };
}
Documentation Links
Common Mistakes
| Mistake | Better Approach | Why |
|---|
Using useAPI or createClient (v1) | Use hc<AppRouter>() from hono/client | These were removed in v2 — use Hono's typed client |
Using mutating router style (.get()) | Use chained style (.get().post()) | Only chained methods preserve types for hc() |
Adding baseUrl inside Agentuity project | Omit baseUrl | Auto-detected in full-stack projects |
| Manual WebSocket management | Use useWebsocket hook | Auto-reconnect, auth injection, message queuing |
| Missing AuthProvider | Wrap app with AuthProvider | Required for auth token injection |
Calling /agent/<name> from frontend | Call /api/<name> routes instead | Agents aren't HTTP endpoints — call the API route that wraps the agent |
| Putting secrets in frontend env vars | Only use AGENTUITY_PUBLIC_*, VITE_*, or PUBLIC_* prefixes | These prefixes are exposed to the browser — never put API keys in them |
Vite config in agentuity.config.ts | Use standard vite.config.ts | v2 moved build config to standard Vite config |
Environment Variables for Frontend
Only variables with these prefixes are exposed to the browser bundle:
AGENTUITY_PUBLIC_*VITE_*PUBLIC_*
Never put secrets or API keys in these variables. LLM API keys are not needed anyway — the AI Gateway handles LLM routing server-side.
When In Doubt, Check the Docs
If you're unsure about any hook, provider, or pattern, check the documentation first rather than guessing:
