LangGraph

Trace LangGraph graphs built with the @langchain/langgraph and @langchain/core packages.

Setup

Install LangGraph alongside Braintrust and the LangChain packages you use.

pnpm add braintrust @langchain/core@^1 @langchain/langgraph@^1 @langchain/openai@^1

npm install braintrust @langchain/core@^1 @langchain/langgraph@^1 @langchain/openai@^1

Auto-instrumentation

To trace LangGraph graphs without modifying your application code, initialize Braintrust normally, then run your app with Braintrust’s import hook to patch @langchain/core at runtime. Requires @langchain/langgraph v1 or later.

Initialize Braintrust and build your graph

import { END, START, StateGraph, Annotation } from "@langchain/langgraph";
import { ChatOpenAI } from "@langchain/openai";
import { initLogger } from "braintrust";

initLogger({
  projectName: "My Project",
  apiKey: process.env.BRAINTRUST_API_KEY,
});

const model = new ChatOpenAI({ model: "gpt-5-mini" });

const StateAnnotation = Annotation.Root({
  message: Annotation(),
});

const graph = new StateGraph(StateAnnotation)
  .addNode("sayHello", async () => {
    const res = await model.invoke("Say hello");
    return { message: res.content };
  })
  .addNode("sayBye", () => ({ message: "Bye." }))
  .addEdge(START, "sayHello")
  .addEdge("sayHello", "sayBye")
  .addEdge("sayBye", END)
  .compile();

await graph.invoke({});

Run with the import hook

node --import braintrust/hook.mjs trace-langgraph-auto.js

The auto-instrumentation example uses plain JavaScript so node --import can run the file directly. The Braintrust APIs work the same in TypeScript projects — compile your TypeScript to JavaScript, then run the compiled file with the import hook.

If you’re using a bundler, see Trace LLM calls for plugin and loader setup.

Manual instrumentation

To control the LangChain handler yourself, construct a BraintrustLangChainCallbackHandler and pass it through the callbacks option when you invoke the graph.

import {
  BraintrustLangChainCallbackHandler,
} from "braintrust";
import { END, START, StateGraph, Annotation } from "@langchain/langgraph";
import { ChatOpenAI } from "@langchain/openai";
import { initLogger } from "braintrust";

const logger = initLogger({
  projectName: "My Project",
  apiKey: process.env.BRAINTRUST_API_KEY,
});

const handler = new BraintrustLangChainCallbackHandler({ logger });

const StateAnnotation = Annotation.Root({
  message: Annotation(),
});

const model = new ChatOpenAI({
  model: "gpt-5-mini",
});

async function sayHello(_state: typeof StateAnnotation.State) {
  const res = await model.invoke("Say hello");
  return { message: res.content };
}

function sayBye(_state: typeof StateAnnotation.State) {
  console.log("From the 'sayBye' node: Bye world!");
  return {};
}

async function main() {
  const graphBuilder = new StateGraph(StateAnnotation)
    .addNode("sayHello", sayHello)
    .addNode("sayBye", sayBye)
    .addEdge(START, "sayHello")
    .addEdge("sayHello", "sayBye")
    .addEdge("sayBye", END);

  const helloWorldGraph = graphBuilder.compile();

  await helloWorldGraph.invoke({}, { callbacks: [handler] });
}

main();

What Braintrust traces

Braintrust logs each step of a graph run as a span nested under the graph invocation:

Graph and node execution spans (chain runs), with each step’s inputs, outputs, and LangChain tags.
Chat model and LLM spans (ChatOpenAI and similar), with the input messages or prompts, the serialized model configuration and request parameters, and the full response including generated messages.
Model name metadata resolved from each model response.
Token usage metrics (prompt_tokens, completion_tokens, tokens, prompt_cached_tokens, cache-creation tokens, and completion_reasoning_tokens when the provider reports them).
Time to first token (time_to_first_token) for streaming model calls.
Tool spans (named for the tool), with the parsed tool input and the tool output.
Retriever spans, with the query as input and the retrieved documents as output.
Errors captured on the failing model, chain, tool, or retriever span.

Resources

LangGraph Platform SDK

Trace runs dispatched to a deployed LangGraph Platform server using the @langchain/langgraph-sdk package.

Setup

Install the LangGraph Platform SDK alongside braintrust.

pnpm add braintrust @langchain/langgraph-sdk

npm install braintrust @langchain/langgraph-sdk

Auto-instrumentation

To trace RunsClient.wait() and RunsClient.stream() calls without modifying your application code, initialize Braintrust normally, then run your app with Braintrust’s import hook. Requires @langchain/langgraph-sdk v1.9.25 or later.

Initialize Braintrust and call your deployed graph

import { Client } from "@langchain/langgraph-sdk";
import { initLogger } from "braintrust";

initLogger({
  projectName: "My Project",
  apiKey: process.env.BRAINTRUST_API_KEY,
});

const client = new Client({
  apiUrl: process.env.LANGGRAPH_API_URL,
});

const result = await client.runs.wait(null, "agent", {
  input: { messages: [{ role: "user", content: "Say hello" }] },
});

Run with the import hook

node --import braintrust/hook.mjs trace-langgraph-sdk-auto.js

If you’re using a bundler, see Trace LLM calls for plugin and loader setup.

Manual instrumentation

To instrument the LangGraph Platform SDK without modifying every call site, wrap your client once with wrapLangGraphSDK. All subsequent runs.wait() and runs.stream() calls on the wrapped client are traced automatically.

import { Client } from "@langchain/langgraph-sdk";
import { initLogger, wrapLangGraphSDK } from "braintrust";

initLogger({
  projectName: "My Project",
  apiKey: process.env.BRAINTRUST_API_KEY,
});

const raw = new Client({
  apiUrl: process.env.LANGGRAPH_API_URL,
});
const client = wrapLangGraphSDK(raw);

const result = await client.runs.wait(null, "agent", {
  input: { messages: [{ role: "user", content: "Say hello" }] },
});

What Braintrust traces

Braintrust captures:

Run wait spans (runs.wait), with the thread ID, assistant ID, and run options as input, and the final graph state as output.
Run stream spans (runs.stream), with the thread ID, assistant ID, and run options as input. Each streamed event is consumed without individual child spans.
Errors on any span that fails, including HTTP errors from the LangGraph server.

AI providers

SDKs

Developer tools

Runtime environments

Setup

Auto-instrumentation

Manual instrumentation

What Braintrust traces

Resources

LangGraph Platform SDK

Setup

Auto-instrumentation

Manual instrumentation

What Braintrust traces

Resources

​Setup

​Auto-instrumentation

​Manual instrumentation

​What Braintrust traces

​Resources

​LangGraph Platform SDK

​Setup

​Auto-instrumentation

​Manual instrumentation

​What Braintrust traces

​Resources

Setup

Auto-instrumentation

Manual instrumentation

What Braintrust traces

Resources

LangGraph Platform SDK

Setup

Auto-instrumentation

Manual instrumentation

What Braintrust traces

Resources