ProjectsSeptember 13, 2026

spring-ai-agent-utils: Mock Tests & Accurate Tool Descriptions (PR #92)

Overview

spring-ai-agent-utils is the official Spring AI community library for agent tooling — web search, file system access, browser automation, and more. It's maintained by Christian Tzolov, Spring AI Lead at Broadcom. This PR fixes two separate issues that were affecting test reliability and LLM behavior in production.

Fix 1 — BraveWebSearchTool: Replace Live Network Tests with Mocks (Issue #87)

The Problem

DomainFilteringTests was calling the live Brave Search API on every test run. This caused:

25-second hangs in offline and CI environments
Flaky results depending on what the live API returned
More critically: the assertions only checked isNotNull() — they never actually verified the domain filtering logic worked

What I Changed

Added a package-private constructor to BraveWebSearchTool that accepts a RestClient.Builder, allowing tests to bind a MockRestServiceServer before the tool is constructed. The production constructor and the public Builder.build() path are completely unchanged. Rewrote DomainFilteringTests with 6 deterministic, offline test cases against a canned 3-result response (spring.io, baeldung.com, example.com): | Test | Asserts | |------|---------| | No filters | all three results present | | Allowed domains | only spring.io kept | | Blocked domains | example.com excluded | | Combined allowed + blocked | both rules applied | | Subdomain matching | docs.spring.io matches parent spring.io | | Empty lists | all results returned, no network call | Result: 19 tests, 0 network calls, deterministic in any environment.

Fix 2 — FileSystemTools.read: Accurate Tool Description (Issue #85)

The Problem

The @tool description for FileSystemTools.read told the LLM it could read PDFs, images, and .ipynb files with visual and structured output. The implementation is a UTF-8 line reader — binary files come back as replacement-character garbage. This caused LLMs (reproduced with Gemini on a workspace containing PDFs) to hallucinate file content or report files as corrupt. The description also referenced "Claude Code" as the specific caller, which is incorrect for a general-purpose Spring AI tool.

What I Changed

Dropped the three false capability bullets and the "Claude Code" / "any file on the machine" framing. Replaced with an accurate single-sentence description: reads UTF-8 text files with cat -n output, 2000-line default, binary files explicitly unsupported.

Result

498/498 tests pass, 0 new failures. PR open, awaiting review by Christian Tzolov.

Tech Stack

Java — Tool implementation
Spring Boot / Spring AI — Framework
MockRestServiceServer — HTTP mocking (spring-test)
JUnit 5 — Test framework

Related projects

Hivemind: Fix Stale BM25 References in Docs (PR #350)

Merged contribution to Hivemind — a YC-backed AI memory layer — correcting stale technical documentation that described a removed lexical search implementation.

Read case study View project

Managed AI Chatbot Service

Built a self-hosted managed AI chatbot service for small businesses, with pilot deployments for a dental clinic and a church.

Read case study

AI Research Agent Workshop

Designed and delivered a hands-on AI agent workshop for engineering teams, built with 13 progressive git commits and a full speaker script.

Read case study

Event-Driven Customer Onboarding System

Architected a mission-critical event-driven system for seamless customer onboarding with resilient distributed transactions using Kafka and the SAGA pattern.

Read case study

Payment Gateway Integration — Springer Nature

Integrated multiple microservices with Razorpay for a robust payment processing system at Springer Nature.

Read case study

Route Search Performance Optimization — Lava Labs

Redesigned a route search system reducing response time from 30s to 2s — a 15x performance improvement.

Read case study