LangChain reference

Already connecting an agent? Start with Connect LangChain to Slack. This page is the adapter API.

@novu/framework/langchain lets you write agent handlers with LangChain. Return a LangChainAgentConfig from onMessage and Novu runs createAgent().invoke() for you - including tool approval gating and resume from ctx.history.

Before you start

Completed Connect LangChain? Your agent, bridge, and project are already set up - jump to Minimal agent.

Otherwise connect first, then come back here for adapter details.

Prerequisites

Install the framework, LangChain, and a model provider:

@novu/framework, langchain, and @langchain/core are required; pick one provider package. Examples on this page use OpenAI model strings - see the LangChain integrations catalog for others.

Minimal agent

Import agent from @novu/framework/langchain, then return a LangChainAgentConfig from onMessage:

import { tool } from '@langchain/core/tools';
import { agent } from '@novu/framework/langchain';
import { z } from 'zod';

const lookupOrder = tool(
  async ({ orderId }) => ({ orderId, status: 'shipped' }),
  {
    name: 'lookupOrder',
    description: 'Look up an order by ID',
    schema: z.object({ orderId: z.string() }),
  },
);

export const supportAgent = agent('support-bot', {
  onMessage: async (message, ctx) => ({
    model: 'openai:gpt-4o',
    system: 'You are a helpful support agent.',
    tools: [lookupOrder],
  }),
});

Make sure the agent id ('support-bot') matches the Identifier in your dashboard, and that this handler is registered on your bridge route - see Connecting your app.

On Next.js, model strings need LangChain listed in serverExternalPackages. See Next.js and Turbopack. npx novu connect --runtime langchain configures this for you.

For handlers, replies, signals, typing, and tool approval, see Building blocks. The sections below cover what's specific to the LangChain adapter.

Returning from onMessage

On the LangChain path, onMessage (and onToolApproval) can return a LangChain result in addition to the usual reply types:

Shorthand when you only need onMessage: pass the handler directly.

const supportAgent = agent('support-bot', async (message, ctx) => ({
  model: 'openai:gpt-4o',
  tools: [lookupOrder],
}));

Next.js and Turbopack

LangChain resolves provider packages for model strings via a runtime dynamic import(). Next.js Turbopack cannot analyze that expression and fails with:

Cannot find module as expression is too dynamic

Keep model strings and externalize LangChain in next.config.mjs:

/** @type {import('next').NextConfig} */
const nextConfig = {
  serverExternalPackages: [
    'langchain',
    '@langchain/core',
    '@langchain/langgraph',
    '@langchain/langgraph-checkpoint',
    '@langchain/openai', // plus any other @langchain/* provider you use
  ],
};

export default nextConfig;

npx novu connect --runtime langchain scaffolds this for you (and adds the provider package you selected).

toLangChainMessages()

Convert ctx.history into LangChain BaseMessage[] when you invoke an agent or graph yourself:

import { toLangChainMessages } from '@novu/framework/langchain';

const messages = toLangChainMessages(ctx.history);

• ctx.history already includes the current inbound message - do not append the message argument on top of it.
• Pass system only when you are not setting system on LangChainAgentConfig - Novu forwards that field to createAgent({ prompt }) for you.
• Tool approval cycles in history are mapped automatically, so auto-resume (below) works.

Invoke your own agent

If you already run a LangChain agent or graph in your handler, return its messages and Novu delivers the final text - tool approval is not managed on this path:

import { createAgent } from 'langchain';
import { agent, toLangChainMessages } from '@novu/framework/langchain';

const billingAgent = createAgent({ model: 'openai:gpt-4o', tools: [lookupOrder] });

export const supportAgent = agent('support-bot', {
  onMessage: async (message, ctx) => {
    const result = await billingAgent.invoke({
      messages: toLangChainMessages(ctx.history),
    });

    return { messages: result.messages };
  },
});

To stream live updates in the thread, post a reply and update it with ReplyHandle.edit() as your graph produces chunks - the adapter does not stream token-by-token when you return a result.

Automatic tool approval

Set needsApproval on LangChainAgentConfig. When the model calls a gated tool, Novu posts the Approve / Deny card and pauses the turn. After the user decides, Novu re-runs onMessage - toLangChainMessages(ctx.history) replays the approval cycle so the agent continues with no extra code from you.

import { tool } from '@langchain/core/tools';
import { agent } from '@novu/framework/langchain';
import { z } from 'zod';

const issueRefund = tool(
  async ({ orderId }) => refund(orderId),
  {
    name: 'issueRefund',
    description: 'Issue a refund for an order',
    schema: z.object({ orderId: z.string() }),
  },
);

export const supportAgent = agent('support-bot', {
  onMessage: async (message, ctx) => ({
    model: 'openai:gpt-4o',
    system: 'You are a helpful support agent.',
    tools: [issueRefund],
    needsApproval: (toolCall) => toolCall.name === 'issueRefund',
  }),
});

Add onToolApproval when you need a hook after the click. See Tool approval for the full API.

Turn failures and onError

When Novu runs createAgent().invoke() for a returned LangChainAgentConfig and the invoke rejects - for example the provider errors or the model call fails - the failure propagates to the same dispatch boundary as a thrown handler error. The same applies when you await your own agent or graph in onMessage and the invoke throws before you return. Register onError on the agent to log, suppress user notification, send custom copy, or fall back to Novu's generic message.

export const supportAgent = agent('support-bot', {
  onMessage: async (message, ctx) => ({
    model: 'openai:gpt-4o',
    system: 'You are a helpful support agent.',
    tools: [lookupOrder],
  }),

  onError: async (error, ctx) => {
    console.error(error.message, error.cause);
    // return nothing → generic user copy from Novu
    // return { suppress: true } → silent
    // return 'Custom apology' → your copy
  },
});

A gated tool waiting for user approval pauses the turn with an approval card - that is not a turn failure and does not trigger onError. See Handlers and context - onError for the full pipeline.

Related