March 27, 2026 Update

Since the last update, we shipped 11 releases and 56 commits across the SDK. This is a big one: SDK v2.0.0 is stable, bringing explicit routing, zero codegen, and a much faster dev server. Let's get into it.

Overview

• SDK v2.0.0 with explicit agent and route registration, no more file-based routing or generated code, and an automated migration tool
• OAuth token lifecycle with refresh, logout, and KV-backed token storage
• Sandbox job logs and scopes for streaming job output and fine-grained sandbox permissions
• CLI reliability with safer deploy streaming, better CI ergonomics, and cleaner exit codes
• And more!

SDK v2.0.0

v2 is the biggest architectural change since launch. Agents and routes are now explicitly registered through createApp(), replacing file-based auto-discovery and codegen entirely. Gabriel Rodrigues led this effort, and wrote about the reasoning in a retrospective.

Here's what the new model looks like:

import { createApp } from '@agentuity/runtime';
import { Hono } from 'hono';
import type { Env } from '@agentuity/runtime';
import hello from '@agent/hello';

const api = new Hono<Env>().post('/hello', hello.validator(), async (c) => {
  const data = c.req.valid('json');
  const result = await hello.run(data);
  return c.json(result);
});

const { server, logger } = await createApp({
  router: { path: '/api', router: api },
});

logger.debug('Running %s', server.url);

What Changed

• Explicit registration. Agents are imported and passed to createApp({ agents }). Routes use a standard Hono router passed to createApp({ router }).
• No more codegen. The src/generated/ folder and ~5,000 lines of AST-based code generation are gone. The build is simpler and faster.
• Faster dev server. Backend HMR now uses bun --hot instead of a manual file-watching restart loop.
• Standard frontend tooling. vite.config.ts replaces the old agentuity.config.ts for frontend configuration. Data fetching hooks (useAPI, useWebsocket, useEventStream) are removed from @agentuity/react. Use Hono Client or any data-fetching library you prefer.
• Auth is separating. Authentication is moving to its own service. More on that soon.

Migrating from v1

v1 projects will continue to work. When you're ready to migrate, the @agentuity/migrate package handles most of the work automatically:

bunx @agentuity/migrate

It removes src/generated/, rewrites routes to chained Hono style, generates barrel files, and cleans up bootstrapRuntimeEnv() calls. After running it, review the changes and adjust anything project-specific.

Starting fresh? Create a v2 project with:

bun create agentuity@next

Breaking Changes

These are the key breaks to be aware of:

• File-based route auto-discovery is removed. Routes must use an explicit Hono router passed to createApp({ router }).
• setup and shutdown hooks are removed from createApp(). Use module-level init and process.on("beforeExit", ...).
• @agentuity/react is deprecated in v2. Use Hono Client or your preferred data-fetching library.

v2 is a stepping stone. Think of it as a batteries-included Hono + SPA with Vite. v3 is about deploying anything into Agentuity, regardless of runtime, language, or structure. Again, v1 projects will continue to work, so migrate at your own pace. More on v3 soon.

OAuth Token Lifecycle

Building on last week's OAuth client management, we added the token lifecycle: refresh when tokens expire, revoke when users log out.

• refreshToken(refreshTokenValue, config) to get a new token response
• logout(token, config) to revoke an access or refresh token
• KeyValueTokenStorage to persist tokens in KV with auto-refresh on get()

import { KeyValueClient } from '@agentuity/keyvalue';
import { KeyValueTokenStorage } from '@agentuity/core/oauth';

const kv = new KeyValueClient();
const storage = new KeyValueTokenStorage(kv, {
	config: { issuer: 'https://auth.agentuity.cloud' },
});

// Retrieve (auto-refreshes if expired and refresh_token is available)
const token = await storage.get('user:123');
if (token) {
	console.log('access token ok:', token.access_token);
}

// Logout (revokes server-side and removes from storage)
await storage.invalidate('user:123');

The refreshToken() and logout() functions are also available as standalone imports if you prefer calling the OAuth primitives directly.

Sandbox Job Logs and Scopes

Two additions to sandboxes this week:

Job logs. You can now stream stdout and stderr from sandbox jobs directly from the CLI:

agentuity cloud sandbox job logs <sandbox-id> <job-id> --follow --timestamps

Supports --follow for real-time tailing, --grep for filtering, --tail to limit output, and --stderr to isolate error streams.

Scopes. Sandbox creation now accepts a scopes option for fine-grained permission opt-in, giving you control over what a sandbox can access at creation time.

Also Shipping

CLI Reliability

• Deploy/build pipelines now stream child-process output to disk, preventing OOM crashes during large builds
• agentuity build --ci works without --url for snapshot-based deploy flows
• Spinner and cursor restoration are guarded with TTY checks, so non-interactive environments stay clean
• CLI exit codes moved to user-defined range (10+) to avoid conflicts with Unix signal codes
• agentuity project show --json and deploy flows now include URL fields

SDK and Runtime

• Sandbox stream reliability and exit code propagation improvements
• Sandbox 404 handling now produces a consistent SandboxNotFoundError
• OAuth KeyValueTokenStorage supports auto-refresh and revocation via invalidate()
• Version mismatch detection warns when @agentuity/* packages have conflicting versions
• Deprecation warnings when v1 packages are used with the v2 runtime

Documentation

• Reorganized docs: APIs content consolidated into Agents and Routes sections for more clarity
• New Agents vs Routes guide for choosing the right pattern
• New Calling Agents from Routes page
• v1 to v2 migration guide added

Bug Fixes

• Vector delete path correctness for single-key operations
• create-agentuity dist-tag logic fixed so bun create agentuity@next resolves beta versions correctly
• Docs pipeline vector updates and sync to fix the "Ask AI" feature in our docs site

Upgrade Now

The CLI will prompt you automatically when a new version is available, or you can upgrade manually:

agentuity upgrade

New to Agentuity? Get started in seconds:

curl -fsSL https://agentuity.sh | sh

Once you're on v2:

• Register agents and routes explicitly with createApp()
• Migrate existing projects with bunx @agentuity/migrate
• Use bun --hot for faster backend dev cycles

---

Resources

• Documentation
• Web Console
• GitHub SDK
• Full Changelog

Questions or feedback? Drop by our Discord to chat. Happy building!