DOC: Document how to pass callbacks with Runnable methods (e.g., .invoke / .batch)

[eyurtsev]

Issue with current documentation:

https://python.langchain.com/docs/modules/callbacks/#when-do-you-want-to-use-each-of-these

Idea or request for content:

Document how to pass callbacks via .invoke

[dosubot]

🤖

In the LangChain framework, callbacks are passed through the config parameter in the invoke, batch, ainvoke, and abatch methods. The config parameter is an instance of RunnableConfig or a list of RunnableConfig instances.

Here is an example of how you can pass a callback using the config parameter:

from langchain_core.tracers.root_listeners import RootListenersTracer

# Define your callbacks
def on_start(run):
    print(f"Start: {run}")

def on_end(run):
    print(f"End: {run}")

def on_error(run):
    print(f"Error: {run}")

# Create a RunnableConfig with your callbacks
config = {
    "callbacks": [
        RootListenersTracer(
            config=config,
            on_start=on_start,
            on_end=on_end,
            on_error=on_error,
        )
    ],
}

# Pass the config to the invoke method
output = runnable.invoke(input, config)

In this example, on_start, on_end, and on_error are callback functions that are called when the Runnable starts, ends, and encounters an error, respectively. These callbacks are wrapped in a RootListenersTracer instance, which is passed to the invoke method through the config parameter.

The same approach can be used for the batch, ainvoke, and abatch methods. You can find more details in the source code.

The invoke and batch methods of the LangChain framework accept the following parameters:

1. invoke method:

   • input: Input: The input to the runnable.
   • config: Optional[RunnableConfig] = None: The config to use for the runnable.
   • **kwargs: Optional[Any]: Additional keyword arguments to pass to the runnable.

2. batch method:

   • inputs: List[Input]: A list of inputs to the runnable.
   • config: Optional[Union[RunnableConfig, List[RunnableConfig]]] = None: The config to use for the runnable. It can be a single config or a list of configs.
   • return_exceptions: bool = False: A flag indicating whether to return exceptions or not.
   • **kwargs: Optional[Any]: Additional keyword arguments to pass to the runnable.

The RunnableConfig class in the LangChain framework accepts the following parameters:

1. tags: This is a list of strings. Tags for this call and any sub-calls (e.g., a Chain calling an LLM). You can use these to filter calls.

2. metadata: This is a dictionary where keys should be strings, and values should be JSON-serializable. Metadata for this call and any sub-calls (e.g., a Chain calling an LLM).

3. callbacks: This is an optional parameter. Callbacks for this call and any sub-calls (e.g., a Chain calling an LLM). Tags are passed to all callbacks, metadata is passed to handle*Start callbacks.

4. run_name: This is a string parameter. Name for the tracer run for this call. Defaults to the name of the class.

5. max_concurrency: This is an optional integer parameter. Maximum number of parallel calls to make. If not provided, defaults to ThreadPoolExecutor's default.

6. recursion_limit: This is an integer parameter. Maximum number of times a call can recurse. If not provided, defaults to 25.

7. configurable: This is a dictionary. Runtime values for attributes previously made configurable on this Runnable, or sub-Runnables, through .configurable_fields() or .configurable_alternatives(). Check .output_schema() for a description of the attributes that have been made configurable.

I hope this helps! If you have any other questions, feel free to ask.

Sources

• libs/core/langchain_core/runnables/base.py
• libs/core/langchain_core/runnables/config.py

---

This response is meant to be useful and save you time. It is not meant to be a precise solution, but rather a starting point for your own research.

Help me be more useful! Please leave a 👍 if this is helpful and 👎 if it is irrelevant.

If you want to continue the conversation, start your reply with @dosu-bot.