SQL Database Query

Overview

Lets the agent look things up in your company database — but only to read, never to change anything. A safe way to give agents access to customer records, sales data, or any structured information you already store.

How it works

Executes the supplied SQL against the Spring JDBC DataSource configured in your application. Allows SELECT only — any statement containing INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, TRUNCATE, GRANT, REVOKE, EXEC, CALL, or MERGE is rejected before it runs. Auto-appends 'LIMIT 50' when missing, with a hard ceiling of 200 rows.

Example

When a user asks:

How many active customers do we have by country?

the agent calls the tool:

database_query(query="SELECT country, COUNT(*) FROM customers WHERE status='active' GROUP BY country")

and gets back: a markdown table with one row per country and its customer count.

Configuration

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

spring.datasource.url required

JDBC URL of the target database.

spring.datasource.username required

Database user (read-only role strongly recommended).

spring.datasource.password required

Database password.

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

# analytics.yaml
name: analytics-crew
process: SEQUENTIAL

agents:
  - id: analyst
    role: Analytics Agent
    goal: Read operational data safely from the warehouse
    tools:
      - database_query

tasks:
  - id: analytics-task
    agent: analyst
    description: Count active customers per country using the customers table.

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.DatabaseQueryTool;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.beans.factory.annotation.Autowired;

@Autowired ChatClient chatClient;
@Autowired DatabaseQueryTool databaseQueryTool;

Agent analyst = Agent.builder()
    .role("Analytics Agent")
    .goal("Read operational data safely from the warehouse")
    .chatClient(chatClient)
    .tool(databaseQueryTool)
    .build();

Task analystTask = Task.builder()
    .description("Count active customers per country using the customers table.")
    .agent(analyst)
    .build();

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

What it's good for

Real scenarios where agents put this tool to work.

Analytics agents pulling top-N rows for a quick sanity check

Support agents looking up a customer by email without full DB access

KPI aggregation (COUNT/SUM/GROUP BY) feeding into a generated report

Schema exploration via information_schema before deeper analysis

Source

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

Open database_query on GitHub →