> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lyzr.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Build an Agent with a Semantic Data Model

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 {Provider} 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.

<Tip>
  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.
</Tip>

***

## 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.

<Tip>
  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.
</Tip>

***

## 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)