Skip to content

nextjs

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

nextjs

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
agentuity
agentuity
 
 
app
app
 
 
.gitignore
.gitignore
 
 
README.md
README.md
 
 
bun.lock
bun.lock
 
 
next-env.d.ts
next-env.d.ts
 
 
next.config.ts
next.config.ts
 
 
package.json
package.json
 
 
tsconfig.json
tsconfig.json
 
 

README.md

Next.js + Agentuity

Upgrade pattern for an existing Next.js App Router frontend that adds an Agentuity backend runtime for AI routes.

What This Example Shows

  • Two-runtime architecture:
    • Next.js frontend runtime (localhost:3000)
    • Agentuity backend runtime (localhost:3500)
  • Dev startup gate: wait-on checks backend health (/api/health) before Next.js boots
  • Translate workflow using plain fetch():
    • POST /api/translate, GET /api/translate/history, and DELETE /api/translate/history
  • Eval wiring on the translate agent:
    • adversarial preset eval
    • language-match custom eval
  • Local proxy mode and cross-origin baseUrl mode

Official References

Project Layout

nextjs/
├── app/                                # Next.js frontend
│   ├── components/TranslateDemo.tsx     # Translate + history UI (plain fetch)
│   ├── layout.tsx
│   └── page.tsx
├── agentuity/                          # Agentuity backend
│   ├── src/agent/translate/agent.ts    # Translate agent
│   ├── src/agent/translate/eval.ts     # Evals (adversarial + language-match)
│   ├── src/agent/translate/state.ts    # History state schema
│   └── src/api/index.ts                # /api/translate* routes
├── next.config.ts                      # /api/* rewrite to Agentuity backend
└── tsconfig.json

Running Locally

Run from the project root (existing-apps/nextjs), not from inside agentuity/. The root dev script starts both the frontend and backend together:

cd existing-apps/nextjs
bun install
bun run build:agent
bun run dev

bun run dev starts both runtimes concurrently, and the web process uses wait-on to check http://127.0.0.1:3500/api/health before launching Next.js. Running bun run dev inside agentuity/ starts only the backend, which serves the API and workbench but not the frontend page.

AI Credentials in Local-Only Mode

If the project is not registered with Agentuity Cloud, translation calls require provider keys:

  • OPENAI_API_KEY for translate agent calls
  • GROQ_API_KEY for eval model calls

Without credentials, the backend still starts and history endpoints work, but POST /api/translate returns 500.

Warnings and Local-vs-Cloud Notes

  • If Next.js warns about workspace root detection, keep outputFileTracingRoot in next.config.ts pointed to the monorepo root.
  • Local default mode uses rewrite proxying in development: /api/:path* -> http://localhost:3500/api/:path*.
  • To override proxy target, set AGENTUITY_PROXY_TARGET (for example https://backend.example.com).
  • Cross-origin mode skips the rewrite and uses NEXT_PUBLIC_AGENTUITY_BASE_URL as the fetch() base URL.
  • In local-only mode without provider credentials, POST /api/translate can return 500; history endpoints still work.
  • If backend startup is delayed, wait-on waits up to 30 seconds before failing with a timeout error.
  • If you see a DEP0060 warning while using Next.js rewrites/proxy in dev, treat it as a known transitive dev-time warning unless request routing is actually failing.

Frontend API Calls

The client component uses plain fetch() to call the Agentuity backend:

  • POST /api/translate with JSON body { text, toLanguage, model }
  • GET /api/translate/history
  • DELETE /api/translate/history

No wrapper library or provider component is needed. The NEXT_PUBLIC_AGENTUITY_BASE_URL env variable sets the base URL for cross-origin mode; in local proxy mode it defaults to empty (same origin).

Verification Workflow

Run this after changing backend routes, schemas, or frontend route calls:

cd existing-apps/nextjs
bun run build:agent
bun run test
  • build:agent builds the Agentuity backend.
  • test is a practical check (build:agent && typecheck), not a separate test framework setup.

Deployment

This example runs two separate runtimes when deployed.

  1. Preferred: host-level proxy/rewrite
  • Route frontend /api/* traffic to the Agentuity backend.
  • Equivalent to local next.config.ts rewrite behavior, but configured at your host/load balancer.
  1. Fallback: explicit backend base URL from the frontend
  • Set frontend env: NEXT_PUBLIC_AGENTUITY_BASE_URL=https://your-agentuity-backend.example.com
  • The fetch() calls in TranslateDemo prepend this as the base URL.
  • Enable cross-origin backend access with:
    • AGENTUITY_CORS_ALLOWED_ORIGINS=https://your-frontend.example.com

By default, the Agentuity runtime reflects any origin for CORS. For tighter control, add a cors option to createApp() (e.g., cors: { sameOrigin: true } or cors: { origin: ['https://your-frontend.example.com'] }).

Related