LangChain IBM Integration

1.0.6 · active · verified Tue Apr 14

langchain-ibm is an integration package that connects LangChain with IBM watsonx.ai, leveraging the ibm-watsonx-ai SDK. It provides wrappers for various IBM watsonx.ai capabilities, including chat models, large language models (LLMs), embedding models, and rerankers, enabling developers to build AI applications using IBM's foundation models within the LangChain framework. The library is actively maintained with frequent updates and releases.

Warnings

breaking LangChain v1 introduced significant changes to package namespaces and import paths within the core LangChain library. If you are migrating from an older LangChain version, ensure your `langchain-core` dependency is compatible and update imports accordingly, as older tutorials may break.
Fix: Upgrade `langchain-core` to a compatible version (>=1.0.0 for LangChain v1) and review LangChain's official migration guides for updated import paths and API changes. Check `langchain-ibm` release notes for specific `langchain-core` version requirements.
gotcha IBM watsonx.ai models require an API key and Project ID, which should ideally be set as environment variables (e.g., `WATSONX_API_KEY`, `WATSONX_PROJECT_ID`) rather than hardcoding. Also, the `model_id` and `url` must be correctly specified for your watsonx.ai service instance.
Fix: Set `WATSONX_API_KEY` and `WATSONX_PROJECT_ID` environment variables. Ensure `model_id` and `url` parameters are accurate for your chosen watsonx.ai model and region during model initialization.
gotcha Different watsonx.ai model types (chat, LLM, reranker) require specific parameter schemas (e.g., `TextChatParameters` for `ChatWatsonx`, `TextGenParameters` for `WatsonxLLM`, `RerankParameters` for `WatsonxRerank`). Using the wrong schema will lead to errors.
Fix: Import and use the correct parameter schema class from `ibm_watsonx_ai.foundation_models.schema` corresponding to the LangChain-IBM model wrapper you are initializing.
breaking A serialization injection vulnerability (CVE-2025-68664) was found in LangChain's `dumps()` and `dumpd()` functions, allowing untrusted data with 'lc' keys to be deserialized as objects. This directly affects `langchain-core` versions and, by extension, applications using `langchain-ibm` that rely on these serialization methods.
Fix: Upgrade `langchain-core` to version 0.3.81 / 1.2.5 or higher. Ensure any downstream IBM products like `watsonx.data` are also updated to their latest patched versions (e.g., `watsonx.data 2.3.1` or `watsonx.data on CPD 5.3.1`).
gotcha There is an open bug where `asyncio` calls may fail due to synchronous, connection-pooled HTTP clients in the underlying `ibm-watsonx-ai` SDK. This can lead to unexpected behavior or deadlocks in asynchronous applications.
Fix: Monitor the `langchain-ibm` GitHub repository for updates and patches related to issue #83. Consider using synchronous calls or implementing workarounds if asynchronous operations are critical and exhibit this behavior.

Install

pip install -U langchain-ibm Install `langchain-ibm`

Imports

ChatWatsonx
```
from langchain_ibm import ChatWatsonx
```
WatsonxLLM
```
from langchain_ibm import WatsonxLLM
```

WatsonxEmbeddings

from langchain_ibm import WatsonxEmbeddings

WatsonxRerank
```
from langchain_ibm import WatsonxRerank
```

TextChatParameters

from ibm_watsonx_ai.foundation_models.schema import TextChatParameters

Required for configuring ChatWatsonx models.

TextGenParameters

from ibm_watsonx_ai.foundation_models.schema import TextGenParameters

Required for configuring WatsonxLLM models.

Quickstart

This quickstart demonstrates how to initialize and use the `ChatWatsonx` model. It requires an IBM Cloud API key and a watsonx.ai Project ID, which should be set as environment variables for security. You also need to specify a `model_id` and the appropriate `url` for your watsonx.ai service instance.

import os
from getpass import getpass
from langchain_ibm import ChatWatsonx
from ibm_watsonx_ai.foundation_models.schema import TextChatParameters

# Set environment variables (replace with your actual values or retrieve from a secure source)
if not os.environ.get("WATSONX_API_KEY"): os.environ["WATSONX_API_KEY"] = getpass("Enter your IBM Cloud API Key: ")
if not os.environ.get("WATSONX_PROJECT_ID"): os.environ["WATSONX_PROJECT_ID"] = getpass("Enter your IBM watsonx.ai Project ID: ")

# Define model parameters
parameters = TextChatParameters(
    temperature=0.7,
    max_completion_tokens=500
)

# Initialize the ChatWatsonx model
# Replace with your actual model_id and url
model = ChatWatsonx(
    model_id="ibm/granite-13b-chat-v2", 
    url="https://us-south.ml.cloud.ibm.com", # Example URL, choose based on your region
    project_id=os.environ["WATSONX_PROJECT_ID"],
    params=parameters,
)

# Invoke the model
response = model.invoke("What is the capital of France?")
print(response.content)

view raw JSON →