Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mutagent.io/llms.txt

Use this file to discover all available pages before exploring further.

​
LangGraph Integration (Python)

The mutagent-langgraph package provides a callback handler that captures LangGraph node executions, graph runs, and edge transitions automatically.

​
Installation

This package is coming soon to PyPI. The install command below will work once published.
pip install mutagent-langgraph
This installs mutagent-langgraph along with its dependencies. Tracing transport is provided by mutagent-sdk via the mutagent.tracing module. The langgraph SDK (>= 0.0.20) is also required and installed automatically.

​
Quick Start

1

Initialize tracing

from mutagent.tracing import init_tracing

init_tracing(api_key="mt_xxxxxxxxxxxx")
2

Create the callback handler

from mutagent_langgraph import MutagentCallbackHandler

handler = MutagentCallbackHandler()
3

Pass the handler to graph.compile()

app = graph.compile()
result = app.invoke(inputs, config={"callbacks": [handler]})
The LangGraph Pregel engine emits standard LangChain callback events enriched with langgraph_node / langgraph_step metadata. The callback handler detects these and emits SpanKind.NODE spans automatically — no manual context managers required.

​
Full Example

import os
from typing import TypedDict
from langgraph.graph import StateGraph
import asyncio
from mutagent_langgraph import MutagentCallbackHandler
from mutagent.tracing import init_tracing, shutdown_tracing

init_tracing(api_key=os.environ["MUTAGENT_API_KEY"])

handler = MutagentCallbackHandler()


class State(TypedDict):
    text: str
    sentiment: str
    response: str


def classify(state: State) -> State:
    sentiment = "positive" if "good" in state["text"].lower() else "negative"
    return {**state, "sentiment": sentiment}


def respond(state: State) -> State:
    if state["sentiment"] == "positive":
        response = "Glad to hear that!"
    else:
        response = "Sorry to hear that. How can I help?"
    return {**state, "response": response}


graph = StateGraph(State)
graph.add_node("classifier", classify)
graph.add_node("responder", respond)
graph.add_edge("classifier", "responder")
graph.set_entry_point("classifier")
graph.set_finish_point("responder")

app = graph.compile()
result = app.invoke(
    {"text": "This is good!", "sentiment": "", "response": ""},
    config={"callbacks": [handler]},
)
print(result["response"])

asyncio.run(shutdown_tracing())

​
What Gets Traced

MutagentCallbackHandler in mutagent-langgraph captures the same events as the LangChain handler, plus LangGraph-specific node metadata:

Graph Execution

Top-level span for the entire graph invocation

Node Execution

Individual SpanKind.NODE spans for each node, tagged with node name

LLM Calls

Any LLM invocations within nodes are automatically nested

​
Span Hierarchy

​
Combining with LangChain Callback Handler

For graphs that invoke LangChain LLMs internally, the same MutagentCallbackHandler from mutagent_langgraph (or mutagent_langchain) handles everything in one pass: 
from mutagent.tracing import init_tracing
from mutagent_langgraph import MutagentCallbackHandler
from langchain_openai import ChatOpenAI

init_tracing(api_key="mt_xxxxxxxxxxxx")

handler = MutagentCallbackHandler()
llm = ChatOpenAI(model="gpt-4", callbacks=[handler])

app = graph.compile()
result = app.invoke(
    state,
    config={"callbacks": [handler]},
)
LLM spans from ChatOpenAI are automatically nested under their parent node span in MutagenT’s trace viewer.

​
Error Handling

Errors raised inside a node are automatically captured with ERROR status: 
result = app.invoke(
    state,
    config={"callbacks": [handler]},
)
# If any node raises, the span gets ERROR status and the error message is preserved.

​
TypeScript Equivalent

For the TypeScript/Node.js LangGraph integration, see the LangGraph (TypeScript) guide.