Use these pages when an existing Agentuity app needs a controlled move between SDK generations. v3 is the default path for new work. Existing v2 apps can stay on v2 until the framework-first app shape is worth the migration work.
npx @agentuity/migrate --v2-to-v3 --dry-runWhen the follow-up steps call the Agentuity CLI, use your package manager's exec wrapper if the CLI is only installed locally, for example npx agentuity ... or bunx agentuity ....
The v2 to v3 migration is an eject from the Agentuity runtime container into a framework-owned app. The tool can move simple runtime code into a Hono starting point, remove v2-only packages, and leave review markers where app state, lifecycle, auth, or frontend behavior needs a human decision.
npx @agentuity/migrate --v2-to-v3 --dry-runStart here when your app imports @agentuity/runtime, calls createApp(), uses createAgent(), or depends on runtime ctx.* service access.
Which guide to use
| Starting point | Use |
|---|---|
v2 app using @agentuity/runtime, createApp(), or createAgent() | Migrating from v2: run the migration in order and review the manual work |
| v1 app using older route files and generated SDK folders | Migration CLI: run --v1-to-v2, verify v2, then decide whether to continue to v3 |
| You want to understand the app model change before editing code | Runtime to Frameworks: map runtime APIs to framework routes, functions, and service clients |
| You want the exact command, flags, and generated changes | Migration CLI: inspect npx @agentuity/migrate before applying it |
Existing v2 apps pinned to the v2 runtime model can keep running while you plan the move. The v3 @agentuity/runtime package is a deprecation shim that throws on createApp() and createAgent(). See Runtime to Frameworks for the exact mapping.
What changes in v3
The v3 migration is not a package bump. It changes where Agentuity sits in your app. Treat it as a one-way door until you have reviewed the diff and run your checks:
- your framework owns the HTTP entry point, routes, server functions, and build script
- Agentuity services are used through standalone clients such as
KeyValueClient,QueueClient, orSandboxClient - Hono apps can use
@agentuity/honowhenc.var.*service access reads better than direct imports agentuity project import,agentuity build, andagentuity deployregister, package, and deploy the framework output
The migration CLI gives you a reviewable starting point. It does not decide your app state model, auth provider, frontend framework, or long-running workflow design.
Should I migrate now?
| Situation | Recommendation |
|---|---|
| the v2 app is stable and only needs small maintenance | stay on v2 for now |
| you are adding framework routes, server functions, or new service clients | plan the v3 migration |
you rely heavily on ctx.thread, ctx.session, lifecycle hooks, or Workbench | budget manual design time before applying changes |
| you are starting a new app | create a v3 app with npm create agentuity |
Recommended Order
- Run the dry run and read the report.
- Apply the migration in a branch with a clean git worktree.
- Review generated files and manual markers.
- Run your app's typecheck and framework build.
- Register the project with Agentuity Cloud.
- Run
agentuity build, then deploy after that build passes.