# 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**](https://auth.faustine.ai/go?to=%2Fweb-assistants) 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**

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

**pnpm**

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

**yarn**

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

**bun**

```bash
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>`.

```tsx filename="app/faustine-agent.tsx"
'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}`.

```tsx filename="app/layout.tsx"
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.

```tsx filename="app/layout.tsx"
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

```bash
npm run dev
```

> **Checkpoint:** The agent's launcher appears on the page and stays after you move to another page. Sign in, select the launcher and send a message. In the portal, the conversation appears under the agent's **Monitoring** tab, with your name and a **Verified** badge.

## Install with a coding agent

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

```bash
npx skills add faustine-ai/skills
```

Then, in your coding agent:

```text
/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](https://docs.faustine.ai/web-agents/nextjs-adapter/).

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| An error that starts `faustineIdentityToken: set FAUSTINE_IDENTITY_SECRET` | The server environment has no secret. | Add the variable to `.env.local` and restart the dev server. |
| No launcher, and the request to `webagent.faustine.ai/embed` returns `404` | No environment of the agent serves a version. | [Publish a version](https://docs.faustine.ai/web-agents/publish-a-version/). |
| No launcher, and the same request returns `403` | The page's domain is not in the environment's allowed domains. | See [Restrict the domains that can load the agent](https://docs.faustine.ai/web-agents/restrict-domains/). |
| The user shows as anonymous in the agent's **Monitoring** tab | The token was signed with another agent's secret. | Copy the secret from this agent's **Identity verification** section. |

## Next steps

- [The Faustine adapter for Next.js](https://docs.faustine.ai/web-agents/nextjs-adapter/): let the agent call Server Actions and server-only data functions.
- [Next.js on Faustine](https://docs.faustine.ai/technologies/nextjs/): what the analysis reads and how the agent navigates.
- [Identity verification](https://docs.faustine.ai/web-agents/identity-verification/): what a verified user gets.
- [Restrict the domains that can load the agent](https://docs.faustine.ai/web-agents/restrict-domains/): allow your own domains only.