diff --git a/docs/docs/concepts.mdx b/docs/docs/concepts.mdx index 924be764ca3..d749d56c830 100644 --- a/docs/docs/concepts.mdx +++ b/docs/docs/concepts.mdx @@ -482,80 +482,64 @@ LangChain provides a callbacks system that allows you to hook into the various s You can subscribe to these events by using the `callbacks` argument available throughout the API. This argument is list of handler objects, which are expected to implement one or more of the methods described below in more detail. +#### Callback Events + +| Event | Event Trigger | Associated Method | +|------------------|---------------------------------------------|-----------------------| +| Chat model start | When a chat model starts | `on_chat_model_start` | +| LLM start | When a llm starts | `on_llm_start` | +| LLM new token | When an llm OR chat model emits a new token | `on_llm_new_token` | +| LLM ends | When an llm OR chat model ends | `on_llm_end` | +| LLM errors | When an llm OR chat model errors | `on_llm_error` | +| Chain start | When a chain starts running | `on_chain_start` | +| Chain end | When a chain ends | `on_chain_end` | +| Chain error | When a chain errors | `on_chain_error` | +| Tool start | When a tool starts running | `on_tool_start` | +| Tool end | When a tool ends | `on_tool_end` | +| Tool error | When a tool errors | `on_tool_error` | +| Agent action | When an agent takes an action | `on_agent_action` | +| Agent finish | When an agent ends | `on_agent_finish` | +| Retriever start | When a retriever starts | `on_retriever_start` | +| Retriever end | When a retriever ends | `on_retriever_end` | +| Retriever error | When a retriever errors | `on_retriever_error` | +| Text | When arbitrary text is run | `on_text` | +| Retry | When a retry event is run | `on_retry` | + #### Callback handlers -`CallbackHandlers` are objects that implement the [`CallbackHandler`](https://api.python.langchain.com/en/latest/callbacks/langchain_core.callbacks.base.BaseCallbackHandler.html#langchain-core-callbacks-base-basecallbackhandler) interface, which has a method for each event that can be subscribed to. -The `CallbackManager` will call the appropriate method on each handler when the event is triggered. +Callback handlers can either be `sync` or `async`: -```python -class BaseCallbackHandler: - """Base callback handler that can be used to handle callbacks from langchain.""" +* Sync callback handlers implement the [BaseCallbackHandler](https://api.python.langchain.com/en/latest/callbacks/langchain_core.callbacks.base.BaseCallbackHandler.html) interface. +* Async callback handlers implement the [AsyncCallbackHandler](https://api.python.langchain.com/en/latest/callbacks/langchain_core.callbacks.base.AsyncCallbackHandler.html) interface. - def on_llm_start( - self, serialized: Dict[str, Any], prompts: List[str], **kwargs: Any - ) -> Any: - """Run when LLM starts running.""" - - def on_chat_model_start( - self, serialized: Dict[str, Any], messages: List[List[BaseMessage]], **kwargs: Any - ) -> Any: - """Run when Chat Model starts running.""" - - def on_llm_new_token(self, token: str, **kwargs: Any) -> Any: - """Run on new LLM token. Only available when streaming is enabled.""" - - def on_llm_end(self, response: LLMResult, **kwargs: Any) -> Any: - """Run when LLM ends running.""" - - def on_llm_error( - self, error: Union[Exception, KeyboardInterrupt], **kwargs: Any - ) -> Any: - """Run when LLM errors.""" - - def on_chain_start( - self, serialized: Dict[str, Any], inputs: Dict[str, Any], **kwargs: Any - ) -> Any: - """Run when chain starts running.""" - - def on_chain_end(self, outputs: Dict[str, Any], **kwargs: Any) -> Any: - """Run when chain ends running.""" - - def on_chain_error( - self, error: Union[Exception, KeyboardInterrupt], **kwargs: Any - ) -> Any: - """Run when chain errors.""" - - def on_tool_start( - self, serialized: Dict[str, Any], input_str: str, **kwargs: Any - ) -> Any: - """Run when tool starts running.""" - - def on_tool_end(self, output: Any, **kwargs: Any) -> Any: - """Run when tool ends running.""" - - def on_tool_error( - self, error: Union[Exception, KeyboardInterrupt], **kwargs: Any - ) -> Any: - """Run when tool errors.""" - - def on_text(self, text: str, **kwargs: Any) -> Any: - """Run on arbitrary text.""" - - def on_agent_action(self, action: AgentAction, **kwargs: Any) -> Any: - """Run on agent action.""" - - def on_agent_finish(self, finish: AgentFinish, **kwargs: Any) -> Any: - """Run on agent end.""" -``` +During run-time LangChain configures an appropriate callback manager (e.g., [CallbackManager](https://api.python.langchain.com/en/latest/callbacks/langchain_core.callbacks.manager.CallbackManager.html) or [AsyncCallbackManager](https://api.python.langchain.com/en/latest/callbacks/langchain_core.callbacks.manager.AsyncCallbackManager.html) which will be responsible for calling the appropriate method on each "registered" callback handler when the event is triggered. #### Passing callbacks The `callbacks` property is available on most objects throughout the API (Models, Tools, Agents, etc.) in two different places: -- **Constructor callbacks**: defined in the constructor, e.g. `ChatAnthropic(callbacks=[handler], tags=['a-tag'])`. In this case, the callbacks will be used for all calls made on that object, and will be scoped to that object only. - For example, if you initialize a chat model with constructor callbacks, then use it within a chain, the callbacks will only be invoked for calls to that model. -- **Request callbacks**: passed into the `invoke` method used for issuing a request. In this case, the callbacks will be used for that specific request only, and all sub-requests that it contains (e.g. a call to a sequence that triggers a call to a model, which uses the same handler passed in the `invoke()` method). - In the `invoke()` method, callbacks are passed through the `config` parameter. +The callbacks are available on most objects throughout the API (Models, Tools, Agents, etc.) in two different places: + +- **Request time callbacks**: Passed at the time of the request in addition to the input data. + Available on all standard `Runnable` objects. These callbacks are INHERITED by all children + of the object they are defined on. For example, `chain.invoke({"number": 25}, {"callbacks": [handler]})`. +- **Constructor callbacks**: `chain = TheNameOfSomeChain(callbacks=[handler])`. These callbacks + are passed as arguments to the constructor of the object. The callbacks are scoped + only to the object they are defined on, and are **not** inherited by any children of the object. + +:::warning +Constructor callbacks are scoped only to the object they are defined on. They are **not** inherited by children +of the object. +::: + +If you're creating a custom chain or runnable, you need to remember to propagate request time +callbacks to any child objects. + +:::important +For code running python >=3.11, LangChain is able to automatically propagate +request time callbacks to child objects. This feature was added since +added as users forgetting to propagate callbacks was a common problem. +::: ## Techniques