December 19, 2025 Update

We've overhauled the build system, added new packages, and shipped a ton of improvements. Here's what's new.

Vite Build System

We've completely overhauled the build system, replacing the custom bundler with Vite + Bun. The result is faster builds, real Hot Module Replacement, and native WebSocket support that works the same in dev and production.

Here's what that means:

• True HMR — React components update without losing state
• Tailwind CSS — The Tailwind template now works properly in dev mode
• Native WebSockets — Bun's built-in WebSocket replaces the ws package
• Bun version checking — The CLI enforces minimum Bun version (1.3.3+) and offers interactive upgrade

The new architecture uses Bun for the server (agents, API routes, WebSockets) and Vite as an asset server (HMR, JSX transform). This eliminates the WebSocket proxy issues we had before and makes the dev experience much smoother.

All changes are backward compatible. Your existing projects will use the new build system automatically when you upgrade.

Framework-Agnostic Frontend Package

The new @agentuity/frontend package extracts our WebSocket and SSE utilities into a framework-agnostic layer. This is what @agentuity/react uses under the hood, but now you can use it directly with Svelte, Vue, or vanilla JavaScript.

import { WebSocketManager, EventStreamManager } from '@agentuity/frontend';

// WebSocket with auto-reconnect and message queuing
const ws = new WebSocketManager<InputType, OutputType>({
  url: '/api/websocket/echo',
  callbacks: {
    onConnect: () => console.log('Connected'),
    onMessage: (data) => console.log('Received:', data),
  },
  reconnect: { threshold: 3, baseDelay: 500 },
});

ws.connect();
ws.send({ message: 'Hello' }); // Queued if not connected yet

Both managers handle automatic reconnection with exponential backoff, message queuing, and proper cleanup. This sets us up for first-class Svelte and Vue support down the road.

Type-Safe API Calling

The build now generates a typed route registry in src/generated/routes.ts. Combined with the useAPI hook, you get fully type-safe API calls:

import { useAPI } from '@agentuity/react';

// Types inferred from your route schemas
const { data, isLoading } = useAPI('GET /api/users');

// POST with typed input
const { invoke } = useAPI('POST /api/hello');
await invoke({ message: 'Hi!' }); // Input type checked!

The build generates a RouteRegistry in src/generated/routes.ts that maps each route to its input/output schemas. The useAPI hook uses this for full type inference—no manual type annotations needed.

This is RPC over HTTP for now. Streaming support may come later.

Authentication with Clerk and Auth0

The new @agentuity/auth package makes adding user authentication straightforward. We've built integrations with Clerk and Auth0 that handle both client and server.

// Client setup
import { ClerkProvider, useAuth } from '@clerk/clerk-react';
import { AgentuityProvider } from '@agentuity/react';
import { AgentuityClerk } from '@agentuity/auth/clerk';

function App() {
  return (
    <ClerkProvider publishableKey={CLERK_KEY}>
      <AgentuityProvider>
        <AgentuityClerk useAuth={useAuth}>
          <YourApp />
        </AgentuityClerk>
      </AgentuityProvider>
    </ClerkProvider>
  );
}

On the server side, protect your routes with the middleware:

import { createMiddleware } from '@agentuity/auth/clerk';

router.get('/api/profile', createMiddleware(), async (c) => {
  const user = await c.var.auth.getUser();
  return c.json({ email: user.email });
});

Auth0 follows the same pattern: swap @agentuity/auth/clerk for @agentuity/auth/auth0 and wrap your app with AgentuityAuth0:

import { Auth0Provider, useAuth0 } from '@auth0/auth0-react';
import { AgentuityProvider } from '@agentuity/react';
import { AgentuityAuth0 } from '@agentuity/auth/auth0';

function App() {
  return (
    <Auth0Provider domain={AUTH0_DOMAIN} clientId={AUTH0_CLIENT_ID}>
      <AgentuityProvider>
        <AgentuityAuth0 useAuth0={useAuth0}>
          <YourApp />
        </AgentuityAuth0>
      </AgentuityProvider>
    </Auth0Provider>
  );
}

There are templates for both Clerk and Auth0, if you want to start with auth built-in. Check out the authentication docs for the full setup guide.

Thread ID Support

Threads let you maintain state across multiple requests—essential for building conversational agents that remember context. Each thread gets a unique ID (thrd_ prefix) that persists for up to an hour.

import { createAgent } from '@agentuity/runtime';

const agent = createAgent('conversation', {
  handler: async (ctx, input) => {
    // Thread persists across sessions
    ctx.logger.info('Thread: %s', ctx.thread.id);

    // Store conversation state
    const count = (ctx.thread.state.get('messageCount') as number) || 0;
    ctx.thread.state.set('messageCount', count + 1);

    return `Message #${count + 1} received`;
  },
});

Thread IDs are cryptographically signed to prevent tampering. We've updated the state management docs with a clear explanation of how threads "wrap" sessions. For a quick summary: threads represent conversations, and sessions represent individual requests within those conversations.

Workbench Updates

Workbench configuration moved from app.ts to agentuity.config.ts. No imports, no manual wiring. Just add the config and it works:

import type { AgentuityConfig } from '@agentuity/cli';

export default {
  workbench: {
    route: '/workbench',
    headers: {},
  },
} satisfies AgentuityConfig;

Also new:

• Thread persistence for testing multi-turn conversations (each browser tab gets its own thread)
• Works for backend-only agent projects (no web frontend required)

Check out the Workbench docs for the full guide.

What Else Is New?

New Capabilities

• VS Code extension chat context provider for workspace awareness
• 8 new language model tools for managing agents, deployments, and dev server from the IDE
• Custom agent scaffolding command (.github/agents/*.agent.md files)
• Interactive project selection in CLI when no project found
• "View on web" links in CLI commands
• PORT environment variable support for dev server
• Generated files now in src/generated/ with improved types and documentation
• Playwright E2E test infrastructure for WebSocket and SSE endpoints

Developer Experience

• Renamed requireUser() to getUser() in auth SDK for clarity
• New useAuth() hook in @agentuity/react
• Region-based service URLs for local vs cloud environments
• Standardized version display (no 'v' prefix)

Bug Fixes

18 bug fixes including:

• LLM provider patching restored in server builds
• Auto-template creation restored for new agent/API directories
• agent.validator() type inference fixed
• Hot reload working for both API and web files
• Profile-specific .env file loading
• Custom define support in agentuity.config.ts across all build phases
• Bun crash on deploy fixed (limited concurrent uploads)
• Stream routes now set Content-Type header correctly

Documentation

• Chat with history cookbook pattern expanded with better examples
• Build configuration updated with AGENTUITY_PUBLIC_* environment variable docs

All changes are backward compatible.

Upgrade Now

Ready to try it out? Run:

agentuity upgrade

Your dependencies will auto-sync on the next build.

---

Resources

• v1 SDK
• v1 Documentation
• Web Console
• Discord Community

As always, let us know what you think. Happy building!