Semantic Vector Search

Overview

Finds documents by meaning, not by matching exact words — the search that powers modern AI assistants. Ask for 'how to onboard a new hire' and it can surface the onboarding guide even if that exact phrase isn't in the title.

How it works

Wraps whatever Spring AI VectorStore bean is configured in your application — Chroma, PGVector, Weaviate, Redis, Milvus, or Qdrant — and performs a natural-language similarity search. The query string is embedded on the fly and matched against stored vectors. Returns up to 20 top-K chunks with similarity scores; an optional threshold filters out weak matches.

Example

When a user asks:

Find internal docs about how we onboard new hires.

the agent calls the tool:

semantic_search(query="onboarding a new employee", topK=5)

and gets back: the 5 most relevant document chunks with similarity scores.

Configuration

Set these before calling the tool. Values marked required must be present or the tool call will fail.

VectorStore bean required

A Spring AI VectorStore bean must be configured (e.g. spring.ai.vectorstore.chroma.* or spring.ai.vectorstore.pgvector.*). The tool auto-wires whatever VectorStore is present.

Use it in a workflow

Wire this tool into a SwarmAI crew. Use the YAML DSL for declarative workflows, or the Java builder API when you want full programmatic control.

YAML DSL

# rag-retrieval.yaml
name: rag-retrieval-crew
process: SEQUENTIAL

agents:
  - id: retriever
    role: RAG Retriever
    goal: Find the most relevant passages from the knowledge base
    tools:
      - semantic_search

tasks:
  - id: rag-retrieval-task
    agent: retriever
    description: Find the top 5 internal document chunks for the query 'onboarding a new employee'.

Java

import ai.intelliswarm.swarmai.agent.Agent;
import ai.intelliswarm.swarmai.task.Task;
import ai.intelliswarm.swarmai.swarm.Swarm;
import ai.intelliswarm.swarmai.swarm.SwarmOutput;
import ai.intelliswarm.swarmai.process.ProcessType;
import ai.intelliswarm.swarmai.tool.common.SemanticSearchTool;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.beans.factory.annotation.Autowired;

@Autowired ChatClient chatClient;
@Autowired SemanticSearchTool semanticSearchTool;

Agent retriever = Agent.builder()
    .role("RAG Retriever")
    .goal("Find the most relevant passages from the knowledge base")
    .chatClient(chatClient)
    .tool(semanticSearchTool)
    .build();

Task retrieverTask = Task.builder()
    .description("Find the top 5 internal document chunks for the query 'onboarding a new employee'.")
    .agent(retriever)
    .build();

SwarmOutput result = Swarm.builder()
    .agent(retriever)
    .task(retrieverTask)
    .process(ProcessType.SEQUENTIAL)
    .build()
    .kickoff();

What it's good for

Real scenarios where agents put this tool to work.

Retrieve top-K document chunks for RAG grounding

Threshold-filtered queries for high-confidence matches only

Local-first or self-hosted RAG over Chroma or PGVector

Blend with web_search — semantic_search for private docs, web_search for public

Source

Implementation lives at swarmai-tools/src/main/java/ai/intelliswarm/swarmai/tool/common/SemanticSearchTool.java in the swarm-ai repository.

Open semantic_search on GitHub →