> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fiddler.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# FiddlerCallbackHandler

> LangChain callback handler that creates Fiddler OTel spans for every

LangChain callback handler that creates Fiddler OTel spans for every
chain, LLM, tool, agent, and retriever lifecycle event.

Can be used directly by passing it in the `callbacks` array of a
LangChain/LangGraph invocation, or automatically injected via
LangGraphInstrumentor.

## Properties

### `name: string`

## Methods

### `constructor(client: FiddlerClient)`

<ParamField path="client" type="FiddlerClient" required={true}>
  An initialized FiddlerClient used to create spans.
</ParamField>

### `handleAgentAction(action: AgentAction, runId: string)`

Called when an agent is about to execute an action,
with the action and the run ID.

<ParamField path="action" type="AgentAction" required={true}>
  The agent action containing tool name and input.
</ParamField>

<ParamField path="runId" type="string" required={true}>
  Run identifier to look up the span.
</ParamField>

### `handleAgentEnd(action: AgentFinish, runId: string)`

Called when an agent finishes execution, before it exits.
with the final output and the run ID.

<ParamField path="action" type="AgentFinish" required={true}>
  The agent finish containing return values.
</ParamField>

<ParamField path="runId" type="string" required={true}>
  Run identifier to look up the span.
</ParamField>

### `handleChainEnd(outputs: ChainValues, runId: string)`

Called at the end of a Chain run, with the outputs and the run ID.

<ParamField path="outputs" type="ChainValues" required={true}>
  Output values produced by the chain.
</ParamField>

<ParamField path="runId" type="string" required={true}>
  Run identifier to look up the span.
</ParamField>

### `handleChainError(error: Error, runId: string)`

Called if a Chain run encounters an error

<ParamField path="error" type="Error" required={true}>
  The error that occurred.
</ParamField>

<ParamField path="runId" type="string" required={true}>
  Run identifier to look up the span.
</ParamField>

### `handleChainStart(serialized: Serialized, inputs: ChainValues, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>)`

Called at the start of a Chain run, with the chain name and inputs
and the run ID.

<ParamField path="serialized" type="Serialized" required={true}>
  Serialized chain/runnable metadata.
</ParamField>

<ParamField path="inputs" type="ChainValues" required={true}>
  Input values passed to the chain.
</ParamField>

<ParamField path="runId" type="string" required={true}>
  Unique run identifier.
</ParamField>

<ParamField path="parentRunId" type="string" required={false}>
  Parent run ID for nesting.
</ParamField>

<ParamField path="tags" type="string[]" required={false}>
  LangChain tags (used for LangGraph node detection).
</ParamField>

<ParamField path="metadata" type="Record<string, unknown>" required={false}>
  LangChain metadata (agent name, node name, etc.).
</ParamField>

### `handleChatModelStart(serialized: Serialized, messages: BaseMessage[][], runId: string, parentRunId?: string, extraParams?: Record<string, unknown>, _tags?: string[], _metadata?: Record<string, unknown>, runName?: string)`

Called at the start of a Chat Model run, with the prompt(s)
and the run ID.

<ParamField path="serialized" type="Serialized" required={true}>
  Serialized chat model metadata.
</ParamField>

<ParamField path="messages" type="BaseMessage[][]" required={true}>
  2D array of chat messages (outer = batches).
</ParamField>

<ParamField path="runId" type="string" required={true}>
  Unique run identifier.
</ParamField>

<ParamField path="parentRunId" type="string" required={false}>
  Parent run ID for nesting.
</ParamField>

<ParamField path="extraParams" type="Record<string, unknown>" required={false}>
  Additional invocation parameters.
</ParamField>

<ParamField path="_tags" type="string[]" required={false} />

<ParamField path="_metadata" type="Record<string, unknown>" required={false} />

<ParamField path="runName" type="string" required={false}>
  Optional explicit run name.
</ParamField>

### `handleLLMEnd(output: LLMResult, runId: string)`

Called at the end of an LLM/ChatModel run, with the output and the run ID.

<ParamField path="output" type="LLMResult" required={true}>
  The LLMResult containing generations and usage.
</ParamField>

<ParamField path="runId" type="string" required={true}>
  Run identifier to look up the span.
</ParamField>

### `handleLLMError(error: Error, runId: string)`

Called if an LLM/ChatModel run encounters an error

<ParamField path="error" type="Error" required={true}>
  The error that occurred.
</ParamField>

<ParamField path="runId" type="string" required={true}>
  Run identifier to look up the span.
</ParamField>

### `handleLLMStart(serialized: Serialized, prompts: string[], runId: string, parentRunId?: string, _extraParams?: Record<string, unknown>, _tags?: string[], _metadata?: Record<string, unknown>, runName?: string)`

Called at the start of an LLM or Chat Model run, with the prompt(s)
and the run ID.

<ParamField path="serialized" type="Serialized" required={true}>
  Serialized LLM metadata.
</ParamField>

<ParamField path="prompts" type="string[]" required={true}>
  Array of prompt strings.
</ParamField>

<ParamField path="runId" type="string" required={true}>
  Unique run identifier.
</ParamField>

<ParamField path="parentRunId" type="string" required={false}>
  Parent run ID for nesting.
</ParamField>

<ParamField path="_extraParams" type="Record<string, unknown>" required={false} />

<ParamField path="_tags" type="string[]" required={false} />

<ParamField path="_metadata" type="Record<string, unknown>" required={false} />

<ParamField path="runName" type="string" required={false}>
  Optional explicit run name.
</ParamField>

### `handleRetrieverEnd(documents: { metadata?: unknown; pageContent?: string }[], runId: string)`

Called when a retriever returns documents.

Sets the concatenated page content as the tool output.

<ParamField path="documents" type="{ metadata?: unknown; pageContent?: string }[]" required={true}>
  Array of retrieved documents with `pageContent`.
</ParamField>

<ParamField path="runId" type="string" required={true}>
  Run identifier to look up the span.
</ParamField>

### `handleRetrieverError(error: Error, runId: string)`

Called when a retriever throws an error.

<ParamField path="error" type="Error" required={true}>
  The error that occurred.
</ParamField>

<ParamField path="runId" type="string" required={true}>
  Run identifier to look up the span.
</ParamField>

### `handleRetrieverStart(serialized: Serialized, query: string, runId: string, parentRunId?: string)`

Called when a retriever begins fetching documents.

Creates a tool-type span with the retriever name and query.

<ParamField path="serialized" type="Serialized" required={true}>
  Serialized retriever metadata.
</ParamField>

<ParamField path="query" type="string" required={true}>
  The search query string.
</ParamField>

<ParamField path="runId" type="string" required={true}>
  Unique run identifier.
</ParamField>

<ParamField path="parentRunId" type="string" required={false}>
  Parent run ID for nesting.
</ParamField>

### `handleToolEnd(output: string, runId: string)`

Called at the end of a Tool run, with the tool output and the run ID.

<ParamField path="output" type="string" required={true}>
  Tool output (string or ToolMessage-like object).
</ParamField>

<ParamField path="runId" type="string" required={true}>
  Run identifier to look up the span.
</ParamField>

### `handleToolError(error: Error, runId: string)`

Called if a Tool run encounters an error

<ParamField path="error" type="Error" required={true}>
  The error that occurred.
</ParamField>

<ParamField path="runId" type="string" required={true}>
  Run identifier to look up the span.
</ParamField>

### `handleToolStart(serialized: Serialized, input: string, runId: string, parentRunId?: string, _tags?: string[], _metadata?: Record<string, unknown>, runName?: string)`

Called at the start of a Tool run, with the tool name and input
and the run ID.

<ParamField path="serialized" type="Serialized" required={true}>
  Serialized tool metadata.
</ParamField>

<ParamField path="input" type="string" required={true}>
  The input string or structured input for the tool.
</ParamField>

<ParamField path="runId" type="string" required={true}>
  Unique run identifier.
</ParamField>

<ParamField path="parentRunId" type="string" required={false}>
  Parent run ID for nesting.
</ParamField>

<ParamField path="_tags" type="string[]" required={false} />

<ParamField path="_metadata" type="Record<string, unknown>" required={false} />

<ParamField path="runName" type="string" required={false}>
  Optional explicit run name.
</ParamField>