Tutorial: Connect your first agent

Create the agent and connect a provider

In the Novu dashboard, open Agents and click Create agent. Set the Identifier to support-agent, since that value must match the agent id you use in code.

On the guided setup page, open Select provider, choose Slack, and follow the prompts to create and install the Slack app. When it finishes, you get a welcome message from the agent in Slack.

For the full provider flow (Slack tokens, install, permissions), see the Quickstart and Create an agent.

Scaffold the bridge app

The bridge app is the project that receives events from Novu and runs your handler code. Copy the pre-filled command from the agent setup page, or run:

npx novu@latest init -t agent \
 --agent-identifier support-agent \
 --secret-key <NOVU_SECRET_KEY> \
 --api-url <NOVU_API_URL>

Run it in the directory where you want the project. The CLI generates a Next.js app with a starter agent. For details, see Scaffold your project.

Run it locally

On the agent detail page, set the bridge to Local. Then, from the project directory, start the app:

npm run dev:novu

This starts your app, opens a dev tunnel, and registers the bridge URL with Novu. When it connects, you get another message from your agent in Slack. Leave this running, it hot-reloads as you edit the handler in the next section.

Define the agent shell

Start with the bare minimum: an agent() call with an id and an onMessage handler. The agent id (support-agent) must match the identifier you set in the Novu dashboard.

Replace the contents of support-agent.tsx with the following echo handler:

/** @jsxImportSource @novu/framework */
import { agent } from '@novu/framework';
 
export const supportAgent = agent('support-agent', {
  onMessage: async ({ message, ctx }) => {
    return `You said: ${message.text}`;
  },
});

Add the /** @jsxImportSource @novu/framework */ pragma at the top of the file so you can return JSX cards in later steps. If you only return strings, you can omit it.

At this point the agent echoes messages back. In the next step, replace that behavior with a welcome card.

Handle the first message

Replace the echo handler with a welcome card. On the first message, the bot introduces itself and asks the user to pick a topic.

Use ctx.conversation.messageCount to detect the first turn. When the count is 1, return a welcome card with three topic buttons:

import { Actions, agent, Button, Card, CardText } from '@novu/framework';
 
export const supportAgent = agent('support-agent', {
  onMessage: async ({ message, ctx }) => {
    const firstName = ctx.subscriber?.firstName;
    const isFirstMessage = ctx.conversation.messageCount <= 1;
 
    if (isFirstMessage) {
      return (
        <Card title={`Hi${firstName ? `, ${firstName}` : ''}! I'm the Pipeliner bot`}>
          <CardText>What can I help you with today?</CardText>
          <Actions>
            <Button id="topic-billing" label="Billing question" value="billing" />
            <Button id="topic-technical" label="Technical issue" value="technical" />
            <Button id="topic-other" label="Something else" value="other" />
          </Actions>
        </Card>
      );
    }
 
    return `You said: ${message.text}`;
  },
});

• ctx.subscriber carries user profile data for personalized greetings.
• Returning JSX is shorthand for await ctx.reply(...).
• Each Button has an id and value used in onAction.

For all card components, see Interactive cards.

Use metadata for context

When the user clicks a button, onAction fires instead of onMessage. Add an onAction handler that stores the user's topic choice in ctx.metadata so the next turn can read it.

export const supportAgent = agent('support-agent', {
  // ...onMessage from step 2...
 
  onAction: async ({ actionId, value, ctx }) => {
    if (actionId.startsWith('topic-') && value) {
      ctx.metadata.set('topic', value);
      return `Got it, a **${value}** issue. Tell me what's going on and I'll take a look.`;
    }
  },
});

Read it back with ctx.metadata.get('topic') on the next message. To alert on-call for technical issues, use ctx.trigger. For details, see Trigger a workflow.

Answer follow-ups with an LLM

After the welcome card, plug in a model. This example uses the Vercel AI SDK with OpenAI.

Install the SDK and set your API key:

npm install ai @ai-sdk/openai

OPENAI_API_KEY=sk-...

Inside onMessage, after the welcome-card branch, add LLM generation:

import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';
 
const topic = ctx.metadata.get('topic') ?? 'unknown';
 
const { text } = await generateText({
  model: openai('gpt-4o-mini'),
  system: `You are a Pipeliner support agent. The user's topic is: ${topic}. Keep answers short and link to docs when relevant.`,
  messages: ctx.history.map((h) => ({
    role: h.role,
    content: h.content,
  })),
});
 
return text;

• ctx.history maps directly to SDK message format.
• For files in replies, use ctx.reply with the files option. For details, see Sending attachments.

Resolve the conversation

When the user confirms the issue is fixed, call ctx.resolve(). Add this check inside onMessage before the LLM branch:

const text = (message.text ?? '').toLowerCase();
 
if (text.includes('thanks') || text.includes('resolve')) {
  ctx.resolve('User confirmed the issue is fixed.');
  return 'Glad I could help. Closing this out, ping me anytime.';
}

The optional summary appears in the dashboard. If the user messages again, the conversation reopens automatically.