IBM watsonx.ai Java SDK

The IBM watsonx.ai Java SDK is an open-source client library that interacts with IBM watsonx.ai, an enterprise-grade AI platform for building, training, and deploying AI models at scale.

Prerequisites

Before getting started, ensure you have:

• A watsonx.ai service instance (IBM Cloud or on-premises)
• Java 17 or higher
• Maven or Gradle

Installation

Add the SDK to your Maven project:

<dependency>
    <groupId>com.ibm.watsonx</groupId>
    <artifactId>watsonx-ai</artifactId>
    <version>0.19.0</version>
</dependency>

Or for Gradle:

implementation 'com.ibm.watsonx:watsonx-ai:0.19.0'

Quick Start

Build and run your first watsonx.ai-powered chat:

ChatService chatService = ChatService.builder()
    .apiKey(System.getenv("WATSONX_API_KEY"))
    .projectId(System.getenv("WATSONX_PROJECT_ID"))
    .baseUrl(CloudRegion.DALLAS)
    .modelId("ibm/granite-4-h-small")
    .build();

AssistantMessage response = chatService
    .chat("Tell me a joke")
    .toAssistantMessage();

System.out.println(response.content());

See the documentation for advanced usage.

Samples

Examples of usage are available in the samples/ directory.

Framework Integrations

The SDK integrates seamlessly with popular Java frameworks:

• LangChain4j – Native integration for building LLM-powered applications in Java.
• Quarkus LangChain4j – Optimized integration for building LLM-powered applications with Quarkus.
• Apache Camel – Integrate AI capabilities into enterprise integration patterns and workflows.

Contributing

We welcome contributions! Please follow these guidelines when submitting a patch:

License header: all source files must include an SPDX header for Apache License 2.0:

/*
 * Copyright 2025 IBM Corporation
 * SPDX-License-Identifier: Apache-2.0
 */

The header and code formatting are applied automatically by running:

./mvnw compile

DCO sign-off: include a Signed-off-by line in your commit message:

Signed-off-by: Your Name <your.email@example.com>

Add it automatically with:

git commit -s

License

Apache License 2.0 — see the LICENSE file for details.