Langchain Integration (Python & JS/TS)
Langfuse integrates with Langchain using Langchain Callbacks (Python (opens in a new tab), JS (opens in a new tab)). Thereby, the Langfuse SDK automatically creates a nested trace for every run of your Langchain applications.
Add Langfuse to your Langchain application
You can configure the integration via (1) constructor arguments or (2) environment variables. Get your Langfuse credentials from the Langfuse dashboard.
Prefer end-to-end examples? Check out the cookbook (Python).
pip install langfuse# Initialize Langfuse handler
from langfuse.callback import CallbackHandler
langfuse_handler = CallbackHandler(
secret_key="sk-lf-...",
public_key="pk-lf-...",
host="https://cloud.langfuse.com", # 🇪🇺 EU region
# host="https://us.cloud.langfuse.com", # 🇺🇸 US region
)
# Your Langchain code
# Add Langfuse handler as callback to `run`, `predict`, `invoke`
# Works for traditional Langchain code and LCEL
chain.run(input="<user_input>", callbacks=[langfuse_handler])
conversation.predict(input="<user_input>", callbacks=[langfuse_handler])
chain.invoke({"input": "<user_input>"}, config={"callbacks": [langfuse_handler]})Done. Now you can explore detailed traces and metrics in the Langfuse dashboard.
Additional Configuration
Optional constructor arguments
When initializing the Langfuse handler, you can pass the following optional arguments to use more advanced features.
| Python | JS/TS | Type | Description |
|---|---|---|---|
user_id | userId | string | The current user. |
session_id | sessionId | string | The current session. |
release | release | string | The release of your application. See experimentation docs for details. |
version | version | string | The version of your application. See experimentation docs for details. |
trace_name | string | Customize the name of the created traces. Defaults to name of chain. |
Supported Langchain interfaces
| Feature/interface | Python | JS/TS |
|---|---|---|
| LCEL | ✅ | ✅ |
invoke() | ✅ | ✅ |
run() | ✅ | ✅ |
call() | ✅ | ✅ |
predict() | ✅ | ✅ |
| async | ✅ | |
batch() | ||
| streaming |
We are interested in your feedback! Raise an issue on GitHub to request support for additional interfaces.
Interoperability with Langfuse SDKs
Use the Langchain integration in combination with the regular Langfuse SDKs if you want to:
- Add non-Langchain related observations to the trace.
- Group multiple Langchain runs into a single trace.
Learn more about the structure of a trace here.
# Intialize Langfuse Client
from langfuse import Langfuse
langfuse = Langfuse()
# Get Langchain handler for a trace
trace = langfuse.trace()
langfuse_handler_trace = trace.get_langchain_handler()
# Get Langchain handler for a span
span = trace.span()
langfuse_handler_span = span.get_langchain_handler()If you pass these callback handlers to your Langchain code, the events will be nested under the respective trace or span in the Langfuse.
See the cookbook for an example of this in action (Python).
Limitation: The input/output of the Langchain code will not be added to the trace or span. Adding them would cause unwanted side-effects if they are set manually or if you add multiple Langchain runs. If you want the input/output of the Langchain run on the trace/span, you need to add them yourself via the regular Langfuse SDKs.
Queuing and flushing
The Langfuse SDKs queue and batch events in the background to reduce the number of network requests and improve overall performance. In a long-running application, this works without any additional configuration.
If you are running a short-lived application, you need to shutdown Langfuse to ensure that all events are flushed before the application exits.
langfuse_handler.shutdown_async()If you want to flush events synchronously without shutting down Langfuse, you can use the flush method.
langfuse_handler.flush_async()