Using Web Search with Tavily
The Quarkus LangChain4j extension supports integrating the Tavily web search engine to enrich your AI services with up-to-date external knowledge.
Web search can be used in two main ways:
-
As a tool that the language model can invoke during function calling.
-
As a content retriever inside a Retrieval-Augmented Generation (RAG) pipeline.
Getting Started
To enable Tavily, add the quarkus-langchain4j-tavily extension to your project:
./mvnw quarkus:add-extension -Dextensions="quarkus-langchain4j-tavily"
Then configure your API key:
quarkus.langchain4j.tavily.api-key=your-api-key
Inject the engine as needed:
@Inject
WebSearchEngine engine;
You can now use it directly in your application via the search method, or make it available to the LLM using tools or RAG.
Proxy and TLS
Requests to Tavily can go through a proxy from the Quarkus Proxy Registry, and use a named configuration from the Quarkus TLS Registry:
quarkus.langchain4j.tavily.proxy-configuration-name=tavily
quarkus.proxy."tavily".host=proxy.example.com
quarkus.proxy."tavily".port=3128
quarkus.langchain4j.tavily.tls-configuration-name=tavily
quarkus.tls.tavily.trust-store.p12.path=truststore.p12
quarkus.tls.tavily.trust-store.p12.password=secret
When no proxy configuration name is set, the default quarkus.proxy.* configuration is used if present.
Using Tavily as a Tool
You can expose web search to the LLM as a tool in a function calling setup. This allows the model to invoke the search when needed and incorporate the results in its response.
There are two main approaches:
-
Use the provided
dev.langchain4j.web.search.WebSearchToolfrom LangChain4j -
Implement your own tool that wraps
WebSearchEngine
Example AI service using the built-in tool:
@RegisterAiService
public interface Assistant {
@ToolBox(WebSearchTool.class)
String chat(String question);
}
For a full working example, see: chatbot-web-search sample.
Using Tavily in a RAG Pipeline
Tavily can also power content retrieval in a Retrieval-Augmented Generation (RAG) workflow. To do this, use the provided WebSearchContentRetriever in a RetrievalAugmentor.
Example:
@ApplicationScoped
public class WebSearchRetrievalAugmentor implements Supplier<RetrievalAugmentor> {
@Inject
WebSearchEngine webSearchEngine;
@Inject
ChatModel chatModel;
@Override
public RetrievalAugmentor get() {
return DefaultRetrievalAugmentor.builder()
.queryTransformer(question -> {
String query = chatModel.generate("""
Transform the user's question into a suitable search query for Tavily.
The query should yield results relevant to answering the user's question.
User's question: """ + question.text());
return Collections.singleton(Query.from(query));
})
.contentRetriever(new WebSearchContentRetriever(webSearchEngine, 10))
.build();
}
}
This approach lets you combine the strengths of LLM reasoning with up-to-date external information retrieved at runtime.
Choosing Between Tool and RAG
Use function calling when: - You want the LLM to choose when to query the web - The web search result is short and structured (e.g. 1–2 snippets)
Use RAG when: - You want to inject relevant documents into the prompt before generation - You need summarization or multi-document synthesis
Tavily Configuration Reference
Configuration property fixed at build time - All other configuration properties are overridable at runtime
Configuration property |
Type |
Default |
|---|---|---|
Base URL of the Tavily API Environment variable: |
string |
|
API key for the Tavily API Environment variable: |
string |
required |
Maximum number of results to return Environment variable: |
int |
|
The timeout duration for Tavily requests. Environment variable: |
|
|
Whether requests to Tavily should be logged Environment variable: |
boolean |
|
Whether responses from Tavily should be logged Environment variable: |
boolean |
|
The search depth to use. This can be "basic" or "advanced". Basic is the default. Environment variable: |
|
|
Include a short answer to original query. Default is false. Environment variable: |
boolean |
|
Include the cleaned and parsed HTML content of each search result. Default is false. Environment variable: |
boolean |
|
A list of domains to specifically include in the search results. By default all domains are included. Environment variable: |
list of string |
|
A list of domains to specifically exclude from the search results. By default no domains are excluded. Environment variable: |
list of string |
|
If set, the named TLS configuration with the configured name will be applied to the HTTP client used to call Tavily Environment variable: |
string |
|
The name of the Quarkus Proxy Registry configuration to use. If not set and the default proxy configuration is configured ( Environment variable: |
string |
|
About the Duration format
To write duration values, use the standard You can also use a simplified format, starting with a number:
In other cases, the simplified format is translated to the
|