Next.js (App Router) quickstart

Add a Web Agent to a Next.js app that uses the App Router. At the end, the agent's launcher is on every page and the agent knows which user is signed in, from a token your server signs.

Prerequisites

• Next.js 14 or later with the App Router, and React 18 or later.
• A Web Agent in your workspace, created with Next.js as its technology, whose analysis has finished, with a version deployed to Production.

1. Copy your agent ID

1. In the portal, go to Web Agents and select your agent.
2. In the Overview tab, find the Install the assistant card and select By hand.
3. In the Mount step, select Show snippet and copy the agentId value.

2. Install the packages

npm install @faustine-ai/next @faustine-ai/web-agent

pnpm add @faustine-ai/next @faustine-ai/web-agent

yarn add @faustine-ai/next @faustine-ai/web-agent

bun add @faustine-ai/next @faustine-ai/web-agent

@faustine-ai/next has the component and the server helpers. @faustine-ai/web-agent is the loader the component uses to fetch the widget and your agent's served version when the page loads.

3. Mount the agent

Create a client component that renders <FaustineAgent>.

'use client';
import { FaustineAgent } from '@faustine-ai/next/client';

export default function Agent({ identityJwt }: { identityJwt?: string | null }) {
  return <FaustineAgent agentId="<AGENT_ID>" identityJwt={identityJwt} />;
}

Render it once from the root layout, after {children}.

import Agent from './faustine-agent';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Agent />
      </body>
    </html>
  );
}

The layout stays a Server Component. The component loads the Production environment. To load another one, pass its name: env="Staging".

4. Identify the signed-in user

Copy the agent's secret from the Settings tab, under Identity verification, and add it to your server environment as FAUSTINE_IDENTITY_SECRET. Do not give the variable a NEXT_PUBLIC_ prefix.

Sign a token in the layout and pass it to the component. getSession stands for your own session helper.

import { faustineIdentityToken } from '@faustine-ai/next';
import Agent from './faustine-agent';

export default async function RootLayout({ children }: { children: React.ReactNode }) {
  const user = await getSession();
  const identityJwt = user
    ? faustineIdentityToken({ id: user.id, name: user.name, email: user.email })
    : null;
  return (
    <html lang="en">
      <body>
        {children}
        <Agent identityJwt={identityJwt} />
      </body>
    </html>
  );
}

faustineIdentityToken signs an HS256 token that expires after 3600 seconds. Only id is required. The secret stays on the server, and the browser receives the token. A visitor with no session gets null and talks to the agent as anonymous.

5. Run your app

npm run dev

Install with a coding agent

The install-faustine skill does steps 2 to 4 in your repository and follows its conventions.

npx skills add faustine-ai/skills

Then, in your coding agent:

/install-faustine <AGENT_ID>

Reach Server Actions

The agent calls what has a URL: your route handlers and external APIs. If the Install the assistant card says that operations of your app are behind Server Actions or server-only functions, add the adapter. See The Faustine adapter for Next.js.

Troubleshooting

Next steps

• The Faustine adapter for Next.js: let the agent call Server Actions and server-only data functions.
• Next.js on Faustine: what the analysis reads and how the agent navigates.
• Identity verification: what a verified user gets.
• Restrict the domains that can load the agent: allow your own domains only.