Add Mortem observability tracing to LangChain agents

Mortem integrates with LangChain through a callback handler. You attach the handler to your chain or agent, and Mortem automatically records each LLM call and tool invocation as a trace event. No changes to your prompt templates, chains, or tool definitions are required.

What gets captured

The MortemCallbackHandler intercepts LangChain lifecycle events and records:

LLM calls — model name, prompts passed to the LLM, and the full output
Tool calls — tool name, input string, and output string
Errors — failures on any LLM or tool step are recorded as failed events on the trace

Prerequisites

Install the SDK and create an agent in the dashboard before continuing. You need MORTEM_API_KEY and MORTEM_AGENT_ID set in your environment. LangChain (langchain and @langchain/core) must be installed separately — Mortem does not depend on them.

Integration

Initialize the Mortem client

Create a Mortem instance at module scope.

import { Mortem } from "@mortemlabs/sdk"

const mortem = new Mortem({
  apiKey: process.env.MORTEM_API_KEY ?? "",
  agentId: process.env.MORTEM_AGENT_ID,
  verifyToken: process.env.MORTEM_VERIFY_TOKEN, // remove after first verified run
  environment: "devnet",
})

verifyToken is only needed during your first deployment. Once the dashboard shows the agent as verified, remove MORTEM_VERIFY_TOKEN from your environment and code.

Create the callback handler

Call mortem.langchainHandler() to get a MortemCallbackHandler instance. This is a synchronous call that returns the handler immediately.

const handler = mortem.langchainHandler()

Alternatively, import createLangChainHandlerAsync directly from the SDK if you want a handler that dynamically subclasses BaseCallbackHandler from @langchain/core. This is useful when you need the handler to satisfy strict instanceof checks in framework code:

import { createLangChainHandlerAsync } from "@mortemlabs/sdk"

const handler = await createLangChainHandlerAsync()

Use createLangChainHandlerAsync when passing the handler to LangChain APIs that require an instance of BaseCallbackHandler. The synchronous mortem.langchainHandler() works for most use cases where duck-typing is sufficient.

Attach the handler to your chain or agent

Pass the handler in the callbacks array when invoking your chain. You can add it at the chain level, the model level, or at the point of invocation — LangChain propagates callbacks through the call tree.

import { ChatOpenAI } from "@langchain/openai"
import { HumanMessage } from "@langchain/core/messages"

const model = new ChatOpenAI({ model: "gpt-4o" })

const response = await model.invoke(
  [new HumanMessage("Should I swap 1 SOL for JUP right now?")],
  { callbacks: [handler] }
)

import { ChatOpenAI } from "@langchain/openai"
import { PromptTemplate } from "@langchain/core/prompts"
import { StringOutputParser } from "@langchain/core/output_parsers"

const prompt = PromptTemplate.fromTemplate(
  "You are a Solana trading bot. {question}"
)
const model = new ChatOpenAI({ model: "gpt-4o" })
const parser = new StringOutputParser()

const chain = prompt.pipe(model).pipe(parser)

const response = await chain.invoke(
  { question: "Should I swap 1 SOL for JUP right now?" },
  { callbacks: [handler] }
)

Wrap the invocation in a Mortem session

Create a session with mortem.startSession and run the chain inside session.run. This links the callback handler’s events to the active trace.

const session = await mortem.startSession({
  inputSummary: "Evaluate trade setup and produce a recommendation",
  tags: ["langchain", "devnet"],
})

try {
  const result = await session.run(async () => {
    return chain.invoke(
      { question: "Should I swap 1 SOL for JUP right now?" },
      { callbacks: [handler] }
    )
  })

  await session.complete(result)
} catch (error) {
  await session.fail(error)
} finally {
  await mortem.close()
}

Always call mortem.close() in a finally block. It flushes the trace buffer and ensures all events reach the ingest service before the process exits.

Complete example

import { Mortem, createLangChainHandlerAsync } from "@mortemlabs/sdk"
import { ChatOpenAI } from "@langchain/openai"
import { PromptTemplate } from "@langchain/core/prompts"
import { StringOutputParser } from "@langchain/core/output_parsers"

const mortem = new Mortem({
  apiKey: process.env.MORTEM_API_KEY ?? "",
  agentId: process.env.MORTEM_AGENT_ID,
  verifyToken: process.env.MORTEM_VERIFY_TOKEN,
  environment: "devnet",
})

const handler = await createLangChainHandlerAsync()

const prompt = PromptTemplate.fromTemplate(
  "You are a Solana trading bot. {question}"
)
const model = new ChatOpenAI({ model: "gpt-4o" })
const parser = new StringOutputParser()

const chain = prompt.pipe(model).pipe(parser)

const session = await mortem.startSession({
  inputSummary: "Evaluate trade setup and produce a recommendation",
  tags: ["langchain", "devnet"],
})

try {
  const result = await session.run(async () => {
    return chain.invoke(
      { question: "Should I swap 1 SOL for JUP right now?" },
      { callbacks: [handler] }
    )
  })

  await session.complete(result)
} catch (error) {
  await session.fail(error)
} finally {
  await mortem.close()
}

Handler variants

The SDK exports three ways to create a LangChain callback handler:

Method	Description
`mortem.langchainHandler()`	Synchronous. Returns a `MortemCallbackHandler` instance immediately. Works via duck-typing for most LangChain APIs.
`createLangChainHandler()`	Same as above, exported directly from `@mortemlabs/sdk`. Use this if you import the function directly rather than through the `Mortem` client.
`createLangChainHandlerAsync()`	Async. Dynamically imports `@langchain/core/callbacks/base` and subclasses `BaseCallbackHandler`. Use when strict `instanceof` checks are required. Falls back to the synchronous handler if `@langchain/core` is not installed.

You can import createLangChainHandler and createLangChainHandlerAsync directly from @mortemlabs/sdk without a Mortem client instance. This is useful if you manage the handler lifecycle separately from the client.

Agent callbacks

For LangChain agents, pass the handler in the callbacks array at the agent executor level. LangChain propagates the handler to all nested chains and tools automatically:

import { AgentExecutor } from "langchain/agents"

const executor = new AgentExecutor({
  agent,
  tools,
  callbacks: [handler],
})

const result = await session.run(() =>
  executor.invoke({ input: "Should I swap 1 SOL for JUP?" })
)

Get Started

SDK

Dashboard

Guides

Reference

Add Mortem observability tracing to LangChain agents

What gets captured

Prerequisites

Integration

Complete example

Handler variants

Agent callbacks

​What gets captured

​Prerequisites

​Integration

​Complete example

​Handler variants

​Agent callbacks

What gets captured

Prerequisites

Integration

Complete example

Handler variants

Agent callbacks