LangChain

Available for: Python and TypeScript.

The ZespanCallbackHandler integrates with LangChain’s callback system to automatically capture every LLM call, tool invocation, chain step, and retrieval operation as linked spans in Zespan. You pass it once and it instruments the entire execution graph — no changes to your chain or agent logic are needed.

How it works

LangChain calls lifecycle methods on every registered BaseCallbackHandler at each stage of execution. The Zespan handler subscribes to:

LangChain event	What Zespan captures
`handleLLMStart` / `handleLLMEnd`	Model, provider, latency, tokens, cost, finish reason
`handleChainStart` / `handleChainEnd`	Chain type, input/output, duration
`handleToolStart` / `handleToolEnd`	Tool name, input args, output, duration
`handleRetrieverStart` / `handleRetrieverEnd`	Query, retrieved document count, duration
`handleAgentAction`	Tool selected, reasoning, input

All events share the same trace_id so you see the entire chain as a single flame graph in the Traces view.

TypeScript

Installation

npm install @zespan/sdk @langchain/core @langchain/openai

Basic usage

import { zespan, ZespanCallbackHandler } from "@zespan/sdk";
import { ChatOpenAI } from "@langchain/openai";
import { HumanMessage, SystemMessage } from "@langchain/core/messages";

zespan.init({ apiKey: process.env.ZESPAN_API_KEY! });

const handler = new ZespanCallbackHandler();

const llm = new ChatOpenAI({
  model: "gpt-4o",
  callbacks: [handler],
});

const response = await llm.invoke([
  new SystemMessage("You are a helpful assistant."),
  new HumanMessage("Summarize the history of the internet in three sentences."),
]);

console.log(response.content);

Chains

Pass the handler to RunnableSequence or any chain using the config argument:

import { ChatPromptTemplate } from "@langchain/core/prompts";
import { StringOutputParser } from "@langchain/core/output_parsers";
import { RunnableSequence } from "@langchain/core/runnables";

const prompt = ChatPromptTemplate.fromMessages([
  ["system", "You are an expert summarizer. Be concise."],
  ["human", "{topic}"],
]);

const chain = RunnableSequence.from([
  prompt,
  new ChatOpenAI({ model: "gpt-4o" }),
  new StringOutputParser(),
]);

const result = await chain.invoke(
  { topic: "quantum computing" },
  { callbacks: [new ZespanCallbackHandler()] }
);

Agents and tools

The handler captures the full agent loop: plan → tool call → observation → next plan. Each iteration appears as linked spans.

import { createOpenAIFunctionsAgent, AgentExecutor } from "langchain/agents";
import { DynamicTool } from "@langchain/core/tools";
import { ChatOpenAI } from "@langchain/openai";
import { ChatPromptTemplate, MessagesPlaceholder } from "@langchain/core/prompts";
import { zespan, ZespanCallbackHandler } from "@zespan/sdk";

zespan.init({ apiKey: process.env.ZESPAN_API_KEY! });

const tools = [
  new DynamicTool({
    name: "get-weather",
    description: "Get current weather for a city",
    func: async (city: string) => `Weather in ${city}: 22°C, sunny`,
  }),
];

const prompt = ChatPromptTemplate.fromMessages([
  ["system", "You are a helpful assistant with access to tools."],
  ["human", "{input}"],
  new MessagesPlaceholder("agent_scratchpad"),
]);

const agent = await createOpenAIFunctionsAgent({
  llm: new ChatOpenAI({ model: "gpt-4o" }),
  tools,
  prompt,
});

const executor = new AgentExecutor({
  agent,
  tools,
  callbacks: [new ZespanCallbackHandler()],
});

const result = await executor.invoke({ input: "What's the weather in Tokyo?" });

RAG with retriever tracing

import { MemoryVectorStore } from "langchain/vectorstores/memory";
import { OpenAIEmbeddings } from "@langchain/openai";
import { createRetrievalChain } from "langchain/chains/retrieval";
import { createStuffDocumentsChain } from "langchain/chains/combine_documents";
import { Document } from "@langchain/core/documents";

const vectorStore = await MemoryVectorStore.fromDocuments(
  [new Document({ pageContent: "LangChain is a framework for building LLM apps." })],
  new OpenAIEmbeddings()
);

const retriever = vectorStore.asRetriever();

const combineDocsChain = await createStuffDocumentsChain({
  llm: new ChatOpenAI({ model: "gpt-4o" }),
  prompt: ChatPromptTemplate.fromMessages([
    ["system", "Answer based on context: {context}"],
    ["human", "{input}"],
  ]),
});

const retrievalChain = await createRetrievalChain({
  retriever,
  combineDocsChain,
});

// All retrieval and LLM calls appear as linked spans
const result = await retrievalChain.invoke(
  { input: "What is LangChain?" },
  { callbacks: [new ZespanCallbackHandler()] }
);

Python

Installation

pip install zespan langchain-core langchain-openai

Basic usage

import zespan
from zespan.integrations.langchain_handler import ZespanCallbackHandler
from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage, SystemMessage

zespan.init(api_key="zsp_your_api_key_here")

handler = ZespanCallbackHandler()

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

response = llm.invoke([
    SystemMessage(content="You are a helpful assistant."),
    HumanMessage(content="What is the Turing test?"),
])
print(response.content)

Chains

from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

prompt = ChatPromptTemplate.from_messages([
    ("system", "Summarize the following topic in two sentences."),
    ("human", "{topic}"),
])

chain = prompt | ChatOpenAI(model="gpt-4o") | StrOutputParser()

result = chain.invoke(
    {"topic": "large language models"},
    config={"callbacks": [ZespanCallbackHandler()]},
)

Agents

from langchain.agents import AgentExecutor, create_openai_functions_agent
from langchain_core.tools import Tool
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder

def get_weather(city: str) -> str:
    return f"Weather in {city}: 22°C, sunny"

tools = [Tool(name="get-weather", func=get_weather, description="Get weather for a city")]

prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a helpful assistant with access to tools."),
    ("human", "{input}"),
    MessagesPlaceholder("agent_scratchpad"),
])

agent = create_openai_functions_agent(
    llm=ChatOpenAI(model="gpt-4o"),
    tools=tools,
    prompt=prompt,
)

executor = AgentExecutor(
    agent=agent,
    tools=tools,
    callbacks=[ZespanCallbackHandler()],
)

result = executor.invoke({"input": "What's the weather in Paris?"})

Tool calls join the tool’s trace

A model, MCP or HTTP call made inside a tool belongs to the tool’s span and to the same trace as the rest of the run, even if you did not wrap the run in withZespanTrace / with_zespan_trace. Before, such a call started a trace of its own. The handler makes the tool’s span the current context when the tool starts and puts the previous context back when it ends or fails; tools running in parallel each see their own span.

TypeScript: the handler is awaited by LangChain so this happens before the tool runs. If you set LANGCHAIN_CALLBACKS_BACKGROUND=true, LangChain runs handlers in the background and the tool’s own calls start their own traces, as before.
Python: the handler runs inline, so this also holds for async runs. A handler created with guardrails keeps LangChain’s default delivery, because its guardrail check is a blocking call that would stall your event loop; in async runs its tools’ own calls then start their own traces, as before.
A tool cancelled by a timeout (Python) never reports its end to LangChain. Its context is put back when the run that called it ends, or at the next top-level LangChain run (Python 3.11 or newer). Wrap each job in with_zespan_trace to put it back as soon as the job ends.

LangGraph node steps

A LangGraph node run is recorded as an agent_step span: zespan.agent.step is the superstep, zespan.agent.route is the node name, and a node that raises also carries zespan.agent.stop_reason: error. Other chains are recorded as before. See Agent steps.

How traces look in the dashboard

A LangChain agent run produces a trace like this in the flame graph:

AgentExecutor (chain)          ─────────────────────────────── 1.8s
  ├── ChatOpenAI (llm)         ──────────────── 820ms  gpt-4o
  │     → tool_calls: [get-weather]
  ├── get-weather (tool)       ──── 12ms
  └── ChatOpenAI (llm)         ──────── 640ms  gpt-4o
        → finish_reason: stop

Each row is a span. The total trace cost is the sum of both LLM spans. Tool call spans show the tool name and execution time but have no token cost.

To associate a LangChain trace with a user session, wrap the chain invocation in withZespanContext:

import { withZespanContext } from "@zespan/sdk";

return withZespanContext({ userId, sessionId }, () =>
  chain.invoke({ input: userMessage }, { callbacks: [handler] })
);

Guardrails with LangChain

Pass guardrail options to ZespanCallbackHandler to enable pre/post content checks on LLM calls made by the chain:

const handler = new ZespanCallbackHandler({
  guardrails: { pre: true, post: true, failClosed: false },
});

handler = ZespanCallbackHandler(guardrails={"pre": True, "post": True})

With guardrails in block mode the call waits for the check and stops on a block: invoke / stream throws (raises) GuardrailBlockedError and the model is not called for a pre-check block. Catch GuardrailBlockedError where you call the chain, drop guardrails from the handler to record without blocking, or set the rule’s action to warn in the dashboard (no deploy needed). Any other problem inside the handler never reaches your code.

Streaming: a pre-check block yields nothing. A post-check block runs after the model has answered, so the stream ends with GuardrailBlockedError after its chunks were already yielded.
Retries: retry wrappers (withRetry / with_retry, a LangGraph retry policy) treat a block like any other error and retry it up to their attempt limit. Exclude GuardrailBlockedError from retries if a retry cannot change the outcome.
The check itself fails (service unreachable, timeout): the call goes on, unless you set failClosed: true / "fail_closed": True on the handler, in which case the check’s error stops the call.

In TypeScript, with LANGCHAIN_CALLBACKS_BACKGROUND=true LangChain delivers handlers after the fact, so a block is recorded but cannot stop the call. The SDK prints one warning and raises nothing. Unset the variable to let a block stop the call.

Overview

CLI

TypeScript SDK

Python SDK

Advanced SDK Configuration

Integrations

LLM Providers

Agent Frameworks

RAG Frameworks

Gateways

Vector Databases

Custom / Other

Guides

How it works

TypeScript

Installation

Basic usage

Chains

Agents and tools

RAG with retriever tracing

Python

Installation

Basic usage

Chains

Agents

Tool calls join the tool’s trace

LangGraph node steps

How traces look in the dashboard

Guardrails with LangChain

​How it works

​TypeScript

​Installation

​Basic usage

​Chains

​Agents and tools

​RAG with retriever tracing

​Python

​Installation

​Basic usage

​Chains

​Agents

​Tool calls join the tool’s trace

​LangGraph node steps

​How traces look in the dashboard

​Guardrails with LangChain

How it works

TypeScript

Installation

Basic usage

Chains

Agents and tools

RAG with retriever tracing

Python

Installation

Basic usage

Chains

Agents

Tool calls join the tool’s trace

LangGraph node steps

How traces look in the dashboard

Guardrails with LangChain