Connecting your app

The bridge is an HTTP endpoint in your app that Novu calls when users message your agent. Your handlers run there; Novu delivers replies to the connected channel.

After you scaffold or wire the bridge, Novu forwards inbound events to that URL and expects your handler code to run in your app - not in Novu's infrastructure.

Project structure

The Quickstart scaffolds a Next.js project with this layout:

app/
  api/novu/route.ts        → Bridge endpoint (Novu calls this URL)
  novu/agents/
    index.ts               → Exports registered agents
    support-agent.tsx      → Agent handlers (edit this)

Your app serves the bridge at /api/novu. Agent logic lives under novu/agents/.

serve() and registering agents

The route file imports serve from a framework adapter and passes your agents:

import { serve } from '@novu/framework/next';
import { supportAgent } from '../../novu/agents';

export const { GET, POST, OPTIONS } = serve({
  agents: [supportAgent],
});

Import serve from the adapter that matches your stack:

The first argument to agent('support-bot', …) must match the agent Identifier in the dashboard. To run multiple agents from one endpoint, add each export to the agents array.

Environment variables

The CLI writes Novu credentials to .env.local when you scaffold:

Provider keys such as OPENAI_API_KEY are separate - add them when you wire your LLM.

Adding to an existing project

Run npx novu connect from your project directory. The CLI detects whether you're starting in an empty folder or an existing app:

• Empty folder - scaffolds a new project with the bridge route, agent handlers, and .env.local credentials.
• Existing project - installs @novu/framework (and runtime packages such as @novu/framework/ai-sdk or @novu/framework/langchain when needed), writes Novu env vars, and wires what it can automatically. It may still leave handler or route wiring for you to finish, depending on your stack.

For the guided onboarding flow, follow the Quickstart. To wire manually:

1. Install @novu/framework (and @novu/framework/ai-sdk or @novu/framework/langchain if you use those adapters).
2. Create a bridge route in your app and call serve({ agents: [...] }).
3. Export one or more agents from agent('your-identifier', { … }).

For local tunneling and deployment, see Quickstart - Run your agent locally and Going to production.

Related