---
meta:
title: "Get started with AI agent notifications using Liveblocks and Next.js"
parentTitle: "Quickstart"
description:
"Learn how to notify users when an AI agent has completed its work using
Liveblocks notifications and Next.js"
---
Liveblocks is a realtime collaboration infrastructure for building performant
collaborative experiences. Follow this guide to create an inbox notification
system in your app, and notify users when an AI agent has completed its work.
This uses a Next.js `/app` directory application, with the hooks from
[`@liveblocks/react`](/docs/api-reference/liveblocks-react), the components from
[`@liveblocks/react-ui`](/docs/api-reference/liveblocks-react-ui), and
[`@liveblocks/node`](/docs/api-reference/liveblocks-node) on the server.
## Quickstart
Install Liveblocks
Every package should use the same version.
```bash trackEvent="install_liveblocks"
npm install @liveblocks/client @liveblocks/react @liveblocks/react-ui @liveblocks/node
```
Initialize the `liveblocks.config.ts` file
We can use this file later to [define types for our application](/docs/api-reference/liveblocks-react#Typing-your-data).
```bash
npx create-liveblocks-app@latest --init --framework react
```
Add your secret key
Create a `.env.local` file and add your Liveblocks secret key from the
[dashboard](/dashboard/apikeys).
```env file=".env.local"
LIVEBLOCKS_SECRET_KEY="{{SECRET_KEY}}"
```
Set up authentication
Create an [authentication](/docs/authentication) API route with
[`identifyUser`](/docs/api-reference/liveblocks-node#id-tokens),
passing a unique user ID.
```ts file="app/api/liveblocks-auth/route.ts"
import { Liveblocks } from "@liveblocks/node";
const liveblocks = new Liveblocks({
secret: process.env.LIVEBLOCKS_SECRET_KEY!,
});
export async function POST(request: Request) {
// Get the current user from your database
const user = __getUserFromDB__(request);
// Identify the user and return the result
const { status, body } = await liveblocks.identifyUser(
{ userId: user.id },
{
userInfo: {
name: user.name,
avatar: user.avatar,
},
},
);
return new Response(body, { status });
}
```
Create a Liveblocks provider
Liveblocks Notifications uses the concept of projects, which relate to
projects in [your dashboard](/dashboard). Notifications are sent between
users in the same project. To connect and receive notifications, you must
add [`LiveblocksProvider`](/docs/api-reference/liveblocks-react#LiveblocksProvider)
to a client component in your app.
```tsx file="app/Providers.tsx" highlight="8-10"
"use client";
import { ReactNode } from "react";
import { LiveblocksProvider } from "@liveblocks/react";
export function Providers({ children }: { children: ReactNode }) {
return (
{children}
);
}
```
Add the provider to your layout
After creating your provider file, it’s time to use it. Import
your room into your `layout.tsx` file.
```tsx file="app/layout.tsx"
import { Providers } from "./Providers";
export default function Layout({ children }) {
return (
// +++
{children}
// +++
);
}
```
Use the Liveblocks hooks and components
Now that we’ve set up the provider, we can start using the Liveblocks hooks and components.
We’ll add [`useInboxNotifications`](/docs/api-reference/liveblocks-react#useInboxNotifications)
to get the current project’s notifications, then we’ll
use [`InboxNotification`](/docs/api-reference/liveblocks-react-ui#InboxNotification) and [`InboxNotificationList`](/docs/api-reference/liveblocks-react-ui#InboxNotificationList) to render them.
```tsx file="app/page.tsx" highlight="10,13-20"
"use client";
import { useInboxNotifications } from "@liveblocks/react/suspense";
import {
InboxNotification,
InboxNotificationList,
} from "@liveblocks/react-ui";
export default function Page() {
const { inboxNotifications } = useInboxNotifications();
return (
{inboxNotifications.map((inboxNotification) => (
))}
);
}
```
Import default styles
The default components come with default styles, you can import them into the
root layout of your app or directly into a CSS file with `@import`.
```tsx file="app/layout.tsx"
import "@liveblocks/react-ui/styles.css";
```
Notify the user when your agent completes
Trigger a notification with
[`triggerInboxNotification`](/docs/api-reference/liveblocks-node#post-inbox-notifications-trigger)
from a server action or route handler at the end of your agent’s work. In
this example, a custom `$agentCompleted` notification is sent once the
agent has finished a task.
```ts file="app/run-agent.ts"
"use server";
import { Liveblocks } from "@liveblocks/node";
const liveblocks = new Liveblocks({
secret: process.env.LIVEBLOCKS_SECRET_KEY!,
});
export async function runAgent({
userId,
task,
}: {
userId: string;
task: string;
}) {
const startedAt = Date.now();
// Run your AI agent here, e.g. generateText, mutateFlow, …
await __runYourAgent__({ task });
// +++
// Notify the user that the agent has finished
await liveblocks.triggerInboxNotification({
userId,
kind: "$agentCompleted",
subjectId: `agent-${task}`,
activityData: {
task,
status: "complete",
durationMs: Date.now() - startedAt,
},
});
// +++
}
```
Render the agent notification
After triggering the custom notification, modify `InboxNotification` to
[render `$agentCompleted` with custom UI](/docs/api-reference/liveblocks-react-ui#Rendering-notification-kinds-differently).
```tsx file="app/page.tsx"
"use client";
import { useInboxNotifications } from "@liveblocks/react/suspense";
import {
InboxNotification,
InboxNotificationList,
} from "@liveblocks/react-ui";
export default function Page() {
const { inboxNotifications } = useInboxNotifications();
return (
{inboxNotifications.map((inboxNotification) => (
(
✨}
>
Your agent finished working on{" "}
{props.inboxNotification.activities[0].data.task}.
),
}}
// +++
/>
))}
);
}
```
Next: add your users
Notifications is set up and working now, but the auth route is using a placeholder
user—the next step is to connect it to your real users, and attach their name and avatar to their notifications.
## What to read next
Congratulations! You’ve set up notifications that fire when your AI agent
finishes its work.
- [API reference](/docs/api-reference/liveblocks-react#Notifications)
- [Component reference](/docs/api-reference/liveblocks-react-ui#Notifications)
- [`triggerInboxNotification` reference](/docs/api-reference/liveblocks-node#post-inbox-notifications-trigger)
- [AI Presence quickstart](/docs/get-started/nextjs-ai-presence)
---
## Examples using Notifications
---
For an overview of all available documentation, see [/llms.txt](/llms.txt).