## Issue
Closes#5258
## Change
Adds typed MCP icon support for MCP list results:
- stores top-level `icons` from MCP tools in
`ToolSpecification.metadata()` under `McpToolMetadataKeys.ICONS` as
`List<McpIcon>`;
- adds `McpIcon` and `McpIconTheme` for the MCP icon schema;
- exposes `_meta` via `metadata()` and top-level `icons` via `icons()`
on `McpResource`, `McpResourceTemplate`, and `McpPrompt`;
- keeps existing public constructors for resource/prompt/template models
for source compatibility;
- removes the metadata helper;
- adds focused parsing tests for present and absent metadata/icons.
## General checklist
- [X] There are no breaking changes (API, behaviour)
- [X] I have added unit and/or integration tests for my change
- [X] The tests cover both positive and negative cases
- [ ] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green
- [ ] I have manually run all the unit and integration tests in the
[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)
and
[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)
modules, and they are all green
- [ ] I have added/updated the
[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)
- [ ] I have added an example in the [examples
repo](https://github.com/langchain4j/langchain4j-examples) (only for
"big" features)
- [ ] I have added/updated [Spring Boot
starter(s)](https://github.com/langchain4j/langchain4j-spring) (if
applicable)
## Checklist for adding new maven module
- [ ] I have added my new module in the root `pom.xml` and
`langchain4j-bom/pom.xml`
## Checklist for adding new embedding store integration
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreIT` that extends
from either `EmbeddingStoreIT` or `EmbeddingStoreWithFilteringIT`
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreRemovalIT` that
extends from `EmbeddingStoreWithRemovalIT`
## Checklist for changing existing embedding store integration
- [ ] I have manually verified that the
`{NameOfIntegration}EmbeddingStore` works correctly with the data
persisted using the latest released version of LangChain4j
## Verification
- `mvn -pl langchain4j-mcp test -Dmaven.javadoc.skip=true -DskipITs
-Ddokka.skip=true`
- `mvn -pl langchain4j-mcp
-Dtest=McpMetadataParsingTest,ToolSpecificationHelperTest test
-Dmaven.javadoc.skip=true -DskipITs -Ddokka.skip=true`
- `mvn -pl langchain4j-mcp spotless:check -Dmaven.javadoc.skip=true
-DskipTests -DskipITs -Ddokka.skip=true`
- `git diff --check`
<!--
Thank you so much for your contribution!
Please fill in all the sections below.
Please open the PR as a draft initially. Once it is reviewed and
approved, we will ask you to add documentation and examples.
Please note that PRs with breaking changes or without tests will be
rejected.
Please note that PRs will be reviewed based on the priority of the
issues they address.
We ask for your patience. We are doing our best to review your PR as
quickly as possible.
Please refrain from pinging and asking when it will be reviewed. Thank
you for understanding!
-->
## Issue
<!-- Please specify the ID of the issue this PR is addressing. For
example: "Closes #1234" or "Fixes #1234" -->
Closes#5311
## Change
I added to documentation how this works and pasting documentation here
for your convenience.
**Multi-turn conversations with A2A servers**
The A2A protocol supports multi-turn conversations through `contextId`
and `taskId` fields on the message envelope. A `contextId` groups
related tasks into a conversation, while a `taskId` references a
specific task within that conversation. When omitted, the A2A server
generates new values; when provided, the server continues the existing
conversation.
To pass these fields on the outgoing message envelope, annotate method
parameters with `@A2AContextId` and `@A2ATaskId`. These parameters are
**not** sent as message content — they are set on the message envelope
instead.
```java
public interface ChatAgent {
@A2AClientAgent(a2aServerUrl = "http://localhost:8080", outputKey = "response")
String chat(@V("question") String question,
@A2AContextId @V("contextId") String contextId,
@A2ATaskId @V("taskId") String taskId);
}
```
When `null` is passed for `contextId` or `taskId`, the field is omitted
from the envelope and the server creates new values.
When the `@A2AContextId` or `@A2ATaskId` parameters also have
recognizable names, possibly configured through the `@V` annotation, the
server-assigned values from the response are automatically written back
to the `AgenticScope` under that name. This enables multi-turn flows
where the first call captures the IDs and subsequent calls reuse them.
If the method returns `ResultWithAgenticScope`, the IDs are accessible
directly:
```java
public interface ChatAgent {
@A2AClientAgent(a2aServerUrl = "http://localhost:8080", outputKey = "response")
ResultWithAgenticScope<String> chat(
@V("question") String question,
@A2AContextId @V("contextId") String contextId,
@A2ATaskId @V("taskId") String taskId);
}
// First turn — server generates contextId and taskId
ResultWithAgenticScope<String> first = chatAgent.chat("hello", null, null);
String contextId = (String) first.agenticScope().readState("contextId");
String taskId = (String) first.agenticScope().readState("taskId");
// Second turn — reuse the server-generated IDs to continue the conversation
ResultWithAgenticScope<String> second = chatAgent.chat("follow-up", contextId, taskId);
```
In this way, when an A2A agent is used in an agentic system, the
`contextId` and `taskId` are automatically propagated through the shared
`AgenticScope`. This means a sequence of two A2A calls to the same
server will naturally form a multi-turn conversation:
```java
public interface EchoSubAgent {
@A2AClientAgent(a2aServerUrl = "http://localhost:8080", outputKey = "response")
String echo(@V("question") String question,
@A2AContextId @V("contextId") String contextId,
@A2ATaskId @V("taskId") String taskId);
}
public interface MultiTurnWorkflow extends AgenticScopeAccess {
@Agent
ResultWithAgenticScope<String> converse(@V("question") String question);
}
EchoSubAgent firstTurn = AgenticServices
.a2aBuilder("http://localhost:8080", EchoSubAgent.class)
.outputKey("firstResponse").build();
EchoSubAgent secondTurn = AgenticServices
.a2aBuilder("http://localhost:8080", EchoSubAgent.class)
.outputKey("secondResponse").build();
MultiTurnWorkflow workflow = AgenticServices.sequenceBuilder(MultiTurnWorkflow.class)
.subAgents(firstTurn, secondTurn)
.outputKey("secondResponse").build();
ResultWithAgenticScope<String> result = workflow.converse("hello");
```
In this sequence, the first agent sends a message with no
`contextId`/`taskId` (they are `null` in the scope). The server creates
a new task and context. The response IDs are written to the scope. When
the second agent runs, it reads the now-populated `contextId` and
`taskId` from the scope and sends them on the message envelope,
continuing the same conversation.
## General checklist
<!-- Please double-check the following points and mark them like this:
[X] -->
- [X] There are no breaking changes (API, behaviour)
- [X] I have added unit and/or integration tests for my change
- [X] The tests cover both positive and negative cases
- [X] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green
- [ ] I have manually run all the unit and integration tests in the
[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)
and
[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)
modules, and they are all green
<!-- Before adding documentation and example(s) (below), please wait
until the PR is reviewed and approved. -->
- [ ] I have added/updated the
[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)
- [ ] I have added an example in the [examples
repo](https://github.com/langchain4j/langchain4j-examples) (only for
"big" features)
- [ ] I have added/updated [Spring Boot
starter(s)](https://github.com/langchain4j/langchain4j-spring) (if
applicable)
## Checklist for adding new maven module
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have added my new module in the root `pom.xml` and
`langchain4j-bom/pom.xml`
## Checklist for adding new embedding store integration
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreIT` that extends
from either `EmbeddingStoreIT` or `EmbeddingStoreWithFilteringIT`
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreRemovalIT` that
extends from `EmbeddingStoreWithRemovalIT`
## Checklist for changing existing embedding store integration
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have manually verified that the
`{NameOfIntegration}EmbeddingStore` works correctly with the data
persisted using the latest released version of LangChain4j
- Implemented comprehensive Batch API support covering all major
modalities: GoogleGenAiBatchChatModel, GoogleGenAiBatchEmbeddingModel,
and GoogleGenAiBatchImageModel. These new classes support both inline
requests and file-based batch job creation, along with retrieval,
cancellation, and deletion operations.
- Exposed GroundingMetadata in GoogleGenAiChatResponseMetadata by
mapping it directly from the SDK's Candidate response in
GoogleGenAiContentMapper.
- Added support for custom labels mapping in GoogleGenAiImageModel and
GoogleGenAiBatchImageModel using GenerateContentConfig.
- Updated test suites to use newer Gemini model versions, replacing
gemini-2.0-flash with gemini-3.1-flash-lite.
---------
Co-authored-by: Akshay Dipta <akshay.dipta@gmail.com>
Co-authored-by: Dmytro Liubarskyi <ljubarskij@gmail.com>
Co-authored-by: Dmytro Skarzhynets <d.skarzh@protonmail.com>
## Issue
Progresses #3916
### Summary
This PR refactors the batch processing response model to use a single
unified `BatchResponse<T>` class instead of the previous sealed
interface hierarchy (`BatchSuccess`, `BatchIncomplete`, `BatchError`).
This simplifies the API and provides a more consistent experience across
different batch model implementations. Will update docs and examples in
separate PRs.
### Breaking Changes
**Batch Models affected:**
- `BatchChatModel` (moved to `dev.langchain4j.model.chat`)
- `BatchEmbeddingModel` (moved to `dev.langchain4j.model.embedding`)
- `BatchImageModel` (moved to `dev.langchain4j.model.image`)
**Google AI Gemini (@Experimental) implementations:**
The existing Gemini batch implementations are updated to reflect these
new interfaces and the unified `BatchResponse` model.
#### Migration Guide
**Before:**
The API used a sealed interface hierarchy (`BatchSuccess`,
`BatchIncomplete`, etc.) and a shared `retrieveBatchResults` method.
```java
BatchResponse<ChatResponse> response = batchModel.retrieveBatchResults(batchName);
if (response instanceof BatchSuccess<ChatResponse> success) {
List<ChatResponse> results = success.responses();
} else if (response instanceof BatchIncomplete) { ... }
```
**After:**
The API uses a unified `BatchResponse<T>` with helper methods and
specialized `submit`/`retrieve` methods. Batch identifiers are now
wrapped in `BatchId`.
```java
// Using the new BatchRequest wrapper and submit method
String id = batchModel.submit(new BatchRequest<>(chatRequests)).batchId();
// Polling with the new retrieve method
BatchResponse<ChatResponse> response = batchModel.retrieve(id);
if (response.state() == BatchState.SUCCEEDED) {
List<ChatResponse> results = response.responses(); // Results list
} else if (!response.state().isTerminal()) {
// Still running
} else if (response.state() == BatchState.FAILED) {
List<BatchError> errors = response.errors(); // Detailed error info
}
```
### Changes
- **Decoupled Interfaces**: Created `BatchChatModel`,
`BatchEmbeddingModel`, and `BatchImageModel` in their respective
packages.
- **Unified `BatchResponse<T>`**: Replaced the sealed hierarchy with a
single class.
- **New `BatchRequest<T>`**: Introduced a wrapper for requests to allow
for future job-level parameters (e.g., Gemini's display name) without
breaking method signatures.
- **New Value Objects**:
- `BatchId`: Type-safe identifier for batch jobs.
- `BatchPage<T>`: Standardized record for paginated results in `list()`
operations.
- `BatchError`: Detailed error tracking including codes and
provider-specific metadata.
- **`BatchState` Enum**: Explicit lifecycle tracking (`PENDING`,
`RUNNING`, `SUCCEEDED`, `FAILED`, `CANCELLED`, `EXPIRED`).
## General checklist
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] There are no breaking changes (API, behaviour)
- [x] I have added unit and/or integration tests for my change
- [x] The tests cover both positive and negative cases
- [x] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green
- [x] I have manually run all the unit and integration tests in the
[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)
and
[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)
modules, and they are all green
<!-- Before adding documentation and example(s) (below), please wait
until the PR is reviewed and approved. -->
- [ ] I have added/updated the
[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)
---------
Signed-off-by: Ricardo Zanini <ricardozanini@gmail.com>
Signed-off-by: dependabot[bot] <support@github.com>
Signed-off-by: ZhangDT-sky <485918776@qq.com>
Co-authored-by: Mario Fusco <mario.fusco@gmail.com>
Co-authored-by: Julien Dubois <julien.dubois@gmail.com>
Co-authored-by: Bruno Baptista <brunobat@gmail.com>
Co-authored-by: Dmytro Liubarskyi <ljubarskij@gmail.com>
Co-authored-by: DragonFSKY <38503900+DragonFSKY@users.noreply.github.com>
Co-authored-by: David Pilato <david@pilato.fr>
Co-authored-by: Jean Bisutti <jean.bisutti@gmail.com>
Co-authored-by: Jan Martiska <wraychus@gmail.com>
Co-authored-by: Qice Sun <qicesun0401@gmail.com>
Co-authored-by: Marco Belladelli <marcobladel@gmail.com>
Co-authored-by: wangji0923 <wjgpt0923@gmail.com>
Co-authored-by: 复试资料 <study@example.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Katia Aresti <karesti@redhat.com>
Co-authored-by: Katia Aresti <karestig@ibm.com>
Co-authored-by: LXT <307322522@qq.com>
Co-authored-by: Chan <59447235+chancehee@users.noreply.github.com>
Co-authored-by: Ricardo Zanini <1538000+ricardozanini@users.noreply.github.com>
Co-authored-by: Farzad Sedaghatbin <farzad@kixy.com>
Co-authored-by: Vasilije Jukic <88736998+VasilijeJukic01@users.noreply.github.com>
Co-authored-by: Faisal Dilawar <dilawar.faisal@gmail.com>
Co-authored-by: Gaurav Katheriya <gauravstu10@gmail.com>
Co-authored-by: Max Lepikhin <46848373+maxlepikhin@users.noreply.github.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: Pedro Vieira <pedrovcristao@hotmail.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Hanabi <78060373+KurobaKaitou@users.noreply.github.com>
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Co-authored-by: odysseaspenta <odysseas@sysnetint.com>
Co-authored-by: Xin Wang <xinwang@apache.org>
Co-authored-by: Daksh R Jain <dakshjain737@gmail.com>
Co-authored-by: 小雨 <1537372358@qq.com>
Co-authored-by: Kimgyuilli <87853959+Kimgyuilli@users.noreply.github.com>
Co-authored-by: jiajingda <dadamonkey1@gmail.com>
Co-authored-by: ZhangDT <485918776@qq.com>
Co-authored-by: Andrea Di Maio <85737936+andreadimaio@users.noreply.github.com>
Co-authored-by: Antoine Rey <antoine.rey@free.fr>
Co-authored-by: Sanel Z. <sanelz@gmail.com>
Co-authored-by: Harikrishna <harikrishna553@gmail.com>
Co-authored-by: Harikrishna <harikrishna.gurram@walmart.com>
Co-authored-by: Srinadh Bhattiprolu <ss.bhattiprolu@gmail.com>
Co-authored-by: eye-gu <734164350@qq.com>
Co-authored-by: leochame <leocham.cn@gmail.com>
Co-authored-by: Hervé Boutemy <hboutemy@apache.org>
Co-authored-by: jrsperry <43385427+jrsperry@users.noreply.github.com>
Co-authored-by: Joshua Sperry <jrsperry@halosight.com>
Co-authored-by: mcopes73 <mcopes73@gmail.com>
Co-authored-by: Dmytro Skarzhynets <d.skarzh@protonmail.com>
Co-authored-by: 정다해(Dahae Jung) <dahae@29cm.co.kr>
Co-authored-by: Diego Berríos <130251753+diegoberriosr@users.noreply.github.com>
Co-authored-by: suryateja-g13 <89782129+suryateja-g13@users.noreply.github.com>
Co-authored-by: Gorre Surya <sgorre92@gmail.com>
Co-authored-by: Sahal Hussain <146409442+sahalhes@users.noreply.github.com>
Co-authored-by: unsignedint <rc@braveface.nz>
Co-authored-by: giveup <giveup@users.noreply.github.com>
Co-authored-by: zxuhan7 <zxuhan7@gmail.com>
Co-authored-by: Stéphane Philippart <stephane.philippart@ovhcloud.com>
Co-authored-by: Eric Lin <31666172+elin-coursera2@users.noreply.github.com>
Co-authored-by: Eric Lin <elin@coursera.org>
## Issue
Closes #
## Change
* Introduce @EmbeddingVector as replacement to avoid naming collisions
* Add utility methods to created and apply embeddings on entities
* Test more databases and add SAP HANA as well as CockroachDB support
## General checklist
- [x] There are no breaking changes (API, behaviour)
- [x] I have added unit and/or integration tests for my change
- [x] The tests cover both positive and negative cases
- [x] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green
- [x] I have manually run all the unit and integration tests in the
[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)
and
[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)
modules, and they are all green
- [x] I have added/updated the
[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)
- [x] I have added an example in the [examples
repo](https://github.com/langchain4j/langchain4j-examples) (only for
"big" features)
- [x] I have added/updated [Spring Boot
starter(s)](https://github.com/langchain4j/langchain4j-spring) (if
applicable)
## Checklist for adding new embedding store integration
- [x] I have added a `{NameOfIntegration}EmbeddingStoreIT` that extends
from either `EmbeddingStoreIT` or `EmbeddingStoreWithFilteringIT`
- [x] I have added a `{NameOfIntegration}EmbeddingStoreRemovalIT` that
extends from `EmbeddingStoreWithRemovalIT`
## Checklist for changing existing embedding store integration
- [x] I have manually verified that the
`{NameOfIntegration}EmbeddingStore` works correctly with the data
persisted using the latest released version of LangChain4j
<!--
Thank you so much for your contribution!
Please fill in all the sections below.
Please open the PR as a draft initially. Once it is reviewed and
approved, we will ask you to add documentation and examples.
Please note that PRs with breaking changes or without tests will be
rejected.
Please note that PRs will be reviewed based on the priority of the
issues they address.
We ask for your patience. We are doing our best to review your PR as
quickly as possible.
Please refrain from pinging and asking when it will be reviewed. Thank
you for understanding!
-->
## Issue
<!-- Please specify the ID of the issue this PR is addressing. For
example: "Closes #1234" or "Fixes #1234" -->
Closes #
## Change
This pull request introduces the new Blackboard agentic pattern working
as explained in the new section added to the `agents.md` documentation.
It also implements a minor non-breaking improvement to the
`HumanInTheLoop` pattern allowing to optionally declare its input keys,
so that they can be used by agentic patterns using the agent's inputs as
precondition for its activation like GOAP, P2P and this new Blackboard
one.
## General checklist
<!-- Please double-check the following points and mark them like this:
[X] -->
- [X] There are no breaking changes (API, behaviour)
- [X] I have added unit and/or integration tests for my change
- [X] The tests cover both positive and negative cases
- [X] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green
- [ ] I have manually run all the unit and integration tests in the
[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)
and
[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)
modules, and they are all green
<!-- Before adding documentation and example(s) (below), please wait
until the PR is reviewed and approved. -->
- [X] I have added/updated the
[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)
- [ ] I have added an example in the [examples
repo](https://github.com/langchain4j/langchain4j-examples) (only for
"big" features)
- [ ] I have added/updated [Spring Boot
starter(s)](https://github.com/langchain4j/langchain4j-spring) (if
applicable)
## Checklist for adding new maven module
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have added my new module in the root `pom.xml` and
`langchain4j-bom/pom.xml`
## Checklist for adding new embedding store integration
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreIT` that extends
from either `EmbeddingStoreIT` or `EmbeddingStoreWithFilteringIT`
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreRemovalIT` that
extends from `EmbeddingStoreWithRemovalIT`
## Checklist for changing existing embedding store integration
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have manually verified that the
`{NameOfIntegration}EmbeddingStore` works correctly with the data
persisted using the latest released version of LangChain4j
## Summary
- Adds a small documentation example showing how to point this project’s
existing OpenAI-compatible configuration at Tuning Engines.
- Keeps this project’s APIs and runtime behavior unchanged: no new
dependency, adapter, or code path.
- Shows a path for teams to keep this framework in charge of app, agent,
tool, workflow, or retrieval logic while routing model calls through a
governed OpenAI-compatible endpoint.
## Why this belongs here
Tuning Engines is an AI control plane for teams that want centralized
model access, routing, tenant-scoped keys, policy/guardrail checks,
audit logs, traces, approvals, and usage/cost visibility around existing
AI applications.
This project already supports OpenAI-compatible endpoints. The docs
change makes that existing capability discoverable for users who want
governance and observability without rewriting their application around
a separate SDK or changing this project’s runtime behavior.
## Testing
- `git diff --check`
Co-authored-by: VC <bazooka720@gmail.com>
## Issue
Closes#5261
## Change
Adds `docs/docs/integrations/embedding-stores/cockroachdb.md` and a row
in
the comparison table at
`docs/docs/integrations/embedding-stores/index.md`
for the new `langchain4j-community-cockroachdb` module.
The page covers:
- Maven dependency and version requirements
- API surface (`CockroachDbEngine`, `CockroachDbSchema`,
`CockroachDbEmbeddingStore`, `CockroachDbChatMemoryStore`)
- Quick-start example
- Connection-string formats (including the Python-style `cockroachdb://`
URL rewrite)
- Parameter summary tables for engine, store, and C-SPANN index
- Multi-tenancy via a namespace column
- Chat memory with optional row-level TTL
- 40001 retry behaviour
- Known limitations, including the pointer to the third-party
`langgraph4j-cockroachdb-saver` for the LangGraph checkpointer
counterpart
## Companion PR
- Integration module: langchain4j/langchain4j-community#673
## General checklist
- [x] There are no breaking changes (API, behaviour)
- [x] I have added unit and/or integration tests for my change (docs
only)
- [x] The tests cover both positive and negative cases (N/A, docs only)
- [x] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green (docs only)
- [x] I have manually run all the unit and integration tests in the
[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)
and
[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)
modules, and they are all green (no code change in those modules)
- [x] I have added/updated the
[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)
(this PR)
- [x] I have added an example in the [examples
repo](https://github.com/langchain4j/langchain4j-examples)
(langchain4j/langchain4j-examples#195)
- [x] I have added/updated [Spring Boot
starter(s)](https://github.com/langchain4j/langchain4j-spring) (included
in the integration PR linked above)
---------
Co-authored-by: Amine El Kouhen <amine.elkouhen@cockroachlabs.com>
## Issue
Closes#4383
## Change
Added a new integration module `langchain4j-google-genai`.
This module integrates the Google Gen AI SDK
(`com.google.genai:google-genai`), enabling support for Google's Gemini
models through the official Java client.
## General checklist
- [x] There are no breaking changes (API, behaviour)
- [x] I have added unit and/or integration tests for my change
- [x] The tests cover both positive and negative cases
- [x] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green
- [x] I have manually run all the unit and integration tests in the core
and main modules, and they are all green
- [x] I have added/updated the documentation
- [ ] I have added an example in the examples repo (only for "big"
features)
- [ ] I have added/updated Spring Boot starter(s) (if applicable)
## Checklist for adding new maven module
- [x] I have added my new module in the root `pom.xml` and
`langchain4j-bom/pom.xml`
---------
Co-authored-by: Guillaume Laforge <glaforge@gmail.com>
Co-authored-by: Dmytro Liubarskyi <ljubarskij@gmail.com>
<!--
Thank you so much for your contribution!
Please fill in all the sections below.
Please open the PR as a draft initially. Once it is reviewed and
approved, we will ask you to add documentation and examples.
Please note that PRs with breaking changes or without tests will be
rejected.
Please note that PRs will be reviewed based on the priority of the
issues they address.
We ask for your patience. We are doing our best to review your PR as
quickly as possible.
Please refrain from pinging and asking when it will be reviewed. Thank
you for understanding!
-->
## Issue
<!-- Please specify the ID of the issue this PR is addressing. For
example: "Closes #1234" or "Fixes #1234" -->
Closes#5135
## Change
Added documentation for the valkey embedded vector store.
## General checklist
<!-- Please double-check the following points and mark them like this:
[X] -->
- [X] There are no breaking changes (API, behaviour)
- [ ] I have added unit and/or integration tests for my change
- [ ] The tests cover both positive and negative cases
- [ ] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green
- [ ] I have manually run all the unit and integration tests in the
[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)
and
[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)
modules, and they are all green
<!-- Before adding documentation and example(s) (below), please wait
until the PR is reviewed and approved. -->
- [ ] I have added/updated the
[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)
- [ ] I have added an example in the [examples
repo](https://github.com/langchain4j/langchain4j-examples) (only for
"big" features)
- [ ] I have added/updated [Spring Boot
starter(s)](https://github.com/langchain4j/langchain4j-spring) (if
applicable)
## Checklist for adding new maven module
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have added my new module in the root `pom.xml` and
`langchain4j-bom/pom.xml`
## Checklist for adding new embedding store integration
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreIT` that extends
from either `EmbeddingStoreIT` or `EmbeddingStoreWithFilteringIT`
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreRemovalIT` that
extends from `EmbeddingStoreWithRemovalIT`
## Checklist for changing existing embedding store integration
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have manually verified that the
`{NameOfIntegration}EmbeddingStore` works correctly with the data
persisted using the latest released version of LangChain4j
## Issue
Relates to #4838
## Change
This PR adds request-side support for OpenAI built-in tools in the
unofficial Responses models:
- `OpenAiResponsesChatModel`
- `OpenAiResponsesStreamingChatModel`
The unofficial API shape stays minimal and provider-specific by
introducing `serverTools` as `List<Map<String, Object>>` on
`OpenAiResponsesChatRequestParameters` and the two model builders.
`toolSpecifications` continues to represent LangChain4j function tools,
while `serverTools` carries raw OpenAI-shaped built-in tools. Both are
merged into the outgoing OpenAI `tools` array, with function tools
serialized first and built-in tools appended after them.
This keeps the unofficial implementation close to the OpenAI wire format
without introducing a new `OpenAiServerTool` abstraction in this patch.
Added coverage includes:
- storing and overriding `serverTools` in request parameters
- propagating `serverTools` through unofficial model builders
- payload construction for built-in tools only
- payload construction for function tools only
- payload construction for mixed function tools and built-in tools
- `toolChoice` serialization when mixed tools are present
Note: this change is intentionally limited to request support. It does
not add built-in tool result extraction yet.
## General checklist
- [X] There are no breaking changes (API, behaviour)
- [X] I have added unit and/or integration tests for my change
- [X] The tests cover both positive and negative cases
- [X] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green
- [X] I have manually run all the unit and integration tests in the
[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)
and
[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)
modules, and they are all green
- [X] I have added/updated the
[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)
- [ ] I have added an example in the [examples
repo](https://github.com/langchain4j/langchain4j-examples) (only for
"big" features)
- [ ] I have added/updated [Spring Boot
starter(s)](https://github.com/langchain4j/langchain4j-spring) (if
applicable)
## Checklist for adding new maven module
- [ ] I have added my new module in the root `pom.xml` and
`langchain4j-bom/pom.xml`
## Checklist for adding new embedding store integration
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreIT` that extends
from either `EmbeddingStoreIT` or `EmbeddingStoreWithFilteringIT`
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreRemovalIT` that
extends from `EmbeddingStoreWithRemovalIT`
## Checklist for changing existing embedding store integration
- [ ] I have manually verified that the
`{NameOfIntegration}EmbeddingStore` works correctly with the data
persisted using the latest released version of LangChain4j
## Issue
Closes#3826
## Change
Added a dedicated embedding-based classification section to the
classification tutorial.
The new section explains when to use `TextClassifier` and
`EmbeddingModelTextClassifier`, shows a minimal sentiment classification
example backed by `AllMiniLmL6V2QuantizedEmbeddingModel`, and mentions
`classifyWithScores(...)` plus the classifier tuning options.
## How tested
- Ran `git diff --check`
- Ran `npm ci` in `docs/`
- Ran `npm run build` in `docs/`
`npm run build` completed successfully and generated the Docusaurus
static site. It reported pre-existing broken link/anchor warnings
outside this tutorial.
## General checklist
- [X] There are no breaking changes (API, behaviour)
- [ ] I have added unit and/or integration tests for my change (N/A:
documentation-only change)
- [ ] The tests cover both positive and negative cases (N/A:
documentation-only change)
- [ ] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green (N/A:
documentation-only change)
- [ ] I have manually run all the unit and integration tests in the
[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)
and
[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)
modules, and they are all green (N/A: documentation-only change)
- [X] I have added/updated the
[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)
- [ ] I have added an example in the [examples
repo](https://github.com/langchain4j/langchain4j-examples) (N/A:
documentation-only change)
- [ ] I have added/updated [Spring Boot
starter(s)](https://github.com/langchain4j/langchain4j-spring) (N/A)
## Checklist for adding new maven module
- [ ] I have added my new module in the root `pom.xml` and
`langchain4j-bom/pom.xml` (N/A)
## Checklist for adding new embedding store integration
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreIT` that extends
from either `EmbeddingStoreIT` or `EmbeddingStoreWithFilteringIT` (N/A)
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreRemovalIT` that
extends from `EmbeddingStoreWithRemovalIT` (N/A)
## Checklist for changing existing embedding store integration
- [ ] I have manually verified that the
`{NameOfIntegration}EmbeddingStore` works correctly with the data
persisted using the latest released version of LangChain4j (N/A)
Co-authored-by: malu <machengyu519@gmail.com>
<!--
Thank you so much for your contribution!
Please fill in all the sections below.
Please open the PR as a draft initially. Once it is reviewed and
approved, we will ask you to add documentation and examples.
Please note that PRs with breaking changes or without tests will be
rejected.
Please note that PRs will be reviewed based on the priority of the
issues they address.
We ask for your patience. We are doing our best to review your PR as
quickly as possible.
Please refrain from pinging and asking when it will be reviewed. Thank
you for understanding!
-->
## Issue
<!-- Please specify the ID of the issue this PR is addressing. For
example: "Closes #1234" or "Fixes #1234" -->
Closes #
## Change
<!-- Please describe the changes you made. -->
This pull requests introduces two new features:
- It allows an agent to switch among different models based on the
result of a selector function of the `AgenticScope`
- A new `Voting` agentic pattern that fans out all sub-agents in
parallel and aggregates their results via a pluggable `VotingStrategy`.
Regarding the new voting pattern, I understand that something quite
similar could have been achieved already with the parallel workflow,
plus an output function, but I received multiple feedback on the fact
that it will be nice to have more explicit and use-case driven agentic
patterns implementation and use them as building blocks for more complex
agentic system, so I collected a few proposals and will add a few other
patterns in the near future.
## General checklist
<!-- Please double-check the following points and mark them like this:
[X] -->
- [X] There are no breaking changes (API, behaviour)
- [X] I have added unit and/or integration tests for my change
- [X] The tests cover both positive and negative cases
- [X] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green
- [ ] I have manually run all the unit and integration tests in the
[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)
and
[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)
modules, and they are all green
<!-- Before adding documentation and example(s) (below), please wait
until the PR is reviewed and approved. -->
- [ ] I have added/updated the
[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)
- [ ] I have added an example in the [examples
repo](https://github.com/langchain4j/langchain4j-examples) (only for
"big" features)
- [ ] I have added/updated [Spring Boot
starter(s)](https://github.com/langchain4j/langchain4j-spring) (if
applicable)
## Checklist for adding new maven module
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have added my new module in the root `pom.xml` and
`langchain4j-bom/pom.xml`
## Checklist for adding new embedding store integration
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreIT` that extends
from either `EmbeddingStoreIT` or `EmbeddingStoreWithFilteringIT`
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreRemovalIT` that
extends from `EmbeddingStoreWithRemovalIT`
## Checklist for changing existing embedding store integration
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have manually verified that the
`{NameOfIntegration}EmbeddingStore` works correctly with the data
persisted using the latest released version of LangChain4j
## Issue
Closes#5085
## Change
- New `@P(defaultValue = "...")` attribute lets tool authors declare a
runtime fallback that LangChain4j substitutes when the LLM omits an
argument.
- Works for primitives, boxed types, `String`, `enum`, `UUID`,
`BigDecimal`/`BigInteger`, `List<T>`/`Set<T>`/arrays, `Map<K,V>`, and
POJOs (including nested and polymorphic
types).
- Eager validation at AI Service registration time: misconfigured
defaults fail with `IllegalConfigurationException` at
`AiServices.builder(...).tools(...).build()` rather than
on the first LLM call.
## Usage
```java
enum SortBy { RELEVANCE, DATE, RATING }
@Tool
List<Article> searchArticles(
String query,
@P(defaultValue = "10") int limit,
@P(defaultValue = "[\"en\"]") List<String> languages,
@P(defaultValue = "RELEVANCE") SortBy sortBy
) {
// limit -> 10, languages -> ["en"], sortBy -> SortBy.RELEVANCE when
omitted by the LLM
}
```
## Semantics
- **Setting `defaultValue` makes the parameter optional in the JSON
schema** — the parameter is *not* added to the schema's `required`
array, regardless of `@P(required)`. The
LLM is told it may omit the argument; if it does, LangChain4j fills in
the default before invoking the method.
- **Defaults are re-parsed on every invocation**, so a tool that mutates
a defaulted `List`/`Map`/POJO does not contaminate later calls.
- **Defaults only apply to absence, not to wrong-typed values**: if the
LLM sends `"banana"` for an `int`, the coercion error propagates
normally — the default is not used as a
fallback.
- **Empty-string default `@P(defaultValue = "") String filter` is
distinct from "no default set"** — implemented via a `NO_DEFAULT`
sentinel constant on `P`.
## Supported types
| Type | Format | Example |
|------------------------------|--------------------------|------------------------------------------|
| `String` | used verbatim | `defaultValue = "USD"` |
| Primitive / boxed primitive | type-specific conversion | `"10"`,
`"3.14"`, `"true"` |
| `enum` | enum constant name | `defaultValue = "EUR"` |
| `UUID` | `UUID.fromString` | `"550e8400-e29b-41d4-a716-446655440000"`
|
| `BigDecimal`, `BigInteger` | numeric literal | `"1.5"`, `"100"` |
| `List<T>` / `Set<T>` / array | JSON array | `"[\"a\",\"b\"]"`,
`"[1,2,3]"` |
| `Map<K,V>` | JSON object | `"{\"a\":1,\"b\":2}"` |
| POJOs (including nested) | JSON object |
`"{\"name\":\"Klaus\",\"age\":42}"` |
## Registration-time validation
The default value string is parsed at AI Service registration time. The
following all throw `IllegalConfigurationException` from
`AiServices.builder(...).tools(...).build()`,
naming the offending `ClassName.methodName.parameterName`:
- Unparseable defaults — typos (`@P(defaultValue = "ten") int x`),
numeric overflow (`"999999999999999"` on an `int`), invalid enum
constants, invalid `UUID`, invalid booleans.
- `defaultValue` combined with `Optional<T>` — `Optional` already
encodes absence; pick one mechanism.
- `defaultValue` on framework-injected parameters (`@ToolMemoryId`,
`InvocationContext`, etc.) — they never come from the LLM.
Existing rule **relaxed**: `@P(required = false)` on a primitive without
`defaultValue` still throws (a primitive can't represent absence), but
is now legal *with* a
`defaultValue`:
```java
@Tool
void process(@P(required = false, defaultValue = "0") int startLine) {
... }
```
The validation error message has been updated to point users to this
option.
## General checklist
- [x] There are no breaking changes (API, behaviour)
- [x] I have added unit and/or integration tests for my change
- [x] The tests cover both positive and negative cases
- [x] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green
- [x] I have manually run all the unit and integration tests in the
[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)
and
[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)
modules, and they are all green
<!-- Before adding documentation and example(s) (below), please wait
until the PR is reviewed and approved. -->
- [x] I have added/updated the
[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)
- [ ] I have added an example in the [examples
repo](https://github.com/langchain4j/langchain4j-examples) (only for
"big" features)
- [ ] I have added/updated [Spring Boot
starter(s)](https://github.com/langchain4j/langchain4j-spring) (if
applicable)
## Issue
Closes#5153
## Change
Adds experimental Ollama image generation support.
Summary:
- Add `OllamaImageModel`, implementing `ImageModel` through Ollama's
native `/api/generate` endpoint.
- Add the experimental image-generation request fields `width`,
`height`, and `steps` to `CompletionRequest`.
- Add the generated image response field `image` to
`CompletionResponse`.
- Send `seed` through Ollama `options.seed`, matching Ollama's current
request handling.
- Add unit coverage for request serialization, response mapping,
validation, experimental annotation, and missing-image responses.
- Add documentation for the experimental Ollama image model.
Scope:
- This PR is intentionally limited to Ollama's experimental
text-to-image path.
- It does not add image editing, multiple-image generation,
OpenAI-compatible image endpoints, web search/fetch, model
recommendations, negative prompts, or streaming progress fields.
- Spring Boot starter support is not included here because starters live
in the separate `langchain4j-spring` repository, and experimental image
model integrations do not appear to be added there immediately in all
cases. This can be handled as a follow-up if maintainers prefer.
## Test Plan
- `./mvnw -B -pl langchain4j-ollama -DskipOllamaITs
-DembeddingsSkipCache -Dtinylog.writer.level=info verify`
- `./mvnw -B -pl langchain4j-core -DskipITs -Drevapi.skip=true test`
- `./mvnw -B -pl langchain4j -DskipITs -Drevapi.skip=true test`
- `npm run build` from `docs/`
- `git diff --check`
- `./mvnw -pl langchain4j-ollama -Pspotless spotless:check` in a regular
checkout
## General checklist
- [X] There are no breaking changes (API, behaviour)
- [X] I have added unit and/or integration tests for my change
- [X] The tests cover both positive and negative cases
- [ ] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green
- [ ] I have manually run all the unit and integration tests in the
[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)
and
[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)
modules, and they are all green
- [X] I have added/updated the
[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)
- [ ] I have added an example in the [examples
repo](https://github.com/langchain4j/langchain4j-examples) (only for
"big" features)
- [ ] I have added/updated [Spring Boot
starter(s)](https://github.com/langchain4j/langchain4j-spring) (if
applicable)
## Issue
Closes#5142
## Change
- Adds `customParameters(Map<String, Object>)` to `OpenAiEmbeddingModel`
so OpenAI-compatible embedding providers can receive provider-specific
JSON body parameters.
- Expands custom embedding parameters into the request body via
`@JsonAnyGetter`, following the existing OpenAI chat and Anthropic
`customParameters` style.
- Keeps the default request body unchanged when custom parameters are
not configured and snapshots the configured map when the model is built.
- Adds focused tests for opt-in behavior, default behavior, and
build-time map snapshotting.
- Adds a short documentation example for provider-specific embedding
parameters.
## General checklist
- [X] There are no breaking changes (API, behaviour)
- [X] I have added unit and/or integration tests for my change
- [X] The tests cover both positive and negative cases
- [ ] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green
- [ ] I have manually run all the unit and integration tests in the
[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)
and
[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)
modules, and they are all green
- [X] I have added/updated the
[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)
- [ ] I have added an example in the [examples
repo](https://github.com/langchain4j/langchain4j-examples) (only for
"big" features)
- [ ] I have added/updated [Spring Boot
starter(s)](https://github.com/langchain4j/langchain4j-spring) (if
applicable)
## Checklist for adding new maven module
- [ ] I have added my new module in the root `pom.xml` and
`langchain4j-bom/pom.xml`
## Checklist for adding new embedding store integration
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreIT` that extends
from either `EmbeddingStoreIT` or `EmbeddingStoreWithFilteringIT`
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreRemovalIT` that
extends from `EmbeddingStoreWithRemovalIT`
## Checklist for changing existing embedding store integration
- [ ] I have manually verified that the
`{NameOfIntegration}EmbeddingStore` works correctly with the data
persisted using the latest released version of LangChain4j
## Tests run
- `./mvnw -pl langchain4j-open-ai -am -Dtest=OpenAiEmbeddingModelTest
-Dsurefire.failIfNoSpecifiedTests=false test`
- `git diff --check origin/main...HEAD`
## Issue
Fixes#5085
## Change
- When the LLM omitted a required primitive parameter (e.g. `int`,
`boolean`), Java reflection threw a generic NPE during unboxing (`Cannot
invoke
"java.lang.Number.intValue()" because the return value of
"sun.invoke.util.ValueConversions.primitiveConversion(...)" is null`).
The error leaked JVM-internal `MethodHandle`
plumbing and gave the LLM nothing actionable to retry with.
- Now `DefaultToolExecutor.prepareArguments` detects the missing
primitive up front and throws `IllegalArgumentException("Required
parameter \"argN\" of tool \"toolName\" is
missing")`. The exception flows through the existing
`wrapToolArgumentsExceptions` path, so AI Service users see a
`ToolArgumentsException` (with the original
`IllegalArgumentException` as cause) and can route it through
`toolArgumentsErrorHandler` as usual.
- Adds eager validation at AI Service build time: `@P(required = false)`
on a primitive parameter is contradictory (primitives cannot represent
absence) and now fails with
`IllegalConfigurationException` from `ToolService.findTools`, alongside
the other tool-misconfig checks. This catches the developer error before
any LLM call.
## Breaking changes
1. **Default behavior: AI Service now throws when the LLM omits a
required primitive parameter, instead of letting the LLM receive an
obscure error message.**
Before this PR, when the LLM called a tool without a required primitive,
Java reflection NPE'd during unboxing. That NPE bubbled up through the
*tool execution* error path (`InvocationTargetException` →
`ToolExecutionException`) and the default `toolExecutionErrorHandler`
returned the (ugly, JVM-internal) message to the LLM as a tool result
with `isError=true`. The agent loop continued and the LLM had a chance
to retry with corrected arguments.
After this PR, the missing primitive is detected before the method is
invoked and surfaced as an *arguments* error (`IllegalArgumentException`
→ wrapped as `ToolArgumentsException`). It is now routed through
`toolArgumentsErrorHandler`, whose default is to **throw** — so
`assistant.chat(...)` propagates the exception out and the AI Service
flow stops.
**Net effect:** what used to be a (clumsy) recoverable agent step is now
a fatal error by default. Users who relied on the LLM-driven recovery
for missing primitives must configure a `toolArgumentsErrorHandler` that
returns the error to the LLM:
```java
AiServices.builder(...)
...
.toolArgumentsErrorHandler((error, ctx) -> ToolErrorHandlerResult.text(error.getMessage()))
.build();
```
The exception text itself is also cleaner:
`IllegalArgumentException("Required parameter \"argN\" of tool \"...\"
is missing") ` instead of the previous `NullPointerException("Cannot
invoke \"java.lang.Number.intValue()\" ...")`. Anyone catching the NPE
by type or matching its text will need to update.
2. `@P(required = false)` on a primitive parameter now fails at AI
Service build time.
Previously this misconfiguration silently passed validation and produced
the runtime NPE described above whenever the LLM happened to omit the
parameter.
Now `AiServices.builder(...).tools(yourToolObject).build()` throws
`IllegalConfigurationException` immediately, naming the offending
ClassName.methodName.
Migration: if you really want parameter to be optional, change the
parameter to a boxed type (`Integer`, `Long`, `Boolean`, …) or
`Optional<T>`.
## General checklist
- [ ] There are no breaking changes (API, behaviour)
- [X] I have added unit and/or integration tests for my change
- [X] The tests cover both positive and negative cases
- [X] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green
- [X] I have manually run all the unit and integration tests in the
[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)
and
[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)
modules, and they are all green
- [ ] I have added/updated the
[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)
- [ ] I have added an example in the [examples
repo](https://github.com/langchain4j/langchain4j-examples) (only for
"big" features)
- [ ] I have added/updated [Spring Boot
starter(s)](https://github.com/langchain4j/langchain4j-spring) (if
applicable)
<!--
Thank you so much for your contribution!
Please fill in all the sections below.
Please open the PR as a draft initially. Once it is reviewed and
approved, we will ask you to add documentation and examples.
Please note that PRs with breaking changes or without tests will be
rejected.
Please note that PRs will be reviewed based on the priority of the
issues they address.
We ask for your patience. We are doing our best to review your PR as
quickly as possible.
Please refrain from pinging and asking when it will be reviewed. Thank
you for understanding!
-->
## Issue
<!-- Please specify the ID of the issue this PR is addressing. For
example: "Closes #1234" or "Fixes #1234" -->
Closes #
## Change
<!-- Please describe the changes you made. -->
## General checklist
<!-- Please double-check the following points and mark them like this:
[X] -->
- [X] There are no breaking changes (API, behaviour)
- [ ] I have added unit and/or integration tests for my change
- [ ] The tests cover both positive and negative cases
- [X] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green
- [ ] I have manually run all the unit and integration tests in the
[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)
and
[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)
modules, and they are all green
<!-- Before adding documentation and example(s) (below), please wait
until the PR is reviewed and approved. -->
- [ ] I have added/updated the
[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)
- [ ] I have added an example in the [examples
repo](https://github.com/langchain4j/langchain4j-examples) (only for
"big" features)
- [ ] I have added/updated [Spring Boot
starter(s)](https://github.com/langchain4j/langchain4j-spring) (if
applicable)
## Checklist for adding new maven module
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have added my new module in the root `pom.xml` and
`langchain4j-bom/pom.xml`
## Checklist for adding new embedding store integration
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreIT` that extends
from either `EmbeddingStoreIT` or `EmbeddingStoreWithFilteringIT`
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreRemovalIT` that
extends from `EmbeddingStoreWithRemovalIT`
## Checklist for changing existing embedding store integration
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have manually verified that the
`{NameOfIntegration}EmbeddingStore` works correctly with the data
persisted using the latest released version of LangChain4j
## Issue
Closes https://github.com/langchain4j/langchain4j/issues/2557
## Change
- Polymorphic types (sealed interfaces/classes, or types annotated with
Jackson
`@JsonSubTypes`/`@JsonTypeInfo`) can now be used as AI Service return
types and as
tool parameters. The schema sent to the LLM contains an `anyOf` over
concrete
subtypes with a discriminator property, and the LLM's response (or tool
call) is
dispatched to the correct subtype automatically.
- Works for the polymorphic type itself, for `List<T>`/`Set<T>` of
polymorphic, and
for polymorphic types nested inside other POJOs. Fixes the
previously-empty schema
generated for interface/abstract return types.
- Sealed types work with **zero annotations**; Jackson-annotated types
are also
supported and respect the user-configured `property`, `defaultImpl`,
`visible`,
`@JsonSubTypes.Type(name=...)`, and `@JsonTypeName`.
- Unsupported Jackson configurations (`Id.CLASS`, `Id.MINIMAL_CLASS`,
`Id.CUSTOM`,
`Id.DEDUCTION`, `As.WRAPPER_OBJECT`, `As.WRAPPER_ARRAY`,
`As.EXTERNAL_PROPERTY`,
`As.EXISTING_PROPERTY`) fail fast with a clear
`UnsupportedFeatureException` at
schema-generation time, instead of silently producing a payload Jackson
can't parse.
- Discriminator field collisions on subtypes are detected and reported
with three
remediation options (rename, change `property=...`, or set
`visible=true`).
## General checklist
- [X] There are no breaking changes (API, behaviour)
- [X] I have added unit and/or integration tests for my change
- [X] The tests cover both positive and negative cases
- [X] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green
- [X] I have manually run all the unit and integration tests in the
[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)
and
[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)
modules, and they are all green
- [X] I have added/updated the
[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)
- [ ] I have added an example in the [examples
repo](https://github.com/langchain4j/langchain4j-examples) (only for
"big" features)
- [ ] I have added/updated [Spring Boot
starter(s)](https://github.com/langchain4j/langchain4j-spring) (if
applicable)
<!--
Thank you so much for your contribution!
Please fill in all the sections below.
Please open the PR as a draft initially. Once it is reviewed and
approved, we will ask you to add documentation and examples.
Please note that PRs with breaking changes or without tests will be
rejected.
Please note that PRs will be reviewed based on the priority of the
issues they address.
We ask for your patience. We are doing our best to review your PR as
quickly as possible.
Please refrain from pinging and asking when it will be reviewed. Thank
you for understanding!
-->
## Issue
<!-- Please specify the ID of the issue this PR is addressing. For
example: "Closes #1234" or "Fixes #1234" -->
Closes #
## Change
<!-- Please describe the changes you made. -->
Update docs about reasoning and partial tool call in
[langchain4j-community-zhipu-ai](https://github.com/langchain4j/langchain4j-community/pull/639)
<!--
Thank you so much for your contribution!
Please fill in all the sections below.
Please open the PR as a draft initially. Once it is reviewed and
approved, we will ask you to add documentation and examples.
Please note that PRs with breaking changes or without tests will be
rejected.
Please note that PRs will be reviewed based on the priority of the
issues they address.
We ask for your patience. We are doing our best to review your PR as
quickly as possible.
Please refrain from pinging and asking when it will be reviewed. Thank
you for understanding!
-->
## Issue
<!-- Please specify the ID of the issue this PR is addressing. For
example: "Closes #1234" or "Fixes #1234" -->
Fix the issue in PR
https://github.com/langchain4j/langchain4j/pull/1355#issuecomment-4257770326
## Change
<!-- Please describe the changes you made. -->
As discussed with @dliubarskyi in the PR, as the OVH AI models are fully
compatible withe the OpenAI client I've updated the doc and tests to use
it.
## General checklist
<!-- Please double-check the following points and mark them like this:
[X] -->
- [X] There are no breaking changes (API, behaviour)
- [X] I have added unit and/or integration tests for my change
- [X] The tests cover both positive and negative cases
- [X] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green
- [X] I have manually run all the unit and integration tests in the
[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)
and
[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)
modules, and they are all green
<!-- Before adding documentation and example(s) (below), please wait
until the PR is reviewed and approved. -->
- [X] I have added/updated the
[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)
- [X] I have added an example in the [examples
repo](https://github.com/langchain4j/langchain4j-examples) (only for
"big" features)
- [X] I have added/updated [Spring Boot
starter(s)](https://github.com/langchain4j/langchain4j-spring) (if
applicable)
## Checklist for adding new maven module
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have added my new module in the root `pom.xml` and
`langchain4j-bom/pom.xml`
## Checklist for adding new embedding store integration
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreIT` that extends
from either `EmbeddingStoreIT` or `EmbeddingStoreWithFilteringIT`
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreRemovalIT` that
extends from `EmbeddingStoreWithRemovalIT`
## Checklist for changing existing embedding store integration
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have manually verified that the
`{NameOfIntegration}EmbeddingStore` works correctly with the data
persisted using the latest released version of LangChain4j
<!--
Thank you so much for your contribution!
Please fill in all the sections below.
Please open the PR as a draft initially. Once it is reviewed and
approved, we will ask you to add documentation and examples.
Please note that PRs with breaking changes or without tests will be
rejected.
Please note that PRs will be reviewed based on the priority of the
issues they address.
We ask for your patience. We are doing our best to review your PR as
quickly as possible.
Please refrain from pinging and asking when it will be reviewed. Thank
you for understanding!
-->
## Issue
<!-- Please specify the ID of the issue this PR is addressing. For
example: "Closes #1234" or "Fixes #1234" -->
Closes#5013
## Change
<!-- Please describe the changes you made. -->
Added support for `PdfFileContent` for the Mistral AI integration, very
similar to https://github.com/langchain4j/langchain4j/pull/4978
- Modified `MistralAiMapper.toMistralAiMessageContents()` so it now
supports mapping `PdfFileContent` to Mistral's API format
(`DocumentURLChunk`).
- Added `MistralAiDocumentUrlContent` and
`MistralAiDocumentBase46Content` classes for modeling
`DocumentUrlChunk`. The API supports both using URLs and base64 strings
for representing the `document_url` field in `DocumentUrlChunk`.
- Added the two classes as well to keep consistency with how image
chunks are handled in the module (`MistralAiImageBase64Content`,
`MistralAiImageUrlContent`, and the audio chunk representations as
well).
- For testing, the URL pdf file is from [Wikimedia
Commons](https://commons.wikimedia.org/wiki/Main_Page) to avoid
copyright issues, and the local one is just one I made up (it only
contains `Bonjour!`).
## General checklist
<!-- Please double-check the following points and mark them like this:
[X] -->
- [X] There are no breaking changes (API, behaviour)
- [X] I have added unit and/or integration tests for my change
- [X] The tests cover both positive and negative cases
- [X] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green
- [ ] I have manually run all the unit and integration tests in the
[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)
and
[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)
modules, and they are all green
<!-- Before adding documentation and example(s) (below), please wait
until the PR is reviewed and approved. -->
- [X] I have added/updated the
[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)
- [ ] I have added an example in the [examples
repo](https://github.com/langchain4j/langchain4j-examples) (only for
"big" features)
- [ ] I have added/updated [Spring Boot
starter(s)](https://github.com/langchain4j/langchain4j-spring) (if
applicable)
---------
Co-authored-by: Dmytro Liubarskyi <ljubarskij@gmail.com>
## Issue
Closes https://github.com/langchain4j/langchain4j/issues/4974
## Change
- Adds a new `ReturnBehavior.IMMEDIATE_IF_LAST` that halts the AI
service execution
loop when a tool with this behavior is the **last** tool call in the LLM
response,
saving one full LLM round trip compared to letting the LLM issue the
halt tool
alone in the next turn.
- Refactors the tool-handling internals (`AiServiceTool`,
`ToolProviderResult`,
`ToolServiceContext`, `ToolService`, `Skills`) so adding future
`ReturnBehavior`
values is a one-liner instead of threading parallel sets through every
layer.
## General checklist
- [X] There are no breaking changes (API, behaviour)
- [X] I have added unit and/or integration tests for my change
- [X] The tests cover both positive and negative cases
- [X] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green
- [X] I have manually run all the unit and integration tests in the
[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)
and
[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)
modules, and they are all green
- [x] I have added/updated the
[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)
- [ ] I have added an example in the [examples
repo](https://github.com/langchain4j/langchain4j-examples) (only for
"big" features)
- [ ] I have added/updated [Spring Boot
starter(s)](https://github.com/langchain4j/langchain4j-spring) (if
applicable)
<!--
Thank you so much for your contribution!
Please fill in all the sections below.
Please open the PR as a draft initially. Once it is reviewed and
approved, we will ask you to add documentation and examples.
Please note that PRs with breaking changes or without tests will be
rejected.
Please note that PRs will be reviewed based on the priority of the
issues they address.
We ask for your patience. We are doing our best to review your PR as
quickly as possible.
Please refrain from pinging and asking when it will be reviewed. Thank
you for understanding!
-->
## Change
Adds a new `thinkingDisplay` builder option to `AnthropicChatModel` and
`AnthropicStreamingChatModel`, plumbed through to the `thinking.display`
field on `AnthropicThinking`. This lets callers request `"summarized"`
thinking content on Claude Opus 4.7 (where the server default is
`"omitted"`), while leaving behavior unchanged on earlier Opus/Sonnet
models that already default to `"summarized"`.
## General checklist
(I've updated the doc before PR given how small the change is)
<!-- Please double-check the following points and mark them like this:
[X] -->
- [X] There are no breaking changes (API, behaviour)
- [ ] I have added unit and/or integration tests for my change
- [ ] The tests cover both positive and negative cases
- [X] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green
- [ ] I have manually run all the unit and integration tests in the
[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)
and
[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)
modules, and they are all green
<!-- Before adding documentation and example(s) (below), please wait
until the PR is reviewed and approved. -->
- [X] I have added/updated the
[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)
- [ ] I have added an example in the [examples
repo](https://github.com/langchain4j/langchain4j-examples) (only for
"big" features)
- [ ] I have added/updated [Spring Boot
starter(s)](https://github.com/langchain4j/langchain4j-spring) (if
applicable)
---------
Co-authored-by: Dmytro Liubarskyi <ljubarskij@gmail.com>
<!--
Thank you so much for your contribution!
Please fill in all the sections below.
Please open the PR as a draft initially. Once it is reviewed and
approved, we will ask you to add documentation and examples.
Please note that PRs with breaking changes or without tests will be
rejected.
Please note that PRs will be reviewed based on the priority of the
issues they address.
We ask for your patience. We are doing our best to review your PR as
quickly as possible.
Please refrain from pinging and asking when it will be reviewed. Thank
you for understanding!
-->
## Issue
<!-- Please specify the ID of the issue this PR is addressing. For
example: "Closes #1234" or "Fixes #1234" -->
Closes#4977
## Change
<!-- Please describe the changes you made. -->
Added support for `AudioContent` for the Mistral AI integration.
- Modified `MistralAiMapper.toMistralAiMessageContents()`' so it
supports mapping `AudioContent` to Mistral's API format (`AudioChunk`).
- Added `MistralAiAudioBase64Content` and `MistralAiAudioUrlContent`
classes for modeling `AudioChunk`. The API supports both using URLs and
base64 strings for representing the content of an audio chunk
- Added the two classes as well to keep consistency with how image
chunks are handled in the module (`MistralAiImageBase64Content` and `
MistralAiImageUrlContent`).
- Added two more values for `MistralAiChatModelName` for easy access to
Voxtral latest models.
- Tests cover `AudioContent` instances generated from base64 data and
URL.
- Audio files are from [Wikipedia
Commons](https://commons.wikimedia.org/wiki/Main_Page) to avoid
copyright issues :).
## General checklist
<!-- Please double-check the following points and mark them like this:
[X] -->
- [X] There are no breaking changes (API, behaviour)
- [X] I have added unit and/or integration tests for my change
- [X] The tests cover both positive and negative cases
- [X] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green
- [ ] I have manually run all the unit and integration tests in the
[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)
and
[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)
modules, and they are all green
<!-- Before adding documentation and example(s) (below), please wait
until the PR is reviewed and approved. -->
- [X] I have added/updated the
[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)
- [ ] I have added an example in the [examples
repo](https://github.com/langchain4j/langchain4j-examples) (only for
"big" features)
- [ ] I have added/updated [Spring Boot
starter(s)](https://github.com/langchain4j/langchain4j-spring) (if
applicable)
## Checklist for adding new maven module
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have added my new module in the root `pom.xml` and
`langchain4j-bom/pom.xml`
## Checklist for adding new embedding store integration
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreIT` that extends
from either `EmbeddingStoreIT` or `EmbeddingStoreWithFilteringIT`
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreRemovalIT` that
extends from `EmbeddingStoreWithRemovalIT`
## Checklist for changing existing embedding store integration
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have manually verified that the
`{NameOfIntegration}EmbeddingStore` works correctly with the data
persisted using the latest released version of LangChain4j
## Change
- Adds `OpenAiOfficialResponsesChatModel` (blocking `ChatModel` for the
Responses API). The official module previously only shipped the
streaming variant.
- Adds `reasoningSummary` parameter to
`OpenAiOfficialResponsesChatRequestParameters` and both models'
builders. When set (e.g. `"auto"`), the reasoning summary is exposed via
`AiMessage.thinking()` and streamed via
`StreamingChatResponseHandler.onPartialThinking()`.
- Captures encrypted reasoning (when `include:
["reasoning.encrypted_content"]` is requested) into
`AiMessage.attributes()` under the key `"encrypted_reasoning"`, and
automatically round-trips it on follow-up requests so the model can
resume its reasoning context across tool calls.
- Extracts shared request-building and response-parsing helpers from
`OpenAiOfficialResponsesStreamingChatModel` so both models reuse them
(no duplicated logic).
## General checklist
- [X] There are no breaking changes (API, behaviour)
- [X] I have added unit and/or integration tests for my change
- [X] The tests cover both positive and negative cases
- [X] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green
- [X] I have manually run all the unit and integration tests in the
[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)
and
[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)
modules, and they are all green
- [X] I have added/updated the
[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)
- [ ] I have added an example in the [examples
repo](https://github.com/langchain4j/langchain4j-examples) (only for
"big" features)
- [ ] I have added/updated [Spring Boot
starter(s)](https://github.com/langchain4j/langchain4j-spring) (if
applicable)
<!--
Thank you so much for your contribution!
Please fill in all the sections below.
Please open the PR as a draft initially. Once it is reviewed and
approved, we will ask you to add documentation and examples.
Please note that PRs with breaking changes or without tests will be
rejected.
Please note that PRs will be reviewed based on the priority of the
issues they address.
We ask for your patience. We are doing our best to review your PR as
quickly as possible.
Please refrain from pinging and asking when it will be reviewed. Thank
you for understanding!
-->
## Issue
<!-- Please specify the ID of the issue this PR is addressing. For
example: "Closes #1234" or "Fixes #1234" -->
Closes#4218
## Change
<!-- Please describe the changes you made. -->
Added documentation for the [Cohere V2 API chat model
integration](https://github.com/langchain4j/langchain4j-community/pull/615)
in the community repo.
## General checklist
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] There are no breaking changes (API, behaviour)
- [ ] I have added unit and/or integration tests for my change
- [ ] The tests cover both positive and negative cases
- [ ] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green
- [ ] I have manually run all the unit and integration tests in the
[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)
and
[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)
modules, and they are all green
<!-- Before adding documentation and example(s) (below), please wait
until the PR is reviewed and approved. -->
- [X] I have added/updated the
[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)
- [ ] I have added an example in the [examples
repo](https://github.com/langchain4j/langchain4j-examples) (only for
"big" features)
- [ ] I have added/updated [Spring Boot
starter(s)](https://github.com/langchain4j/langchain4j-spring) (if
applicable)
## Checklist for adding new maven module
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have added my new module in the root `pom.xml` and
`langchain4j-bom/pom.xml`
## Change
- Add `reasoningSummary` parameter to `OpenAiResponsesChatModel` and
`OpenAiResponsesStreamingChatModel` to request reasoning summaries via
the Responses API (`reasoning.summary` field)
- Parse reasoning summary from response output items and expose via
`AiMessage.thinking()`
- For streaming, `onPartialThinking()` is called when reasoning summary
text is streamed
- Support round-tripping of encrypted reasoning content
(`reasoning.encrypted_content`) for stateless conversations: extracted
from responses into `AiMessage.attributes()` and automatically sent back
in follow-up requests
## General checklist
- [X] There are no breaking changes (API, behaviour)
- [X] I have added unit and/or integration tests for my change
- [X] The tests cover both positive and negative cases
- [X] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green
- [X] I have manually run all the unit and integration tests in the
[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)
and
[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)
modules, and they are all green
- [X] I have added/updated the
[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)
- [ ] I have added an example in the [examples
repo](https://github.com/langchain4j/langchain4j-examples) (only for
"big" features)
- [ ] I have added/updated [Spring Boot
starter(s)](https://github.com/langchain4j/langchain4j-spring) (if
applicable)
Bumps [dompurify](https://github.com/cure53/DOMPurify) from 3.3.3 to
3.4.0.
<details>
<summary>Release notes</summary>
<p><em>Sourced from <a
href="https://github.com/cure53/DOMPurify/releases">dompurify's
releases</a>.</em></p>
<blockquote>
<h2>DOMPurify 3.4.0</h2>
<p><strong>Most relevant changes:</strong></p>
<ul>
<li>Fixed a problem with <code>FORBID_TAGS</code> not winning over
<code>ADD_TAGS</code>, thanks <a
href="https://github.com/kodareef5"><code>@kodareef5</code></a></li>
<li>Fixed several minor problems and typos regarding MathML attributes,
thanks <a
href="https://github.com/DavidOliver"><code>@DavidOliver</code></a></li>
<li>Fixed <code>ADD_ATTR</code>/<code>ADD_TAGS</code> function leaking
into subsequent array-based calls, thanks <a
href="https://github.com/1Jesper1"><code>@1Jesper1</code></a></li>
<li>Fixed a missing <code>SAFE_FOR_TEMPLATES</code> scrub in
<code>RETURN_DOM</code> path, thanks <a
href="https://github.com/bencalif"><code>@bencalif</code></a></li>
<li>Fixed a prototype pollution via
<code>CUSTOM_ELEMENT_HANDLING</code>, thanks <a
href="https://github.com/trace37labs"><code>@trace37labs</code></a></li>
<li>Fixed an issue with <code>ADD_TAGS</code> function form bypassing
<code>FORBID_TAGS</code>, thanks <a
href="https://github.com/eddieran"><code>@eddieran</code></a></li>
<li>Fixed an issue with <code>ADD_ATTR</code> predicates skipping URI
validation, thanks <a
href="https://github.com/christos-eth"><code>@christos-eth</code></a></li>
<li>Fixed an issue with <code>USE_PROFILES</code> prototype pollution,
thanks <a
href="https://github.com/christos-eth"><code>@christos-eth</code></a></li>
<li>Fixed an issue leading to possible mXSS via Re-Contextualization,
thanks <a
href="https://github.com/researchatfluidattacks"><code>@researchatfluidattacks</code></a>
and others</li>
<li>Fixed an issue with closing tags leading to possible mXSS, thanks <a
href="https://github.com/frevadiscor"><code>@frevadiscor</code></a></li>
<li>Fixed a problem with the type dentition patcher after Node version
bump</li>
<li>Fixed freezing BS runs by reducing the tested browsers array</li>
<li>Bumped several dependencies where possible</li>
<li>Added needed files for OpenSSF scorecard checks</li>
</ul>
<p><strong>Published Advisories are here:</strong>
<a
href="https://github.com/cure53/DOMPurify/security/advisories?state=published">https://github.com/cure53/DOMPurify/security/advisories?state=published</a></p>
</blockquote>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="5b16e0b892"><code>5b16e0b</code></a>
Getting 3.x branch ready for 3.4.0 release (<a
href="https://redirect.github.com/cure53/DOMPurify/issues/1250">#1250</a>)</li>
<li>See full diff in <a
href="https://github.com/cure53/DOMPurify/compare/3.3.3...3.4.0">compare
view</a></li>
</ul>
</details>
<br />
[](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores)
Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.
[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)
---
<details>
<summary>Dependabot commands and options</summary>
<br />
You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot show <dependency name> ignore conditions` will show all
of the ignore conditions of the specified dependency
- `@dependabot ignore this major version` will close this PR and stop
Dependabot creating any more for this major version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this minor version` will close this PR and stop
Dependabot creating any more for this minor version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this dependency` will close this PR and stop
Dependabot creating any more for this dependency (unless you reopen the
PR or upgrade to it yourself)
You can disable automated security fix PRs for this repo from the
[Security Alerts
page](https://github.com/langchain4j/langchain4j/network/alerts).
</details>
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
## Change
- Added `OpenAiResponsesChatModel` as a non-streaming `ChatModel`
implementation backed by OpenAI `/v1/responses`.
- Extended `OpenAiResponsesClient` with synchronous `chat(...)` support
and response parsing for:
- assistant text output
- tool execution requests
- response metadata and token usage
- Added a new integration test `OpenAiResponsesChatModelIT` that
exercises a basic tool-calling flow:
- first request asks model to call `create_person`
- second request sends tool result
- final assertion verifies person details in assistant response
- Updated OpenAI docs to include non-streaming Responses API usage and
note GPT-5.4 requirement to use Responses API for tools + reasoning
effort.
## General checklist
- [x] There are no breaking changes (API, behaviour)
- [x] I have added unit and/or integration tests for my change
- [x] The tests cover both positive and negative cases
- [x] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green
- [x] I have manually run all the unit and integration tests in the
[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)
and
[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)
modules, and they are all green
- [x] I have added/updated the
[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)
- [ ] I have added an example in the [examples
repo](https://github.com/langchain4j/langchain4j-examples) (only for
"big" features)
- [ ] I have added/updated [Spring Boot
starter(s)](https://github.com/langchain4j/langchain4j-spring) (if
applicable)
## Checklist for adding new maven module
- [ ] I have added my new module in the root `pom.xml` and
`langchain4j-bom/pom.xml`
## Checklist for adding new embedding store integration
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreIT` that extends
from either `EmbeddingStoreIT` or `EmbeddingStoreWithFilteringIT`
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreRemovalIT` that
extends from `EmbeddingStoreWithRemovalIT`
## Checklist for changing existing embedding store integration
- [ ] I have manually verified that the
`{NameOfIntegration}EmbeddingStore` works correctly with the data
persisted using the latest released version of LangChain4j
## Validation performed
- `./mvnw -pl langchain4j-open-ai spotless:check`
- `./mvnw -pl langchain4j-open-ai -Dtest=OpenAiResponsesChatModelIT
-DfailIfNoTests=false test`
---------
Co-authored-by: Joshua Sperry <jrsperry@halosight.com>
Co-authored-by: Dmytro Liubarskyi <ljubarskij@gmail.com>
Bumps
[follow-redirects](https://github.com/follow-redirects/follow-redirects)
from 1.15.11 to 1.16.0.
<details>
<summary>Commits</summary>
<ul>
<li><a
href="0c23a22306"><code>0c23a22</code></a>
Release version 1.16.0 of the npm package.</li>
<li><a
href="844c4d302a"><code>844c4d3</code></a>
Add sensitiveHeaders option.</li>
<li><a
href="5e8b8d024e"><code>5e8b8d0</code></a>
ci: add Node.js 24.x to the CI matrix</li>
<li><a
href="7953e2255a"><code>7953e22</code></a>
ci: upgrade GitHub Actions to use setup-node@v6 and checkout@v6</li>
<li><a
href="86dc1f86e4"><code>86dc1f8</code></a>
Sanitizing input.</li>
<li>See full diff in <a
href="https://github.com/follow-redirects/follow-redirects/compare/v1.15.11...v1.16.0">compare
view</a></li>
</ul>
</details>
<br />
[](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores)
Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.
[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)
---
<details>
<summary>Dependabot commands and options</summary>
<br />
You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot show <dependency name> ignore conditions` will show all
of the ignore conditions of the specified dependency
- `@dependabot ignore this major version` will close this PR and stop
Dependabot creating any more for this major version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this minor version` will close this PR and stop
Dependabot creating any more for this minor version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this dependency` will close this PR and stop
Dependabot creating any more for this dependency (unless you reopen the
PR or upgrade to it yourself)
You can disable automated security fix PRs for this repo from the
[Security Alerts
page](https://github.com/langchain4j/langchain4j/network/alerts).
</details>
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Follow-up on #3816.
This PR tightens OpenAI Responses support in both official and
unofficial integrations:
- keep `strict` disabled by default and align Responses-mode JSON-schema
handling with actual supported behavior
- add explicit `previousResponseId` request parameters instead of shared
mutable model state
- restore unofficial client logging and remove extra local
`maxToolCalls` truncation
- improve streaming behavior and test coverage for
reasoning/tool-call/error/completion paths
- simplify Response-related AI-service test overrides via shared hooks
- add license metadata required for
`internal/langchain4j-internal-test-retry`
- fix brittle Vertex AI Anthropic integration-test initialization by
moving the quota-gating condition out of a class with provider-dependent
static initialization
## General checklist
- [x] There are no breaking changes (API, behaviour)
- [x] I have added unit and/or integration tests for my change
- [x] The tests cover both positive and negative cases
- [x] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green
- [ ] I have manually run all the unit and integration tests in the
[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)
and
[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)
modules, and they are all green
- [x] I have added/updated the
[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)
- [ ] I have added an example in the [examples
repo](https://github.com/langchain4j/langchain4j-examples) (only for
"big" features)
- [ ] I have added/updated [Spring Boot
starter(s)](https://github.com/langchain4j/langchain4j-spring) (if
applicable)
## Checklist for adding new maven module
- [ ] I have added my new module in the root `pom.xml` and
`langchain4j-bom/pom.xml`
## Checklist for adding new embedding store integration
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreIT` that extends
from either `EmbeddingStoreIT` or `EmbeddingStoreWithFilteringIT`
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreRemovalIT` that
extends from `EmbeddingStoreWithRemovalIT`
## Checklist for changing existing embedding store integration
- [ ] I have manually verified that the
`{NameOfIntegration}EmbeddingStore` works correctly with the data
persisted using the latest released version of LangChain4j
---------
Co-authored-by: Dmytro Liubarskyi <ljubarskij@gmail.com>
Adds a short ChatRequestOptions example to the Chat Model Observability
tutorial.
This documents how to pass per-invocation listener metadata via
listenerAttributes, and clarifies that these options stay within the
LangChain4j invocation chain and are not sent to the LLM provider.
## Issue
<!-- Please specify the ID of the issue this PR is addressing. For
example: "Closes #1234" or "Fixes #1234" -->
Closes#4268
## Change
Documentation of the changes applied to the `langchain4j-spring`
project: the https://github.com/langchain4j/langchain4j-spring/pull/175
## General checklist
<!-- Please double-check the following points and mark them like this:
[X] -->
- [X] There are no breaking changes (API, behaviour)
- [ ] I have added unit and/or integration tests for my change
- [ ] The tests cover both positive and negative cases
- [ ] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green
- [ ] I have manually run all the unit and integration tests in the
[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)
and
[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)
modules, and they are all green
<!-- Before adding documentation and example(s) (below), please wait
until the PR is reviewed and approved. -->
- [X] I have added/updated the
[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)
- [ ] I have added an example in the [examples
repo](https://github.com/langchain4j/langchain4j-examples) (only for
"big" features)
- [ ] I have added/updated [Spring Boot
starter(s)](https://github.com/langchain4j/langchain4j-spring) (if
applicable)
## Checklist for adding new maven module
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have added my new module in the root `pom.xml` and
`langchain4j-bom/pom.xml`
## Checklist for adding new embedding store integration
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreIT` that extends
from either `EmbeddingStoreIT` or `EmbeddingStoreWithFilteringIT`
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreRemovalIT` that
extends from `EmbeddingStoreWithRemovalIT`
## Checklist for changing existing embedding store integration
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have manually verified that the
`{NameOfIntegration}EmbeddingStore` works correctly with the data
persisted using the latest released version of LangChain4j
## Issue
Closes https://github.com/langchain4j/langchain4j/issues/4652
## Change
- Add support for `@Tool`-annotated methods to return multimodal content
(images) to the LLM, not just text. Tools can now return `Image`,
`ImageContent`, `Content`, `List<Content>`, `Content[]`, etc.
- Refactor `ToolExecutionResultMessage` to store `List<Content>`
internally instead of a plain `String`, with backward-compatible
`text()` accessor and new `contents()` / `hasSingleText()`
methods.
- Refactor `ToolExecutionResult` to support
`resultContents(List<Content>)` as an alternative to
`resultText(String)` and `resultTextSupplier(Supplier)`.
- Implement multimodal tool result mapping for providers that support
it: Anthropic, Amazon Bedrock, and Google AI Gemini.
- Add `UnsupportedFeatureException` guards in providers that do not
support non-text tool results: Azure OpenAI, GitHub Models, Jlama,
Mistral AI, Ollama, OpenAI (Chat Completions
& Responses), Vertex AI (Anthropic & Gemini), Watsonx, and Workers AI.
- Update `ToolExecutedEvent` / `DefaultToolExecutedEvent` to carry
`resultContents` alongside the existing `resultText` accessor.
- Add comprehensive unit and integration tests
(`should_execute_tool_returning_Image`,
`should_execute_tool_returning_ImageContent`,
`should_execute_tool_returning_ContentList`,
`should_fail_when_tool_returns_image_and_provider_does_not_support_it`).
- Update tools documentation with new "Returning Images and Multimodal
Content" and "Multimodal Tool Results" sections.
## General checklist
- [X] There are no breaking changes (API, behaviour)
- [X] I have added unit and/or integration tests for my change
- [X] The tests cover both positive and negative cases
- [X] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green
- [X] I have manually run all the unit and integration tests in the
[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)
and
[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)
modules, and they are all green
- [X] I have added/updated the
[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)
- [ ] I have added an example in the [examples
repo](https://github.com/langchain4j/langchain4j-examples) (only for
"big" features)
- [ ] I have added/updated [Spring Boot
starter(s)](https://github.com/langchain4j/langchain4j-spring) (if
applicable)
<!--
Thank you so much for your contribution!
Please fill in all the sections below.
Please open the PR as a draft initially. Once it is reviewed and
approved, we will ask you to add documentation and examples.
Please note that PRs with breaking changes or without tests will be
rejected.
Please note that PRs will be reviewed based on the priority of the
issues they address.
We ask for your patience. We are doing our best to review your PR as
quickly as possible.
Please refrain from pinging and asking when it will be reviewed. Thank
you for understanding!
-->
## Issue
<!-- Please specify the ID of the issue this PR is addressing. For
example: "Closes #1234" or "Fixes #1234" -->
Closes #
## Change
The new section in the `agents.md` file explains how this new feature
works.
## General checklist
<!-- Please double-check the following points and mark them like this:
[X] -->
- [X] There are no breaking changes (API, behaviour)
- [X] I have added unit and/or integration tests for my change
- [X] The tests cover both positive and negative cases
- [X] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green
- [ ] I have manually run all the unit and integration tests in the
[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)
and
[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)
modules, and they are all green
<!-- Before adding documentation and example(s) (below), please wait
until the PR is reviewed and approved. -->
- [ ] I have added/updated the
[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)
- [ ] I have added an example in the [examples
repo](https://github.com/langchain4j/langchain4j-examples) (only for
"big" features)
- [ ] I have added/updated [Spring Boot
starter(s)](https://github.com/langchain4j/langchain4j-spring) (if
applicable)
## Checklist for adding new maven module
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have added my new module in the root `pom.xml` and
`langchain4j-bom/pom.xml`
## Checklist for adding new embedding store integration
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreIT` that extends
from either `EmbeddingStoreIT` or `EmbeddingStoreWithFilteringIT`
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreRemovalIT` that
extends from `EmbeddingStoreWithRemovalIT`
## Checklist for changing existing embedding store integration
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have manually verified that the
`{NameOfIntegration}EmbeddingStore` works correctly with the data
persisted using the latest released version of LangChain4j
add 'dependencies' tag in 'dependencyManagement'
<!--
Thank you so much for your contribution!
Please fill in all the sections below.
Please open the PR as a draft initially. Once it is reviewed and
approved, we will ask you to add documentation and examples.
Please note that PRs with breaking changes or without tests will be
rejected.
Please note that PRs will be reviewed based on the priority of the
issues they address.
We ask for your patience. We are doing our best to review your PR as
quickly as possible.
Please refrain from pinging and asking when it will be reviewed. Thank
you for understanding!
-->
## Issue
<!-- Please specify the ID of the issue this PR is addressing. For
example: "Closes #1234" or "Fixes #1234" -->
Closes #
## Change
<!-- Please describe the changes you made. -->
## General checklist
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] There are no breaking changes (API, behaviour)
- [ ] I have added unit and/or integration tests for my change
- [ ] The tests cover both positive and negative cases
- [ ] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green
- [ ] I have manually run all the unit and integration tests in the
[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)
and
[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)
modules, and they are all green
<!-- Before adding documentation and example(s) (below), please wait
until the PR is reviewed and approved. -->
- [ ] I have added/updated the
[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)
- [ ] I have added an example in the [examples
repo](https://github.com/langchain4j/langchain4j-examples) (only for
"big" features)
- [ ] I have added/updated [Spring Boot
starter(s)](https://github.com/langchain4j/langchain4j-spring) (if
applicable)
## Checklist for adding new maven module
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have added my new module in the root `pom.xml` and
`langchain4j-bom/pom.xml`
## Checklist for adding new embedding store integration
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreIT` that extends
from either `EmbeddingStoreIT` or `EmbeddingStoreWithFilteringIT`
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreRemovalIT` that
extends from `EmbeddingStoreWithRemovalIT`
## Checklist for changing existing embedding store integration
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have manually verified that the
`{NameOfIntegration}EmbeddingStore` works correctly with the data
persisted using the latest released version of LangChain4j
<!--
Thank you so much for your contribution!
Please fill in all the sections below.
Please open the PR as a draft initially. Once it is reviewed and
approved, we will ask you to add documentation and examples.
Please note that PRs with breaking changes or without tests will be
rejected.
Please note that PRs will be reviewed based on the priority of the
issues they address.
We ask for your patience. We are doing our best to review your PR as
quickly as possible.
Please refrain from pinging and asking when it will be reviewed. Thank
you for understanding!
-->
## Issue
<!-- Please specify the ID of the issue this PR is addressing. For
example: "Closes #1234" or "Fixes #1234" -->
Closes #
## Change
<!-- Please describe the changes you made. -->
## General checklist
<!-- Please double-check the following points and mark them like this:
[X] -->
- [X] There are no breaking changes (API, behaviour)
- [X] I have added unit and/or integration tests for my change
- [X] The tests cover both positive and negative cases
- [X] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green
- [ ] I have manually run all the unit and integration tests in the
[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)
and
[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)
modules, and they are all green
<!-- Before adding documentation and example(s) (below), please wait
until the PR is reviewed and approved. -->
- [ ] I have added/updated the
[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)
- [ ] I have added an example in the [examples
repo](https://github.com/langchain4j/langchain4j-examples) (only for
"big" features)
- [ ] I have added/updated [Spring Boot
starter(s)](https://github.com/langchain4j/langchain4j-spring) (if
applicable)
## Checklist for adding new maven module
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have added my new module in the root `pom.xml` and
`langchain4j-bom/pom.xml`
## Checklist for adding new embedding store integration
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreIT` that extends
from either `EmbeddingStoreIT` or `EmbeddingStoreWithFilteringIT`
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreRemovalIT` that
extends from `EmbeddingStoreWithRemovalIT`
## Checklist for changing existing embedding store integration
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have manually verified that the
`{NameOfIntegration}EmbeddingStore` works correctly with the data
persisted using the latest released version of LangChain4j
## Issue
No issue opened.
## Changes
* Migrated from RestClient to ElasticsearchClient in embedding store and
related classes.
* Upgraded Elasticsearch to 9.3.1.
Now that the `ElasticsearchClient` can be super easily built with a
simple line like:
```java
ElasticsearchClient esClient = ElasticsearchClient.of(b -> b
.host(serverUrl)
.apiKey(apiKey)
);
```
We don't need to import the old Low Level rest client anymore.
I marked some of the old APIs as `@Deprecated`. I just don't know when
we are allowed to remove them.
Also this will make the documentation looking much better in
https://github.com/langchain4j/langchain4j-examples/tree/main/elasticsearch-example.
I'm in the process of updating also this examples repo...
## General checklist
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] There are no breaking changes (API, behaviour)
- [X] I have added unit and/or integration tests for my change
- [ ] The tests cover both positive and negative cases
- [X] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green
- [ ] I have manually run all the unit and integration tests in the
[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)
and
[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)
modules, and they are all green
- [ ] I have added/updated the
[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)
- [ ] I have added an example in the [examples
repo](https://github.com/langchain4j/langchain4j-examples) (only for
"big" features)
- [ ] I have added/updated [Spring Boot
starter(s)](https://github.com/langchain4j/langchain4j-spring) (if
applicable)
## Checklist for changing existing embedding store integration
- [X] I have manually verified that the
`{NameOfIntegration}EmbeddingStore` works correctly with the data
persisted using the latest released version of LangChain4j
Allows passing `_meta` fields for MCP client invocations. See the
`docs/docs/tutorials/mcp.md` file for explanation.
The first commit slightly reorganizes the internal protocol messages to
more closely mirror the MCP schema
(https://github.com/modelcontextprotocol/modelcontextprotocol/blob/2025-06-18/schema/2025-06-18/schema.json).
It doesn't introduce any breaking change. The gist is the introduction
of `McpClientRequest`,`McpClientResponse`,`McpClientNotification` in the
middle of the hierarchy to provide the proper distinction between these
types of messages. `McpClientRequest` and ,`McpClientNotification` now
contain a common `params` field instead of each implementation providing
its own field - instead, where appropriate, they have their own subclass
of `McpClientParams` to hold their specific params, so it's more
typesafe and the meta fields can be applied to each request type in a
unified way. I've also added javadoc comments to make it clear which
schema type each class corresponds to.
This is a prerequisite for proper implementation of distributed tracing
of MCP client
(https://github.com/quarkiverse/quarkus-langchain4j/issues/2221)
## Change
#### Skill-Scoped Tools
You can attach tools directly to a skill. These tools are **only exposed
to the LLM
after the skill has been activated** via the `activate_skill` tool.
This keeps the LLM's tool list small and focused, and ensures
skill-specific tools only
appear when they are relevant.
##### Using `@Tool`-Annotated Methods
The simplest way to attach tools is to pass objects with
`@Tool`-annotated methods:
```java
class OrderTools {
@Tool("Validates a customer order by ID")
String validateOrder(String orderId) {
// validation logic
return "valid";
}
@Tool("Charges payment for a customer order")
String chargePayment(String orderId) {
// payment logic
return "charged";
}
}
Skill skill = Skill.builder()
.name("process-order")
.description("Processes a customer order end-to-end")
.content("""
To process an order:
1. Call `validateOrder(orderId)` to check the order is valid.
2. Call `chargePayment(orderId)`.
""")
.tools(new OrderTools())
.build();
```
Tools can also be attached to an already-built skill using `toBuilder()`
— for example,
to add tools to a skill loaded from the file system:
```java
FileSystemSkill skill = FileSystemSkillLoader.loadSkill(Path.of("skills/process-order"));
Skill skillWithTools = skill.toBuilder()
.tools(new OrderTools())
.build();
```
##### Using Tool Providers
You can also attach `ToolProvider`s to a skill — for example, to expose
tools from an
MCP server only after the skill is activated:
```java
ToolProvider mcpToolProvider = McpToolProvider.builder()
.mcpClients(mcpClient)
.toolFilter((tool, mcpClient) -> tool.name().startsWith("inventory_"))
.build();
Skill skill = Skill.builder()
.name("inventory-management")
.description("Manages warehouse inventory")
.content("""
Use inventory tools to check stock levels and update quantities.
""")
.toolProviders(mcpToolProvider)
.build();
```
##### Using a `Map<ToolSpecification, ToolExecutor>`
For full control over tool specifications and execution logic, you can
pass a map directly:
```java
ToolSpecification validateOrder = ToolSpecification.builder()
.name("validateOrder")
.description("Validates a customer order by ID")
.addParameter("orderId", JsonSchemaProperty.STRING, JsonSchemaProperty.description("The order ID"))
.build();
ToolExecutor validateOrderExecutor = (request, memoryId) -> {
String orderId = parseOrderId(request.arguments());
return validate(orderId);
};
Skill skill = Skill.builder()
.name("process-order")
.description("Processes a customer order end-to-end")
.content("""
To process an order:
1. Call `validateOrder(orderId)` to check the order is valid.
""")
.tools(Map.of(validateOrder, validateOrderExecutor))
.build();
```
All three approaches can be combined — `@Tool` methods, `ToolProvider`s,
and `Map` entries
are merged into a single set of skill-scoped tools:
```java
Skill skill = Skill.builder()
.name("process-order")
.description("Processes a customer order end-to-end")
.content("...")
.tools(new OrderTools())
.tools(Map.of(validateOrder, validateOrderExecutor))
.toolProviders(mcpToolProvider)
.build();
```
##### Wiring It Up
```java
Skills skills = Skills.from(skill);
MyAiService service = AiServices.builder(MyAiService.class)
.chatModel(chatModel)
.chatMemory(MessageWindowChatMemory.withMaxMessages(100))
.toolProvider(skills.toolProvider())
.systemMessage("You have access to the following skills:\n" + skills.formatAvailableSkills()
+ "\nWhen the user's request relates to one of these skills, activate it first.")
.build();
```
##### How Skill-Scoped Tools Work
1. Before skill activation, the LLM only sees the `activate_skill` (and
`read_skill_resource`) tools.
Skill-scoped tools are not included in the tool list.
2. When the LLM calls `activate_skill("process-order")`, the activation
is recorded in the `ToolExecutionResultMessage`.
3. Before the next LLM call (within the same AI Service invocation), the
AI Service re-evaluates dynamic tool providers
against the current messages. The skill-scoped tools (e.g.
`validateOrder`) become
visible and the LLM can call them immediately, in the same AI Service
invocation.
The skill-scoped tools stay visible to the LLM in the next AI Service
invocations, they become invisible only when
the skill is deactivated.
##### Using Skills with Tool Search
Skills work alongside [Tool Search](/tutorials/tools#tool-search). When
both are configured,
they operate independently:
- **Skill-scoped tools are never searchable.** They don't appear in the
searchable tool pool
and cannot be found via `tool_search_tool`. They only become visible
after the LLM activates
the corresponding skill.
- **Regular tools remain searchable.** Tools registered via
`.tools(...)` on the AI Service
(not on a skill) continue to be searchable, regardless of whether any
skill is activated.
- **`activate_skill` is always visible.** It is marked as
`ALWAYS_VISIBLE`, so the LLM can
always call it even when Tool Search is enabled.
```java
Skills skills = Skills.from(mySkills);
MyAiService service = AiServices.builder(MyAiService.class)
.chatModel(chatModel)
.chatMemory(MessageWindowChatMemory.withMaxMessages(100))
.tools(new MySearchableTools()) // these are searchable
.toolProvider(skills.toolProvider()) // skill-scoped tools are NOT searchable
.toolSearchStrategy(new SimpleToolSearchStrategy())
.systemMessage("You have access to the following skills:\n" + skills.formatAvailableSkills()
+ "\nWhen the user's request relates to one of these skills, activate it first.")
.build();
```
## General checklist
- [x] There are no breaking changes (API, behaviour)
- [x] I have added unit and/or integration tests for my change
- [x] The tests cover both positive and negative cases
- [x] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green
- [x] I have manually run all the unit and integration tests in the
[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)
and
[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)
modules, and they are all green
- [x] I have added/updated the
[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)
- [ ] I have added an example in the [examples
repo](https://github.com/langchain4j/langchain4j-examples) (only for
"big" features)
- [ ] I have added/updated [Spring Boot
starter(s)](https://github.com/langchain4j/langchain4j-spring) (if
applicable)
<!--
Thank you so much for your contribution!
Please fill in all the sections below.
Please open the PR as a draft initially. Once it is reviewed and
approved, we will ask you to add documentation and examples.
Please note that PRs with breaking changes or without tests will be
rejected.
Please note that PRs will be reviewed based on the priority of the
issues they address.
We ask for your patience. We are doing our best to review your PR as
quickly as possible.
Please refrain from pinging and asking when it will be reviewed. Thank
you for understanding!
-->
## Issue
<!-- Please specify the ID of the issue this PR is addressing. For
example: "Closes #1234" or "Fixes #1234" -->
Closes#4442
## Change
<!-- Please describe the changes you made. -->
## General checklist
<!-- Please double-check the following points and mark them like this:
[X] -->
- [X] There are no breaking changes (API, behaviour)
- [X] I have added unit and/or integration tests for my change
- [X] The tests cover both positive and negative cases
- [X] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green
- [ ] I have manually run all the unit and integration tests in the
[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)
and
[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)
modules, and they are all green
<!-- Before adding documentation and example(s) (below), please wait
until the PR is reviewed and approved. -->
- [ ] I have added/updated the
[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)
- [ ] I have added an example in the [examples
repo](https://github.com/langchain4j/langchain4j-examples) (only for
"big" features)
- [ ] I have added/updated [Spring Boot
starter(s)](https://github.com/langchain4j/langchain4j-spring) (if
applicable)
## Checklist for adding new maven module
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have added my new module in the root `pom.xml` and
`langchain4j-bom/pom.xml`
## Checklist for adding new embedding store integration
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreIT` that extends
from either `EmbeddingStoreIT` or `EmbeddingStoreWithFilteringIT`
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreRemovalIT` that
extends from `EmbeddingStoreWithRemovalIT`
## Checklist for changing existing embedding store integration
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have manually verified that the
`{NameOfIntegration}EmbeddingStore` works correctly with the data
persisted using the latest released version of LangChain4j
---------
Co-authored-by: Dmytro Liubarskyi <ljubarskij@gmail.com>
## Summary
- add a dedicated docs page for the
`langchain4j-community-prompt-repetition` module
- add discovery links from the guardrails and RAG tutorials
- document the module as an experimental, ready-made prompt repetition
integration
## Details
This adds documentation in the main `langchain4j` docs site for the
community prompt repetition module introduced in
`langchain4j-community`.
It includes:
- a new integration page under `Integrations > Prompt Repetition`
- a short pointer from the guardrails tutorial to
`PromptRepeatingInputGuardrail`
- a short pointer from the RAG tutorial to `RepeatingQueryTransformer`
The docs position the module as:
- an optional community module
- an experimental but real integration, not just an evaluation harness
- inspired by the paper [Prompt Repetition Improves Non-Reasoning
LLMs](https://arxiv.org/html/2512.14982v1)
- a way to apply the core repeated-input transformation in LangChain4j
for eligible inputs
- something users should still validate on their own prompts, models,
and tasks
The wording intentionally avoids claiming that this module reproduces
the paper's full methodology or results.
## Issue
Closes#4725.
## Change
This PR switches `ElasticsearchConfiguration` from an abstract class to
an interface with default methods throwing an
`UnsupportedOperationException`.
This allows creating a self-made implementation. See the
`ElasticsearchConfigurationCustomIT` test and its
`ElasticsearchConfigurationCustom` class.
```java
public class ElasticsearchConfigurationCustom implements ElasticsearchConfiguration {
@Override
public SearchResponse<Document> vectorSearch(
ElasticsearchClient client, String indexName, EmbeddingSearchRequest embeddingSearchRequest)
throws ElasticsearchException {
// Implement here
}
}
```
## General checklist
- [X] There are no breaking changes (API, behaviour)
- [X] I have added unit and/or integration tests for my change
- [ ] The tests cover both positive and negative cases
- [X] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green
- [ ] I have manually run all the unit and integration tests in the
[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)
and
[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)
modules, and they are all green
- [X] I have added/updated the
[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)
- [ ] I have added an example in the [examples
repo](https://github.com/langchain4j/langchain4j-examples) (only for
"big" features)
- [ ] I have added/updated [Spring Boot
starter(s)](https://github.com/langchain4j/langchain4j-spring) (if
applicable)
## Checklist for adding new maven module
- [ ] I have added my new module in the root `pom.xml` and
`langchain4j-bom/pom.xml`
## Checklist for adding new embedding store integration
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreIT` that extends
from either `EmbeddingStoreIT` or `EmbeddingStoreWithFilteringIT`
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreRemovalIT` that
extends from `EmbeddingStoreWithRemovalIT`
## Checklist for changing existing embedding store integration
- [ ] I have manually verified that the
`{NameOfIntegration}EmbeddingStore` works correctly with the data
persisted using the latest released version of LangChain4j
<!--
Thank you so much for your contribution!
Please fill in all the sections below.
Please open the PR as a draft initially. Once it is reviewed and
approved, we will ask you to add documentation and examples.
Please note that PRs with breaking changes or without tests will be
rejected.
Please note that PRs will be reviewed based on the priority of the
issues they address.
We ask for your patience. We are doing our best to review your PR as
quickly as possible.
Please refrain from pinging and asking when it will be reviewed. Thank
you for understanding!
-->
## Issue
<!-- Please specify the ID of the issue this PR is addressing. For
example: "Closes #1234" or "Fixes #1234" -->
Closes #
## Change
<!-- Please describe the changes you made. -->
## General checklist
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] There are no breaking changes (API, behaviour)
- [ ] I have added unit and/or integration tests for my change
- [ ] The tests cover both positive and negative cases
- [ ] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green
- [ ] I have manually run all the unit and integration tests in the
[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)
and
[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)
modules, and they are all green
<!-- Before adding documentation and example(s) (below), please wait
until the PR is reviewed and approved. -->
- [ ] I have added/updated the
[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)
- [ ] I have added an example in the [examples
repo](https://github.com/langchain4j/langchain4j-examples) (only for
"big" features)
- [ ] I have added/updated [Spring Boot
starter(s)](https://github.com/langchain4j/langchain4j-spring) (if
applicable)
## Checklist for adding new maven module
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have added my new module in the root `pom.xml` and
`langchain4j-bom/pom.xml`
## Checklist for adding new embedding store integration
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreIT` that extends
from either `EmbeddingStoreIT` or `EmbeddingStoreWithFilteringIT`
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreRemovalIT` that
extends from `EmbeddingStoreWithRemovalIT`
## Checklist for changing existing embedding store integration
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have manually verified that the
`{NameOfIntegration}EmbeddingStore` works correctly with the data
persisted using the latest released version of LangChain4j
## Issue
Closes#4543
## Change
Implemented support for **Structured Output** in AWS Bedrock, allowing
models to generate responses adhering to a specific JSON schema.
**Key changes:**
- **SDK Upgrade**: Upgraded `aws-java-sdk-bedrockruntime` from `2.33.5`
to `2.41.22` to access `OutputConfig` and `JsonSchemaDefinition` APIs.
- **New Feature**: Added `outputConfig` support to `ConverseRequest` in
`BedrockChatModel` and `BedrockStreamingChatModel`.
- **Schema Mapping**: Created `BedrockSchemaMapper` to convert
LangChain4j `JsonSchema` objects into AWS SDK `Document` format.
- **Validation**: Removed the `UnsupportedFeatureException` that was
previously thrown when `ResponseFormat.JSON` was requested.
## General checklist
- [x] There are no breaking changes (API, behaviour)
- [x] I have added unit and/or integration tests for my change
- [x] The tests cover both positive and negative cases
- [x] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green
- [ ] I have manually run all the unit and integration tests in the
[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)
and
[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)
modules, and they are all green
- [ ] I have added/updated the
[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)
- [ ] I have added an example in the [examples
repo](https://github.com/langchain4j/langchain4j-examples) (only for
"big" features)
- [ ] I have added/updated [Spring Boot
starter(s)](https://github.com/langchain4j/langchain4j-spring) (if
applicable)
## Checklist for adding new maven module
- [ ] I have added my new module in the root
[pom.xml](cci:7://file:///Users/mohankumarsagadevan/Documents/projects/github/langchain4j/langchain4j-parent/pom.xml:0:0-0:0)
and
[langchain4j-bom/pom.xml](cci:7://file:///Users/mohankumarsagadevan/Documents/projects/github/langchain4j/langchain4j-bom/pom.xml:0:0-0:0)
## Checklist for adding new embedding store integration
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreIT` that extends
from either `EmbeddingStoreIT` or `EmbeddingStoreWithFilteringIT`
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreRemovalIT` that
extends from `EmbeddingStoreWithRemovalIT`
## Checklist for changing existing embedding store integration
- [ ] I have manually verified that the
`{NameOfIntegration}EmbeddingStore` works correctly with the data
persisted using the latest released version of LangChain4j
---------
Co-authored-by: Mohan Kumar Sagadevan <mohankumarsagadevan@Mohans-MacBook-Air.local>
Co-authored-by: Dmytro Liubarskyi <ljubarskij@gmail.com>
## Issue
Closes https://github.com/langchain4j/langchain4j/issues/4396
## Change
Introduces support for [Agent Skills](https://agentskills.io/home)
# Skills
:::note
The Skills API is experimental. APIs and behavior may still change in
future releases.
:::
Skills is a mechanism for equipping an LLM with reusable, self-contained
behavioral instructions.
A skill bundles a name, a short description, and a body of instructions
(its _content_),
together with optional resources (e.g., references, assets, templates,
etc.).
The LLM loads a skill on demand, keeping the initial context small and
only pulling in
the detailed instructions when they are actually needed.
:::note
Skills are designed according to the [Agent Skills
specification](https://agentskills.io).
:::
## Creating Skills
### From the File System
Typically, each skill lives in its own directory containing a `SKILL.md`
file.
The file must start with a YAML front matter block that declares the
skill's `name` and `description`.
Everything below the front matter becomes the skill's content — the
instructions given to the LLM
when it activates the skill.
```
skills/
├── docx/
│ ├── SKILL.md
│ └── references/
│ └── tracked-changes.md ← loaded as a resource
└── data-analysis/
└── SKILL.md
```
Example `SKILL.md`:
```markdown
---
name: docx
description: Edit and review Word documents using tracked changes
---
When the user asks you to edit a Word document:
1. Always use tracked changes so edits can be reviewed.
...
```
Any file in the skill directory (other than `SKILL.md` itself and files
under a `scripts/`
subdirectory) is automatically loaded as a `SkillResource` that the LLM
can read on demand.
Use `FileSystemSkillLoader` from the `langchain4j-skills` module to load
skills from the file system:
```xml
<dependency>
<groupId>dev.langchain4j</groupId>
<artifactId>langchain4j-skills</artifactId>
<version>1.12.0-beta20</version>
</dependency>
```
```java
// Load all skills found in immediate subdirectories:
List<FileSystemSkill> skills = FileSystemSkillLoader.loadSkills(Path.of("skills/"));
// Or load a single skill by its directory:
FileSystemSkill skill = FileSystemSkillLoader.loadSkill(Path.of("skills/docx"));
```
### Programmatically
Skills do not have to be file-system based.
You can create them from any source — a database, a remote API,
generated at runtime — using the builder API:
```java
Skill skill = Skill.builder()
.name("incident-response")
.description("Step-by-step runbook for diagnosing and resolving production incidents")
.content("""
When a production alert fires:
1. Call `fetchRecentLogs(serviceName)` to retrieve the last 5 minutes of logs.
2. Call `checkServiceHealth(serviceName)` to get current health metrics.
3. Based on the findings, call `createIncidentTicket(summary, severity)`.
4. If severity is CRITICAL, also call `pageOnCall(incidentId)`.
""")
.build();
```
You can also attach resources programmatically:
```java
SkillResource reference = SkillResource.builder()
.relativePath("references/tone-guide.md")
.content("Use warm, concise language. Avoid jargon.")
.build();
Skill skill = Skill.builder()
.name("customer-support")
.description("Handles customer support inquiries")
.content("Follow the tone guide in references/tone-guide.md ...")
.resources(List.of(reference))
.build();
```
## Modes
Skills can be integrated with an AI Service in two distinct modes,
depending on how much
control and trust you need.
### Tool Mode (Recommended)
**Class:** `Skills` (from the `langchain4j-skills` module)
This corresponds to the **Tool-based agents** integration approach
described in the
[Agent Skills specification](https://agentskills.io/integrate-skills).
In this mode, the LLM activates a skill to receive step-by-step
instructions, then carries
them out by calling the [tools](/tutorials/tools) you have explicitly
registered.
**The LLM has no access to the file system at inference time** — all
skill content and
resources are loaded into memory upfront (e.g. via
`FileSystemSkillLoader`), and the `activate_skill`
and `read_skill_resource` tools returns that preloaded content rather
than reading from disk.
Because only your pre-defined tools can be invoked, **there is no risk
of arbitrary code execution**.
#### Registered Tools
| Tool | When registered |
|-----------------------|-----------------------------------------------------------------------------------------------|
| `activate_skill` | Always. The LLM calls this to load a skill's full
instructions into the context. |
| `read_skill_resource` | When at least one skill has resources. The LLM
calls this to read individual reference files. |
#### How It Works
1. The system message lists the available skills (names and
descriptions) so the LLM can choose.
2. The user asks a question that requires a specific skill.
3. The LLM calls `activate_skill("my-skill")` to receive its
instructions.
4. The LLM follows those instructions to complete the task, optionally
reading resource files along the way.
#### Example Skill
Skills describe the _policy_ — the exact order of calls, required
arguments, error-handling steps,
and worked examples — while the actual execution stays in type-safe,
tested Java code:
```markdown
---
name: process-order
description: Processes a customer order end-to-end
---
To process an order:
1. Call `validateOrder(orderId)` to check the order is valid.
2. Call `reserveInventory(orderId)` to reserve the required stock.
3. Only if reservation succeeds, call `chargePayment(orderId)`.
4. Finally, call `sendConfirmationEmail(orderId)`.
If any step fails, call `rollbackOrder(orderId)` before reporting the error.
```
#### Wiring It Up
Pass the `ToolProvider` from `Skills` to your AI Service builder
alongside your regular tools.
Use `formatAvailableSkills()` to inject the skill catalogue into the
system message so
the LLM knows which skills it can activate:
```java
Skills skills = Skills.from(FileSystemSkillLoader.loadSkills(Path.of("skills/")));
MyAiService service = AiServices.builder(MyAiService.class)
.chatModel(chatModel)
.tools(new OrderTools()) // your tools
.toolProvider(skills.toolProvider()) // or .toolProviders(mcpToolProvider, skills.toolProvider())
.systemMessage("You have access to the following skills:\n" + skills.formatAvailableSkills()
+ "\nWhen the user's request relates to one of these skills, activate it first using the `activate_skill` tool before proceeding.")
.build();
```
`formatAvailableSkills()` returns an XML-formatted block listing each
skill's name and description:
```xml
<available_skills>
<skill>
<name>process-order</name>
<description>Processes a customer order end-to-end</description>
</skill>
<skill>
<name>data-analysis</name>
<description>Analyse tabular data and produce charts</description>
</skill>
</available_skills>
```
#### Customisation
The name, description, and parameter metadata of each tool can be
overridden through the
corresponding config class on the builder:
```java
Skills skills = Skills.builder()
.skills(mySkills)
.activateSkillToolConfig(ActivateSkillToolConfig.builder()
.name(...) // tool name (default: "activate_skill")
.description(...) // tool description
.parameterName(...) // parameter name (default: "skill_name")
.parameterDescription(...) // parameter description
.throwToolArgumentsExceptions(...) // throw ToolArgumentsException instead of ToolExecutionException (default: false)
.build())
.readResourceToolConfig(ReadResourceToolConfig.builder()
.name(...) // tool name (default: "read_skill_resource")
.description(...) // tool description
.skillNameParameterName(...) // skill_name parameter name (default: "skill_name")
.skillNameParameterDescription(...) // skill_name parameter description
.relativePathParameterName(...) // relative_path parameter name (default: "relative_path")
.relativePathParameterDescription(...) // static description (takes precedence over provider)
.relativePathParameterDescriptionProvider(...) // dynamic description based on available resources
.throwToolArgumentsExceptions(...) // throw ToolArgumentsException instead of ToolExecutionException (default: false)
.build())
.build();
```
### Shell Mode (Experimental)
**Class:** `ShellSkills` (from the
`langchain4j-experimental-skills-shell` module)
This corresponds to the **Filesystem-based agents** integration approach
described in the
[Agent Skills specification](https://agentskills.io/integrate-skills).
:::warning
**Shell execution is inherently unsafe.**
Commands run directly in the host process environment **without any
sandboxing, containerization,
or privilege restriction**. A misbehaving or prompt-injected LLM can
execute arbitrary commands
on the machine running your application.
Only use this in controlled environments where you fully trust the input
and accept
the associated risks.
:::
In this mode, the LLM is given a single `run_shell_command` tool and
reads skill instructions
directly from the file system using shell commands. There is no
`activate_skill` or
`read_skill_resource` tool — the LLM navigates skill files like a human
developer would.
#### Registered Tools
| Tool | When registered |
|---------------------|---------------------------------------------------------------------------------------------------|
| `run_shell_command` | Always. The LLM runs shell commands to read
`SKILL.md` files, resource files and execute scripts. |
#### How It Works
1. The system message lists available skills with their absolute
filesystem paths.
2. The user asks a question that requires a specific skill.
3. The LLM runs `cat /path/to/skills/docx/SKILL.md` to read the
instructions.
4. The LLM follows those instructions by running further shell commands.
#### Dependency
Shell execution lives in a separate experimental artifact — add it to
your build:
```xml
<dependency>
<groupId>dev.langchain4j</groupId>
<artifactId>langchain4j-experimental-skills-shell</artifactId>
<version>1.12.0-beta20</version>
</dependency>
```
#### Wiring It Up
All skills must be filesystem-based (loaded via
`FileSystemSkillLoader`).
Use `ShellSkills` instead of `Skills`:
```java
ShellSkills skills = ShellSkills.from(FileSystemSkillLoader.loadSkills(Path.of("skills/")));
MyAiService service = AiServices.builder(MyAiService.class)
.chatModel(chatModel)
.toolProvider(skills.toolProvider()) // or .toolProviders(mcpToolProvider, skills.toolProvider())
.systemMessage("You have access to the following skills:\n" + skills.formatAvailableSkills()
+ "\nWhen the user's request relates to one of these skills, read its SKILL.md before proceeding.")
.build();
```
`formatAvailableSkills()` includes a `<location>` field so the LLM knows
exactly where to find each `SKILL.md`:
```xml
<available_skills>
<skill>
<name>docx</name>
<description>Edit and review Word documents using tracked changes</description>
<location>/path/to/skills/docx/SKILL.md</location>
</skill>
<skill>
<name>data-analysis</name>
<description>Analyse tabular data and produce charts</description>
<location>/path/to/skills/data-analysis/SKILL.md</location>
</skill>
</available_skills>
```
#### When to Use Shell Mode
This mode is best suited for **experimentation and prototyping**, or
when you want to use
third-party skills published by the community (e.g. from the
[agentskills.io](https://agentskills.io) ecosystem) without first
porting them to Java.
It lets you wire up a working workflow quickly, then migrate individual
actions
to tools as the solution matures.
#### Customisation
Use `RunShellCommandToolConfig` to tune the working directory, output
limits,
and parameter names:
```java
ShellSkills skills = ShellSkills.builder()
.skills(mySkills)
.runShellCommandToolConfig(RunShellCommandToolConfig.builder()
.name(...) // tool name (default: "run_shell_command")
.description(...) // tool description (default: includes OS name)
.commandParameterName(...) // command parameter name (default: "command")
.commandParameterDescription(...) // command parameter description
.timeoutSecondsParameterName(...) // timeout parameter name (default: "timeout_seconds")
.timeoutSecondsParameterDescription(...) // timeout parameter description
.workingDirectory(...) // working directory for commands (default: JVM's user.dir)
.maxStdOutChars(...) // max stdout chars in result (default: 10_000)
.maxStdErrChars(...) // max stderr chars in result (default: 10_000)
.executorService(...) // ExecutorService for reading stdout/stderr streams
.throwToolArgumentsExceptions(...) // throw ToolArgumentsException instead of ToolExecutionException (default: false)
.build())
.build();
```
## General checklist
- [X] There are no breaking changes (API, behaviour)
- [X] I have added unit and/or integration tests for my change
- [X] The tests cover both positive and negative cases
- [X] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green
- [X] I have manually run all the unit and integration tests in the
[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)
and
[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)
modules, and they are all green
- [X] I have added/updated the
[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)
- [ ] I have added an example in the [examples
repo](https://github.com/langchain4j/langchain4j-examples) (only for
"big" features)
- [ ] I have added/updated [Spring Boot
starter(s)](https://github.com/langchain4j/langchain4j-spring) (if
applicable)
## Checklist for adding new maven module
- [X] I have added my new module in the root `pom.xml` and
`langchain4j-bom/pom.xml`
## Issue
This PR adds observability support for `ModerationModel`
implementations, following the same patterns established for `ChatModel`
listeners. It introduces a new request/response API for moderation
operations and provides listener callbacks for monitoring moderation
requests, responses, and errors.
## Change
Commits:
1)
[f025c0f61](https://github.com/jeanbisutti/langchain4j/commit/f025c0f61)
- **Add ModerationRequest/ModerationResponse API to ModerationModel**
- Introduce `ModerationRequest` with builder pattern supporting both
text and messages
- Introduce `ModerationResponse` with metadata (model name, token usage,
finish reason)
- Add `moderate(ModerationRequest)` method to `ModerationModel`
interface
- Update all implementations (OpenAI, MistralAI, Watsonx) to support the
new API
- Add unit tests for request/response classes
2)
[aed77bf60](https://github.com/jeanbisutti/langchain4j/commit/aed77bf60)
- **Add moderation model listener support**
- Add `ModerationModelListener` interface with `onRequest`,
`onResponse`, `onError` callbacks
- Add context classes: `ModerationModelRequestContext`,
`ModerationModelResponseContext`, `ModerationModelErrorContext`
- Add `ModerationModelListenerUtils` for consistent listener invocation
across implementations
- Implement listener support in OpenAI, MistralAI, and Watsonx
moderation models
- Add `AbstractModerationModelListenerIT` base test class for consistent
testing
- Add documentation in observability tutorial
3)
[2c600cd90](https://github.com/jeanbisutti/langchain4j/commit/2c600cd90)
- **Refactoring - Add toInputs and toText utility methods to
ModerationModel**
- Extract common `toInputs()` and `toText()` utility methods to
`ModerationModel` interface
- Remove duplicate code from OpenAI, MistralAI, and Watsonx
implementations
**Backward Compatibility:** The existing `moderate(String text)` and
`moderate(ChatMessage... messages)` methods remain unchanged. The new
`moderate(ModerationRequest)` API is additive. Listener support is
opt-in via builder configuration.
## General checklist
<!-- Please double-check the following points and mark them like this:
[X] -->
- [X] There are no breaking changes (API, behaviour)
- [X] I have added unit and/or integration tests for my change
- [X] The tests cover both positive and negative cases
- [X] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green
- [X] I have manually run all the unit and integration tests in the
[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)
and
[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)
modules, and they are all green
<!-- Before adding documentation and example(s) (below), please wait
until the PR is reviewed and approved. -->
- [X] I have added/updated the
[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)
- [ ] I have added an example in the [examples
repo](https://github.com/langchain4j/langchain4j-examples) (only for
"big" features)
- [ ] I have added/updated [Spring Boot
starter(s)](https://github.com/langchain4j/langchain4j-spring) (if
applicable)
---------
Co-authored-by: Dmytro Liubarskyi <ljubarskij@gmail.com>
<!--
Thank you so much for your contribution!
Please fill in all the sections below.
Please open the PR as a draft initially. Once it is reviewed and
approved, we will ask you to add documentation and examples.
Please note that PRs with breaking changes or without tests will be
rejected.
Please note that PRs will be reviewed based on the priority of the
issues they address.
We ask for your patience. We are doing our best to review your PR as
quickly as possible.
Please refrain from pinging and asking when it will be reviewed. Thank
you for understanding!
-->
## Issue
<!-- Please specify the ID of the issue this PR is addressing. For
example: "Closes #1234" or "Fixes #1234" -->
Closes #
## Change
Allows agents to be monitored by simply extending the new
`MonitoredAgent` interface. This will be convenient especially using the
declarative API, so that the `AgentMonitor` could be directly retrieved
from the top level agent instance.
## General checklist
<!-- Please double-check the following points and mark them like this:
[X] -->
- [X] There are no breaking changes (API, behaviour)
- [X] I have added unit and/or integration tests for my change
- [X] The tests cover both positive and negative cases
- [X] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green
- [ ] I have manually run all the unit and integration tests in the
[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)
and
[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)
modules, and they are all green
<!-- Before adding documentation and example(s) (below), please wait
until the PR is reviewed and approved. -->
- [ ] I have added/updated the
[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)
- [ ] I have added an example in the [examples
repo](https://github.com/langchain4j/langchain4j-examples) (only for
"big" features)
- [ ] I have added/updated [Spring Boot
starter(s)](https://github.com/langchain4j/langchain4j-spring) (if
applicable)
## Checklist for adding new maven module
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have added my new module in the root `pom.xml` and
`langchain4j-bom/pom.xml`
## Checklist for adding new embedding store integration
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreIT` that extends
from either `EmbeddingStoreIT` or `EmbeddingStoreWithFilteringIT`
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreRemovalIT` that
extends from `EmbeddingStoreWithRemovalIT`
## Checklist for changing existing embedding store integration
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have manually verified that the
`{NameOfIntegration}EmbeddingStore` works correctly with the data
persisted using the latest released version of LangChain4j
<!--
Thank you so much for your contribution!
Please fill in all the sections below.
Please open the PR as a draft initially. Once it is reviewed and
approved, we will ask you to add documentation and examples.
Please note that PRs with breaking changes or without tests will be
rejected.
Please note that PRs will be reviewed based on the priority of the
issues they address.
We ask for your patience. We are doing our best to review your PR as
quickly as possible.
Please refrain from pinging and asking when it will be reviewed. Thank
you for understanding!
-->
## Issue
<!-- Please specify the ID of the issue this PR is addressing. For
example: "Closes #1234" or "Fixes #1234" -->
Closes#4490
## Change
<!-- Please describe the changes you made. -->
## General checklist
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] There are no breaking changes (API, behaviour)
- [ ] I have added unit and/or integration tests for my change
- [ ] The tests cover both positive and negative cases
- [ ] I have manually run all the unit and integration tests in the
module I have added/changed, and they are all green
- [ ] I have manually run all the unit and integration tests in the
[core](https://github.com/langchain4j/langchain4j/tree/main/langchain4j-core)
and
[main](https://github.com/langchain4j/langchain4j/tree/main/langchain4j)
modules, and they are all green
<!-- Before adding documentation and example(s) (below), please wait
until the PR is reviewed and approved. -->
- [x] I have added/updated the
[documentation](https://github.com/langchain4j/langchain4j/tree/main/docs/docs)
- [ ] I have added an example in the [examples
repo](https://github.com/langchain4j/langchain4j-examples) (only for
"big" features)
- [ ] I have added/updated [Spring Boot
starter(s)](https://github.com/langchain4j/langchain4j-spring) (if
applicable)
## Checklist for adding new maven module
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have added my new module in the root `pom.xml` and
`langchain4j-bom/pom.xml`
## Checklist for adding new embedding store integration
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreIT` that extends
from either `EmbeddingStoreIT` or `EmbeddingStoreWithFilteringIT`
- [ ] I have added a `{NameOfIntegration}EmbeddingStoreRemovalIT` that
extends from `EmbeddingStoreWithRemovalIT`
## Checklist for changing existing embedding store integration
<!-- Please double-check the following points and mark them like this:
[X] -->
- [ ] I have manually verified that the
`{NameOfIntegration}EmbeddingStore` works correctly with the data
persisted using the latest released version of LangChain4j
DragonFSKY