Backstory
For a while now I've been working on our internal systems, specifically what we call "ops-center" (our internal dashboard for managing our system), but I ran into performance issues with the dev server. I took a break from that to investigate how I could make the process faster, make the dev server more reliable, and improve the overall development experience.
Let's go. In and out. 20-minute adventure. - Rick Sanchez
It wasn't.
Fixing dev mode required understanding the underlying model that runs our unusual mix of framework and custom stack.
Let me preface this by saying the challenges I encountered are mostly a result of developing in an ecosystem that is in constant, highly experimental flux. I don't blame anyone for the decisions that were made during the development of v1 and our SDK.
Agentuity has always been about building useful infrastructure for agents. Anything outside that scope existed to support that main premise. Our thinking for the SDK was to make agents first-class citizens from the get-go. The entire runtime was built around the idea of providing hard typing and a good experience for developers using agents in their codebase.
We built a base structure for the backend using Hono and implemented file-based routing since it's developer-friendly. The frontend would simply be a SPA app served via Vite.
The Issues with v1
Bun Isn't There Yet
I love Bun (the entire team does), but that doesn't change the fact that many of its more detailed implementations are currently broken.
As a result, we do a lot of monkey patching to make things work, especially when it comes to WebSockets.
The Agent Abstraction Didn't Hold
We designed our agents to be first-class citizens with defined schemas and names. This works well in our UI, where it's useful to think in terms of agents calling other agents, each with their own shapes and behaviors.
But the problem is that this is a wrapper (a very complex wrapper) around basic logic.
What we consider an "agent" is both the AI Gateway call and all the code processing that happens around that call, wrapped into a hard-typed input and output structure.
What we've observed is that users, including coding agents like Claude Code, Codex, and Copilot, don't treat agents this way. For them, the AI Gateway is just a function that should be used inside code normally, without much classification. The concept of "agent" loses value in that structure unless it's something that can run standalone and execute behavior independently. But at that point, the agent is just a backend route. So the "Agent" abstraction in our system stopped making sense.
There's also the fact that we're focused on the infrastructure side of things, so building an AI SDK is outside our scope.
What most users really want is something we already do that has nothing to do with the runtime or framework: make AI Gateways work and transparently show costs and usage. For that, we don't really care about how you structure your code.
Codegen and File-Based Routing Fell Short
I'll be the first to admit I don't particularly like file-based routing unless it's really well executed, and here, we fell short. We implemented file-based routing because it was an appealing concept, but the implementation left a lot to be desired. The codegen was necessary to maintain first-class agent classification, enforcing an "okay" code pattern as long as your app wasn't particularly large. But we noticed, especially as the ops center grew in complexity, that this approach made development increasingly difficult.
We could have pushed to improve the codegen and file-based routing. But ultimately, it wasn't what we wanted to enforce.
Codegen also helped with type-safe backend calls, but alternatives like Hono Client and Tanstack Query were already available, battle-tested, and better options.
The conclusion we reached: instead of building less useful tools to compete with what the industry is already doing well, we should encourage the use of those existing solutions.
It's All Middleware and SDK Calls
Our runtime exists for two main reasons: to make SDK calls to our services — Key-Value storage, Databases, Sandboxes, and more — part of the backend app's context, and to integrate the app with our analytics and observability infrastructure.
Nothing was stopping us from making these standalone packages and moving toward a "bring your own project" approach.
So that's what I've been working on.
v2, released alongside this post, is a path to making the true shape of the Agentuity runtime an agnostic runner (agnostic to frameworks, languages, and runtimes). You should consider v2 as a batteries-included Hono + SPA with Vite.
v2
So what exactly is v2?
v2 moves into bringing things to a more declarative scope. We want to make the runtime more like what most of the industry is already doing. No "special magic". If things are supposed to be magic, they should either be invisible or be very obvious.
Things that changed from v1 to v2 in summary:
- We moved into making everything declarative (routes, agents), no more file-based routing weirdness.
- No more generated code. We still do our internal file generation for things like our metadata, but we no longer provide the "generated folder" with generated code from the backend.
- This means that things like our custom React hooks and data fetching are no longer part of the packages. Just use your preferred methods to fetch your data. We recommend using Hono Client, since it's a Hono backend.
- Some structure on the frontend will change, like our AgentuityContext wrapper.
- Auth is now going to be its own service. We've been moving towards this, and you'll hear more about that soon.
Most of the migration can be handled by our new "@agentuity/migrate" package. This is probably an evergreen thing we are going to take forward even for v2 -> v3 migration in the future.
v2 Then v3... Immediately?
So, what is the future for the Agentuity Runtime and deploying on Agentuity?
To summarize:
v2 is a batteries-included Hono + SPA with Vite, just a better version of v1 with faster dev mode.
v3 is just deploying anything into Agentuity.
All our packages are currently available as standalone installations. If you use Agentuity Services in your project and that's all you care about, you should switch to calling the SDK through its dedicated packages.
If your goal is to deploy your app on Agentuity, you can either use our framework for now, or wait a bit to be able to deploy any project to our infrastructure.
If you're new to Agentuity, get started with:
bun create agentuity@nextIf you already have a project on Agentuity, migrate to v2 with:
bunx @agentuity/migratev3 is not that far. The goal for v3 is simple: deploy any app on Agentuity, no matter the runtime, language, or structure. As long as it can run in a container, it can run on Agentuity.
We're targeting a public beta within the next two weeks.
Related reading
- Agentuity v1 Is Here - The original v1 announcement
- AI Agent Runtime - Understanding the runtime architecture