Agentuity Documentation

The create flow runs the framework's official scaffolding tool, then layers on Agentuity dependencies, scripts, and a working AI translation example. Your framework's file layout is unchanged. Nothing is moved into an Agentuity-owned runtime structure.

What the scaffold adds

After npm create agentuity, expect the framework's normal files plus:

Addition	Where	When
`@agentuity/cli`	`package.json` devDependencies	Always
`@agentuity/aigateway`	`package.json` dependencies	When the AI example is included
`swr`	`package.json` dependencies	Next.js AI example
Selected service packages, for example `@agentuity/keyvalue`	`package.json` dependencies	When selected with `--services` or the service prompt
`deploy: agentuity deploy`	`package.json` scripts	Always
Translation page and API route	Framework-specific paths (see below)	When the AI example is included
`agentuity.json`	Project root	When you register (default)
`.env` with `AGENTUITY_SDK_KEY`	Project root	When you register (default)
`.gitignore` entries: `.agentuity/`, `.env`, `.env.local`, `agentuity.json`	Project root	Always
`AGENTS.md`, `CLAUDE.md`	Project root	Always

The framework's own create command owns dev, build, and start scripts; Agentuity adds deploy on top.

If you scaffolded with --no-register, run agentuity project import later to register the directory and write agentuity.json plus the AGENTUITY_SDK_KEY.

Project metadata lives where you import

For a single-app repo, run agentuity project import from the app root. In a monorepo, run it from the app package directory, or pass --dir apps/web, so agentuity.json and .env are written next to that app's package.json.

Framework File Layouts

For create-supported frameworks, the scaffold places the AI translation example where each framework expects routes and pages:

Framework	API route	App UI	Dev script
Next.js	`src/app/api/translate/route.ts`	`src/app/page.tsx`	`next dev`
Nuxt	`server/api/translate.post.ts`	`app/app.vue`	`nuxt dev`
SvelteKit	`src/routes/+page.server.ts`	`src/routes/+page.svelte`	`vite dev`
Astro	`src/pages/api/translate.ts`	`src/pages/index.astro`	`astro dev`
Hono	`src/index.ts`	`src/landing.tsx`	the scaffold's `dev` script

agentuity dev calls the framework's own dev script through your package manager.

React Router, Vite + React, and TanStack Start are existing-app adoption paths today. See Frameworks for adding Agentuity to those apps without using the Agentuity create flow.

Routes and Services

Routes live where the framework expects them. To add Agentuity services, import a standalone client inside the route or function that owns the work:

import { KeyValueClient } from '@agentuity/keyvalue';
 
const kv = new KeyValueClient();
 
await kv.set('sessions', 'user-123', {
  lastSeenAt: new Date().toISOString(),
});

The client reads AGENTUITY_SDK_KEY (with AGENTUITY_CLI_KEY as a fallback) from process env. agentuity dev supplies the key for local runs, and registered deployed apps receive it as a project secret.

This pattern is portable across framework server code, scripts, and workers. See Using Standalone Packages for the full client list.

Hono can also use middleware

In Hono projects, @agentuity/hono exposes service clients on c.var.* for routes that prefer Hono context. Use standalone clients as the default; reach for the middleware when you want Hono-specific ergonomics.

App Entrypoints

There is no Agentuity entrypoint. Each framework owns startup and routing as usual:

Framework	Entrypoints
Next.js	`src/app/` and `next.config.*`
Nuxt	`app/`, `server/`, and `nuxt.config.*`
SvelteKit	`src/routes/` and `svelte.config.*`
Astro	`src/pages/` and `astro.config.*`
Hono	`src/index.ts` and `src/landing.tsx`

agentuity build packages the framework's build output for deploy. agentuity deploy does both, then encrypts and uploads the bundle.

Build Output

agentuity build writes .agentuity/launch.json. That file is the process contract Agentuity uses at deploy time:

json.agentuity/launch.json

{
  "processes": [
    {
      "type": "web",
      "command": "node server.js",
      "default": true
    }
  ],
  "framework": {
    "name": "nextjs"
  },
  "runtime": {
    "name": "node",
    "port": 3000
  }
}

In a detected monorepo subpackage, the output is staged at the workspace root and the process includes a working directory:

json.agentuity/launch.json

{
  "processes": [
    {
      "type": "web",
      "command": "node server.js",
      "default": true,
      "workingDirectory": "apps/web"
    }
  ],
  "framework": {
    "name": "nextjs"
  },
  "runtime": {
    "name": "node",
    "port": 3000
  }
}

Inspect launch.json after the first build. It shows the exact command the platform will run.

Next Steps

App Configuration: scripts, agentuity.json, env vars, and service clients
Frameworks: per-framework setup, route patterns, and deploy notes
Using Standalone Packages: every Agentuity service client and constructor option
Deploy Framework Apps: register, package, and ship a project
Migration: compare older runtime app structure with the current framework structure