Skip to main content

​
LangGraph

LangGraph is built on LangChain’s Runnable system. The same MutagentCallbackHandler from @mutagent/langchain works automatically for all LangGraph graphs — every node execution, LLM call, tool invocation, and retriever query within the graph is captured without any LangGraph-specific instrumentation.
There is no need for a separate @mutagent/langgraph package. The @mutagent/langchain callback handler propagates through the entire graph execution tree via LangChain’s inheritable_handlers mechanism.

​
Installation

bun add @mutagent/langchain @mutagent/sdk
Peer dependencies: @mutagent/sdk >=0.1.0, @langchain/core >=1.1.8

​
Quick Start

1

Initialize tracing

Call initTracing() once at application startup.
import { initTracing } from '@mutagent/sdk/tracing';

initTracing({ apiKey: process.env.MUTAGENT_API_KEY! });
2

Create the callback handler

import { MutagentCallbackHandler } from '@mutagent/langchain';

const handler = new MutagentCallbackHandler({
  sessionId: 'my-session',  // optional
  userId: 'user-123',       // optional
});
3

Pass to graph.invoke()

const result = await graph.invoke(input, {
  callbacks: [handler],
});
// Full graph execution tree is automatically traced

​
Full Example

import { initTracing } from '@mutagent/sdk/tracing';
import { MutagentCallbackHandler } from '@mutagent/langchain';
import { StateGraph, MessagesAnnotation } from '@langchain/langgraph';
import { ChatOpenAI } from '@langchain/openai';

// 1. Initialize SDK tracing (once at app startup)
initTracing({ apiKey: process.env.MUTAGENT_API_KEY! });

// 2. Build your LangGraph graph as usual
const model = new ChatOpenAI({ model: 'gpt-4o' });

const callModel = async (state: typeof MessagesAnnotation.State) => {
  const response = await model.invoke(state.messages);
  return { messages: [response] };
};

const graph = new StateGraph(MessagesAnnotation)
  .addNode('agent', callModel)
  .addEdge('__start__', 'agent')
  .addEdge('agent', '__end__')
  .compile();

// 3. Create the handler and invoke
const handler = new MutagentCallbackHandler();
const result = await graph.invoke(
  { messages: [{ role: 'user', content: 'Hello!' }] },
  { callbacks: [handler] },
);

​
How Callback Propagation Works

When you pass the MutagentCallbackHandler to graph.invoke(), LangChain’s callback system automatically propagates it through the entire execution tree: The callback handler uses LangChain’s inheritable_handlers — meaning every child Runnable (nodes, LLMs, tools, retrievers) inside the graph automatically receives the handler. You do not need to pass it to individual nodes.

​
What Gets Traced

EventSpan KindData Captured
Graph invocationchainGraph name, input/output
Node executionchainNode name, input/output
LLM callllm.chatMessages, model, token usage
Tool calltoolTool name, input/output
Retriever queryretrievalQuery string, retrieved documents
ErrorsAnyError message, status

​
Handler Options

const handler = new MutagentCallbackHandler({
  sessionId: 'chat-session-123',  // Group traces by session
  userId: 'user-456',             // Attribute traces to a user
  tags: ['production', 'v2'],     // Filter traces by tag
  metadata: { version: '2.0' },   // Custom metadata
});
OptionTypeDescription
sessionIdstringGroup related traces into a session
userIdstringAttribute traces to a specific user
tagsstring[]Tags for filtering in the dashboard
metadataRecord<string, unknown>Custom key-value metadata

​
Migration from @mutagent/langgraph

@mutagent/langgraph and its MutagentGraphTracer are deprecated. The package now re-exports MutagentCallbackHandler from @mutagent/langchain for backwards compatibility, but will be removed in a future version.
Before (deprecated): 
import { MutagentGraphTracer } from '@mutagent/langgraph';
const tracer = new MutagentGraphTracer();
tracer.handleGraphStart('my-graph', inputs);
// ... manually call every node/edge transition
tracer.handleGraphEnd(outputs);
After (recommended): 
import { MutagentCallbackHandler } from '@mutagent/langchain';
const handler = new MutagentCallbackHandler();
const result = await graph.invoke(input, { callbacks: [handler] });

​
CLI Shortcut

mutagent integrate langgraph

​
Python

Looking for the Python LangGraph integration? See the Python LangGraph guide.