FutureSmart Database Agent

An open-source AI Database Agent by FutureSmart AI. Ask questions about your SQL database in plain English.

Connect PostgreSQL or MySQL, turn natural-language questions into SQL, inspect the results, explore charts, and keep asking follow-up questions without writing SQL yourself.

Whether you want to explore business data, build an AI-powered application, or adapt a complete database agent to your own requirements, you can use the hosted application, deploy it yourself, or integrate it through its API.

Try the live application → · Developer docs · Run it locally · Explore the API · What it can do today

Open source · Apache-2.0 · Self-hostable

What you can do

• Ask questions about your data. Explore customers, orders, revenue, products and anything else in the database you connect.
• Inspect the SQL and results. Every answer shows the SQL that was generated and the rows it returned, so you can check how the answer was reached.
• Explore charts. View supported results as charts alongside the table to see comparisons, trends and patterns.
• Continue the conversation. Ask follow-up questions, narrow a result, and reopen saved conversations later.
• Try it with sample data. The hosted application includes a free demo on a ready-made e-commerce database: a year of synthetic customers, products, orders, payments and returns for a fictional online shop. Sign in, then pick a suggested question or ask your own; you don't need your own database or an OpenAI API key. Each account gets 20 free questions per rolling 24 hours and 100 in total.
• Use the API or customise the application. Call the same agents from your own software through the direct product API, or change the open-source implementation and its model configuration. The developer docs cover the hosted API end to end: quickstart, API keys, the full API reference, streaming and errors.
• Ask from Claude Code and other MCP clients. The included MCP server exposes your agents as tools: ask a question and get the answer, SQL, rows and chart metadata, continue the conversation, or read saved results. Setup for the hosted product: MCP server and Claude Code.

Improved through real-world AI research

We use findings from AI Demos to identify limitations, investigate issues and improve Database Agent. Our public improvement history connects benchmark results to engineering decisions, code changes and verification, while preserving the failures.

Explore the improvement history · View published benchmark results

Example: an answer using the wrong data

The research finding — S64. A user asked how many five-star reviews had been received. The connected database had no review data, but the agent queried an unrelated activity log and returned zero. The published benchmark result was Fail.

What we improved. We added an explicit answerability decision: does the available schema support the requested information? Unsupported questions should produce an unavailable answer, while a valid query that genuinely returns zero remains answerable. Read the investigation, code and regression controls.

What we verified. Existing engineering regressions use mocked model/database boundaries. Separate historical browser checks covered missing information, genuine zero results and valid positive counts. These are engineering checks, not a new independently graded benchmark run.

Engineering correction released · Original benchmark Fail preserved · Independent benchmark retest pending.

Explore all research-driven findings and engineering outcomes →

We prioritize a dependable, deployable product and reproducible evidence over commercial feature parity or a higher benchmark score.

A complete reference application, not just a library

The repository includes the backend, web interface, database integrations, sample data, deployment configuration, and evaluation tools.

You can run the application, explore its architecture, reproduce supported test cases, and adapt the implementation to your own requirements.

We prioritize correctness, reliability, reproducibility, and a usable product experience over adding every feature found in commercial database-agent platforms.

One repository contains the FastAPI backend and Next.js UI. The supported stack uses Docker Compose, PostgreSQL metadata, and Qdrant vectors. Source connections support PostgreSQL and MySQL. Ordinary background tasks run in the API; the included in-process report executor needs no separate worker service.

Install

You need Git, Docker with Compose v2, and one OPENAI_API_KEY. The versioned FutureSmart recommended profile assigns models automatically. Python 3.11 is optional; configuration can run in a container.

git clone https://github.com/FutureSmart-AI/database-agent.git database-agent
cd database-agent
docker run --rm -v "${PWD}:/workspace" -w /workspace python:3.11-slim python deploy/configure.py

Set OPENAI_API_KEY in your shell before starting the API. Keep it private. Compose forwards it at runtime; provider keys are not frontend configuration or image build arguments.

docker compose build
docker compose up -d metadata-db sample-db qdrant
docker compose run --rm bootstrap
docker compose up -d api ui

Open localhost:3001/database-agent/. Sign in with STANDALONE_LOGIN_PASSWORD from the generated root .env. No FutureSmart account is needed. Configuration generates independent secrets and refuses to overwrite an existing file.

Recommended defaults: GPT-6.1 Sol for SQL and complex reasoning, GPT-6 Luna for routing/descriptions/presentation, and text-embedding-3-small for new embeddings. See model configuration for single-provider chat and per-operation overrides, endpoint requirements and existing-vector compatibility.

Try the sample

Create an agent in the UI and choose PostgreSQL:

Field	Value
Host / port	sample-db / 5432
Database	sample_sales
Username	sample_reader
Password	local-reader-only
Description	Synthetic orders by region; amount is revenue in USD.

Test the connection and finish the wizard. It discovers the orders table. Ask:

What is the total amount for each region in orders? Show a bar chart.

Check the SQL, rows, answer, and chart against North: 250.00 and South: 200.00. The sample has four orders and database-level read-only grants. Use a dedicated read-only account for your own source databases.

Stop and restart

docker compose down
docker compose up -d metadata-db sample-db qdrant api ui

Named volumes retain agents, conversations, sample data, and vectors. Keep .env, especially APP_MASTER_KEY and HASH_SALT, with your backups: changing them can make saved credentials unreadable. Avoid down -v unless you intend to erase this installation's data.

Guides and checks

• Product capabilities: what exists, hosted vs standalone, and how to use it
• Configuration and authentication
• Direct product API and OpenAPI reference
• MCP server for Claude Code and other MCP clients
• AWS deployment: ECS/Fargate and static UI
• Development and reproducible evaluation
• Architecture and source layout
• Frontend development

docker compose run --rm evaluate --fixture-only
docker compose run --rm evaluate

The first command checks sample results and read-only grants without a model call. The second invokes real providers and verifies SQL, rows, and the answer. Use the UI flow above to check the chart. Local ports bind to loopback; hosting requires HTTPS, matching login origin, secure cookies, and private datastores.

Known limits

Use read-only source credentials: the existing execution path is not a general SQL sandbox. Review generated queries and results. Query-time descriptions do not automatically include PostgreSQL table comments. PostgreSQL connections accept any TCP port; MySQL connections are accepted on port 3306 only.

Flat and nested stacked-bar responses render through the same live and saved conversation path. Stacked charts preserve individual series values, explicit zeros and missing series. Invalid segmented data shows an explanation while the supplied Data, Query and Raw views remain available.

Standalone login is for one operator. On the hosted service (2026-10-22), each account uses either its own provider keys or the platform key, set per account. An account on its own keys uses them for setup, questions, charts and embeddings, and gets a clear error, with no fallback to the platform key, when its key is missing. That was verified on one bounded hosted journey: one answered and one refused question, using a temporary key. It is not a load or multi-tenant security assessment. Shared website widget assets and the retired external report-consumer lane remain separate work. The in-process report option is included. Targeted installation checks do not establish general benchmark accuracy or load capacity.

License and provenance

Copyright 2026 FutureSmart AI. Released under the Apache License 2.0. The bundled fonts retain their original SIL OFL notices; see NOTICE. This repository starts from a clean source snapshot rather than importing private development history. Historical commit, PR and CI IDs in our improvement records identify earlier work; they are not links to commits in this fresh repository.

Publication and compatibility notes explain the retained optional hosted URLs, source boundaries, and limited installation verification.