Skip to main content
This cookbook walks through building a complete, working agent end to end in Lyzr Studio that can answer natural-language questions directly against a real database — no SQL knowledge required from the end user. Example used throughout: a Sales Analytics Agent for an e-commerce store. It connects to the store’s own orders/customers/products database and answers questions like “What were total sales last month?” or “Who are our top 5 customers by revenue?” by translating them into database queries behind the scenes.

Before you start

You’ll need:
  • Connection details for a real database (host, port, username, password, database name) — e.g. a PostgreSQL or MySQL instance containing your orders, customers, and products tables.
  • Read access to that database from wherever Lyzr Studio’s backend runs.

Part 1 — Connect your database

  1. Sidebar → Configure → Data Connectors.
  2. Click the Database tab.
  3. Find your database type’s card (e.g. PostgreSQL) and click its + icon.
  4. A panel titled “Connect Database” opens. Fill in:
    • Unique Name (required) — a name for this connection, e.g. “Ecommerce Sales DB”
    • The provider-specific fields — typically Host, Port, User, Password, and the database name (exact fields vary slightly by provider, since they’re generated from that provider’s own schema)
  5. Click Submit.
Your database is now available to attach to a knowledge base.

Part 2 — Build the Semantic Data Model knowledge base

2a. Create the knowledge base shell

  1. Sidebar → Knowledge Bases.
  2. Click New ▾ → choose Semantic Data Model.
  3. In the “Create Knowledge Base” panel, fill in:
    • Name (required) — lowercase letters, numbers, and underscores only, e.g. ecommerce_sales_analytics
    • Description (optional) — e.g. “Orders, customers, and products database for sales Q&A”
    • Vector Store / LLM Embedding Model — leave the pre-filled defaults
  4. A Database Configuration section appears with two more required fields:
    • Database — select the connection you created in Part 1 (e.g. “Ecommerce Sales DB”). (If none show up, there’s a “Configure New Database” link here that jumps straight to Data Connectors.)
    • Documentation Agent — this is a small helper agent that reads your database schema and writes plain-English descriptions of each table and column. Click Create New to set one up (see 2b), or pick an existing one from the dropdown if you already have one.
  5. Click Create Knowledge Base.

2b. Create the Documentation Agent (if you don’t have one yet)

Clicking “Create New” above opens a small dialog titled “Schema Documentation Agent”:
  • Name (required) — e.g. “Sales DB Documentation Agent”
  • Model — pick an LLM provider and model (defaults to OpenAI / gpt-5-mini; click “Need help choosing?” if unsure)
  • Temperature (default 0.7) and Top P (default 0.9) — sliders, safe to leave at defaults
  • Click Submit.

2c. Document and add each table

After creating the knowledge base, you land on a screen listing every table found in your connected database, with columns Table Name, Status (Added / Not Added), and a Configure → button per row. For each table you want the agent to be able to query (e.g. orders, customers, products):
  1. Click Configure → next to that table.
  2. You’ll see a Column Name / Description table. Descriptions are pre-filled automatically by your Documentation Agent — read through them and edit any that are unclear or wrong (they’re plain editable text fields).
  3. (Optional) Click Preview table to see a sample of the actual rows, to sanity-check you’re looking at the right data.
  4. Click Save & Add to Semantic Data Model.
Repeat for every table the agent needs. Once saved, that table’s Status flips to Added back on the table list. You can revisit any added table later and click Remove if you need to take it back out.
Only add the tables actually relevant to the questions you expect — e.g. skip internal/admin tables. Fewer, well-documented tables produce more accurate query generation than dumping in your whole schema.

Part 3 — Build the agent and attach the semantic data model

  1. Sidebar → Agents.
  2. Click New ▾ → choose Agent.
  3. Once in the editor, you’re on the Build tab by default. Fill in:
    • Name — e.g. “Sales Analytics Agent”
    • Instructions (system prompt) — e.g. “You help the sales team answer questions about orders, customers, and products using the connected database. Always state numbers precisely and mention the time period covered. If a question can’t be answered from the available tables, say so rather than guessing.”
  4. In the right-hand settings, open the Features section and find “Data Query” (under Core Features, described “Answers questions instantly by querying and reading data from your data source”). Toggle it on.
  5. This opens a panel titled “Configure Data Query.” Fill in:
    • Semantic Data Model (required) — select ecommerce_sales_analytics, the one you built in Part 2.
    • Max tries — leave at the default (3). This is how many times it’ll retry generating a query if the first attempt fails.
    • Time limit (s) — leave at the default (60).
    • Auto train agent (optional) — turn this on if you want successful queries saved for future reference; if enabled, pick an Auto Training Knowledge Base to store them in.
  6. Click Save.
  7. (Optional) Configure Model (choose your preferred LLM) — Knowledge, Tools, Automation are not required for this use case.
  8. Click Create (top-right) to save the agent.
Once a Semantic Data Model is selected, a “Configure” link appears right next to its label in this same panel — click it any time to jump straight back into the table/column setup from Part 2c.

Part 4 — Test it in the Playground

  1. Click the Playground tab.
  2. Ask it real questions your database can answer, e.g.:
    • “What were our total sales last month?”
    • “Who are our top 5 customers by revenue this year?”
    • “How many orders came from repeat customers vs. new customers?”
  3. Check the answers against what you know to be true in the underlying data. If something’s off, go back to Part 2c and improve that table’s column descriptions — vague or missing descriptions are the most common cause of wrong query generation — then re-test.

Part 5 — Deploy (optional)

  1. Click the Deploy tab.
  2. Copy the ready-to-use API snippets, or use Share / Publish to make the agent available to teammates or your organization.

Quick checklist

  • Database connected in Data Connectors, with valid credentials (Part 1)
  • Semantic Data Model knowledge base created, linked to that database (Part 2a)
  • Documentation Agent created and generating descriptions (Part 2b)
  • Each relevant table configured, reviewed, and marked “Added” (Part 2c)
  • Agent created with clear instructions (Part 3)
  • Data Query feature enabled, with the Semantic Data Model selected (Part 3)
  • Tested with real questions in the Playground, descriptions refined as needed (Part 4)