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.

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.WebSearchTool from 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
`quarkus.langchain4j.tavily.base-url` Base URL of the Tavily API Environment variable: `QUARKUS_LANGCHAIN4J_TAVILY_BASE_URL`	string	`https://api.tavily.com`
`quarkus.langchain4j.tavily.api-key` API key for the Tavily API Environment variable: `QUARKUS_LANGCHAIN4J_TAVILY_API_KEY`	string	required
`quarkus.langchain4j.tavily.max-results` Maximum number of results to return Environment variable: `QUARKUS_LANGCHAIN4J_TAVILY_MAX_RESULTS`	int	`5`
`quarkus.langchain4j.tavily.timeout` The timeout duration for Tavily requests. Environment variable: `QUARKUS_LANGCHAIN4J_TAVILY_TIMEOUT`	Duration	`60S`
`quarkus.langchain4j.tavily.log-requests` Whether requests to Tavily should be logged Environment variable: `QUARKUS_LANGCHAIN4J_TAVILY_LOG_REQUESTS`	boolean	`false`
`quarkus.langchain4j.tavily.log-responses` Whether responses from Tavily should be logged Environment variable: `QUARKUS_LANGCHAIN4J_TAVILY_LOG_RESPONSES`	boolean	`false`
`quarkus.langchain4j.tavily.search-depth` The search depth to use. This can be "basic" or "advanced". Basic is the default. Environment variable: `QUARKUS_LANGCHAIN4J_TAVILY_SEARCH_DEPTH`	`basic`, `advanced`	`basic`
`quarkus.langchain4j.tavily.include-answer` Include a short answer to original query. Default is false. Environment variable: `QUARKUS_LANGCHAIN4J_TAVILY_INCLUDE_ANSWER`	boolean	`false`
`quarkus.langchain4j.tavily.include-raw-content` Include the cleaned and parsed HTML content of each search result. Default is false. Environment variable: `QUARKUS_LANGCHAIN4J_TAVILY_INCLUDE_RAW_CONTENT`	boolean	`false`
`quarkus.langchain4j.tavily.include-domains` A list of domains to specifically include in the search results. Default is [], which includes all domains. Environment variable: `QUARKUS_LANGCHAIN4J_TAVILY_INCLUDE_DOMAINS`	list of string	`[]`
`quarkus.langchain4j.tavily.exclude-domains` A list of domains to specifically exclude from the search results. Default is [], which doesn’t exclude any domains. Environment variable: `QUARKUS_LANGCHAIN4J_TAVILY_EXCLUDE_DOMAINS`	list of string	`[]`

Configuration property

Type

Default

quarkus.langchain4j.tavily.base-url

Base URL of the Tavily API

Environment variable: QUARKUS_LANGCHAIN4J_TAVILY_BASE_URL

string

https://api.tavily.com

quarkus.langchain4j.tavily.api-key

API key for the Tavily API

Environment variable: QUARKUS_LANGCHAIN4J_TAVILY_API_KEY

string