How to Intermediate · 3 min read

How to use LangChain callbacks

Q: How to use LangChain callbacks

Use LangChain callbacks by implementing callback handler classes that inherit from BaseCallbackHandler and registering them with your LangChain components like ChatOpenAI. Callbacks enable monitoring, logging, and custom actions during AI calls.

Quick answer

Use LangChain callbacks by implementing callback handler classes that inherit from BaseCallbackHandler and registering them with your LangChain components like ChatOpenAI. Callbacks enable monitoring, logging, and custom actions during AI calls.

PREREQUISITES

Python 3.8+
OpenAI API key (free tier works)
pip install langchain_openai>=0.2 langchain_community>=0.2

Setup

Install the necessary LangChain packages and set your OpenAI API key as an environment variable.

Install packages: pip install langchain_openai langchain_community
Set environment variable in your shell: export OPENAI_API_KEY='your_api_key'

bash

pip install langchain_openai langchain_community

Step by step

Create a custom callback handler by subclassing BaseCallbackHandler, then pass it to a ChatOpenAI instance to log events during chat completions.

python

import os
from langchain_openai import ChatOpenAI
from langchain.callbacks.base import BaseCallbackHandler

class MyCallbackHandler(BaseCallbackHandler):
    def on_llm_start(self, serialized, prompts, **kwargs):
        print(f"LLM start with prompts: {prompts}")

    def on_llm_end(self, response, **kwargs):
        print(f"LLM end with response: {response}")

    def on_llm_error(self, error, **kwargs):
        print(f"LLM error: {error}")

# Initialize client with callback
llm = ChatOpenAI(
    model="gpt-4o",
    callbacks=[MyCallbackHandler()],
    verbose=True
)

response = llm("Hello, LangChain callbacks!")
print("Final output:", response)

output

LLM start with prompts: ['Hello, LangChain callbacks!']
LLM end with response: ChatResult(generations=[[Generation(text='Hello! How can I assist you today?', generation_info=None)]], llm_output=None)
Final output: Hello! How can I assist you today?

Common variations

You can use async callbacks by subclassing AsyncCallbackHandler, stream tokens with callbacks, or attach multiple handlers for logging, metrics, and UI updates. Different models like gpt-4o or claude-3-5-sonnet-20241022 support callbacks similarly.

python

import asyncio
from langchain_openai import ChatOpenAI
from langchain.callbacks.base import AsyncCallbackHandler

class AsyncLogger(AsyncCallbackHandler):
    async def on_llm_new_token(self, token: str, **kwargs):
        print(f"New token: {token}")

async def main():
    llm = ChatOpenAI(
        model="gpt-4o",
        callbacks=[AsyncLogger()],
        streaming=True,
        verbose=True
    )
    response = await llm.acall("Stream tokens with callbacks.")
    print("Final output:", response)

asyncio.run(main())

output

New token: S
New token: t
New token: r
New token: e
New token: a
New token: m
New token: i
New token: n
New token: g
New token:  
New token: t
New token: o
New token: k
New token: e
New token: n
New token: s
New token:  
New token: w
New token: i
New token: t
New token: h
New token:  
New token: c
New token: a
New token: l
New token: l
New token: b
New token: a
New token: c
New token: k
New token: s
Final output: Streaming tokens with callbacks.

Troubleshooting

If callbacks do not trigger, ensure callbacks parameter is passed to the LangChain component.
Verbose mode (verbose=True) helps debug callback flow.
For async callbacks, confirm you use acall and AsyncCallbackHandler.

✅

Key Takeaways

Implement custom callback handlers by subclassing BaseCallbackHandler or AsyncCallbackHandler.
Pass callback instances to LangChain components via the callbacks parameter to monitor AI calls.
Use verbose=True to debug callback execution and flow.
Async callbacks require AsyncCallbackHandler and async calls like acall.
Callbacks enable logging, streaming token handling, error catching, and custom metrics.

Verified 2026-04 · gpt-4o, claude-3-5-sonnet-20241022

Verify ↗