In this article, we’ll explore 3 paths:

• Calling the AI Studio API surface directly,
• Calling Gemma 4 hosted via a vLLM instance thanks to the LangChain4j bridge.
• Calling Gemma 4 locally via Ollama

With the appropriate model weights format, we’ll also be able to run Gemma 4 locally via Ollama. But that’s for another day.

1 — The Easy Case: Gemma 4 on AI Studio

If you’re using Gemma 4 via the Google AI Studio API surface, you have to use the Gemini model builder and reference the model name:

Gemini gemma4 = Gemini.builder()
    .modelName("gemma-4-31b-it")
    .apiKey(System.getenv("GEMINI_API_KEY"))
    .build();

LlmAgent agent = LlmAgent.builder()
    .model(gemma4)
    // ... instructions and tools
    .build();

Here, Gemma 4 is exposed the same way as the Gemini models, via the same API surface. That’s why the model is an instance of Gemini.

LlmAgent agent = LlmAgent.builder()
    .model("gemma-4-31b-it")
    // ... instructions and tools
    .build();

2 — Calling a vLLM hosted Gemma 4 via LangChain4j

During the beta testing period, internally at Google, my colleague Vlad was exposing the Gemma 4 model weights via vLLM, running inside a Google Cloud Run instance with GPU. And I was using his endpoint to test Gemma 4 😉

However, vLLM features an OpenAI-compatible API. So Gemma 4 on vLLM needs to be called with that API surface, not with the Gemini one.

Fortunately, with the LangChain4j bridge I developed last year, you can configure OpenAI-compatible models, thanks to the OpenAiChatModel (or the streaming variant) chat model from LangChain4j to connect to the vLLM server.

Creating a Simple Agent

First, we need to configure the OpenAiChatModel (or OpenAiStreamingChatModel):

ChatModel model = OpenAiChatModel.builder()
    .modelName("gg-hf-gg/gemma-4-31b-it")
    .apiKey("YOUR_API_KEY") // A dummy key if not required by your vLLM setup
    .baseUrl("https://your-vllm-instance/v1")
    .timeout(Duration.ofMinutes(5))
    .customParameters(
        Map.of("chat_template_kwargs", Map.of("enable_thinking", true))
    )
    .build();

Let’s have a look at a simple science teacher agent:

LlmAgent teacherAgent = LlmAgent.builder()
    .name("science-teacher")
    .model(LangChain4j.builder()
        .chatModel(model)
        .modelName("gg-hf-gg/gemma-4-31b-it")
        .build())
    .instruction("""
        You're a friendly science teacher
        who explains concepts simply.
        """)
    .build();

We use the LangChain4j.builder() to wrap the OpenAI compatible chat model as a Java class extending ADK’s BaseLlm class, which is the parent class of all LLMs supported by ADK.

Adding Tools (Local Java Functions)

Gemma 4’s reasoning capabilities shine when you add tools. You can expose any Java method as a tool using ADK’s FunctionTool.

LlmAgent orderAgent = LlmAgent.builder()
    .name("order-agent")
    .model(LangChain4j.builder()
        .chatModel(model)
        .modelName("gg-hf-gg/gemma-4-31b-it")
        .build())
    .instruction(
        "Use the `lookup_order` tool to retrieve order details.")
    .tools(FunctionTool.create(this, "retrieveOrder"))
    .build();

@Annotations.Schema(name = "lookup_order",
        description = "Retrieve order details by ID")
public Map<String, Object> retrieveOrder(String orderId) {
    // Your database logic here...
    return Map.of("status", "out_for_delivery");
}

In this example, we reference a local Java function to lookup order details, so Gemma 4 can call it should the user ask for the status of their order.

3 — Calling Gemma 4 locally via Ollama

It’s also possible to take on a third path, with Ollama’s Gemma 4 support. Thanks to the LangChain4j bridge again, you can configure Gemma 4 with the following LangChain4j chat model definition:

OllamaChatModel ollamaChatModel = OllamaChatModel.builder()
   .modelName("gemma4:e4b")
   .baseUrl("http://127.0.0.1:11434")
   .build();

Wrapping up

That’s about it for today! With ADK Java and Gemma 4, you have a powerful, flexible, and open-weight foundation for your next AI agent project! 🤖 Thanks to the LangChain4j / ADK bridge, it’s even possible to invoke Gemma via different API surfaces than Gemini’s.

What’s impressive is that I didn’t even have to leave my terminal or read documentation. The entire process was a conversation with Gemini CLI, leveraging its ability to search the web, find libraries, and even check migration guides!

The Interactive Process

I started by asking Gemini CLI about the Wikipedia API. Instead of guessing, I used the @search command to find the exact “contracts” for searching and retrieving pages.

The conversation went something like this:

1. Exploring the API: I asked @search what is the contract for the Wikipedia API to search for Wikipedia pages?. Gemini found the modern Wikimedia REST API (/search/page) and the older Action API.

   

   

   Using @search in Gemini CLI to find information about the Wikipedia API

2. Retrieving Content: I then asked how to get the actual page content. It identified the /page/html/{title} endpoint as the best way to get clean HTML.

   

   

   Gemini CLI screenshot showing the search about the full Wikipedia page retrieval

3. Finding a Converter: Since LLMs prefer Markdown over raw HTML (returned by the Wikipedia API), I searched for a Java library: @search how to render HTML to Markdown in Java?. It suggested CopyDown (a Java port of Turndown) as the simplest option.

   

   

   Gemini CLI interactive session on how to find an HTML to Markdown converter

One particularly “pro” move from Gemini: it noticed I wanted to use Jackson for JSON parsing. It proactively searched for the latest version, found that Jackson 3.0.0-rc4 was just released, and even checked the migration guide to ensure the new tools.jackson package names were used correctly!

Then, I asked Gemini CLI to use my JBang / LangChain4j MCP server creation skill to generate the code of my Wikipedia STDIO MCP server:

The Resulting Java Code

Once we had the blueprint, it triggered my jbang-mcp-server skill. It scaffolded the following JBang script, combining LangChain4j’s MCP support with our chosen libraries.

///usr/bin/env jbang "$0" "$@" ; exit $?
//DEPS dev.langchain4j:langchain4j-core:1.11.0
//DEPS dev.langchain4j:langchain4j-community-mcp-server:1.11.0-beta19
//DEPS org.slf4j:slf4j-simple:2.0.17
//DEPS io.github.furstenheim:copy_down:1.1
//DEPS tools.jackson.core:jackson-databind:3.0.0-rc4
//JAVA 21

import dev.langchain4j.agent.tool.Tool;
import dev.langchain4j.community.mcp.server.McpServer;
import dev.langchain4j.community.mcp.server.transport.StdioMcpServerTransport;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import io.github.furstenheim.CopyDown;
import tools.jackson.databind.ObjectMapper;
import tools.jackson.databind.JsonNode;
import tools.jackson.databind.json.JsonMapper;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.List;
import java.util.concurrent.CountDownLatch;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;

public class WikipediaMcpServer {

    static {
        // Configure SLF4J Simple Logger to write to System.err
        // This is crucial for MCP servers over STDIO to avoid polluting stdout
        System.setProperty("org.slf4j.simpleLogger.logFile", "System.err");
    }

    private static final Logger log = LoggerFactory.getLogger(WikipediaMcpServer.class);

    public static void main(String[] args) throws Exception {
        log.info("Starting Wikipedia MCP Server...");

        WikipediaTools tools = new WikipediaTools();
        McpServer server = new McpServer(List.of(tools));
        StdioMcpServerTransport transport = new StdioMcpServerTransport(server);

        log.info("MCP Server started successfully on STDIO.");
        new CountDownLatch(1).await();
    }

    public static class WikipediaTools {
        private final HttpClient httpClient = HttpClient.newBuilder().followRedirects(HttpClient.Redirect.NORMAL).build();
        private final ObjectMapper objectMapper = JsonMapper.builder().build();
        private final CopyDown copyDown = new CopyDown();
        private final String USER_AGENT = "WikipediaMcpServer/1.0 (contact@example.com)";

        @Tool("Search Wikipedia for a given query and return a list of matching page titles and brief descriptions. Use this to find the exact page title before retrieving content.")
        public String searchWikipedia(String query) throws Exception {
            log.info("Searching Wikipedia for: {}", query);
            String encodedQuery = URLEncoder.encode(query, StandardCharsets.UTF_8);
            String url = "https://en.wikipedia.org/w/rest.php/v1/search/page?q=" + encodedQuery + "&limit=5";

            HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create(url))
                    .header("User-Agent", USER_AGENT)
                    .GET()
                    .build();

            HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

            if (response.statusCode() != 200) {
                return "Error searching Wikipedia: " + response.statusCode() + " - " + response.body();
            }

            JsonNode rootNode = objectMapper.readTree(response.body());
            JsonNode pagesNode = rootNode.get("pages");
            StringBuilder result = new StringBuilder("Search Results:\n\n");

            if (pagesNode != null && pagesNode.isArray()) {
                for (JsonNode page : pagesNode) {
                    String title = page.has("title") ? page.get("title").asText() : "";
                    String description = page.has("description") ? page.get("description").asText() : "No description";
                    result.append("- **").append(title).append("**: ").append(description).append("\n");
                }
            }

            if (result.length() == "Search Results:\n\n".length()) {
                return "No results found for query: " + query;
            }

            return result.toString();
        }

        @Tool("Retrieve the content of a specific Wikipedia page by its exact title, converted to Markdown format. Use the exact title returned by searchWikipedia.")
        public String getWikipediaPageContent(String title) throws Exception {
            log.info("Retrieving Wikipedia page: {}", title);
            String encodedTitle = URLEncoder.encode(title.replace(" ", "_"), StandardCharsets.UTF_8);
            String url = "https://en.wikipedia.org/api/rest_v1/page/html/" + encodedTitle;

            HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create(url))
                    .header("User-Agent", USER_AGENT)
                    .GET()
                    .build();

            HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

            if (response.statusCode() != 200) {
                return "Error retrieving Wikipedia page: " + response.statusCode() + " - " + response.body();
            }

            String htmlContent = response.body();
            log.info("Converting HTML to Markdown for page: {}", title);
            return copyDown.convert(htmlContent);
        }
    }
}

I didn’t even touch the code at all, and it worked flawlessly out of the box. I would probably only update the version dependency on LangChain4j which is not up-to-date. But that’s about it.

Configuring the MCP Server in Gemini CLI

To use this server, you just need to register it in your ~/.gemini/settings.json. Gemini CLI will then automatically launch it as a child process and communicate with it over Standard Input/Output.

Add the following to your mcpServers section:

{
  "mcpServers": {
    "wikipedia-mcp": {
      "command": "jbang",
      "args": [
        "run",
        "--quiet",
        "/path/to/your/WikipediaMcpServer.java"
      ]
    }
  }
}

Once the MCP configuration is saved and Gemini CLI reloaded, I could check that the MCP server was available, by running the /mcp list command:

List of available MCP servers tools in Gemini CLI

There are 2 tools available: one for fetching a list of relevant pages, and the other to fetch the content of an individual page.

Putting it up to the test

Yesterday, the 🚀 Artemis 2 mission launched to travel around the moon 🌔 I’m sure Wikipedia is already updated with the latest information about the status of the mission. Let’s double check:

Asking about the Artemis 2 mission

It found relevant pages, then it loaded the content of those pages and found the information, and summarized its findings:

Response about the status of the Artemis 2 mission

Mission in progress! But my own personal mission over those few interactive prompts inside Gemini CLI is accomplished: in less than 5 minutes, I had my custom MCP server to query Wikipedia! And it took me actually more time to write this article itself!

Wrapping up

My winning combo of the day: Gemini CLI, agent skills, Java, JBang, and LangChain4j… and boom 💥

Maybe we’ll find that obvious in a few months, but I’m still impressed by how it is today, in just a few prompts, to create something useful like an MCP server that your friendly AI agents can use. Building tools for your AI agents has never been this fluid.

Happy hacking! 🚀 And let’s go to the 🌔 and beyond!

Screenshot of the Comic Trip app

The Comic Trip agent is a fun little application that transforms your travel photography into a vibrant, pop-art comic strip experience. Beyond the visual style, it also guesses locations (thanks to Gemini) and enriches each “panel” with nearby points of interest (via Google Maps integration).

For a recap and a demo of what this application is capable of, please check out the YouTube video:

This project is a showcase for the Agent Development Kit (ADK) for Java 1.0, demonstrating how to build multi-agent systems with:

• smart models — Gemini and 🍌 Nano Banana,
• ADK tools — 🔍 Google Search, 🗺️ Google Maps,
• ADK services — Google Cloud Storage artifact service, and
• cloud-native storage integration — Google Cloud Firestore database.

Powered by ADK for Java 1.0

ADK for Java 1.0 makes it easier to build and coordinate AI agents. In this application, I leverage several key concepts:

• App & Plugins: The entire agent hierarchy is encapsulated within an App. We use the LoggingPlugin for seamless execution observability and debugging. Via this App shell, the logging plugin is actually applied to all the sub-agents involved in the multi-agent system. No need to configure each sub-agent individually.

• Runners & Sessions: An InMemoryRunner manages the execution flow, while an InMemorySessionService ensures that the context for each user’s trip is isolated and persistent throughout the multi-step process.

• Specialized Agents: We utilize a variety of agent types, including

  • LlmAgent for LLM-based tasks,
  • SequentialAgent for step-by-step flows, and
  • ParallelAgent for running multiple agents in parallel.

Multi-Agent Architecture

The core intelligence of the Comic Trip agent is driven by the following agent hierarchy:

1. picture_analyzer_agent (Gemini 3 Flash): The entry point of our flow. It analyzes the uploaded photograph to extract a detailed description and identify the location. It’s impressive to see how good Gemini is at guessing the location of a landmark globally!

2. poi_and_comic_flow (Parallel Execution): Once the context is established, two specialized agents run in parallel:

   • comic_illustrator_agent (Gemini 3.1 Flash Image): This multimodal agent (also known as 🍌 “Nano Banana 2”) transforms the original image into a pop-art masterpiece.

   • points_of_interest_agent (Gemini 2.5 Flash): Equipped with the GoogleMapsTool, it searches for nearby attractions based on the identified location, adding depth to the travel experience.

To configure the Google Maps integration, you just need to add the .tools(new GoogleMapsTool()) call to your agent definition:

LlmAgent poiGoogleMapsAgent = LlmAgent.builder()
    .name("points_of_interest_agent")
    .model("gemini-2.5-flash")
    .instruction("""
        Given the location in:
        {description_and_location}

        Please list points of interest (POI)
        in the area no further than a kilometer away
        using the `google_maps` tool.

        Each POI should have a name and a description.

        Don't mention distances in your response.
        And don't start with introductory text for the list.
        """)
    .tools(new GoogleMapsTool())
    .outputKey(OUTPUT_KEY_POINTS_OF_INTEREST)
    .build();

The entire process is orchestrated by a SequentialAgent named main_flow, which strictly orders the initial analysis before triggering the parallel phase.

Architecture diagram of the various agents and flows

The Visuals: Multimedia Generation and Artifacts

Generating a high-quality comic panel is just the first step. ADK 1.0 handles the resulting multimedia artifacts as well.

The comic_illustrator_agent uses an afterModelCallback to intercept the generated image bytes. These bytes are then persisted using the GcsArtifactService, which automatically handles the upload to a Google Cloud Storage bucket. This integration ensures that generated media is stored and is easily accessible via public URLs (for the frontend):

gs://comic-trip-picture-bucket/comic_trip_app/comic_trip_user/{tripId}/{imageId}.png/0

The code in the callback goes through the Content and Parts to find parts that contain the generated image (in an inlineData field), and we save it as an artifact, via the saveArtifact() method of the callbackContext:

.afterModelCallback((callbackContext, llmResponse) ->
    Maybe.fromOptional(llmResponse.content()
        .flatMap(Content::parts)
        .stream()
        .flatMap(List::stream)
        .filter(part -> part.inlineData().isPresent())
        .findFirst()
        .flatMap(part -> {
            String imageId = generateId();
            callbackContext.saveArtifact(imageId + ".png", part)
                .blockingAwait();

            return Optional.of(llmResponse.toBuilder()
                .content(Content.fromParts(Part.fromText(imageId)))
                .build());
        }))

Backend Architecture: Quarkus & Cloud Services

The application’s web backend is built with the Quarkus framework, and deployed on Google Cloud Run. It also serves the frontend assets.

When a user uploads a batch of images, the MissionControlResource receives the multipart request. To ensure maximum throughput, it uses Java 21 Virtual Threads to run the ComicTripAnalyzer agent for each image in parallel.

While the images live in GCS, the trip’s metadata and enriched details (descriptions, POIs, and image links) are stored in Google Cloud Firestore. This saving action is also triggered at the web controller level, once all the agents have run through each image to process.

Frontend: Vibe-Coded with Stitch and Antigravity

The user interface of the Comic Trip agent was designed by Google Stitch and implemented using Antigravity.

Screenshot of the Stich user interface where the frontend was designed

The frontend interacts with the backend via a simple REST API. Images are sent as multipart/form-data, and the backend returns a comprehensive JSON response, after reading the metadata from Firestore. The frontend then dynamically renders the “Comic Strip” view, pulling the comic-styled illustrations directly from the GCS bucket URLs.

What’s next?

The Comic Trip app shows that you can build sophisticated, multi-agent tools without having to worry about low-level state or orchestration. ADK for Java 1.0 handles the plumbing, so you can focus on defining how your agents behave and what tools they use.

If you’re ready to start building:

• Poke around the source code for Comic Trip.
• Check out the video for a deep dive into ADK 1.0 features.
• Read the official announcement for more context.
• Grab the Maven template to bootstrap your own agent.

Happy building! 🤖

And of course, if you’re a Java developer like me, you can do all that in Java!

In this article, we’ll learn how to create our own songs and clips with the Lyria 3 model, in Java, using my Gemini Interactions API Java SDK.

GeminiInteractionsClient client = GeminiInteractionsClient.builder()
       .apiKey(System.getenv("GEMINI_API_KEY"))
       .build();

Clip vs. Pro: The Models

Lyria 3 comes in two primary flavors:

• lyria-3-clip-preview — Perfect for generating short clips (30 second long), snippets, or quick iterations for sound effects, choruses, and jingles.
• lyria-3-pro-preview — Fully capable of generating long, structurally cohesive, full-length songs (up to 3 minutes).

Here’s an example of firing off a request for a full-length song using the SDK:

ModelInteractionParams request = ModelInteractionParams.builder()
    .model("models/lyria-3-pro-preview")
    .input("""
        Write a full length epic power metal song
        about a brave knight fighting a dragon.
        It should have a guitar solo.
        """)
    .responseModalities(
        Interaction.Modality.AUDIO,
        Interaction.Modality.TEXT)
    .build();

Interaction interaction = client.create(request);

In addition to the MP3, Lyria also generated the following lyrics:

[[A0]]
[[B1]]
[16.0:] Cold mountain peaks in the morning haze,
[:] The knight rides forth through the silver maze,
[:] With steel in hand and a heart of fire,
[:] To face the beast and the burning pyre.
[:] Through ancient gates where the shadows sleep,
[:] He finds the path to the valley deep,
[:] No fear of death in his iron soul,
[:] He seeks the fire and the final goal.
[[C2]]
[48.0:] Upon the wind comes the dragon’s breath!
[:] A storm of flame and a dance of death!
[:] Oh, carry the flame on the steel of the knight!
[:] Into the dragon, into the light!
[:] The world will tremble as titans collide!
[:] Nowhere for the ancient beast to hide!
[:] Into the light!
[[B3]]
[80.0:] The claws of iron and teeth of obsidian,
[:] A mountain of scales in the dark stygian,
[:] The sword strikes home but the sparks do fly,
[:] Underneath the heavy sulfur sky.
[:] A roar that echoes through the mountain hall,
[:] The knight stands steady, he will not fall,
[:] Through smoke and cinders the legend grows,
[:] He strikes the heart where the furnace glows!
[[C4]]
[112.0:] Upon the wind comes the dragon’s breath!
[:] A storm of flame and a dance of death!
[:] Oh, carry the flame on the steel of the knight!
[:] Into the dragon, into the light!
[:] The world will tremble as titans collide!
[:] Nowhere for the ancient beast to hide!
[:] Into the light!
[[A5]]
[[B6]]
[160.0:] The wings are broken, the fire is out,
[:] The knight is standing amidst the doubt,
[:] A savior's light in the dark of the cave,
[:] To the halls of legend, he’s wise and brave.
[[D7]]
[176.0:] The legend remains. Forevermore!
[:] (Forevermore!)

MP3 Decoding and Dual Modalities

One of the coolest features of the Interactions API is the ability to request multiple Response Modalities. Notice the responseModalities parameter in the code snippet above? By requesting both AUDIO and TEXT, the API will return:

1. Text: The actual lyrics generated and the structural breakdown of the song.
2. Audio: The music itself natively encoded as an MP3 file.

Because of the API’s MP3 formatting return type, you don’t need to do any complex WAV header manipulation or PCM decoding. You can safely extract the returned bytes from the payload and push them directly onto disks as an .mp3 file:

interaction.outputs().stream()
    .filter(output -> output instanceof AudioContent)
    .map(output -> (AudioContent) output)
    .findFirst()
    .ifPresent(audio ->
        Files.write(Paths.get("song.mp3"), audio.data()));

Prompt Constraints

The Lyria 3 model is highly receptive to prompting constraints. Depending on what you pass into the text input, here are four major ways to dictate the song output:

1. Give it Lyrics

You don’t have to rely on the model inventing lyrics. If you have written your own song, you can literally paste the lyrics into the prompt:

ModelInteractionParams request = ModelInteractionParams.builder()
    .model("models/lyria-3-clip-preview")
    .input("""
        An uplifting song with guitar riffs about nano banana.
        The lyrics should be:
          Yellow peel, a tiny sweet,
          The Nano Banana, a tropical treat.
          But wait—it hums, it starts to create,
          Switching into AI mode...
        """)
    .responseModalities(
        Interaction.Modality.AUDIO,
        Interaction.Modality.TEXT)
    .build();

Interaction interaction = client.create(request);

2. Control the Structure

You can instruct the model on song composition layout by using bracketed metadata such as [Intro], [Verse], [Chorus], and [Outro].

ModelInteractionParams request = ModelInteractionParams.builder()
    .model("models/lyria-3-clip-preview")
    .input("""
        [Intro] Calm piano music setting a sunset scene on the beach
        [Verse] Epic rock ballad as the storm rages.
        [Outro] Opera with choir as the sun reappears
                again through the black clouds.
        """)
    .responseModalities(
        Interaction.Modality.AUDIO,
        Interaction.Modality.TEXT)
    .build();

Interaction interaction = client.create(request);

3. Instrumental Only

If you aren’t looking for lyrics or vocals, simply instruct the model that the track should be instrumental. It excels at generating ambient background loops!

ModelInteractionParams request = ModelInteractionParams.builder()
    .model("models/lyria-3-clip-preview")
    .input("""
        Create a looping meditation music that feels like the wind.
        Instrumental only.
        """)
    .responseModalities(Interaction.Modality.AUDIO)
    .build();

Interaction interaction = client.create(request);

4. Give it a Picture for Inspiration!

Since Lyria 3 is a multimodal model, not only can it accept a prompt in input, but you can also pass images to drive its generative inspiration:

// picture of a groceries list which will drive the lyrics
byte[] imageBytes = URI.create(
    "https://storage.googleapis.com/generativeai-downloads/images/groceries.jpeg")
    .toURL()
    .openStream()
    .readAllBytes();

ModelInteractionParams request = ModelInteractionParams.builder()
    .model("models/lyria-3-clip-preview")
    .input(
        new TextContent("""
            An epic song with opera voices about this quest.
            Deep synths and a speeding up tempo.
            """),
        new ImageContent(imageBytes, "image/jpeg")
    )
    .responseModalities(
        Interaction.Modality.AUDIO,
        Interaction.Modality.TEXT)
    .build();

Interaction interaction = client.create(request);

Wrap Up

Adding music generation to Java applications or AI agents is easier than ever with the Interactions API and Lyria 3. I highly recommend taking a look at the newly added test cases over in the LyriaTest.java class within the SDK repository to see the full setup in action.

Happy prompting & rocking! 🎸

I wrote JsonSpotter to handle this. It’s a small Java library that finds and extracts JSON-like structures from any text, even if the JSON itself is a bit messy. Then, you can use a lenient JSON parser like Jackson 3 to parse the extracted JSON to work with proper type-safe Java objects, instead of text or maps of lists of maps of… more basic types.

Why not just use Regex?

You could try indexOf("{") or a regular expression, but those break quickly. Nested objects, extra braces in the conversational text, or complex arrays make string manipulation a nightmare.

JsonSpotter uses a recursive descent parser. It actually understands the structure it’s looking for. It doesn’t just find brackets; it validates the object or array boundaries structurally as it scans. By doing so, it can accurately find the longest well-balanced JSON-like structure in the text, ensuring that nested objects are handled correctly and that it doesn’t get tripped up by random braces in the conversational text.

Handling “lenient” JSON

Sometimes LLMs output what I call “human-friendly” JSON. They don’t always output strict and valid JSON. They can add comments to explain fields, add an ellipsis to omit parts of the content, or leave trailing commas. By default, standard libraries like Jackson or Gson will throw an error immediately when they see a // comment or a trailing ,.

JsonSpotter is built to be lenient during extraction. It recognizes:

• Single and multi-line comments (//, /* */, #)
• Unquoted keys and single-quoted strings
• Trailing commas
• Non-standard numbers like .5 or NaN

Once JsonSpotter extracts the raw string, you can pass it to a proper JSON parser configured for leniency (i.e. being tolerant to malformed JSON content).

A quick example

First, extract the JSON from your LLM response:

String rawText = "..."; // Text returned by your LLM
String jsonString = JsonSpotter.extractJson(rawText);

Then, parse it with something like Jackson 3 (which has great support for lenient features):

import tools.jackson.databind.json.JsonMapper;
import tools.jackson.core.json.JsonReadFeature;

JsonMapper mapper = JsonMapper.builder()
    .enable(JsonReadFeature.ALLOW_JAVA_COMMENTS)
    .enable(JsonReadFeature.ALLOW_TRAILING_COMMA)
    .enable(JsonReadFeature.ALLOW_SINGLE_QUOTES)
    .enable(JsonReadFeature.ALLOW_UNQUOTED_PROPERTY_NAMES)
    .build();

MyClass myObj =  mapper.readValue(jsonString, MyClass.class);
// or
JsonNode node = mapper.readTree(jsonString);

Get it

JsonSpotter is dependency-free and available on Maven Central.

Add the dependency to your pom.xml:

<dependency>
    <groupId>io.github.glaforge.jsonspotter</groupId>
    <artifactId>jsonspotter</artifactId>
    <version>0.1.2</version>
</dependency>

Or your build.gradle:

dependencies {
    implementation("io.github.glaforge.jsonspotter:jsonspotter:0.1.2")
}

Give it a try and let me know what you think on GitHub if you find it useful.

A site called tropes.fyi tracks these patterns. It lists the exact words and structures that give AI away. You’ll see callouts for overused adverbs like “deeply” and “arguably,” the dreaded “delve” family, and structural crutches like “It’s not X, it’s Y.”

I wanted a way to automatically fix these issues in my own generated text. So, I built a deslopify skill for Gemini CLI.

How I built it

Gemini CLI has a built-in skill-creator that handles the boilerplate. I just asked the CLI to create a new skill, and it generated the folder structure and a SKILL.md file. It took as reference the Markdown file shared by tropes.fyi with all the typical elements of AI sloppiness.

The SKILL.md file tells the agent how to behave. I wrote a short workflow instructing the agent to read the user’s text, cross-reference it with the anti-patterns from tropes.fyi, and rewrite it. The goal is just to make the text sound like a normal person wrote it.

Here’s what the skill generated by Gemini CLI looks like:

deslopify generated skill

The structure of the skill is just this SKILL.md file, and a references/ directory containing the style guide:

deslopify/
├── SKILL.md
└── references/
      └── style_guide.md

I didn’t even have to modify the generated SKILL.md as it did the job perfectly, and was clear out of the box.

Trying it out

The code is up on GitHub: glaforge/deslopify.

You can install it directly from the repo in Gemini CLI:

gemini skills install https://github.com/glaforge/deslopify

Installing the deslopify skill within Gemini CLI

Then reload your interactive session:

/skills reload

Once it’s loaded, you can ask Gemini CLI (or your preferred agent tool) to clean up your text:

• "Deslopify this article: [URL]"
• "Naturalize this draft: [paste text]"
• "Remove the AI slop from my README.md file."

The agent will strip out the pompous phrasing and weird structural tics, leaving you with something far more readable.

I wanted a way to build these servers in Java without the heavy boilerplate of a traditional Maven or Gradle project, or with a complex framework. The solution? Combining JBang, LangChain4j, and… 🥁… a custom Gemini CLI skill!

In this post, I’ll walk you through how I streamlined the creation of MCP STDIO servers, by creating an agent SKILL.md to replicate what I had learned in my previous article.

The Recap: JBang and LangChain4j

In that article I wrote recently, JBang was perfect for writing and running self-contained Java scripts. It automatically handles dependencies and JVM execution, making it perfect for lightweight MCP servers. No need for a directory structure, for build files, or pre-compilation.

LangChain4j’s recent release provided the langchain4j-community-mcp-server module, which allows you to create STDIO MCP servers, without the need for a server framework. By simply annotating a method of a Java class with @Tool, we can expose some useful tool to an LLM.

But to create and install a new MCP server, I had to do a fair bit of copy and paste, and a bit of scaffolding. That’s how I came up with the 💡 idea of creating an agent skill to simplify this task!

Step 1 — Automating with a Skill for Gemini CLI

Instead of writing the boilerplate manually every time, I first created a custom Gemini CLI skill (jbang-mcp-server.skill). To do this efficiently, I leveraged Gemini CLI’s own skill-creator skill, which is designed to bootstrap new capabilities for the agent.

Requesting a SKILL.md Creation by Gemini CLI’s Skill Creator

I fed the skill creator the whole article mentioned above, and it produced the following SKILL.md file to act as a specialized “generator” for automating the repetitive parts of building and installing Java-based MCP servers:

---
name: jbang-mcp-server
description: Scaffolds and installs zero boilerplate Java-based MCP STDIO servers using JBang and LangChain4j for Gemini CLI. Use this to quickly bootstrap an MCP server from scratch.
---

# JBang LangChain4j MCP Server Creator

This skill helps quickly scaffold a new Java-based MCP STDIO server using JBang and LangChain4j, and installs it into Gemini CLI's `settings.json`.

## Process

1.  **Ask User for Details:**
    *   Desired file name (e.g., `McpToolServer.java`) and path to save it.
    *   The name of the server to register in `~/.gemini/settings.json` (e.g., `java-calc`).
    *   (Optional) High-level description of the tools they want to add initially.

2.  **Scaffold the Server:**
    *   Read the template file located at `assets/McpServerTemplate.java` using the `read_file` tool. Note that the path to `assets/McpServerTemplate.java` needs to be resolved relative to the skill directory or read from the skill's bundled assets. As an alternative if the absolute path is unknown, directly write out the template contents described below.
    *   Replace `{SERVER_CLASS_NAME}` with the base name of the requested Java file (e.g., `McpToolServer` if file is `McpToolServer.java`).
    *   Replace `{TOOL_CLASS_NAME}` with a related name (e.g., `MyTools`).
    *   (Optional) Modify the `@Tool` annotated methods to reflect the user's requirements.
    *   Write the finalized content to the user's requested path using the `write_file` tool.
    *   Make the file executable using `chmod +x <path_to_file>` via `run_shell_command`.

3.  **Verify the Server:**
    *   Run jbang build <path_to_file> using the run_shell_command tool to check for any compilation errors.
    *   If there are compilation errors, use the `replace_tool` to fix them.
    *   Repeat the compilation check until successful.

4.  **Install the Server in Gemini CLI:**
    *   Read `~/.gemini/settings.json`.
    *   Use the `replace` tool or jq via `run_shell_command` to inject a new entry under `mcpServers`.
    *   The new entry should look like this:
        ```json
        "{server_name}": {
          "command": "jbang",
          "args": [
            "run",
            "--quiet",
            "{absolute_path_to_java_file}"
          ]
        }
        ```
    *   Inform the user that the server has been created and configured, and remind them that Gemini CLI automatically reloads configurations.

## Template Backup
If `assets/McpServerTemplate.java` cannot be read, use this template:
```java
///usr/bin/env jbang "$0" "$@" ; exit $?
//DEPS dev.langchain4j:langchain4j-core:1.11.0
//DEPS dev.langchain4j:langchain4j-community-mcp-server:1.11.0-beta19
//DEPS org.slf4j:slf4j-simple:2.0.17
//JAVA 21

import dev.langchain4j.agent.tool.Tool;
import dev.langchain4j.community.mcp.server.McpServer;
import dev.langchain4j.community.mcp.server.transport.StdioMcpServerTransport;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.util.List;
import java.util.concurrent.CountDownLatch;

public class {SERVER_CLASS_NAME} {

    static {
        // Configure SLF4J Simple Logger to write to System.err
        // This is crucial for MCP servers over STDIO to avoid polluting stdout
        System.setProperty("org.slf4j.simpleLogger.logFile", "System.err");
    }

    private static final Logger log = LoggerFactory.getLogger({SERVER_CLASS_NAME}.class);

    public static void main(String[] args) throws Exception {
        log.info("Starting LangChain4j MCP Server...");

        // Instantiate tools
        {TOOL_CLASS_NAME} tools = new {TOOL_CLASS_NAME}();

        // Create Server
        McpServer server = new McpServer(List.of(tools));

        // Start Transport
        StdioMcpServerTransport transport = new StdioMcpServerTransport(server);

        log.info("MCP Server started successfully on STDIO.");

        // Keep Alive
        new CountDownLatch(1).await();
    }

    // --- Tool Definition ---
    public static class {TOOL_CLASS_NAME} {

        @Tool("Description of your tool")
        public String sampleTool(String input) {
            log.info("Called sampleTool with {}", input);
            return "Processed: " + input;
        }
    }
}

Along the way, Gemini CLI asked me a few questions, like how to name the skill, the Java class, etc. And of course, it also asked me for permission to create that skill:

Gemini CLI asked for Permission to Create a Skill

Once installed, I could check that the skill was available in my Gemini CLI session:

Gemini CLI Skills List

Here is how the skill works and why it’s useful:

Zero-Boilerplate Scaffolding

When triggered, the skill creates a standalone Java file that is immediately ready to run as a script. It automatically includes:

• JBang Directives: //DEPS and //JAVA lines so you don’t need a pom.xml or build.gradle.
• MCP Server Setup: The boilerplate code required to initialize the McpServer and connect it to a StdioMcpServerTransport.
• Critical Logging Configuration: It includes a static block that redirects all SLF4J logs to System.err. This is vital for MCP STDIO servers because logging to System.out would corrupt the JSON-RPC messages used to talk to the AI.

Automatic Registration

One of the most tedious parts of adding an MCP server is editing the ~/.gemini/settings.json file manually. This skill handles that automatically:

• It calculates the absolute path to your new Java file.
• It injects a new entry into the mcpServers section of your configuration.
• It sets up the jbang run --quiet command so Gemini CLI knows exactly how to start your server.

Rapid Tool Development

The skill provides a template with a sample @Tool. This means you can go from “I want a new tool” to “I have a working tool” in seconds by just naming the server and then having the AI modifying the logic inside the newly generated Java class.

With this skill installed, bootstrapping a new MCP server takes seconds rather than minutes.

Step 2 — Building the “File Tree” Tool

Using our new skill, to take it for a ride, I scaffolded a server named TreeMcpServer.java. My goal was to create a tool that the LLM could use to inspect the local file system structure.

I let Gemini CLI implement a FileTreeTools class with a tree method. This method takes a directory path and uses Java’s java.nio.file API to recursively build a string representation of the directory tree (limiting the depth to prevent massive outputs).

@Tool("Displays a tree of the local directories and files in the specified path")
public String tree(String pathStr) {
    // ... directory traversal logic ...
}

Step 3 — Troubleshooting the Build

I hit a small snag during development. When I first asked Gemini CLI to show the file tree, it couldn’t connect to the tool. This was actually due to a compilation error.

To debug, I asked Gemini CLI to run a compilation check using JBang: jbang build TreeMcpServer.java. This immediately highlighted the issue: I had some unclosed string literals in the generated Java code where newline characters were literally inserted instead of escaped.

Using the Gemini CLI’s replace tool, I quickly fixed the string literals. But what was interesting with this issue is that I was able to ask Gemini CLI to update the SKILL.md to double check that the generated code compiled properly. This allowed me to improve the skill to be more rock-solid!

/skills reload

The Result

With the compilation issues resolved, the Gemini CLI immediately recognized the newly registered file-tree MCP server. When asked to “Show me a file tree of the current directory,” the CLI autonomously invoked our Java tool:

Gemini CLI MCP Tool Call Approval

…and returned a clean, formatted representation of the workspace directly in the chat:

Gemini CLI MCP Tool Result

This workflow — using an AI assistant to build a skill, which in turn builds a tool that extends the assistant itself — is a powerful demonstration of how quickly we can iterate and expand our development capabilities using standard Java tools like JBang and LangChain4j.

Conclusion

Agent skills are a powerful way to automate boring, repetitive work. Instead of manually scaffolding boilerplate code every time you want to create a new MCP server (or any other task), you can delegate that task to an AI agent — and then automatically package what you learned into a reusable skill that you can even share with others.

What’s particularly interesting is how the Gemini CLI agent creation skill works as a bridge between exploration and automation. During my interactive session with Gemini CLI, I experimented with building MCP servers, discovered the patterns, and hit challenges that I solved on the fly.

Rather than keeping that knowledge locked in chat history, the agent creation skill let me capture and summarize everything I had learned — the best practices, the gotchas, the template structure — into a single, reusable SKILL.md file.

Now, what took me a session of trial-and-error can be replicated instantly by anyone (or by future me) with a single skill invocation.

As a Java developer, you might be wondering: How can I easily and quickly run my own MCP servers?

On this blog, I’ve explained how to develop MCP servers with Quarkus and Micronaut. But thanks to a recent community contribution to LangChain4j, and the simplicity of JBang, building a local MCP server in Java is even easier and with zero boilerplate.

In this post, we’ll build a standalone Java MCP server that runs over STDIO, perfect for local integration with tools like the Gemini CLI or other locally running agentic tools supporting MCP servers.

The Stack: Why This Matters

To keep things lightweight, we’re using two powerful tools:

1. LangChain4j: The leading framework for building AI-powered Java applications. It now includes a dedicated MCP server module for the STDIO protocol (in addition to the existing MCP client module.)
2. JBang: A tool that lets you run Java files as scripts. No pom.xml, no Gradle builds, just a single .java file with your dependencies declared right at the top.

The Code: A Standalone MCP Server

Here is a complete, runnable MCP server in a single Java file. This server exposes a “Calculator” tool to any MCP-compatible LLM.

No build file, no project directory structure or anything. Just a single Java file.

///usr/bin/env jbang "$0" "$@" ; exit $?
//DEPS dev.langchain4j:langchain4j-core:1.11.0
//DEPS dev.langchain4j:langchain4j-community-mcp-server:1.11.0-beta19
//DEPS org.slf4j:slf4j-simple:2.0.17
//JAVA 21

import dev.langchain4j.agent.tool.Tool;
import dev.langchain4j.community.mcp.server.McpServer;
import dev.langchain4j.community.mcp.server.transport.StdioMcpServerTransport;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.util.List;
import java.util.concurrent.CountDownLatch;

public class McpToolServer {

    static {
        // Important: Redirect logs to System.err
        System.setProperty("org.slf4j.simpleLogger.logFile",
                           "System.err");
    }

    private static final Logger log =
            LoggerFactory.getLogger(McpToolServer.class);

    public static void main(String[] args) throws Exception {
        log.info("Starting LangChain4j MCP Server...");

        // 1. Define your tools
        CalculatorTools tools = new CalculatorTools();

        // 2. Wrap them in an McpServer
        McpServer server = new McpServer(List.of(tools));

        // 3. Connect to the STDIO transport
        StdioMcpServerTransport transport =
                new StdioMcpServerTransport(server);

        log.info("MCP Server started successfully on STDIO.");

        // Keep the script alive
        new CountDownLatch(1).await();
    }

    // Define MCP tools
    public static class CalculatorTools {
        @Tool("Calculates the sum of two numbers")
        public double add(double a, double b) {
            log.info("Called add({}, {})", a, b);
            return a + b;
        }

        @Tool("Calculates the square root of a number")
        public double sqrt(double x) {
            log.info("Called sqrt({})", x);
            return Math.sqrt(x);
        }
    }
}

Breaking It Down

• JBang Directives: The //DEPS lines at the top handle all your dependencies. When you run this file, JBang downloads everything automatically (like Groovy’s @Grab annotation).
• The @Tool Annotation: Any public method annotated with LangChain4j’s @Tool annotation is automatically converted into a JSON-RPC tool specification that the LLM can understand.
• StdioMcpServerTransport: Most local MCP clients communicate via Standard Input/Output. This transport layer handles the JSON-RPC handshake for you.

The “Secret Sauce”: Logging to System.err

There is one critical rule for MCP servers running over STDIO: System.out is for communication ONLY.

I could have reduced the size of the example above almost by half by removing all the logging code. But it’s important to highlight it, if you want to be able to somehow log information along the way.

The MCP protocol uses stdout to send JSON-RPC messages back and forth. If your application (or a library) prints a generic INFO: Hello World to stdout, it will corrupt the JSON stream and crash the connection.

That’s why we use this static block:

static {
    System.setProperty("org.slf4j.simpleLogger.logFile", "System.err");
}

By forcing all logs to stderr, we keep the communication channel clean while still being able to see our logs in the terminal.

Testing Your Server

Before you plug it into an LLM, you can test it using the MCP Inspector. It’s a handy web UI that lets you see exactly what’s happening under the hood.

Run your server with the following command:

npx @modelcontextprotocol/inspector jbang run --quiet McpToolServer.java

Once the inspector is running, you can click to connect to the server, list the tools, select a tool, all in your browser, and watch your Java code execute in real-time.

Running it in Gemini CLI

To let Gemini use your new tool, add it to your ~/.gemini/settings.json:

{
  "mcpServers": {
    "java-calc": {
      "command": "jbang",
      "args": ["run", "--quiet", "/path/to/McpToolServer.java"]
    }
  }
}

Now, when you ask Gemini “What is the square root of 144?”, it will reach out to your JBang script, execute the Java method, and give you the answer.

Well… maybe it won’t call the tool because the LLM already knows the answer to such a simple question 😃 thanks to its training data and understanding of simple math, but for more specific and complex tools, it should be called! In my case, it actually figured out it should call it. And the response seems correct to me 😃

Wrapping Up

Building MCP servers doesn’t have to be complex. With LangChain4j and JBang, you get the best of both worlds: the power of the Java ecosystem with the agility of a scripting language!

So next time you need to give an LLM access to a legacy Java library or a complex calculation, remember: you’re only one @Tool annotation away.

Java developers can be as agile as all the script kiddies! Happy MCP server coding!

In RAG, the quality of your generation (when an LLM crafts its answer based on search results) is only as good as your retrieval (the actually retrieved search results).

While vector search (semantic) and keyword search (BM25) each have their strengths, combining them often yields the best results. That’s what we often call Hybrid Search: combining two search techniques or the results of different searches with slight variations.

But how do you meaningfully combine a cosine similarity score of 0.85 (from vector search) with a BM25 score of 12.4? Those values are on two distinct unrelated scales!

Enter Reciprocal Rank Fusion (RRF).

I vibe-coded a little RRF simulator that shows how two lists of documents are ranked into one. For the impatient, feel free to go ahead and play with it, otherwise, you’ll find more information at the bottom of this article on how to use this simulator.

What is RRF?

RRF is a robust, “zero-shot” algorithm for merging search results from different retrieval methods. The technique was formally introduced by Gordon V. Cormack and his colleagues in their 2009 SIGIR paper, “Reciprocal Rank Fusion outperforms Condorcet and individual Rank Learning Methods”.

Instead of trying to somehow normalize arbitrary scores, RRF ignores the scores entirely and focuses on rank.

It operates on a simple premise: Documents that appear at the top of multiple lists are likely the most relevant. In their research, the authors found that RRF consistently outperformed individual search systems and more complex fusion methods, providing a stable and scalable way to combine diverse ranking signals.

The Formula Simplified

The RRF score for a document is calculated as:

• $\text{rank}(r, d)$ : The position of the document in a specific search result list (1st, 2nd, etc.).
• $k$ : A smoothing constant, typically set to 60.

Why is $k$ so important?

Think of $k$ as a “balance” dial.

• If $k$ is low (e.g., 1): The formula gives a massive advantage to the top-ranked items. This configuration favors Precision — trusting that the absolute top results are correct and allowing a single high-performing retriever to dominate.
• If $k$ is high (e.g., 60): The advantage of being #1 shrinks. This configuration improves Recall and Consensus. It ensures that even if the “perfect” result is buried at rank #10 across multiple lists, it will still rise to the top.

Why use 60? By setting $k=60$ (the industry standard), RRF prioritizes consensus over individual outliers. It ensures that a document appearing consistently (e.g., ranked #10 in both keyword and vector search) will score higher than a document that is #1 in only one list but completely missing from the others.

It rewards documents that multiple algorithms agree on, rather than letting a single outlier dominate the results.

Why Use RRF in RAG?

1. Normalization Free: You don’t need to know the distribution of your vector or BM25 scores. RRF works purely on position.
2. Scalability: It’s extremely efficient for sharded, billion-scale indices where global score normalization is expensive.
3. Candidate Selection: RRF is an excellent “first stage” reranker. A common pattern is to retrieve the top 100 documents via RRF, and then use a more expensive (but precise) Cross-Encoder (a reranker model) to rank the top 10 for the LLM context window (see below more for details).

The Two-Stage Architecture: RRF + Cross-Encoder

While RRF is excellent at merging lists, it lacks deep semantic understanding of the query-document relationship. This is where Cross-Encoders shine — models like BERT that score the actual interaction between query and text. However, they are computationally expensive and slow.

The industry standard pattern is a “Two-Stage” architecture:

1. Stage 1 (Candidate Selection): Use Hybrid Search (Vector + Keyword) fused with RRF to retrieve a broad pool of candidates (e.g., top 100). This ensures high Recall — the right answer is likely somewhere in this list.
2. Stage 2 (Precision Reranking): Pass only these top 100 candidates to a Cross-Encoder. The model re-scores them based on deep relevance, picking the absolute best 5-10 chunks for the LLM’s context window.

This pipeline gives you the best of both worlds: the speed and breadth of RRF with the precision of a Cross-Encoder.

Going Further: RAG-Fusion

RAG-Fusion takes the hybrid approach a step further. This technique was introduced by Zackary Rackauckas in the 2024 paper, “RAG-Fusion: a New Take on Retrieval-Augmented Generation”. It uses an LLM to generate multiple variations of the user’s original query to “broaden the net” and find relevant context that a single query might miss.

The process follows a clever loop:

1. Multi-Query Generation: An LLM generates 3-5 different versions of the user’s query (e.g., synonyms, rephrasings, or breaking down a complex question).
2. Parallel Retrieval: Each variation is sent to the search engine (both Vector and Keyword).
3. RRF Aggregation: All resulting lists are fused using RRF.

By using RRF to merge results from multiple query variations, the system naturally filters out “topic drift.” Documents that appear consistently across many query variants rise to the top, while noise from a single poor query variation is pushed down. This “consensus” approach significantly reduces hallucination rates by ensuring the LLM is provided with content validated by multiple search angles.

RRF in the Wild: LangChain4j

RRF isn’t just a theoretical concept; it’s a standard component in modern AI stacks. LangChain4j, the popular Java library for building LLM-powered applications, uses RRF as its default mechanism for aggregating results from multiple sources.

The DefaultContentAggregator class in LangChain4j employs a ReciprocalRankFuser to merge ranked lists of content. This means if you configure a RAG pipeline with multiple retrievers (e.g., one for recent web data and one for internal documents), LangChain4j automatically applies RRF to give you the best of both worlds without any manual tuning.

Here is how you can set up a hybrid retrieval system in LangChain4j that implicitly uses RRF:

// 1. Define your retrievers
ContentRetriever bm25Retriever = ...;

ContentRetriever vectorSearchRetriever =
    EmbeddingStoreContentRetriever.builder()
        .embeddingStore(embeddingStore)
        .embeddingModel(embeddingModel)
        .maxResults(10)
        .build();

// 2. Combine them in the RetrievalAugmentor
// DefaultRetrievalAugmentor uses
// DefaultContentAggregator which uses RRF
RetrievalAugmentor retrievalAugmentor =
    DefaultRetrievalAugmentor.builder()
        .contentRetriever(bm25Retriever)
        .contentRetriever(vectorSearchRetriever)
        .build();

// 3. Configure the augmentor on the AI service
Assistant assistant = AiServices.builder(Assistant.class)
    ...
    .retrievalAugmentor(retrievalAugmentor)
    .build();

By simply adding multiple retrievers, the DefaultContentAggregator kicks in, calculating the $\frac{1}{k + \text{rank}}$ score for every item found by either retriever and re-sorting them into a single, high-quality context for your LLM.

Try the Simulator

To truly understand how the smoothing constant $k$ impacts rankings and how different lists merge, I’ve built a Reciprocal Rank Fusion Simulator.

You can experiment with different document rankings and see the fusion math in real-time here: 👉 Launch RRF Simulator

Use this tool to visualize how RRF balances precision (favoring top ranks) vs. consensus (favoring agreement across lists) and tune your intuition for hybrid search architectures.

• Interactive Rank Experimentation: Create new lists, add/remove documents, shuffle the lists, etc. Use drag-and-drop to reorder results in two independent search engines. Since RRF ignores raw scores and focuses only on position, you can see exactly how moving a document up or down one list impacts its final “fused” standing.
• Visualizing Consensus: The simulation demonstrates RRF’s “consensus” logic, indeed documents that appear in both lists (even at mediocre ranks) often outperform documents that rank #1 in only one list. This highlights why hybrid search is so effective.
• Real-Time Parameter Tuning: By adjusting the $k$ constant, you can see how the algorithm’s sensitivity changes. You’ll observe how a lower prioritizes “top-heavy” results, while a higher gives more weight to documents found deeper in the search results.

Summary

I hope this article helped you get a better intuition of Reciprocal Rank Fusion, why it’s so useful, and how it works! By focusing on rank rather than arbitrary scores, RRF provides a robust and scalable way to merge diverse search results, making it a cornerstone of modern hybrid search and advanced RAG architectures.

How do I use my API key without leaking it to the browser?

In this post (although vibe-coding is supposed to be all about not looking at the code at all) we’ll dissect exactly how this architecture works, why it’s safer than a client-side key, and where its security limits lie.

The Problem: Client-Side Keys

When building an app with a React, Vue, or vanilla JS frontend that talks to an AI model, the path of least resistance would often be:

// ❌ DANGEROUS: Do not do this in production
const API_KEY = "AIzaSy...";
const genAI = new GoogleGenerativeAI(API_KEY);

The moment you deploy this, your API key is visible in the browser’s “Network” tab of the Dev tools, or by inspecting the JavaScript source. A malicious actor can grab your key and use your quota for their own projects, potentially racking up bills or exhausting your limits.

Scary illustration of a person on his computer horrified to discover on his screen that his LLM tokens have been consumed because of a leaked API key

The Solution: The “Transparent” Proxy

💡 Google AI Studio’s exported starter code uses a Node.js proxy server combined with Service Workers to hide the key while letting you write frontend code as if you were calling the API directly.

The classical approach is to have your frontend call your backend code, and it’s only your backend code that has access to the API key. Here, the approach taken by AI Studio for Cloud Run deployment is to let developers continue to write frontend code as usual, calling the generative AI API as if it were a direct call from the frontend… But in reality, the call is intercepted and proxied to a server backend that takes care of making the real call to the AI model, and handle the API key on the backend, without ever exposing it.

Part 1: The Server

The heart of the system is an Express.js server (server/server.js). It serves your frontend files but also listens on a special endpoint: /api-proxy.

When a request hits this endpoint, the server:

1. Injects the API Key: It takes the key from a secure environment variable on the server-side (GEMINI_API_KEY).
2. Forwards the Request: It sends the modified request to Google’s real API (generativelanguage.googleapis.com).
3. Streams the Response: It pipes the answer back to your browser.

Here is the critical logic in server.js where the key is added:

// server/server.js

// ... inside the /api-proxy route handler ...

// Prepare headers for the outgoing request
const outgoingHeaders = {};

// Copy most headers from the incoming request (content-type, etc.)
// ... (code to copy headers) ...

// 🔐 KEY INJECTION HAPPENS HERE
outgoingHeaders['X-Goog-Api-Key'] = process.env.GEMINI_API_KEY;

const axiosConfig = {
    method: req.method,
    url: `https://generativelanguage.googleapis.com/${targetPath}`,
    headers: outgoingHeaders,
    // ...
};

// Forward the request to Google
const apiResponse = await axios(axiosConfig);

The frontend never receives the key. It only receives the results of the API call.

Part 2: Client-Side Interception

If you look at the frontend code (e.g., in App.tsx), you might see standard calls to the Gemini API (usually it’s implemented in a dedicated services/geminiService.ts file):

// Frontend code looks like it's calling Google directly!
const model = genAI.getGenerativeModel({
  model: "gemini-3-flash-preview",
  temperaturecontents: {...}
});
const result = await model.generateContent(prompt);

How does this work if the frontend doesn’t have the key?

The server injects two scripts into your index.html at runtime:

1. websocket-interceptor.js
2. service-worker.js

The Service Worker

The service-worker.js acts like a network traffic cop inside your browser. It monitors all outgoing fetch requests. If it sees a request headed for generativelanguage.googleapis.com, it stops it and redirects it to your local server instead.

// server/public/service-worker.js

const TARGET_URL_PREFIX = 'https://generativelanguage.googleapis.com';

self.addEventListener('fetch', (event) => {
  const requestUrl = event.request.url;

  if (requestUrl.startsWith(TARGET_URL_PREFIX)) {
    // ✋ Stop! Don't go to Google directly.
    // 👉 Go to our local proxy instead.
    const remainingPath = requestUrl.substring(TARGET_URL_PREFIX.length);
    const proxyUrl = `${self.location.origin}/api-proxy${remainingPath}`;

    // Forward the request to /api-proxy
    event.respondWith(fetch(new Request(proxyUrl, { ... })));
  }
});

This “transparent” redirection means you don’t have to change your frontend code to point to http://localhost:3000/api-proxy. You just write standard SDK code, and the Service Worker handles the routing.

The WebSocket Interceptor

For streaming features or chat, the Gemini API uses WebSockets. Service Workers cannot easily intercept WebSocket connections, so the solution uses a different trick: Monkey Patching.

The websocket-interceptor.js overwrites the global browser WebSocket constructor.

// server/public/websocket-interceptor.js

const originalWebSocket = window.WebSocket;

window.WebSocket = new Proxy(originalWebSocket, {
  construct(target, args) {
    let [url, protocols] = args;

    // Check if the connection is destined for Gemini
    if (url.includes('generativelanguage.googleapis.com')) {
       // Redirect to our local proxy endpoint
       url = url.replace('wss://generativelanguage.googleapis.com',
                         `wss://${window.location.host}/api-proxy`);
    }

    // Create the WebSocket with the new URL
    return new originalWebSocket(url, protocols);
  }
});

Security Reality Check

Is this secure? Yes and No.

✅ The Good: Credential Protection

This architecture successfully hides the “Secret String” (your API Key), as if you had written your own backened server.

• It is not in the JavaScript bundle.
• It is not in the network traffic (except between your server and Google).
• A user cannot “copy-paste” your key to use in their own unrelated backend script.

⚠️ The Bad: The “Open Proxy” Risk

Because the server is a “dumb pipe” — it blindly signs any request sent to /api-proxy. A malicious user on your site can still abuse your quota, by opening Chrome DevTools and running:

// This will be intercepted by the Service Worker and proxied!
fetch('https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent', {
    method: 'POST',
    body: JSON.stringify({ contents: [{ parts: [{ text: "Generate 5000 words of spam..." }] }] })
})

Your server will happily stamp this request with your API key and send it to Google.

🛡️ The Mitigation: Rate Limiting

The AI Studio team anticipated this. The generated server includes Rate Limiting to prevent a single user from draining your quota instantly.

// server/server.js

const proxyLimiter = rateLimit({
    windowMs: 15 * 60 * 1000, // 15 minutes
    max: 100, // Limit each IP to 100 requests per window
    message: 'Too many requests from this IP...'
});

app.use('/api-proxy', proxyLimiter);

This ensures that while a user can make requests via your proxy, they are capped at a lower speed (e.g., 100 requests per 15 minutes, but that might still be a bit too much!)

Conclusion

I’ve always been curious to understand how Google AI Studio was protecting the Gemini API key, although the code appeared to directly make use of the API key on the frontend. But the (real) code that is actually deployed on Cloud Run is pretty smart, making use of some interesting tricks to not expose the key, and to mitigate the abuse of your quota.

The Google AI Studio proxy server is a nice piece of engineering for prototyping and demos. It allows for a “serverless-feeling” frontend development experience while adhering to the basic security rule of keeping API keys on the server.

However, for a production application, you should eventually replace this generic proxy with specific backend endpoints (e.g., /api/generate-recipe, /api/chat-response) that:

1. Validate user input (“Is this actually a recipe request?”).
2. Authenticate the user (“Is this user logged in?”).
3. Apply strict business logic before calling the Gemini API.

Even if Google AI Studio protects your API key to some extent, your quota can still be exhausted by a malicious user. So if you’re exposing such an application to the public, ask AI Studio to either add authentication, or to request the user to pass their own API key. Or even both!

I hope you found this exploration interesting!

New Image Generation Models (Gemini 2.5 & 3.0 Preview, aka 🍌 Nano Banana)

There’s a new GoogleAiGeminiImageModel class which allows text-to-image generation and image editing using the latest 🍌 Nano Banana models.

Supported Models:

• gemini-2.5-flash-image (Nano Banana): Optimized for speed.
• gemini-3-pro-image-preview (Nano Banana Pro): High-fidelity, up to 4K resolution.

Features:

• Text-to-Image: Generate images from prompts.
• Image Editing: Edit existing images using text prompts (with optional mask support).
• Search Grounding: Ground image generation in Google Search results.

Text-to-Image Generation

var imageModel = GoogleAiGeminiImageModel.builder()
    .apiKey(System.getenv("GEMINI_API_KEY"))
    .modelName("gemini-2.5-flash-image")
    .aspectRatio("16:9")
    .imageSize("2K")
    .build();

Response<Image> response = imageModel.generate(
        "A cinematic shot of a futuristic city at sunset");

// Save the generated image to a file
Image image = response.content();
byte[] imageBytes = Base64.getDecoder().decode(image.base64Data());
Files.write(Paths.get("output.png"), imageBytes);

As you can see, different configuration parameters are possible;

• aspectRatio: among 16:9, 4:3, 3:2, 1:1, 2:3, 3:4, and 9:16
• imageSize: among 1K, 2K, 4K

Image Generation with Google Search Grounding

A powerful capability of Nano Banana Pro is the ability to ground its image generation in Google Search results, with the useGoogleSearchGrounding(true) flag.

It’s a model that’s able to search for image references on the web, or for the latest information about a topic.

var groundedModel = GoogleAiGeminiImageModel.builder()
    .apiKey(System.getenv("GEMINI_API_KEY"))
    .modelName("gemini-3-pro-image-preview") // search only in Pro
    .useGoogleSearchGrounding(true)
    .aspectRatio("1:1")
    .build();

Response<Image> groundedResponse = groundedModel.generate("""
    A kawaii illustration of the current weather forecast for Paris
    showing the current temperature (in Celsius)
    """);

Here, we want to create a kawaii illustration of the current weather in Paris. So Nano Banana Pro is going to search on Google to find about the weather forecast at this point in time!

At the time of this writing, the forecast is:

A Kawaii illustration of a little cloud and sun characters indicating a temperature of 13°C in Paris

Pretty kawaii, right? 😃

Google Maps Grounding

You can now enable Google Maps grounding to allow the model to access real-world location data, including place IDs, addresses, and reviews.

var chatModel = GoogleAiGeminiChatModel.builder()
    .apiKey(System.getenv("GEMINI_API_KEY"))
    .modelName("gemini-2.5-flash")
    .allowGoogleMaps(true) // Enable Google Maps tool
    .retrieveGoogleMapsWidgetToken(true) // Optional: UI widget
    .build();

String response = chatModel.chat(
    "Find the best restaurant near the Eiffel tower");

Gemini might answer something along the lines of this (with details coming from Maps, as star rating proves, not from its training knowledge):

For a memorable dining experience near the Eiffel Tower, several highly-rated restaurants offer a range of cuisines and atmospheres.

French Cuisine with a View: For an exceptional meal with stunning views, consider Jules Verne, an elegant restaurant located within the Eiffel Tower itself, boasting a 4.5-star rating. Another option is Francette, a refined restaurant on a barge on the Seine, also with a 4.5-star rating and direct views of the tower.

Café de l’Homme is a stylish bistro in the Musée de l’Homme, featuring outdoor tables with Eiffel Tower views and a 4.1-star rating.

Top-Rated French Bistros: If a classic French bistro is more your style, De la Tour is a popular family-run establishment with a 4.8-star rating. Arnaud Nicolas, known for its artfully presented tasting menus, has a 4.7-star rating. With a 4.8-star rating, Milagro is another excellent choice. Also highly rated is Le CasseNoix, a charming, retro spot with a 4.7-star rating.

Italian Options: If you’re in the mood for Italian food, Chez Pippo is a cozy trattoria with a 4.6-star rating. La Casa di Alfio is another popular choice with a 4.5-star rating. With a 4.7-star rating, In Casa is also nearby. And Pink Mamma has an impressive 4.7-star rating with over 45,000 reviews.

Google Search Grounding

Standard text generation can now be grounded using Google Search, ensuring responses are based on up-to-date web information.

var chatModel = GoogleAiGeminiChatModel.builder()
    .apiKey(System.getenv("GEMINI_API_KEY"))
    .modelName("gemini-3-flash-preview")
    .allowGoogleSearch(true) // Enable Google Search tool
    .build();

String response = chatModel.chat(
    "What are the latest models from OpenAI, Anthropic, and Google?");

URL Context Tool

This feature allows the model to access and use information directly from specific URLs provided in the prompt context.

var chatModel = GoogleAiGeminiChatModel.builder()
    .apiKey(System.getenv("GEMINI_API_KEY"))
    .modelName("gemini-3-flash-preview")
    .allowUrlContext(true) // Enable URL Context tool
    .build();

// The model can now fetch and reason
// over content from URLs in the prompt
String response = chatModel.chat("""
    Check Guillaume Laforge's blog archive at
    https://glaforge.dev/archive/
    and tell me how many articles he wrote in January 2026
    """);

Suffice to have URLs in your prompt. No need to fetch or scrape the content yourself ahead of making the LLM call.

Multimodal Agents (Image Generation)

AiServices now supports returning generated images directly, enabling the creation of multimodal agents that can produce visual content.

interface CreativeAssistant {
    @UserMessage("Generate a high-quality image of {{description}}")
    ImageContent generateArtwork(@V("description") String description);
}

CreativeAssistant assistant = AiServices
    .builder(CreativeAssistant.class)
    .chatModel(GoogleAiGeminiChatModel.builder()
        .apiKey(System.getenv("GEMINI_API_KEY"))
        .modelName("gemini-3-pro-image-preview")
        .build())
    .build();

ImageContent artwork = assistant.generateArtwork(
    "a cyberpunk street food stall");

Then you can retrieve the image via artwork.image().base64data() and save it.

Gemini 3.0 Thinking Configuration

You can configure the “thinking” process (Chain-of-Thought) for Gemini 3.0 models, allowing you to control the depth of reasoning.

Thinking levels available: MINIMAL, LOW, MEDIUM, HIGH.

var thinkingModel = GoogleAiGeminiChatModel.builder()
    .apiKey(System.getenv("GEMINI_API_KEY"))
    .modelName("gemini-3-flash-preview")
    .sendThinking(true)   // Send thinking process to the model
    .returnThinking(true) // Return thought process in the response
    .thinkingConfig(GeminiThinkingConfig.builder()
        .thinkingLevel(GeminiThinkingLevel.HIGH) // Reasoning depth
        .build())
    .build();

String response = thinkingModel.chat(
    "Solve this complex logic puzzle...");

Enhanced Metadata & Token Usage

Responses from both Chat and Image models now include richer metadata, including detailed token usage and grounding source information (e.g., which web pages or map locations were used).

ChatResponse response = chatModel.chat(request);

// Cast to the Gemini specific response type
// to get access to the metadata provided by Gemini
GoogleAiGeminiChatResponseMetadata metadata =
        (GoogleAiGeminiChatResponseMetadata) response.metadata();

// Access Grounding Metadata
if (metadata.groundingMetadata() != null) {
    metadata.groundingMetadata()
        .groundingChunks().forEach(chunk -> {
            if (chunk.web() != null) {
                System.out.println("Source: " +
                    chunk.web().title() + " (" +
                    chunk.web().uri() + ")");
            }
        });
}

Summary

These Gemini-related enhancements in LangChain4j 1.11.0 further expand the capabilities of the Gemini integration.

From advanced image generation and editing with Nano Banana (Gemini 2.5 and 3.0 Preview) to powerful grounding features with Google Search and Google Maps, developers can now build more intelligent and context-aware applications.

The introduction of the URL Context tool, multimodal agents, and configurable thinking processes for Gemini 3.0 allow for richer interactions and more precise control over model behavior.

The improved metadata and token usage reporting also provide valuable insights for optimizing and understanding model responses.

Have fun with Gemini!

Everything is distilled in that article: Implementing Webhooks, not as trivial as it may seem

It likely took me a full week to dive deep into this subject, finding sources and experimenting with design patterns myself. But nowadays, AI makes it easier to dive deeper into topics, explore unfamiliar aspects, and share findings with your team.

As I built a research agent based on Google’s Deep Research agent, I wanted to see how far it’d go with a topic I had covered a while ago.

Armed with my custom research agent (via the Javelit frontend I built around it), I entered the query: Webhook best practices for rock solid and resilient deployments.

Gemini 3 Flash gave me a list of topics associated with that theme, and I selected the following ones:

• Cryptographic signature verification using HMAC-SHA256
• Implementing idempotency keys to prevent duplicate event processing
• Asynchronous processing architectures using message queues and background workers
• Preventing replay attacks with timestamp validation and nonces
• Retry strategies using exponential backoff with jitter
• Dead letter queue (DLQ) implementation and management for failed deliveries
• Security through Mutual TLS (mTLS) and IP allowlisting
• Webhook payload versioning and backward compatibility strategies
• Handling high-volume event bursts with rate limiting and buffering
• Circuit breaker patterns to protect downstream services from failure
• Schema validation and data minimization in webhook payloads

There’s significant overlap with the topics I covered in my old presentation! I talked about idempotency, signatures, dead-letter queues, IP allowlisting, rate limiting & buffering, etc. This validates my previous findings and shows that today’s generative AI capabilities can identify the same key topics.

So I let Deep Research explore those topics. After a few minutes, my agent wrote a long report in a concise style (I used prompts to steer the report generation toward concise writing and avoid “AI Slop”). Then Gemini 3 Pro created a summary, and Nano Banana Pro generated a sketchnote illustration.

Let’s start with the illustration (the same you saw as the banner for this post):

Infographics

I have a special prompt to generate such sketchnotes, which I find readable, and appealing to share on social media:

Create a hand-drawn and hand-written sketchnote style
summary infographic, with a pure white background,
use fluo highlighters for the key points,
about the following information: ...

And I pass the summary generated by Gemini 3 Pro below.

Summary

The summary is generated via this prompt, passing the entire research:

Create a concise summary of the research below.
Go straight to the summary; don't introduce it
(don't write "Here's a summary..." or equivalent).

For this research on Webhooks, here’s what the summary was. The summary’s structure also guided the organization of the sketchnote above:

Webhooks facilitate real-time, event-driven communication between systems but require a defensive architecture to ensure security, reliability, and scalability. Unlike polling, webhooks utilize a “push” model, necessitating robust handling of network partitions, malicious activity, and traffic spikes.

Security and Authentication Security implementation must go beyond obscured URLs. The industry standard involves HMAC-SHA256 signature verification to ensure payload integrity and authenticity. Critical implementation details include using constant-time string comparisons to prevent timing attacks and validating raw, unparsed payloads. To prevent replay attacks, systems should enforce timestamp tolerance windows and utilize nonces. While Mutual TLS (mTLS) offers a higher security standard for zero-trust environments, it introduces significant complexity compared to signatures and IP allowlisting.

Reliability and Architecture Because webhooks typically guarantee “at-least-once” delivery, receivers must implement idempotency using unique event keys and atomic storage to prevent duplicate processing from corrupting data. To handle high throughput and avoid timeouts, architectures should be asynchronous: an ingestion layer should immediately acknowledge requests (returning 202 Accepted) and offload the payload to a message queue for background processing by workers.

Failure Handling and Recovery Robust systems employ exponential backoff with jitter for retries to prevent “thundering herd” scenarios that could overwhelm the receiver. Messages that fail all retry attempts should be routed to a Dead Letter Queue (DLQ) for inspection and potential redrive rather than being discarded. Additionally, circuit breakers are essential to pause delivery to failing endpoints, protecting the infrastructure from cascading failures during outages.

Scalability and Payload Design To manage bursty traffic, providers should enforce rate limiting and buffering. Payload design involves a trade-off between “Fat” payloads (full state, convenient but larger attack surface) and “Thin” payloads (notifications only, secure but require callback API calls). Best practices suggest keeping payloads under 20kb, minimizing PII, and utilizing additive versioning per event type to maintain backward compatibility.

Even just the summary, as is, is already valuable when researching a subject, as it gives you all the key pointers to go further.

Generating a Slide Deck

I delivered my Webhook talk at a handful of conferences in Europe. And of course, I needed a slide deck! I often spend significant time on my decks, as I want them to be polished, clear, and beautiful. Usually, I try to reduce the amount of text in favor of visual representations like diagrams and photographic illustrations.

Right, so I have a report and an infographic, but what about the deck? My agent doesn’t (yet?) handle that, so instead, I turned to NotebookLM, gave it my research, and asked it to generate a slide deck with a particular design:

A slide deck for a technical audience, describing all the best practices to implement rock solid resilient webhooks. Opt for a blueprint architectural style, with illustrations.

And it complied, generating the following deck, which I could see myself presenting:

The style is consistent across the deck and quite beautiful. I usually put less text on slides, but it works here. Under the hood, NotebookLM uses 🍌 Nano Banana Pro (aka Gemini 3 Pro Image), and the included graphics look spot on, sharp, and accurate. I didn’t even spot typos in the generated text.

Going Further: Should I share those?

More and more I use AI in my work, but I still prefer writing my articles by hand. I can use generative AI to do a first draft, explain a piece of code, or come up with a conclusion. I also use image generation to create either illustrations or sketchnotes. But otherwise, it’s still me. My writing, my design, my style, my authentic voice.

What I’m wondering though is what to do with such research reports. I run such reports to explore a particular topic, to avoid forgetting some key angle or aspect. But I usually keep that research for me (sometimes saved inside my Obsidian vault, or as Google Docs here and there)

This week, I had a nice lunch with a couple old friends who were thinking that it was worth sharing those reports more widely, rather than keeping them private (one of my friend was sharing his research publicly in a GitHub repository.)

On the one hand, I don’t want to increase the quantity of AI slop available on the internet, but on the other hand, once they’re generated, it’s sad to see all those tokens wasted, and benefiting me exclusively! I would clearly label them as AI generated research reports or similar though, but maybe others would find those useful and interesting?

I’d be curious to hear your thoughts on this! Don’t hesitate to share them with me on social media.

Generative AI, assisted with agents that do targeted web searches, really changes the game in terms of research. Tools like NotebookLM are able to find the right sources of information, and can generate all sorts of artifacts and visualisations (audio and video podcasts, mindmaps, infographics, quizes, etc.) And image models like 🍌 Nano Banana are incredible and able to generate very clear visuals. This is really an interesting era to learn more about any topics, and at a much greater depth than scouring your favorite search engine manually! Deep Research and NotebookLM give you the URLs of the sources, so you can double check the accuracy of the reference material.

For the curious, here’s the full research report below, that my agent crafted about rock-solid webhooks:

This guide will walk you through setting up Gemini CLI as a custom agent in IntelliJ IDEA.

Prerequisites

• IntelliJ IDEA (or other JetBrains IDEs) version 2025.3 or later.
• Node.js installed (version 20+ recommended), needed by Gemini CLI.
• Gemini CLI installed.

Step 1: Install Gemini CLI

If you haven’t already, install the Gemini CLI globally using npm:

npm install -g @google/gemini-cli

Once installed, verify it works by running:

gemini --version

Step 2: Locate the Gemini Executable

You need the absolute path to the installed gemini executable for the configuration file.

On macOS / Linux: Run the following command in your terminal:

which gemini

Example output: /Users/username/.nvm/versions/node/v22.16.0/bin/gemini

On Windows: Run the following command in Command Prompt or PowerShell:

where gemini

Example output: C:\ Program Files\nodejs\gemini.cmd (or similar inside AppData)

Step 3: Configure the ACP Agent

JetBrains IDEs look for a specific JSON configuration file to load external agents. You need to create or edit this file.

File Location:

• macOS / Linux: ~/.jetbrains/acp.json
• Windows: %USERPROFILE%\.jetbrains\acp.json

Configuration Content:

Create the file (if it doesn’t exist) and add the following JSON content. Paste the path you found in Step 2 into the "command" field.

{
  "agent_servers": {
    "Gemini CLI": {
      "command": "/path/to/your/gemini",
      "args": [
        "--experimental-acp"
      ],
      "use_idea_mcp": true,
      "use_custom_mcp": true
    }
  }
}

Configuration Breakdown:

• "Gemini CLI": This is the display name you will see in the IDE.
• "command": The absolute path to the Gemini executable.
• "args": We pass --experimental-acp to tell Gemini to start in Agent Communication Protocol mode. You can also pass other flags supported by Gemini, for example for forcing a particular Gemini model version, etc.
• "use_idea_mcp": true: This is crucial. It allows Gemini to access the IDE’s built-in Model Context Protocol (MCP) server, giving it context about your open files, project structure, and more.
• "use_custom_mcp": true: Allows Gemini to use any other custom MCP servers you might have configured in the IDE.

Step 4: Restart and Connect

1. Restart your IntelliJ IDEA to load the new configuration.
2. Open the AI Assistant tool window (usually on the right side).
3. Look for the Agent Selector. It might be a dropdown menu at the top of the chat or a “More” (…) menu.
4. Select “Gemini CLI” from the list.

In the AI Chat window, you should see something like this:

Select Gemini CLI from that drop-down menu. And you’re good to go!

Usage

Once selected, you can chat with Gemini just like the default AI assistant, but with the added capabilities of the CLI!

• Context Awareness: It knows about your project files via the IDE’s MCP.
• Tool Use: It can perform actions defined in the CLI’s toolset.

Troubleshooting

• Agent not appearing? Double-check the path in acp.json. If you use nvm (Node Version Manager), ensure the path points to the specific version currently in use, not a generic alias that might not be available to the IDE’s environment.
• Permissions: On macOS/Linux, ensure the file ~/.jetbrains/acp.json is readable by your user.
• Experimental Flag: Ensure you didn’t forget the --experimental-acp argument; otherwise, the CLI will try to launch in interactive terminal mode and hang.

The Research Pipeline: From Query to Infographic

• First, the user enters the subject of the research.
• A button action triggers the research of possible topics about that subject (ie. the different possible facets or angles of the subject), using Gemini 3 Flash with Google Search activated.
• The user selects the facets they’re interested in, to restrict the research to only those aspects.
• Then the Deep Research agent kicks in, via the Gemini Interactions API, and spends a few minutes researching the topic.
• Once the final report is ready, Gemini 3 Pro creates a solid summary.
• The summary is used to generate a sketchnote with Nano Banana Pro.

A Look at the User Interface

Let’s say, as a user, I want to research information about the OpenClaw / MoltBot / ClawdBot personal AI assistant (unless it has again changed its name? 😃)

With Javelit, the code looks like this:

// The main title
Jt.title("🔎 Deep Research Agent").use();

// A header
Jt.header("Subject").use();

// The form containing the text area and submit buttons
var formSubject = Jt.form().key("form_subject").use();
String subject = Jt.textArea("Subject")
        .key("subject")
        .placeholder("Enter the subject you want to research...")
        .use(formSubject);

// The buttons (submit and clear) are inside 2 columns on a row
var columns = Jt.columns(2).widths(List.of(0.9, 0.1)).use(formSubject);

// I clear the state if the user clicks the clear button
Jt.formSubmitButton("Clear All").onClick(b -> {
    Jt.setComponentState("subject", "");
    Jt.sessionState().remove("topics");
}).use(columns.col(1));

// We proceed with the next steps
// if the user clicks the exploration button
Jt.formSubmitButton("Explore Topics").type("primary").onClick(b -> {
    Jt.sessionState().remove("topics");
}).use(columns.col(0));

1. Topic Exploration (Gemini 3 Flash)

Then, I click on Explore Topics to find the various facets of that story. Looks like Gemini 3 Flash is thinking, and is actively searching for the most up-to-date information on Google Search:

Indeed, I created a model interaction invoking Gemini 3 directly, and requesting to return a structured output (an array of strings), containing the different facets of the subject:

ModelInteractionParams planParams = ModelInteractionParams.builder()
        .model("gemini-3-flash-preview")
        .input(String.format("""
                Find a list of topics to research
                on the following subject:
                %s
                """, state.subject))
        .responseFormat(GSchema.fromClass(String[].class))
        .tools(new GoogleSearch())
        .store(true)
        .build();

Interaction planInteraction = client.create(planParams);

In terms of UI, as the UI elements are rendered synchronously, as the code is being executed, we can define placeholder elements that will receive future components:

// A header
Jt.header("Topics").use();

// The form containing the text area and submit buttons
var formTopics = Jt.form().key("form_topics").use();

// An "empty" container to hold an info bubble and the future topics
var topicsContainer =
        Jt.empty().key("topics_container").use(formTopics);
Jt.info("Preparing topics...").icon(":hourglass:")
        .use(topicsContainer);

In the above, the Jt.empty() component receives the Jt.info() bubble. But once the list of facets is returned by the model interaction, the info bubble will be replaced by a list of checkboxes with the topics to select:

var topicSelectionContainer =
        Jt.container().key("topics").use(topicsContainer);

List<String> selectedTopics = topics.stream()
        .filter(topic ->
            Jt.checkbox(topic).use(topicSelectionContainer))
        .toList();

Jt.formSubmitButton("Launch Research").type("primary").use(formTopics);

if (selectedTopics.isEmpty()) {
    // wait for user to select topics and hit form submit button
    return;
}

Gemini 3 found a good list of facets. Let me select the ones I’m the most interested in:

2. The Deep Dive (Deep Research Pro)

Now when I click the Launch Research button, the Deep Research agent is actively working:

In this part of the interface, you’ll notice the use of tabs, to separate the full report, the summary, and the infographic. This is achieved with the Jt.tabs() component.

// A header
Jt.header("Report").use();

// The 3 tabs
var tabLabels = List.of("Full Report", "Summary", "Infographic");
var tabs = Jt.tabs(tabLabels).use();

// Each tab has a placeholder
var reportPlaceholder =
        Jt.empty().key("fullReport").use(tabs.tab(tabLabels.get(0)));
var summaryPlaceholder =
        Jt.empty().key("summary").use(tabs.tab(tabLabels.get(1)));
var infographicPlaceholder =
        Jt.empty().key("infographic").use(tabs.tab(tabLabels.get(2)));

// The placeholders are info bubbles,
// soon replaced by the report, summary, and infographic
Jt.info("Preparing full report...")
        .icon(":hourglass:")
        .use(reportPlaceholder);
Jt.info("Preparing summary...")
        .icon(":hourglass:")
        .use(summaryPlaceholder);
Jt.info("Preparing infographic...")
        .icon(":hourglass:")
        .use(infographicPlaceholder);

As the research and thinking progress, Deep Research shares its thoughts and current actions with me (the info bubbles being replaced by the thoughts and actions):

It’s important to pause to see how the thoughts are streamed in real time.

Let’s have a look at the agent interaction definition:

AgentInteractionParams researchParams =
    AgentInteractionParams.builder()
        .agent("deep-research-pro-preview-12-2025")
        .input(String.format("""
            Write a concise research report on the following subject:
            <subject>
            %s
            </subject>

            By focusing on the following topics:
            <topics>
            %s
            </topics>
            """,
            subject, topicsList))
        .background(true)
        .stream(true)
        .agentConfig(
                new DeepResearchAgentConfig(ThinkingSummaries.AUTO))
        .store(true)
        .build();

The important bits here are:

• background(true) to state it’s a background operation that can take time to complete.
• stream(true) to state it should be streamed in real time.
• And .agentConfig(new DeepResearchAgentConfig(ThinkingSummaries.AUTO)) says that thoughts should be sent as they occur.

The part taking care of the streaming is the stream() method on the agent interaction:

client.stream(researchParams).forEach(event -> {
    if (event instanceof ContentDelta delta) {
        if (delta.delta() instanceof ThoughtSummaryDelta thought) {
            if (thought.content() instanceof TextContent textContent) {
                Jt.markdown(textContent.text()).use(reportPlaceholder);
            }
        } else if (delta.delta() instanceof TextDelta textPart) {
            reportBuilder.append(textPart.text());
            Jt.markdown(reportBuilder.toString())
                    .use(reportPlaceholder);
        }
    // ...

The client is receiving thoughts, but it’s also later going to receive the report in the stream. So as soon as thoughts or pieces of the report arrive, they are reflected in the UI of our research agent.

And after a little while (from one to six minutes or so) the final report is ready:

3. Synthesis (Gemini 3 Pro)

But I can go straight to the TL;DR, because Gemini 3 Pro will have prepared a high-level summary of the report:

The summary is prepared by a call to Gemini 3 Pro:

ModelInteractionParams summaryParams = ModelInteractionParams.builder()
    .model("gemini-3-pro-preview")
    .input(String.format("""
        Create a concise summary of the research below.
        Go straight with the summary, don't introduce the summary
        (don't write "Here's a summary..." or equivalent).

        %s
        """, reportBuilder))
    .store(true)
    .build();

4. Visualizing with Infographics (Gemini 3 Pro Image)

Thanks to the talent of 🍌 Nano Banana Pro:

For generating the image, we just pass the summary to the model:

var infographicParams = ModelInteractionParams.builder()
    .model("gemini-3-pro-image-preview")
    .input(String.format("""
        Create a hand-drawn and hand-written sketchnote
        style summary infographic, with a pure white background,
        use fluorescent highlighters for the key points,
        about the following information:

        %s
        """, summaryText))
    .responseModalities(Interaction.Modality.IMAGE)
    .build();

Whipping up the UI with Javelit

What makes this research frontend interesting isn’t just the AI logic with the Gemini Interactions API, it’s how quickly you’re able to whip up a functional web UI for it using Javelit, without the hassle of a complicated web framework.

The Rendering Loop Philosophy

The core of Javelit is its rendering loop. You provide a lambda that describes your UI (or a main method when running with the javelit command). Every time an interaction occurs (a button click, a checkbox toggle…) it re-executes the UI code from top to bottom.

As Cyril de Catheu (the creator of Javelit) would put it, it’s a bit like a video game loop. A state update triggers a repaint. But contrary to video games, catching input and state updates is done automatically by the Javelit components, and the repaint isn’t flying at 60fps, but only when there’s a UI interaction. Because the code runs top-to-bottom, you don’t need to manage complex event listeners or manual DOM updates.

Conclusion

By combining the power of specialized Gemini models and agents with the Gemini Interactions API (and my Java SDK for it) with the rapid UI development of Javelit, I was able to build a sophisticated research tool, taking advantage of the powerful Deep Research agent, in a fraction of the time it would take with a traditional frontend stack.

The ability to stream thoughts from the Deep Research agent directly into a reactive Javelit container makes the whole experience feel “alive” and transparent.

And everything in Java… No Python was harmed in this exercise! 😃

This project allows you to create AI-driven automation, pipelines, and autonomous bots using mere Markdown text files. You can find the project on GitHub at https://github.com/glaforge/gcli-mdrun.

Quick Start

Imagine a file named weather.md:

#!/usr/bin/env gemini-run
Use only the Google Search tool to find the answer to the question below:
What is the weather like in Paris right now?

Run it like any other script:

chmod +x weather.md
./weather.md

And you’d get something like:

I will search for the current weather in Paris.
The current weather in Paris is cloudy with a temperature of 7 °C.
Humidity is at 84%. Wind is blowing from the Southeast at 11 km/h.
There is currently no precipitation.

The prompt (below the shebang line) is actually executed by Gemini CLI.

How to Install

To get started, you need the gemini-run wrapper script from the gcli-mdrun epository.

1. Download the script: You can find it in the scripts/ directory of the repo.
2. Install it: Make it executable and move it to your system path.

chmod +x gemini-run
sudo mv gemini-run /usr/local/bin/

Usage & Features

YOLO Mode (Autonomous Execution, aka Live Dangerously)

By using the Gemini CLI --yolo flag in the shebang of your markdown scripts, Gemini will execute tools and commands automatically without asking for confirmation.

#!/usr/bin/env -S gemini-run --yolo
List all files in the current directory and rename any file
with a '.txt' extension to have a '.bak' extension instead.

Piping and Pipelines

Because gemini-run supports stdin, you can chain multiple markdown scripts together or mix them with standard Unix tools.

cat customers.log | ./step1_extract.md | ./step2_analyze.md

And also redirect their outputs to files, with >.

Real-World Examples

Here are some cool things you can do with gcli-mdrun (look at those 3 examples from the repo:

1. Automated Release Notes (git-log-summary.md)

This script analyzes your recent git commits (in the git project in the current folder) a nd generates structured release notes. It uses the run_shell_command tool to fetch git logs and diffs (using the git command).

I won’t copy the whole script here as it’s a bit too long, but I’d like just to show you the shebang line:

#!/usr/bin/env -S gemini-run --model gemini-2.5-flash --allowed-tools=run_shell_command(git)

Gemini CLI allows you to specify which tools to allow or forbid, which MCP servers to use or restrict, etc. Here, I only allowed the execution of the git command via Gemini CLI’s run_shell_command tool.

For example, I applied the script to my gcli-mdrun repository and got this (after piping the output to the glow Markdown highlighter):

Release notes for gcli-mdrun

2. Intelligent Search (google-search.md)

Leverage the power of Google Search directly from your Markdown scripts. This example fetches real-time information from the web, requesting the weather forecast for Paris:

#!/usr/bin/env -S gemini-run --allowed-tools=google_web_search,web_fetch

Use Google Search to find the answer to the question below.
Don't use any other tools.

What is the weather currently Paris?
(be sure to use international units exclusively)

3. Visual Summaries with Nano Banana (nano-banana.md)

This is where it gets really creative. You can use the nanobanana MCP server or Nano Banana Gemini CLI extension to generate infographics and mindmaps from articles or search results.

For example, I ran it against one of my recent articles:

#!/usr/bin/env -S gemini-run --allowed-mcp-server-names=nanobanana

* Find the key points of the article at
  https://glaforge.dev/posts/2026/01/03/building-a-research-assistant-with-the-interactions-api-in-java/
* Make a sketchnote mindmap of the article, with pure white background.
  Use highlighters to stress important keywords, and colored thick arrows for each section.
* Display this infographic

And it generated this beautiful sketchnote mindmap:

Sketchnote mindmap of building a research assistant

4. Chaining Search and Graphics (nano-banana-chain.md)

You can even pipe the output of a search script into a graphics script. For instance, getting the weather in Paris from the Google Search script we’ve already seen, and immediately generating a kawaii-style infographic of it by piping the weather output to a 🍌 Nano Banana script…

☁️ And then you can get a super-cute output like this one to illustrate the weather! ☀️

Infographic of current weather in Paris

Conclusion

gcli-mdrun is all about making AI more accessible and integrable into your existing workflows. By treating Markdown as code, we can bridge the gap between human-readable documentation and machine-executable tasks, thanks to Gemini CLI and a little bit of glue shell script.

Check out the project on GitHub and tell me what cool and handy executable Markdown scripts you’ll create!

My goal was to shed light on some lesser-known aspects of the Model Context Protocol:

• 🛠️ While the majority of MCP servers use the tools feature to expose actions that LLMs can request to call,
• 📄 An MCP server can also share resources (and resource templates), exposing various static assets the AI app might be interested in,
• ✏️ And prompts (and prompt templates) that users can access and reuse to utilize the MCP server effectively.

The Combo: Antigravity + Quarkus + Java

To implement this server, I selected the Quarkus framework (in Java) and its extensive MCP support (documented here).

I enlisted Antigravity to help me in this adventure. I pointed my agentic IDE to the arXiv API User’s Manual to draft and scaffold my project, and iteratively collaborated with it to expand the coverage of the arXiv API. It was a pretty productive session! I highly recommend checking out Antigravity!

A Look at the arXiv API

PDFs are accessible at a URL of the form https://arxiv.org/pdf/{paperID}.

The arXiv API offers programmatic access to e-prints via HTTP requests with parameters for searches, specific paper IDs, pagination, and sorting. Users can build complex queries using boolean operators, phrases, and grouping.

So for searching, I’ve created a REST client that I used in my MCP server implementation:

@RegisterRestClient(baseUri = "https://export.arxiv.org/api")
@RegisterProvider(ArxivResponseFilter.class)
public interface ArxivClient {

    @GET
    @Path("/query")
    @Produces("*/*")
    String search(
        @QueryParam("search_query") String searchQuery,
        @QueryParam("id_list") String idList,
        @QueryParam("start") int start,
        @QueryParam("max_results") int maxResults,
        @QueryParam("sortBy") String sortBy,
        @QueryParam("sortOrder") String sortOrder);
}

Unusually, the arXiv API returns results in Atom 1.0 XML format (rather than the typical JSON), providing detailed metadata for both the query and individual articles, including titles, abstracts, authors, categories, and links.

In order to parse the Atom format and map the feeds to Java classes, I simply went with Jackson’s XML parser (perhaps I could have used the venerable Rome project).

Here’s one of the entities used in the ATOM domain model:

@JsonIgnoreProperties(ignoreUnknown = true)
public class Entry {
    @JacksonXmlProperty(namespace = "http://www.w3.org/2005/Atom")
    public String id;

    @JacksonXmlProperty(namespace = "http://www.w3.org/2005/Atom")
    public String published;

    @JacksonXmlProperty(namespace = "http://www.w3.org/2005/Atom")
    public String title;

    @JacksonXmlProperty(namespace = "http://www.w3.org/2005/Atom")
    public String summary;

    @JacksonXmlElementWrapper(useWrapping = false)
    @JacksonXmlProperty(localName = "author",
                        namespace = "http://www.w3.org/2005/Atom")
    public List<Author> authors;

    // ...
}

(It is somewhat ironic to use the @JsonIgnoreProperties annotation when parsing XML!)

Let’s Start with Tools

What I like about the Quarkus MCP support is that to turn a Quarkus app into an MCP server, you just need a few Java annotations, and everything is handled for you!

In my ArxivMcpServer, I injected my ArxivClient REST client:

public class ArxivMcpServer {
    @Inject
    @RestClient
    ArxivClient arxivClient;
    // ...
}

Then to define a tool, I used the @Tool annotation:

@Tool(
    description = "Search for papers on arXiv",
    name = "search_papers")
public Feed searchPapers(String query, int maxResults,
                         SortBy sortBy, SortOrder sortOrder) {
    return performSearch(
        query, null, 0, maxResults == 0 ? 5 : maxResults,
        sortBy == null ? null : sortBy.name(),
        sortOrder == null ? null : sortOrder.name());
}

I could have added @ToolArg annotations on the parameters of this method to give the LLM more context on their role, but the parameter names were self-explanatory.

Expose the Taxonomy as a Resource

For well-known static assets like the taxonomy of all the domain categories of research papers, you can expose an MCP Resource:

@Resource(
    uri = "arxiv://taxonomy",
    description = "List of arXiv categories and their codes",
    mimeType = "text/markdown")
public TextResourceContents getTaxonomy() {
    return TextResourceContents.create("arxiv://taxonomy",
        """
        # arXiv Category Taxonomy

        ## Computer Science (cs)
        *   **Artificial Intelligence** (cs.AI)
        *   **Computation and Language** (cs.CL)
        *   **Computer Vision** (cs.CV)
        *   **Machine Learning** (cs.LG)
        *   **Robotics** (cs.RO)
        *   **Software Engineering** (cs.SE)
        *   ... and many more.

        ## Physics
        ...
        """);
}