# March 27, 2026 Update

Since the [last update](/content/blog/march-20-2026-update/index.html), 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!](/content/blog/march-27-2026-update#also-shipping/index.html)

## 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](/content/blog/the-path-to-be-agnostic/index.html).

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](https://hono.dev/docs/guides/rpc) 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](https://hono.dev/docs/guides/rpc) 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](/content/blog/march-20-2026-update/index.html) 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](/content/product/sandboxes/index.html) 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](https://agentuity.dev/agents/when-to-use) guide for choosing the right pattern
- New [Calling Agents from Routes](https://agentuity.dev/routes/calling-agents) page
- [v1 to v2 migration guide](https://agentuity.dev/reference/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](https://agentuity.dev/)
- [Web Console](https://app.agentuity.com/)
- [GitHub SDK](https://github.com/agentuity/sdk)
- [Full Changelog](https://github.com/agentuity/sdk/releases)

Questions or feedback? Drop by [our Discord](https://discord.gg/agentuity) to chat. Happy building!