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. For LangGraph tools that need replay mocking, the first-class integration intercepts ToolNode execution so an output mock can be returned without running the tool against the real world. Canonical signatures: TypeScript reference · Python reference

Supported Languages

Language	Method	Status
TypeScript	`getLangGraphCallbackHandler()`	✅ Supported
Python	`get_langgraph_callback_handler()`	✅ Supported
TypeScript	`getLangGraphIntegration()` for replayable `ToolNode` tools	🧪 Experimental (alpha)
Python	`get_langgraph_integration()` for replayable `ToolNode` tools	🧪 Experimental (alpha)
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]},
)

Mock LangGraph tool calls on replay

Experimental (alpha): The tool replay integration uses public LangGraph APIs, but its API and matching behavior may change before it is stable. The callback-only tracing APIs above remain fully supported.

Callbacks observe tool execution but cannot prevent it. Use the first-class LangGraph integration when tools need output mocks during replay. It combines:

wrapTools() in TypeScript, or LangGraph’s native ToolNode hooks in Python, at the tool execution boundary
createInvoker() / create_invoker() for the normal graph entry point; it adds the callback handler and replayable root together
callbackHandler / callback_handler and wrapInvoke() / wrap_invoke() as low-level primitives for workflows with meaningful application work around the graph invocation

import { Bitfab } from "@bitfab/sdk"
import { END, MessagesAnnotation, START, StateGraph } from "@langchain/langgraph"
import { ToolNode, toolsCondition } from "@langchain/langgraph/prebuilt"

const bitfab = new Bitfab({ apiKey: process.env.BITFAB_API_KEY })
const integration = bitfab.getLangGraphIntegration("support-agent")
const tools = integration.wrapTools([lookupCustomer, searchDocs])
const modelWithTools = model.bindTools(tools)
const graph = new StateGraph(MessagesAnnotation)
  .addNode("agent", async (state: typeof MessagesAnnotation.State) => ({
    messages: [await modelWithTools.invoke(state.messages)],
  }))
  .addNode("tools", new ToolNode(tools))
  .addEdge(START, "agent")
  .addConditionalEdges("agent", toolsCondition, ["tools", END])
  .addEdge("tools", "agent")
  .compile()

const runSupportAgent = integration.createInvoker(graph)

await runSupportAgent(input)
await bitfab.replay("support-agent", runSupportAgent, { limit: 10 })

import os

from bitfab import Bitfab
from langgraph.graph import START, MessagesState, StateGraph
from langgraph.prebuilt import ToolNode, tools_condition

bitfab = Bitfab(api_key=os.environ["BITFAB_API_KEY"])
integration = bitfab.get_langgraph_integration("support-agent")
tools = [lookup_customer, search_docs]
model_with_tools = model.bind_tools(tools)
tool_node = ToolNode(
    tools,
    wrap_tool_call=integration.wrap_tool_call,
    awrap_tool_call=integration.awrap_tool_call,
)


def call_model(state: MessagesState):
    return {"messages": [model_with_tools.invoke(state["messages"])]}


builder = StateGraph(MessagesState)
builder.add_node("agent", call_model)
builder.add_node("tools", tool_node)
builder.add_edge(START, "agent")
builder.add_conditional_edges("agent", tools_condition)
builder.add_edge("tools", "agent")
graph = builder.compile()


run_support_agent = integration.create_invoker(graph)
run_support_agent(input)
bitfab.replay("support-agent", run_support_agent, limit=10)

Python uses LangGraph’s native interception API directly: Bitfab supplies the two hook callables and the application remains responsible for constructing and configuring ToolNode. LangGraph JS does not currently expose equivalent tool-call hooks, so the TypeScript integration wraps each tool’s public Runnable invoke() method and returns a normal tools array for bindTools() and ToolNode. It does not subclass ToolNode or depend on protected internals. The invoker uses LangGraph’s public withConfig() / with_config() API, so invocation-time configuration and existing callbacks are preserved. Only the graph input is recorded as the replay root input; callback managers and runtime configuration are not serialized. For an async-only Python graph, use create_async_invoker() and replay the returned async callable. When input preparation or post-processing should be inside the same trace, keep using the low-level form: pass callbackHandler / callback_handler in the graph invocation config and wrap the full application function with wrapInvoke() / wrap_invoke(). By default, every integration-managed tool is marked for replay mocking. Pass mockToolsOnReplay: ["searchDocs"] or mock_tools_on_replay=["search_docs"] to mark only selected tools; pass false to leave them unmarked. Replay’s mock: "all" strategy and matching mock overrides can still substitute any integration-managed tool. The integration records a serializable view of LangGraph’s result and reconstructs a real ToolMessage or Command during replay. Every reconstructed tool message uses the current invocation’s tool-call ID, so a recorded result remains valid when the model generates a different ID. Recorded tool calls are matched by tool name and occurrence order within one replay item. If a tool is marked for replay mocking and that occurrence has no recorded output or matching override, Bitfab refuses to execute the live tool. LangGraph then applies the ToolNode’s configured error behavior. Use replay with mock: "none" only when running real tools is intentional.

Current alpha limitations

Repeated tools are order-sensitive. Calls are matched by tool name and occurrence order. If the same tool runs concurrently, or current code changes its call order, replay can select the wrong recorded occurrence. Use this integration first on graphs whose same-name tool calls have deterministic ordering.
Every tool call must cross the integration boundary. In TypeScript, use the array returned by wrapTools() everywhere the graph references those tools. In Python, construct each replayable ToolNode with the integration’s hooks. Calling the original tool directly is not intercepted and cannot be mocked.
TypeScript proxies the public invoke() method. Standard LangChain tools work through this boundary. Custom tool objects that depend on exact object identity, custom proxy behavior, or a path that bypasses invoke() may be incompatible.
Tool inputs and outputs must serialize. Native ToolMessage and Command results are supported. Streaming tool results and unusual custom return objects are not yet guaranteed to round-trip.
Fail-closed errors follow ToolNode error handling. When tool-error handling is enabled, LangGraph may turn a missing-recording error into an error ToolMessage and let the graph continue. Configure the node to propagate tool errors if a missing recording should abort the replay.
The convenience invoker covers invoke() / ainvoke(). For streaming, batch execution, or custom graph entry points, use callbackHandler / callback_handler and wrapInvoke() / wrap_invoke() directly.

Test the replay path with non-production dependencies before relying on it for a workflow with unsafe side-effects. Callback-only tracing does not provide this protection because callbacks run after tool execution has already started.

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"

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

const result = await graph.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[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

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

result = graph.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

Callback-only graphs are 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. Their observed framework calls run live during replay. 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 runtime wiring inside the callable (config["configurable"] values, dependency objects, API keys); the trace records only the graph state. Put unsafe calls behind replay-mockable marked spans; use a no-op only for a replay-only callback slot with no recorded call to mock. For LangGraph tools that must not run, use getLangGraphIntegration() / get_langgraph_integration() as shown above. 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

Primitives

Account

SDKs

Framework Integrations

Integrations

Web Portal

Reference

Changelog

LangGraph / LangChain

Supported Languages

Quick Start

Mock LangGraph tool calls on replay

Current alpha limitations

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

​Mock LangGraph tool calls on replay

​Current alpha limitations

​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

Mock LangGraph tool calls on replay

Current alpha limitations

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