Add Agentuity to an existing app

Choose this path when the app already exists and you want to add one server-side Agentuity endpoint without changing the router, scripts, or build setup.

npm install -D @agentuity/cli
npm install @agentuity/keyvalue

Pick the Right Path

For an existing app, keep the app shape you have. Add service clients only inside server-only routes, handlers, server actions, or background jobs.

Keep Your Existing Stack

Agentuity fits beside the app stack you already trust. Keep the thing that owns the request, session, data model, or vendor account, then add Agentuity where a managed resource or project credential helps.

Add Agentuity service clients only in server-only code. Verify the change with your app's normal dev server and build first, then run through agentuity dev and agentuity build before deploy.

Add One Server Route

This Next.js route is a small read-only validation route. It keeps AGENTUITY_SDK_KEY on the server and does not use a NEXT_PUBLIC_* env var. Use app/api/agentuity/route.ts instead if your Next.js app does not use a src/ directory.

import { KeyValueClient } from '@agentuity/keyvalue';
import { NextResponse } from 'next/server';
 
const kv = new KeyValueClient();
const namespace = 'my-app';
 
export async function GET(): Promise<Response> {
  try {
    const result = await kv.get<{ readonly checkedAt: string }>(
      namespace,
      'health',
    );
 
    return NextResponse.json({
      sdkKeyAvailable: Boolean(process.env.AGENTUITY_SDK_KEY),
      keyValue: {
        ok: true,
        exists: result.exists,
      },
    });
  } catch (error) {
    return NextResponse.json(
      {
        sdkKeyAvailable: Boolean(process.env.AGENTUITY_SDK_KEY),
        keyValue: {
          ok: false,
          error:
            error instanceof Error ? error.message : 'Unknown key-value error',
        },
      },
      { status: 503 },
    );
  }
}

Use the same idea in the route shape your framework already uses:

Validate Locally

Run the app the way you normally do:

cd existing-app
npm run dev

Check the existing page and the new route:

curl http://localhost:3000/
curl http://localhost:3000/api/agentuity

Then run the native build:

npm run build

Add Agentuity Project Metadata

Validate the directory before writing project metadata:

npx agentuity project import --validate-only

If the output looks right, register the project and write agentuity.json:

npx agentuity project import --name existing-app --confirm

For non-interactive cloud setup, pass the org explicitly:

npx agentuity project import \
  --name existing-app \
  --org-id <org-id> \
  --confirm

In a monorepo, run the command from the app package or pass --dir:

npx agentuity project import \
  --dir apps/web \
  --name existing-web-app \
  --org-id <org-id> \
  --confirm

That writes apps/web/agentuity.json and apps/web/.env. The build step detects the workspace root and writes a launch command with workingDirectory: "apps/web" for the app subdirectory.

Run Through Agentuity

agentuity dev wraps your existing dev script and injects Agentuity env values into the server process:

npx agentuity dev --port 3000

If the framework prints a different URL, open or curl the printed URL. Some framework dev scripts own their port flags.

Build the Agentuity package after the native build passes:

npx agentuity build

This is a packaging check. When .agentuity/launch.json exists, inspect it before deploying. The launch command is the process Agentuity will start for the packaged app. For a local validation check, run that command from .agentuity and curl the root page and the route you added.

Deploy

After import and local validation, deploy from the same directory:

npx agentuity deploy

An interactive agentuity deploy can offer to register an unregistered directory before it builds. In a non-interactive shell, pass --confirm and a name, or run project import --confirm first:

npx agentuity deploy --name existing-app --confirm

Remote Repos

You can import from GitHub when the app is not local:

npx agentuity project import --source owner/repo --name existing-app --confirm

Use --deploy when you want the import flow to deploy after the project is registered:

npx agentuity project import --source owner/repo --name existing-app --deploy --confirm

Next Steps

• Frameworks: add framework-specific route and deploy notes
• Deploy Framework Apps: inspect build output before deploying
• AI Commands: give coding agents CLI context before they edit your app