0
# Callback System
1

2
Event handling and observability framework for monitoring and debugging LangChain operations. Callbacks provide hooks into the execution lifecycle of runnables, models, and tools.
3

4
## Capabilities
5

6
### Base Callback Handler
7

8
Abstract base class for all callback handlers.
9

10
```typescript { .api }
11
/**
12
 * Abstract base class for callback handlers
13
 */
14
abstract class BaseCallbackHandler {
15
  /** Handler name for identification */
16
  name: string;
17
  /** Whether to ignore LLM events */
18
  ignoreLLM: boolean;
19
  /** Whether to ignore chain events */
20
  ignoreChain: boolean;
21
  /** Whether to ignore agent events */
22
  ignoreAgent: boolean;
23
  /** Whether to ignore retriever events */
24
  ignoreRetriever: boolean;
25
  /** Whether to ignore chat model events */
26
  ignoreChatModel: boolean;
27
  /** Whether to ignore custom events */
28
  ignoreCustomEvent: boolean;
29
  /** Whether handler should raise errors */
30
  raiseError: boolean;
31
  
32
  constructor(input?: BaseCallbackHandlerInput);
33
  
34
  /** LLM start event */
35
  handleLLMStart?(llm: Serialized, prompts: string[], runId: string, parentRunId?: string, extraParams?: Record<string, unknown>, tags?: string[], metadata?: Record<string, unknown>, runName?: string): Promise<void> | void;
36
  
37
  /** LLM new token event */
38
  handleLLMNewToken?(token: string, idx: NewTokenIndices, runId: string, parentRunId?: string, tags?: string[], fields?: Record<string, unknown>): Promise<void> | void;
39
  
40
  /** LLM end event */
41
  handleLLMEnd?(output: LLMResult, runId: string, parentRunId?: string, tags?: string[]): Promise<void> | void;
42
  
43
  /** LLM error event */
44
  handleLLMError?(err: Error, runId: string, parentRunId?: string, tags?: string[]): Promise<void> | void;
45
  
46
  /** Chat model start event */
47
  handleChatModelStart?(llm: Serialized, messages: BaseMessage[][], runId: string, parentRunId?: string, extraParams?: Record<string, unknown>, tags?: string[], metadata?: Record<string, unknown>, runName?: string): Promise<void> | void;
48
  
49
  /** Chain start event */
50
  handleChainStart?(chain: Serialized, inputs: ChainValues, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>, runType?: string, runName?: string): Promise<void> | void;
51
  
52
  /** Chain end event */
53
  handleChainEnd?(outputs: ChainValues, runId: string, parentRunId?: string, tags?: string[], kwargs?: Record<string, unknown>): Promise<void> | void;
54
  
55
  /** Chain error event */
56
  handleChainError?(err: Error, runId: string, parentRunId?: string, tags?: string[], kwargs?: Record<string, unknown>): Promise<void> | void;
57
  
58
  /** Tool start event */
59
  handleToolStart?(tool: Serialized, input: string, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>, runName?: string): Promise<void> | void;
60
  
61
  /** Tool end event */
62
  handleToolEnd?(output: ToolMessage, runId: string, parentRunId?: string, tags?: string[]): Promise<void> | void;
63
  
64
  /** Tool error event */
65
  handleToolError?(err: Error, runId: string, parentRunId?: string, tags?: string[]): Promise<void> | void;
66
  
67
  /** Retriever start event */
68
  handleRetrieverStart?(retriever: Serialized, query: string, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>, runName?: string): Promise<void> | void;
69
  
70
  /** Retriever end event */
71
  handleRetrieverEnd?(documents: Document[], runId: string, parentRunId?: string, tags?: string[]): Promise<void> | void;
72
  
73
  /** Retriever error event */
74
  handleRetrieverError?(err: Error, runId: string, parentRunId?: string, tags?: string[]): Promise<void> | void;
75
  
76
  /** Text event (for streaming) */
77
  handleText?(text: string, runId: string, parentRunId?: string, tags?: string[]): Promise<void> | void;
78
  
79
  /** Custom event */
80
  handleCustomEvent?(eventName: string, data: unknown, runId: string, tags?: string[], metadata?: Record<string, unknown>): Promise<void> | void;
81
  
82
  /** Agent action event */
83
  handleAgentAction?(action: AgentAction, runId: string, parentRunId?: string, tags?: string[]): Promise<void> | void;
84
  
85
  /** Agent end event */
86
  handleAgentEnd?(action: AgentFinish, runId: string, parentRunId?: string, tags?: string[]): Promise<void> | void;
87
  
88
  /** Create handler from methods object */
89
  static fromMethods(methods: CallbackHandlerMethods): BaseCallbackHandler;
90
}
91
```
92

93
**Usage Examples:**
94

95
```typescript
96
import { BaseCallbackHandler } from "@langchain/core/callbacks";
97

98
// Custom callback handler
99
class MyCallbackHandler extends BaseCallbackHandler {
100
  name = "my_callback_handler";
101
  
102
  async handleLLMStart(llm: Serialized, prompts: string[], runId: string) {
103
    console.log(`LLM ${llm._type} started with prompts:`, prompts);
104
  }
105
  
106
  async handleLLMEnd(output: LLMResult, runId: string) {
107
    console.log("LLM finished with output:", output.generations);
108
  }
109
  
110
  async handleChainStart(chain: Serialized, inputs: any, runId: string) {
111
    console.log(`Chain ${chain._type} started with inputs:`, inputs);
112
  }
113
  
114
  async handleChainEnd(outputs: any, runId: string) {
115
    console.log("Chain finished with outputs:", outputs);
116
  }
117
}
118

119
// Use callback
120
const handler = new MyCallbackHandler();
121
const result = await model.invoke(
122
  "What is the capital of France?",
123
  { callbacks: [handler] }
124
);
125
```
126

127
### Callback Manager
128

129
Manages multiple callback handlers and coordinates event distribution.
130

131
```typescript { .api }
132
/**
133
 * Manages and coordinates callback handlers
134
 */
135
class CallbackManager extends BaseCallbackManager {
136
  /** Registered handlers */
137
  handlers: BaseCallbackHandler[];
138
  /** Inheritable handlers */
139
  inheritable_handlers: BaseCallbackHandler[];
140
  /** Parent callback manager */
141
  parent_run_id?: string;
142
  /** Run ID for this manager */
143
  run_id?: string;
144
  /** Tags for this manager */
145
  tags: string[];
146
  /** Metadata for this manager */
147
  metadata: Record<string, unknown>;
148
  
149
  constructor(parentRunId?: string, options?: CallbackManagerOptions);
150
  
151
  /** Add a callback handler */
152
  addHandler(handler: BaseCallbackHandler, inherit?: boolean): void;
153
  
154
  /** Remove a callback handler */
155
  removeHandler(handler: BaseCallbackHandler): void;
156
  
157
  /** Add tags */
158
  addTags(tags: string[], inherit?: boolean): void;
159
  
160
  /** Add metadata */
161
  addMetadata(metadata: Record<string, unknown>, inherit?: boolean): void;
162
  
163
  /** Configure callback manager from environment */
164
  static configure(inheritable_handlers?: Callbacks, local_handlers?: Callbacks, verbose?: boolean, tags?: string[], metadata?: Record<string, unknown>): CallbackManager | undefined;
165
  
166
  /** Create child manager for a specific run */
167
  child(runType?: string, runId?: string, tags?: string[], metadata?: Record<string, unknown>): CallbackManagerForLLMRun | CallbackManagerForChainRun | CallbackManagerForToolRun | CallbackManagerForRetrieverRun;
168
}
169
```
170

171
### Specialized Run Managers
172

173
Run managers for specific operation types.
174

175
```typescript { .api }
176
/**
177
 * Callback manager for LLM runs
178
 */
179
class CallbackManagerForLLMRun extends BaseCallbackManager {
180
  /** Handle new token */
181
  async handleLLMNewToken(token: string, idx: NewTokenIndices): Promise<void>;
182
  
183
  /** Handle LLM end */
184
  async handleLLMEnd(output: LLMResult): Promise<void>;
185
  
186
  /** Handle LLM error */
187
  async handleLLMError(err: Error): Promise<void>;
188
}
189

190
/**
191
 * Callback manager for chain runs
192
 */
193
class CallbackManagerForChainRun extends BaseCallbackManager {
194
  /** Handle chain end */
195
  async handleChainEnd(output: ChainValues, kwargs?: Record<string, unknown>): Promise<void>;
196
  
197
  /** Handle chain error */
198
  async handleChainError(err: Error, kwargs?: Record<string, unknown>): Promise<void>;
199
  
200
  /** Get child manager for nested operations */
201
  getChild(tag?: string): CallbackManager;
202
}
203

204
/**
205
 * Callback manager for tool runs
206
 */
207
class CallbackManagerForToolRun extends BaseCallbackManager {
208
  /** Handle tool end */
209
  async handleToolEnd(output: ToolMessage): Promise<void>;
210
  
211
  /** Handle tool error */
212
  async handleToolError(err: Error): Promise<void>;
213
}
214

215
/**
216
 * Callback manager for retriever runs
217
 */
218
class CallbackManagerForRetrieverRun extends BaseCallbackManager {
219
  /** Handle retriever end */
220
  async handleRetrieverEnd(documents: Document[]): Promise<void>;
221
  
222
  /** Handle retriever error */
223
  async handleRetrieverError(err: Error): Promise<void>;
224
}
225
```
226

227
### Console Callback Handler
228

229
Built-in handler for logging to console.
230

231
```typescript { .api }
232
/**
233
 * Built-in callback handler for console logging
234
 */
235
class ConsoleCallbackHandler extends BaseCallbackHandler {
236
  name = "console_callback_handler";
237
  
238
  /** Log all events to console with formatting */
239
  handleLLMStart?(llm: Serialized, prompts: string[], runId: string): void;
240
  handleLLMEnd?(output: LLMResult, runId: string): void;
241
  handleChainStart?(chain: Serialized, inputs: ChainValues, runId: string): void;
242
  handleChainEnd?(outputs: ChainValues, runId: string): void;
243
  handleToolStart?(tool: Serialized, input: string, runId: string): void;
244
  handleToolEnd?(output: ToolMessage, runId: string): void;
245
}
246
```
247

248
**Usage Examples:**
249

250
```typescript
251
import { ConsoleCallbackHandler } from "@langchain/core/callbacks";
252

253
// Use built-in console handler
254
const consoleHandler = new ConsoleCallbackHandler();
255

256
const result = await chain.invoke(
257
  { question: "What is LangChain?" },
258
  { callbacks: [consoleHandler] }
259
);
260
// Logs all events to console
261
```
262

263
## Callback Configuration
264

265
### Base Callback Config
266

267
```typescript { .api }
268
interface BaseCallbackConfig {
269
  /** Callback handlers or manager */
270
  callbacks?: Callbacks;
271
  /** Tags for categorizing runs */
272
  tags?: string[];
273
  /** Additional metadata */
274
  metadata?: Record<string, unknown>;
275
  /** Human-readable name for the run */
276
  runName?: string;
277
  /** Unique run identifier */
278
  runId?: string;
279
}
280
```
281

282
### Callback Types
283

284
```typescript { .api }
285
type Callbacks = CallbackManager | (BaseCallbackHandler | CallbackHandlerMethods)[];
286

287
interface CallbackHandlerMethods {
288
  handleLLMStart?: (llm: Serialized, prompts: string[], runId: string, parentRunId?: string, extraParams?: Record<string, unknown>, tags?: string[], metadata?: Record<string, unknown>) => Promise<void> | void;
289
  handleLLMEnd?: (output: LLMResult, runId: string, parentRunId?: string, tags?: string[]) => Promise<void> | void;
290
  handleLLMError?: (err: Error, runId: string, parentRunId?: string, tags?: string[]) => Promise<void> | void;
291
  handleChainStart?: (chain: Serialized, inputs: ChainValues, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>) => Promise<void> | void;
292
  handleChainEnd?: (outputs: ChainValues, runId: string, parentRunId?: string, tags?: string[]) => Promise<void> | void;
293
  handleChainError?: (err: Error, runId: string, parentRunId?: string, tags?: string[]) => Promise<void> | void;
294
  // ... other methods
295
}
296

297
interface BaseCallbackHandlerInput {
298
  ignoreLLM?: boolean;
299
  ignoreChain?: boolean;
300
  ignoreAgent?: boolean;
301
  ignoreRetriever?: boolean;
302
  ignoreChatModel?: boolean;
303
  ignoreCustomEvent?: boolean;
304
  raiseError?: boolean;
305
}
306

307
interface CallbackManagerOptions {
308
  verbose?: boolean;
309
  tags?: string[];
310
  metadata?: Record<string, unknown>;
311
}
312
```
313

314
## Types
315

316
```typescript { .api }
317
interface NewTokenIndices {
318
  prompt: number;
319
  completion: number;
320
}
321

322
type ChainValues = Record<string, unknown>;
323

324
interface Serialized {
325
  _type: string;
326
  [key: string]: unknown;
327
}
328
```