Agent Toolkit

What is the Agent Toolkit?

The @novu/agent-toolkit package lets you expose Novu notification workflows as tools for LLM agents. It works with OpenAI, LangChain, and Vercel AI SDK. The toolkit automatically discovers your Novu workflows and converts them into strongly-typed tools that an LLM can invoke, letting your AI agent send notifications, manage subscriber preferences, and trigger any workflow you’ve built in Novu.

The Agent Toolkit is a code-level SDK for embedding Novu tools inside your own AI agents. For giving AI coding assistants (Claude Code, Cursor, Copilot) context about Novu, see Agent Skills. For connecting AI tools to Novu via the Model Context Protocol, see MCP.

Installation

npm install @novu/agent-toolkit

Then install the peer dependency for the AI framework you use:

Framework	Peer Dependency	Import Path
OpenAI	`openai >= 4.0.0`	`@novu/agent-toolkit/openai`
LangChain	`@langchain/core >= 0.2.0`	`@novu/agent-toolkit/langchain`
Vercel AI SDK	`ai >= 6.0.0`	`@novu/agent-toolkit/ai-sdk`

Quick Start

import { createNovuAgentToolkit } from '@novu/agent-toolkit/openai';
import OpenAI from 'openai';

const openai = new OpenAI();

const toolkit = await createNovuAgentToolkit({
  secretKey: process.env.NOVU_SECRET_KEY,
  subscriberId: 'user-123',
});

const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Send a welcome email to user-123' }],
  tools: toolkit.tools,
});

for (const toolCall of response.choices[0].message.tool_calls ?? []) {
  const result = await toolkit.handleToolCall(toolCall);
  console.log(result);
}

Configuration

Every adapter’s createNovuAgentToolkit accepts a NovuToolkitConfig object:

type NovuToolkitConfig = {
  secretKey: string;
  subscriberId: string;
  backendUrl?: string;
  workflows?: {
    tags?: string[];
    workflowIds?: string[];
  };
};

Option	Required	Description
`secretKey`	Yes	Your Novu API secret key from dashboard.novu.co/settings/api-keys.
`subscriberId`	Yes	Default subscriber ID used when triggering workflows.
`backendUrl`	No	Custom Novu API URL (defaults to Novu Cloud).
`workflows.tags`	No	Filter discovered workflows by tags.
`workflows.workflowIds`	No	Restrict discovered workflows to specific IDs.

Framework Adapters

Each adapter exposes a createNovuAgentToolkit function that returns tools in the native format for that framework.

OpenAI
LangChain
Vercel AI SDK

import { createNovuAgentToolkit } from '@novu/agent-toolkit/openai';

const toolkit = await createNovuAgentToolkit({
  secretKey: process.env.NOVU_SECRET_KEY,
  subscriberId: 'user-123',
});

// toolkit.tools          — OpenAI function tool definitions
// toolkit.handleToolCall — execute a tool call and return a tool message

The returned toolkit provides:

tools — Array of OpenAI-compatible function tool definitions.
handleToolCall(toolCall) — Executes a tool call and returns a \{ role: 'tool', tool_call_id, content \} message ready to append to the conversation.

import { createNovuAgentToolkit } from '@novu/agent-toolkit/langchain';

const toolkit = await createNovuAgentToolkit({
  secretKey: process.env.NOVU_SECRET_KEY,
  subscriberId: 'user-123',
});

// toolkit.tools — DynamicStructuredTool[] ready for LangChain agents

The returned toolkit provides:

tools — Array of DynamicStructuredTool instances that can be passed directly to LangChain agents or executors.

import { createNovuAgentToolkit } from '@novu/agent-toolkit/ai-sdk';

const toolkit = await createNovuAgentToolkit({
  secretKey: process.env.NOVU_SECRET_KEY,
  subscriberId: 'user-123',
});

// toolkit.tools — ToolSet compatible with generateText / streamText

The returned toolkit provides:

tools — A ToolSet object that can be passed to generateText, streamText, or other Vercel AI SDK functions.

Built-in Tools

The toolkit ships with two built-in tools that are always available regardless of which workflows you have configured.

`trigger_workflow`

Triggers any Novu workflow by its identifier. Use this as a generic entry point to send notifications.

Parameter	Type	Required	Description
`workflowId`	`string`	Yes	The workflow identifier to trigger.
`payload`	`Record<string, unknown>`	No	Data passed to the workflow for rendering notification content.
`overrides`	`Record<string, unknown>`	No	Provider-specific configuration overrides.
`subscriberId`	`string`	No	Target subscriber (defaults to configured `subscriberId`).
`transactionId`	`string`	No	Unique key for deduplication.

`update_preferences`

Updates notification channel preferences for a subscriber, either globally or for a specific workflow.

Parameter	Type	Required	Description
`workflowId`	`string`	No	Scope to a specific workflow. Omit for global preferences.
`channels`	`object`	No	Channel toggles: `email`, `sms`, `push`, `inApp`, `chat`.
`subscriberId`	`string`	No	Target subscriber (defaults to configured `subscriberId`).

Dynamic Workflow Tools

On initialization the toolkit fetches your Novu workflows and creates a dedicated tool for each one. These tools are named trigger_<workflow_id> (with hyphens replaced by underscores) and include the workflow’s payload schema so the LLM knows exactly what data to provide. Filter which workflows are exposed using the workflows config option:

const toolkit = await createNovuAgentToolkit({
  secretKey: process.env.NOVU_SECRET_KEY,
  subscriberId: 'user-123',
  workflows: {
    tags: ['ai-agent'],
    workflowIds: ['welcome-email', 'order-confirmation'],
  },
});

For example, if you have a workflow with ID welcome-email, the toolkit generates a trigger_welcome_email tool whose parameter schema matches the workflow’s payloadSchema. The LLM sees a purpose-built tool instead of a generic trigger, which improves accuracy and reduces prompt engineering.

Use Cases

Customer support agents — Let an AI agent send order confirmations, shipping updates, or support ticket notifications through Novu workflows.
Internal tooling — Build Slack bots or internal agents that trigger team notifications, incident alerts, or onboarding workflows.
Preference management — Allow users to manage their notification preferences through a conversational AI interface.
Multi-channel broadcasting — Enable agents to send coordinated notifications across email, SMS, push, in-app, and chat from a single tool call.

Source Code

The @novu/agent-toolkit package is part of the Novu monorepo on the next branch.

Package Structure

packages/agent-toolkit/
├── src/
│   ├── index.ts              # Main entry point
│   ├── core/                  # Core toolkit classes and types
│   │   ├── novu-toolkit.ts    # NovuToolkit class (initialization, workflow discovery)
│   │   ├── novu-tool.ts       # NovuTool factory function
│   │   └── types.ts           # NovuToolkitConfig, NovuToolDefinition types
│   ├── tools/                 # Built-in tool definitions
│   │   ├── trigger-workflow.ts
│   │   ├── preferences.ts
│   │   └── workflows-as-tools.ts  # Dynamic workflow-to-tool conversion
│   ├── openai/                # OpenAI adapter
│   ├── langchain/             # LangChain adapter
│   └── ai-sdk/                # Vercel AI SDK adapter
├── package.json
├── tsconfig.json
└── tsup.config.ts

Available Exports

Import Path	Description
`@novu/agent-toolkit`	Core `NovuToolkit` class, `NovuTool` factory, and types.
`@novu/agent-toolkit/openai`	OpenAI adapter with `createNovuAgentToolkit`.
`@novu/agent-toolkit/langchain`	LangChain adapter with `createNovuAgentToolkit`.
`@novu/agent-toolkit/ai-sdk`	Vercel AI SDK adapter with `createNovuAgentToolkit`.
`@novu/agent-toolkit/core`	Core classes and types (for building custom adapters).

​What is the Agent Toolkit?

​Installation

​Quick Start

​Configuration

​Framework Adapters

​Built-in Tools

​trigger_workflow

​update_preferences

​Dynamic Workflow Tools

​Use Cases

​Source Code

​Package Structure

​Available Exports

What is the Agent Toolkit?

Installation

Quick Start

Configuration

Framework Adapters

Built-in Tools

`trigger_workflow`

`update_preferences`

Dynamic Workflow Tools

Use Cases

Source Code

Package Structure

Available Exports