Quickstart

This page follows the framework-first happy path with Next.js. You end with a normal Next.js app that uses Agentuity for service clients, local environment wiring, and deploy packaging. The same create flow works for the five create-supported frameworks: Next.js, Nuxt, SvelteKit, Astro, and Hono. For React Router, Vite + React, and TanStack Start, start with the framework CLI and then import the app.

1. Create the Project

npm create agentuity -- \
  --name my-app \
  --framework nextjs \
  --package-manager npm
cd my-app

The scaffold runs create-next-app, then layers on:

• @agentuity/cli as a devDependency
• @agentuity/aigateway and swr as dependencies
• A working translation page at src/app/page.tsx
• An API route at src/app/api/translate/route.ts that uses AIGatewayClient
• deploy: agentuity deploy in package.json
• agentuity.json with the registered project's metadata
• .env with the project's AGENTUITY_SDK_KEY

Expected result: the command exits with a my-app/ directory that contains the framework files, agentuity.json, .env, and the translation route. If it stops before those files exist, rerun the command from an empty directory. If authentication fails before the project is created, run npx @agentuity/cli auth login, then create the project again.

2. Run It Locally

npx agentuity dev

npx runs the local CLI from devDependencies. The CLI runs next dev as a child process and patches AGENTUITY_SDK_KEY plus service environment values into its env, so @agentuity/aigateway can call the gateway for the project. Open the URL Next.js prints (typically http://localhost:3000) and try a translation.

You can also call the API route directly:

curl -X POST http://localhost:3000/api/translate \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello from Agentuity","toLanguage":"French"}'

The response includes the translation, token count, model, and target language.

If the dev server starts but the route fails, read the route response and terminal error first. 401 or missing-key errors usually mean the command is not running from the registered project root or AGENTUITY_SDK_KEY is missing from the dev process. If the port is already in use, run npx agentuity dev --port 8080 or use the port your framework prints.

3. Make an Edit

Open src/app/page.tsx and add a language to the picker:

const LANGUAGES = ['Spanish', 'French', 'German', 'Chinese', 'Japanese'] as const;

Save the file. Next.js hot-reloads, the new option appears in the dropdown, and the route accepts it without any other change.

4. Add a Service Client

Service clients work in any framework route or script. Add key-value storage without touching the router or runtime:

npm install @agentuity/keyvalue

import { KeyValueClient } from '@agentuity/keyvalue';
 
const kv = new KeyValueClient();
 
await kv.set('analytics', 'last-translation-at', { at: new Date().toISOString() });

The client reads AGENTUITY_SDK_KEY from process env. agentuity dev supplies that key for local runs, and registered deployed apps receive it as a project secret.

See Services for queues, vector storage, email, schedules, sandbox execution, and the rest.

5. Deploy

npm run deploy

The deploy script runs agentuity deploy, which:

• Detects the framework from package.json and config files
• Runs the framework's build, then packages the output into .agentuity/
• Encrypts the bundle, uploads it, and starts the deployment

The CLI prints both the deployment-specific URL and the latest deployment URL. Visit either in a browser, or check app.agentuity.com for logs and resource settings.

Verify the Path

Next Steps

• Project Structure: the file map for each framework
• App Configuration: scripts, agentuity.json, env vars, and service clients
• Frameworks: per-framework setup, route patterns, and deploy notes
• Local Development: how agentuity dev resolves the SDK key, env files, and gateway routing