Skip to main content

CallbackHandler

lc_callbacks

Trait CallbackHandler 

Source 
pub trait CallbackHandler: Send + Sync {

Show 17 methods    // Required methods
    fn on_run_start<'life0, 'life1, 'async_trait>(
        &'life0 self,
        run: &'life1 RunTree,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn on_run_end<'life0, 'life1, 'async_trait>(
        &'life0 self,
        run: &'life1 RunTree,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn on_run_error<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        run: &'life1 RunTree,
        error: &'life2 str,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait;

    // Provided methods
    fn on_llm_start<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        run: &'life1 RunTree,
        _messages: &'life2 [Message],
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
    fn on_llm_end<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        run: &'life1 RunTree,
        _response: &'life2 str,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
    fn on_llm_new_token<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        _run: &'life1 RunTree,
        _token: &'life2 str,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
    fn on_llm_thinking<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        _run: &'life1 RunTree,
        _thinking: &'life2 str,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
    fn on_llm_error<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        run: &'life1 RunTree,
        error: &'life2 str,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
    fn on_chain_start<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        run: &'life1 RunTree,
        _inputs: &'life2 Value,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
    fn on_chain_end<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        run: &'life1 RunTree,
        _outputs: &'life2 Value,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
    fn on_chain_error<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        run: &'life1 RunTree,
        error: &'life2 str,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
    fn on_tool_start<'life0, 'life1, 'life2, 'life3, 'async_trait>(
        &'life0 self,
        run: &'life1 RunTree,
        _tool_name: &'life2 str,
        _input: &'life3 str,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait,
             'life3: 'async_trait { ... }
    fn on_tool_end<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        run: &'life1 RunTree,
        _output: &'life2 str,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
    fn on_tool_error<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        run: &'life1 RunTree,
        error: &'life2 str,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
    fn on_retriever_start<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        run: &'life1 RunTree,
        _query: &'life2 str,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
    fn on_retriever_end<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        run: &'life1 RunTree,
        _documents: &'life2 [Value],
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
    fn on_retriever_error<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        run: &'life1 RunTree,
        error: &'life2 str,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }

}
Expand description

Callback handler trait for tracing and monitoring

Implement this trait to receive callbacks during execution. Can be used for logging, tracing, monitoring, etc.

§Two information layers

The trait is split into two layers:

  1. Generic lifecycle layer — on_run_start, on_run_end and on_run_error carry the run’s lifecycle with only the RunTree (name, type, inputs/outputs, timing). They are type-agnostic: a chain, an LLM call, a tool and a retriever all funnel through the same three hooks.
  2. Typed payload layer — on_llm_*, on_chain_*, on_tool_* and on_retriever_* additionally receive the type-specific payload (messages, tokens, tool name, query, …). Their default implementations delegate to the generic layer, so a handler that only cares about lifecycle may override just the three generic methods, while a handler that needs typed data overrides the typed ones.

Handlers should prefer overriding the typed methods when they need more than lifecycle signals; the built-in FileCallbackHandler and GenericHandler do exactly that.

Required Methods§

Source

fn on_run_start<'life0, 'life1, 'async_trait>( &'life0 self, run: &'life1 RunTree, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Called when any run starts

Source

fn on_run_end<'life0, 'life1, 'async_trait>( &'life0 self, run: &'life1 RunTree, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Called when a run ends successfully

Source

fn on_run_error<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, run: &'life1 RunTree, error: &'life2 str, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Called when a run fails

Provided Methods§

Source

fn on_llm_start<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, run: &'life1 RunTree, _messages: &'life2 [Message], ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Called when an LLM starts

Source

fn on_llm_end<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, run: &'life1 RunTree, _response: &'life2 str, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Called when an LLM ends

Source

fn on_llm_new_token<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _run: &'life1 RunTree, _token: &'life2 str, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Called for each new token during streaming

Source

fn on_llm_thinking<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _run: &'life1 RunTree, _thinking: &'life2 str, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Called for each thinking token during streaming (extended thinking).

Anthropic’s extended thinking feature emits thinking content blocks before the final text response. This callback fires for each chunk of thinking content, allowing consumers to observe the model’s reasoning process in real time.

Source

fn on_llm_error<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, run: &'life1 RunTree, error: &'life2 str, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Called when an LLM errors

Source

fn on_chain_start<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, run: &'life1 RunTree, _inputs: &'life2 Value, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Called when a chain starts

Source

fn on_chain_end<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, run: &'life1 RunTree, _outputs: &'life2 Value, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Called when a chain ends

Source

fn on_chain_error<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, run: &'life1 RunTree, error: &'life2 str, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Called when a chain errors

Source

fn on_tool_start<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, run: &'life1 RunTree, _tool_name: &'life2 str, _input: &'life3 str, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Called when a tool starts

Source

fn on_tool_end<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, run: &'life1 RunTree, _output: &'life2 str, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Called when a tool ends

Source

fn on_tool_error<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, run: &'life1 RunTree, error: &'life2 str, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Called when a tool errors

Source

fn on_retriever_start<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, run: &'life1 RunTree, _query: &'life2 str, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Called when a retriever starts

Source

fn on_retriever_end<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, run: &'life1 RunTree, _documents: &'life2 [Value], ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Called when a retriever ends

Source

fn on_retriever_error<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, run: &'life1 RunTree, error: &'life2 str, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Called when a retriever errors

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§