LangGraph / LangChain

Bitfab integrates with LangGraph and LangChain via a callback handler that automatically captures graph node execution, LLM calls, tool invocations, and retriever queries as traced spans, with no manual withSpan or @span decorators needed on your graph nodes. Canonical signatures: TypeScript reference · Python reference

Supported Languages

Language	Method	Status
TypeScript	`getLangGraphCallbackHandler()`	✅ Supported
Python	`get_langgraph_callback_handler()`	✅ Supported
Ruby	-	Not yet supported
Go	-	Not yet supported

Working with plain LangChain (no LangGraph)? The same handler serves both, and the SDK exposes it under a LangChain name too: getLangChainCallbackHandler() / get_langchain_callback_handler() and the BitfabLangChainCallbackHandler class are aliases of their LangGraph counterparts. Use whichever name matches your stack; the behavior is identical.

Quick Start

import { Bitfab } from "@bitfab/sdk"

const bitfab = new Bitfab({ apiKey: process.env.BITFAB_API_KEY })
const handler = bitfab.getLangGraphCallbackHandler("my-agent")

const result = await agent.invoke(
  { messages: [{ role: "user", content: "What's the weather?" }] },
  { callbacks: [handler] },
)

import os
from bitfab import Bitfab

bitfab = Bitfab(api_key=os.environ["BITFAB_API_KEY"])
handler = bitfab.get_langgraph_callback_handler("my-agent")

result = agent.invoke(
    {"messages": [{"role": "user", "content": "What's the weather?"}]},
    config={"callbacks": [handler]},
)

Plain LangChain Chains

The handler works the same way on LangChain chains and runnables; pass it in callbacks when invoking:

const handler = bitfab.getLangChainCallbackHandler("summarize-doc")

const result = await chain.invoke(
  { document: docText },
  { callbacks: [handler] },
)

handler = bitfab.get_langchain_callback_handler("summarize-doc")

result = chain.invoke(
    {"document": doc_text},
    config={"callbacks": [handler]},
)

What Gets Captured

The callback handler hooks into LangChain’s callback system and creates spans automatically:

Event	Span Type	Captured Data
Graph nodes (chains)	`agent`	Configured run name or node name, inputs, outputs, LangGraph metadata
Chat model calls	`llm`	Configured run name or model name, messages (role/content), token usage, LangGraph metadata
LLM calls	`llm`	Configured run name or model name, prompts, token usage, LangGraph metadata
Tool invocations	`function`	Configured run name or tool name, input, output
Retriever queries	`function`	Configured run name or retriever name, query, documents

Trace Lifecycle

The first callback in a framework invocation becomes the trace root. For full LangGraph runs this is usually a chain/graph node; for plain LangChain usage it can also be a direct chat model, LLM, tool, or retriever call. The handler registers that root immediately as a pending external trace, then completes it when the root callback ends, so long-running invocations can appear as in progress before their final output is available. If the handler runs inside an active Bitfab withSpan / @span root, its spans attach to that outer trace instead. In that case the handler still records the framework span tree, but the outer Bitfab root owns final trace completion. You do not need an outer withSpan / @span root when the workflow is just the LangGraph or LangChain invocation. Add one only when there is meaningful application work around invoke() that should be part of the same trace, such as input preparation, retrieval outside LangChain, post-processing, persistence, or downstream service calls. When you do add an outer root, use the same trace function key for the outer span and the callback handler.

LangGraph Metadata

LangGraph-specific metadata is automatically extracted and stored as span context:

langgraph_step: Current step number
langgraph_node: Current node name
langgraph_triggers: What triggered this node
langgraph_path: Execution path
langgraph_checkpoint_ns: Checkpoint namespace

Token Usage

For LLM spans, token usage is captured from the LLM result. The handler prefers LangChain’s standardized usage_metadata on each generation’s message (which is also how usage arrives on the final aggregated chunk of streaming runs), then falls back to provider-native response_metadata shapes (OpenAI, Anthropic, Google Gemini / Vertex), and finally the legacy llm_output.token_usage location:

inputTokens: Prompt tokens. For Anthropic, cache reads and cache creation are added back so the value reflects the true prompt size.
outputTokens: Completion tokens
totalTokens: Total tokens
cachedInputTokens: Cached prompt tokens, from usage_metadata.input_token_details.cache_read, OpenAI prompt_tokens_details.cached_tokens, or Anthropic cache_read_input_tokens
model: Model name (extracted from serialized config or metadata)

When a result has multiple generations, usage is summed across them. Only provider-reported numbers are recorded: if the provider reports nothing (for example OpenAI streaming without stream_usage: true / stream_options: {"include_usage": true}), the fields are left unset rather than estimated.

TypeScript

Installation

npm install @bitfab/sdk @langchain/core @langchain/langgraph @langchain/openai zod

Method Signature

bitfab.getLangGraphCallbackHandler(traceFunctionKey: string): BitfabLangGraphCallbackHandler

Parameters:

traceFunctionKey (string, required): Groups all traces from this handler under one key in Bitfab

Returns: A BitfabLangGraphCallbackHandler that implements the LangChain callback handler interface (duck-typed, no @langchain/core dependency required).

Usage

import { Bitfab } from "@bitfab/sdk"
import { ChatOpenAI } from "@langchain/openai"
import { createReactAgent } from "@langchain/langgraph/prebuilt"
import { tool } from "@langchain/core/tools"
import { z } from "zod"

const bitfab = new Bitfab({ apiKey: process.env.BITFAB_API_KEY })

const getWeather = tool(
  async ({ city }) => {
    return `Sunny, 72°F in ${city}`
  },
  {
    name: "getWeather",
    description: "Get the current weather for a city.",
    schema: z.object({ city: z.string() }),
  },
)

const model = new ChatOpenAI({ model: "gpt-4o-mini" })
const agent = createReactAgent({ llm: model, tools: [getWeather] })

// Create the callback handler
const handler = bitfab.getLangGraphCallbackHandler("weather-agent")

// Pass as a callback: all graph execution is traced automatically
const result = await agent.invoke(
  { messages: [{ role: "user", content: "What's the weather in SF?" }] },
  { callbacks: [handler] },
)

Callback Hooks

LangChain invokes these callback hooks on the handler:

Method	Creates Span	Type
`handleChainStart(...)`	Yes	`agent`
`handleChainEnd(...)`	Completes span	-
`handleChainError(...)`	Completes span with error	-
`handleChatModelStart(...)`	Yes	`llm`
`handleLLMStart(...)`	Yes	`llm`
`handleLLMEnd(...)`	Completes span with tokens	-
`handleLLMError(...)`	Completes span with error	-
`handleToolStart(...)`	Yes	`function`
`handleToolEnd(...)`	Completes span	-
`handleToolError(...)`	Completes span with error	-
`handleRetrieverStart(...)`	Yes	`function`
`handleRetrieverEnd(...)`	Completes span	-
`handleRetrieverError(...)`	Completes span with error	-

Nesting with Core Tracing

The handler integrates with Bitfab’s span stack. If the application has meaningful work around the graph or chain invocation, create a same-key withSpan wrapper around that outer workflow and the LangGraph spans nest as children. Handler-only instrumentation is enough for a plain LangGraph / LangChain call:

const pipeline = bitfab.getFunction("my-pipeline")

const tracedRun = pipeline.withSpan(
  { name: "RunAgent", type: "agent" },
  async (query: string) => {
    const handler = pipeline.getLangGraphCallbackHandler() // same key as the root
    return agent.invoke(
      { messages: [{ role: "user", content: query }] },
      { callbacks: [handler] },
    )
  },
)

await tracedRun("What's the weather?")
// LangGraph spans appear nested under the "RunAgent" span

Use the same trace function key in both places. Both bitfab.getFunction(...) and bitfab.getLangGraphCallbackHandler(...) take a key; pass the same key ("my-pipeline" above) to both. If you use two different keys here, the same flow will register as two separate overlapping trace functions in the dashboard, an anti-pattern to avoid.

Error Handling

GraphBubbleUp: LangGraph’s internal interrupt mechanism. Detected automatically and completed silently (no error recorded).
All other errors: Error message captured in the span. The handler never throws; all callbacks are wrapped in try/catch.
Missing serialized callback data: Some framework versions can pass nullish serialized payloads. The handler still records the span using fallback names such as chain, llm, tool, or retriever.
Reusability: The handler resets after each root span completes and can be reused across multiple invocations.

Python

Installation

pip install bitfab-py langchain-core langgraph langchain-openai

Method Signature

bitfab.get_langgraph_callback_handler(trace_function_key: str) -> BitfabLangGraphCallbackHandler

Parameters:

trace_function_key (str, required): Groups all traces from this handler under one key in Bitfab

Returns: A BitfabLangGraphCallbackHandler instance that extends BaseCallbackHandler from langchain-core.

Usage

import os
from bitfab import Bitfab
from langchain_openai import ChatOpenAI
from langchain_core.tools import tool
from langgraph.prebuilt import create_react_agent

bitfab = Bitfab(api_key=os.environ["BITFAB_API_KEY"])

@tool
def get_weather(city: str) -> str:
    """Get the current weather for a city."""
    return f"Sunny, 72°F in {city}"

model = ChatOpenAI(model="gpt-4o-mini")
agent = create_react_agent(model, tools=[get_weather])

# Create the callback handler
handler = bitfab.get_langgraph_callback_handler("weather-agent")

# Pass as a callback: all graph execution is traced automatically
result = agent.invoke(
    {"messages": [{"role": "user", "content": "What's the weather in SF?"}]},
    config={"callbacks": [handler]},
)

Callback Methods

The handler implements these LangChain callback methods:

Method	Creates Span	Type
`on_chain_start(serialized, inputs, *, run_id, parent_run_id?, ...)`	Yes	`agent`
`on_chain_end(outputs, *, run_id, ...)`	Completes span	-
`on_chain_error(error, *, run_id, ...)`	Completes span with error	-
`on_chat_model_start(serialized, messages, *, run_id, ...)`	Yes	`llm`
`on_llm_start(serialized, prompts, *, run_id, ...)`	Yes	`llm`
`on_llm_end(response, *, run_id, ...)`	Completes span with tokens	-
`on_llm_error(error, *, run_id, ...)`	Completes span with error	-
`on_tool_start(serialized, input_str, *, run_id, ...)`	Yes	`function`
`on_tool_end(output, *, run_id, ...)`	Completes span	-
`on_tool_error(error, *, run_id, ...)`	Completes span with error	-
`on_retriever_start(serialized, query, *, run_id, ...)`	Yes	`function`
`on_retriever_end(documents, *, run_id, ...)`	Completes span	-
`on_retriever_error(error, *, run_id, ...)`	Completes span with error	-

Nesting with Core Tracing

Bind the key once with get_function so the root and the handler share it (no repeated string to keep in sync). Use this only when the application has meaningful work around the graph or chain invocation; handler-only instrumentation is enough for a plain LangGraph / LangChain call:

pipeline = bitfab.get_function("my-pipeline")


@pipeline.span(type="agent")
def run_agent(query: str):
    handler = pipeline.get_langgraph_callback_handler()  # same key as the root
    return agent.invoke(
        {"messages": [{"role": "user", "content": query}]},
        config={"callbacks": [handler]},
    )


run_agent("What's the weather?")
# LangGraph spans appear nested under the "my-pipeline" span

Use the same trace function key for the root and the handler. Binding via get_function does this for you. The plain @bitfab.span("my-pipeline") / bitfab.get_langgraph_callback_handler("my-pipeline") forms work too, but you must pass the same key to both, otherwise the same flow registers as two separate overlapping trace functions in the dashboard, an anti-pattern to avoid.

Error Handling

GraphBubbleUp: LangGraph’s internal interrupt mechanism. Detected automatically and completed silently (no error recorded).
All other errors: repr(error) captured in the span. The handler never raises; all callbacks are wrapped in try/except.
Missing serialized callback data: Some framework versions can pass nullish serialized payloads. The handler still records the span using fallback names such as chain, llm, tool, or retriever.
Reusability: The handler resets after each root span completes and can be reused across multiple invocations.

Replay

Handler-instrumented graphs are fully replayable, even though no @span / withSpan root exists in the application code. The handler records the graph invocation as the root span, with the initial graph state as the recorded input. To replay, pass the handler’s key plus a plain callable that re-invokes the graph (the SDK wraps it internally):

handler = bitfab.get_langgraph_callback_handler("weather-agent")  # same key

def replay_weather_agent(state):  # recorded state arrives as one argument
    return agent.invoke(state, config={"callbacks": [handler]})

result = bitfab.replay("weather-agent", replay_weather_agent, limit=10)

const handler = bitfab.getLangGraphCallbackHandler("weather-agent")

const replayWeatherAgent = async (
  state: AgentState,  // recorded state arrives as a single argument
) => agent.invoke(state, { callbacks: [handler] })

const result = await bitfab.replay("weather-agent", replayWeatherAgent, {
  limit: 10,
})

The key is the only link between the handler-recorded production traces and the replay callable. Rebuild any runtime environment inside the callable (config["configurable"] values, dependency objects, API keys); the trace records only the graph state. Use no-op substitutes for side-effectful wiring (billing callbacks, notification senders). On SDKs that predate explicit-key replay, wrap the callable under the same key yourself (Python: @bitfab.span("weather-agent") with a (**state) signature; TypeScript: getFunction("weather-agent").withSpan(...)). Full details: Replaying handler-instrumented functions in the Python SDK and TypeScript SDK pages.

Getting Started

Account

SDKs

Framework Integrations

Integrations

Web Portal

Reference

Changelog

LangGraph / LangChain

Supported Languages

Quick Start

Plain LangChain Chains

What Gets Captured

Trace Lifecycle

LangGraph Metadata

Token Usage

TypeScript

Installation

Method Signature

Usage

Callback Hooks

Nesting with Core Tracing

Error Handling

Python

Installation

Method Signature

Usage

Callback Methods

Nesting with Core Tracing

Error Handling

Replay

​Supported Languages

​Quick Start

​Plain LangChain Chains

​What Gets Captured

​Trace Lifecycle

​LangGraph Metadata

​Token Usage

​TypeScript

​Installation

​Method Signature

​Usage

​Callback Hooks

​Nesting with Core Tracing

​Error Handling

​Python

​Installation

​Method Signature

​Usage

​Callback Methods

​Nesting with Core Tracing

​Error Handling

​Replay

Supported Languages

Quick Start

Plain LangChain Chains

What Gets Captured

Trace Lifecycle

LangGraph Metadata

Token Usage

TypeScript

Installation

Method Signature

Usage

Callback Hooks

Nesting with Core Tracing

Error Handling

Python

Installation

Method Signature

Usage

Callback Methods

Nesting with Core Tracing

Error Handling

Replay