Get started with Novu for Agents

Create your agent

1. Go to the Novu dashboard.
2. In the sidebar, click Agents.
3. Click Create agent.
4. Fill in the required fields:
   • Agent name: The display name for your agent.
   • Identifier: A unique slug used in code. You cannot change it after creation.
   • Description: Optional.
5. Click Setup agent.

After you create the agent, Novu opens the guided setup page.

Select a provider

1. In the setup page, open the Select provider dropdown.
2. Select Slack.

The dashboard detects the selected provider and unlocks the Slack setup steps.

Create a Slack app

Novu can create the Slack app for you automatically using a Slack App Configuration Token. You'll generate the token once, paste it into Novu, and Novu handles the rest.

1. In the setup step, click Slack App Configuration Token. This will open the Slack API apps page.
2. Under Your App Configuration Tokens, click Generate Token.
3. Select the Slack workspace where you want the agent to live.
4. Click Generate.
5. Copy the generated token.
6. Back in the Novu dashboard, paste the token into the input field and click Create app. Novu uses the token to create the Slack app in your workspace.

Install the app in your workspace

After Novu creates the Slack app, install it to your workspace. This is the same flow your end users will follow when they install the agent.

1. Click Install agent. If the button uses the agent name, it may appear as Install [agent name].
2. Slack opens a permissions review page.
3. Review the requested permissions.
4. Click Allow.

Once installed, you'll receive a welcome message from the agent. The provider connection is now complete.

Scaffold your agent project

With the provider connected, the dashboard shows the next phase: connecting your code. Novu provides a pre-filled CLI command that creates a starter project with your agent identifier and secret key already configured.

1. Copy the scaffold command from the dashboard.

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

2. Open your terminal.
3. Go to the directory where you want to create the project and paste the command.
4. Run the copied command.

The CLI creates a new project with the bridge endpoint preconfigured.

Start your agent locally

Run the dev command below in your project directory. This starts your app, opens a dev tunnel, and registers the bridge URL with Novu so messages can reach your local handler.

npm run dev:novu

The dashboard polls for the bridge connection. Once it confirms the connection, you'll see another message in Slack from your agent

Send a message

Open the Slack channel where your app is installed and send a message to your bot. Your onMessage handler fires, and the reply appears in the thread.

Edit the files in app/novu/agents/ to customize how your agent responds. See Handle Events for the full list of events your agent can respond to.