Quickstart

#1. Create an agent in the app

Open Database Agent and sign in. Create an agent and connect your database:

• PostgreSQL or MySQL, reachable from the internet. Use a dedicated read-only database user — the agent only reads, and a read-only account makes that a guarantee rather than a promise.
• Pick the tables the agent may use. Anything you leave out is never queried.

Ask one question in the app to confirm the connection works.

#2. Issue an API key

In the agent, open Share, expand API and click Generate API key. The key works for that one agent only. The code samples on the same screen already contain your agent's id (it looks like NL2SQL_1A2B3C4D). Store both as environment variables rather than in your code:

export DATABASE_AGENT_API_KEY="your-key"
export DATABASE_AGENT_ID="NL2SQL_1A2B3C4D"

On Windows PowerShell use $env:DATABASE_AGENT_API_KEY = "your-key" instead.

#3. Ask a question

import os
import requests

API_ROOT = "https://futuresmart.ai/database-agent/api"
AGENT_ID = os.environ["DATABASE_AGENT_ID"]

r = requests.post(
    f"{API_ROOT}/v1/agents/{AGENT_ID}/chat",
    headers={"X-API-Key": os.environ["DATABASE_AGENT_API_KEY"]},
    json={"query": "How many customers are there?", "debug_info": True},
    timeout=180,
)
r.raise_for_status()
answer = r.json()

print(answer["response"])
print(answer["debug_info"]["sql_query"])

const API_ROOT = "https://futuresmart.ai/database-agent/api";
const AGENT_ID = process.env.DATABASE_AGENT_ID;

const res = await fetch(`${API_ROOT}/v1/agents/${AGENT_ID}/chat`, {
  method: "POST",
  headers: {
    "X-API-Key": process.env.DATABASE_AGENT_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "How many customers are there?", debug_info: true }),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const answer = await res.json();

console.log(answer.response);
console.log(answer.debug_info.sql_query);

curl -sS -X POST "https://futuresmart.ai/database-agent/api/v1/agents/$DATABASE_AGENT_ID/chat" \
  -H "X-API-Key: $DATABASE_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "How many customers are there?", "debug_info": true}'

The JavaScript sample uses top-level await and the built-in fetch: save it as ask.mjs and run it with Node.js 18 or later.

A typical answer takes 10–30 seconds: the agent reads your schema, writes SQL, runs it and phrases the result. Set your HTTP client's timeout to at least two minutes.

#4. Read the answer

{
  "response": "There are **2,400 customers**.",
  "session_id": "184b72b3-625c-4c10-93ec-621f2e154e00",
  "chat_id": "1008c506-2935-405c-b20a-0ae0d28bb1f5",
  "is_answered": true,
  "follow_up": ["How many customers are there in each region?"],
  "debug_info": {
    "sql_query": "SELECT COUNT(*) AS customer_count FROM customers",
    "db_result": {
      "columns": [{ "name": "customer_count", "type": "integer" }],
      "rows": [{ "customer_count": 2400 }],
      "row_count": 1,
      "truncated": false
    }
  },
  "chart_output": null
}

• response is Markdown. Render it, or strip it to plain text.
• session_id identifies the conversation. Send a follow-up to it — see Follow-ups and conversations.
• debug_info carries the SQL and rows only because the request set debug_info: true and the agent's settings allow showing them.

#Next steps

• Ask questions: charts, follow-up suggestions and every response field.
• End-to-end examples: a CLI, a backend endpoint and a scheduled report.
• MCP server and Claude Code: use the agent from your editor.