Struct FileCallbackHandler 

pub struct FileCallbackHandler {
    pub color: Option<String>,
    /* private fields */
}

Callback Handler that writes to a file.

This handler supports writing callback output to a file. It can be used to log chain execution to a file for debugging or auditing purposes.

Example

use agent_chain_core::callbacks::FileCallbackHandler;

// Using with mode string (recommended, matches Python API)
let handler = FileCallbackHandler::with_mode("output.txt", "a")?;

// Using with append boolean
let handler = FileCallbackHandler::new("output.txt", false)?;

Fields

color: Option<String>

The color to use for the text (not used for file output but kept for API compatibility).

Implementations

impl FileCallbackHandler

pub fn new<P: AsRef<Path>>(filename: P, append: bool) -> Result<Self>

Create a new FileCallbackHandler.

Arguments

• filename - The path to the output file.
• append - Whether to append to the file or truncate it.

Returns

A Result containing the FileCallbackHandler or an IO error.

pub fn with_mode<P: AsRef<Path>>(filename: P, mode: &str) -> Result<Self>

Create a new FileCallbackHandler with a specific file mode.

This matches the Python API more closely.

Arguments

• filename - Path to the output file.
• mode - File open mode (e.g., “w”, “a”, “x”). Defaults to “a”.

Returns

A Result containing the FileCallbackHandler or an IO error.

pub fn with_color<P: AsRef<Path>>( filename: P, mode: &str, color: impl Into<String>, ) -> Result<Self>

Create a new FileCallbackHandler with a specific color.

Arguments

• filename - Path to the output file.
• mode - File open mode (e.g., “w”, “a”). Defaults to “a”.
• color - Default text color for output.

pub fn filename(&self) -> &str

Get the file path (filename).

pub fn mode(&self) -> &str

Get the file mode.

pub fn close(&mut self)

Close the file if it’s open.

This method is safe to call multiple times and will only close the file if it’s currently open.

pub fn flush(&mut self) -> Result<()>

Flush the writer.

Trait Implementations

impl BaseCallbackHandler for FileCallbackHandler

fn name(&self) -> &str

Get a unique name for this handler. Note: This is a Rust-specific addition for debugging purposes.

fn raise_error(&self) -> bool

Whether to raise an error if an exception occurs.

fn run_inline(&self) -> bool

Whether to run the callback inline.

fn ignore_llm(&self) -> bool

Whether to ignore LLM callbacks.

fn ignore_retry(&self) -> bool

Whether to ignore retry callbacks.

fn ignore_chain(&self) -> bool

Whether to ignore chain callbacks.

fn ignore_agent(&self) -> bool

Whether to ignore agent callbacks.

fn ignore_retriever(&self) -> bool

Whether to ignore retriever callbacks.

fn ignore_chat_model(&self) -> bool

Whether to ignore chat model callbacks.

fn ignore_custom_event(&self) -> bool

Whether to ignore custom events.

impl CallbackManagerMixin for FileCallbackHandler

fn on_chain_start( &mut self, serialized: &HashMap<String, Value>, _inputs: &HashMap<String, Value>, _run_id: Uuid, _parent_run_id: Option<Uuid>, _tags: Option<&[String]>, metadata: Option<&HashMap<String, Value>>, )

Run when a chain starts running.

fn on_llm_start( &mut self, serialized: &HashMap<String, Value>, prompts: &[String], run_id: Uuid, parent_run_id: Option<Uuid>, tags: Option<&[String]>, metadata: Option<&HashMap<String, Value>>, )

Run when LLM starts running.

fn on_chat_model_start( &mut self, serialized: &HashMap<String, Value>, messages: &[Vec<BaseMessage>], run_id: Uuid, parent_run_id: Option<Uuid>, tags: Option<&[String]>, metadata: Option<&HashMap<String, Value>>, )

Run when a chat model starts running.

fn on_retriever_start( &mut self, serialized: &HashMap<String, Value>, query: &str, run_id: Uuid, parent_run_id: Option<Uuid>, tags: Option<&[String]>, metadata: Option<&HashMap<String, Value>>, )

Run when the Retriever starts running.

fn on_tool_start( &mut self, serialized: &HashMap<String, Value>, input_str: &str, run_id: Uuid, parent_run_id: Option<Uuid>, tags: Option<&[String]>, metadata: Option<&HashMap<String, Value>>, inputs: Option<&HashMap<String, Value>>, )

Run when the tool starts running.

impl ChainManagerMixin for FileCallbackHandler

fn on_agent_action( &mut self, action: &Value, _run_id: Uuid, _parent_run_id: Option<Uuid>, _color: Option<&str>, )

Handle agent action by writing the action log.

fn on_agent_finish( &mut self, finish: &Value, _run_id: Uuid, _parent_run_id: Option<Uuid>, _color: Option<&str>, )

Handle agent finish by writing the finish log.

fn on_chain_end( &mut self, _outputs: &HashMap<String, Value>, _run_id: Uuid, _parent_run_id: Option<Uuid>, )

Run when chain ends running.

fn on_chain_error( &mut self, error: &dyn Error, run_id: Uuid, parent_run_id: Option<Uuid>, )

Run when chain errors.

impl Debug for FileCallbackHandler

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for FileCallbackHandler

fn drop(&mut self)

Executes the destructor for this type.

impl LLMManagerMixin for FileCallbackHandler

fn on_llm_new_token( &mut self, token: &str, run_id: Uuid, parent_run_id: Option<Uuid>, chunk: Option<&Value>, )

Run on new output token. Only available when streaming is enabled.

fn on_llm_end( &mut self, response: &ChatResult, run_id: Uuid, parent_run_id: Option<Uuid>, )

Run when LLM ends running.

fn on_llm_error( &mut self, error: &dyn Error, run_id: Uuid, parent_run_id: Option<Uuid>, )

Run when LLM errors.

impl RetrieverManagerMixin for FileCallbackHandler

fn on_retriever_error( &mut self, error: &dyn Error, run_id: Uuid, parent_run_id: Option<Uuid>, )

Run when Retriever errors.

fn on_retriever_end( &mut self, documents: &[Value], run_id: Uuid, parent_run_id: Option<Uuid>, )

Run when Retriever ends running.

impl RunManagerMixin for FileCallbackHandler

fn on_text( &mut self, text: &str, _run_id: Uuid, _parent_run_id: Option<Uuid>, _color: Option<&str>, end: &str, )

Handle text output.

fn on_retry( &mut self, retry_state: &dyn Any, run_id: Uuid, parent_run_id: Option<Uuid>, )

Run on a retry event.

fn on_custom_event( &mut self, name: &str, data: &dyn Any, run_id: Uuid, tags: Option<&[String]>, metadata: Option<&HashMap<String, Value>>, )

Override to define a handler for a custom event.

impl ToolManagerMixin for FileCallbackHandler

fn on_tool_end( &mut self, output: &str, _run_id: Uuid, _parent_run_id: Option<Uuid>, _color: Option<&str>, observation_prefix: Option<&str>, llm_prefix: Option<&str>, )

Handle tool end by writing the output.

fn on_tool_error( &mut self, error: &dyn Error, run_id: Uuid, parent_run_id: Option<Uuid>, )

Run when tool errors.