> ## 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 a Voice Agent with a Knowledge Base

This cookbook walks through building a complete, working voice agent end to end in Lyzr Studio — from creating its knowledge base, to building the agent, testing it live, and connecting a real phone number so customers can call it.

**Example used throughout:** an AI voice receptionist for a dental clinic ("Bright Smile Dental") that answers patient questions about hours, services, insurance, and booking, using the clinic's own FAQ document as its knowledge source.

***

## Before you start

Have a simple document ready (Word, PDF, or plain text) containing the information you want the agent to know — for a clinic receptionist, that's hours, services, insurance accepted, address, booking process, cancellation policy, and common FAQs.

***

## Part 1 — Build the Knowledge Base

1. Sidebar → click **Knowledge Bases**.
2. Click **New ▾** at the top of the page.
3. From the dropdown, choose **Knowledge Base** (not "Knowledge Graph" or "Semantic Data Model" — those are for graph-relationship or live-database use cases).
4. A panel titled **"Create Knowledge Base"** opens. It shows a **Knowledge Base Type** selector — leave it on **Knowledge Base**. Fill in:
   * **Name** *(required)* — **lowercase letters, numbers, and underscores only** (no capitals, spaces, or hyphens), e.g. `bright_smile_dental_faq`
   * **Description** *(optional)* — e.g. "Clinic hours, services, insurance, booking info"
   * **Vector Store** *(required)* — already pre-filled with a default; no need to change it
   * **LLM Embedding Model** *(optional)* — already pre-filled with a default; no need to change it
5. Click **Create Knowledge Base**.
6. It immediately opens the knowledge base's detail panel with a 3-step wizard: **Choose Source → Configure → Upload**.
7. On **Choose Source**, pick **File Upload** ("Upload PDF, DOCX, or TXT files," up to 5 files).
8. On **Configure**, leave the default parser options as-is.
9. On **Upload**, add your FAQ document and confirm.
10. Once processing finishes, use the **Playground Retrieval** panel on the right: type a real test question (e.g. *"Do you accept Delta Dental insurance?"*), click **Retrieve**, and confirm it returns the correct passage.

***

## Part 2 — Build the Voice Agent

1. Sidebar → click **Agents**.
2. Click **New ▾** → choose **Voice Agent**. This opens a dedicated voice agents area with three tabs: **Agents**, **Telephony**, **Transcripts**.
3. Click **Create Agent**.

You land on the voice agent editor — three tabs: **Build**, **Playground**, **Deploy** (you start on **Build**).

### Name it

Click the title text at the top-left of the page and type a name, e.g. `Bright Smile Front Desk`.

### Left pane — the basics

* **Who Speaks First** — choose **AI** (so the agent greets the caller first).
* An **AI Introduction Text** box appears — write the greeting, e.g.:
  *"Thanks for calling Bright Smile Dental, how can I help you today?"*
* **Goal** — e.g. "Answer patient questions about clinic hours, services, insurance, and help them understand how to book an appointment."
* **Role** — e.g. "A friendly, professional dental clinic receptionist."
* **Instructions** — e.g. "Always be warm and reassuring. If a patient asks something not covered in the knowledge base, tell them you'll have a staff member call them back — never guess at medical advice."

### Right pane, top to bottom

**Engine Mode**

* Choose **Realtime** (badge: "Low latency") — the simplest, recommended option for a straightforward FAQ agent. ("Pipeline," badge "Customizable," splits speech-to-text/LLM/text-to-speech into separate steps — more control, not needed here.)
* Pick a **Voice** from the dropdown (preview a few).
* Set the **Language** (defaults to English).

**Voice session** — three optional toggles:

* **Call recording**
* **Preemptive generation**
* **Noise cancellation** (powered by Krisp)

**Knowledge** — attach the knowledge base from Part 1:

* Click the small **+** button next to "Knowledge."
* A popover titled **"Knowledge Base"** opens with a search box and a list of your existing knowledge bases.
* Find and click **bright\_smile\_dental\_faq** — this selects and attaches it (it appears as a chip below).
* *(A "Create new" option at the bottom of the same popover lets you build one inline if you skipped Part 1.)*

**Tools** — skip for a simple FAQ receptionist; no external actions needed.

**Features** — click **View All** to see optional features, e.g.:

> #### Adding Call Escalation (optional but recommended)
>
> Find **Call escalation** in the list and toggle its switch **on** — this opens a **"Call escalation"** configuration panel.
>
> * **Destination type** — choose **Phone number** (the other option, "SIP warm transfer," is for call-center system integrations like Five9).
> * **"When the caller…"** — describe the trigger condition in plain English, e.g. *"…asks to speak to a real person, mentions a dental emergency, or seems upset and needs a human."*
> * **Destination phone number** — enter the front desk's real number in international format, e.g. `+19515550148`.
> * *(Optional)* Click **"Add another routing rule"** for a second condition/number, e.g. a separate rule for billing questions.
> * Click **Done**.
>
> ⚠️ Note: a badge on this panel confirms **"Escalation rules apply on phone calls only"** — it will not trigger during the in-browser Playground test call in Part 3, only on real calls once Telephony (Part 4) is connected.

4. Click **Save** (top-right). It briefly shows "Saving…" then "Saved."

***

## Part 3 — Test it in the Playground

1. Click the **Playground** tab.
2. If you've edited the agent since your last save, you'll see an amber banner: *"You are testing an older saved version… Use **Update** to test the newest version of this agent in playground."* → go back to **Build** and click **Update** first if so.
3. Click **Start voice call**.
   * If your account has zero credits, it'll show: *"You have no credits left. Top up or upgrade before starting a call."*
4. Once connected, you'll see: an agent audio indicator (left), a live chat/transcript panel (center), and a control bar (right) with a mic mute toggle and a red **End call** button.
5. Talk to it — e.g. *"What time do you close on Saturdays?"* — and confirm it answers correctly using the attached knowledge base.
6. Click **End call** when done.

***

## Part 4 — Connect a real phone number (Telephony)

1. Go back to the voice agents area (**Agents** → **Voice Agent**) and click the **Telephony** tab.

### Connect a provider account

2. Click **Add Integration**. Options: **Telnyx**, **Twilio**, **Plivo**, **SIP**.
3. Pick one, e.g. **Twilio** — the dialog becomes **"Connect Twilio Account"** and asks for:
   * **Account SID**
   * **Auth Token**
   * A name for this connection, e.g. "Clinic Twilio Account"
4. Click **Save & Connect**.

> ⚠️ **Lyzr Studio does not sell or provision phone numbers.** If the connected account has none yet, you'll see: *"No numbers found for this integration. Purchase numbers from your provider to get started."* Buy the number directly in your Twilio/Telnyx/Plivo dashboard — it will then appear here automatically.

### Assign the number to your agent

5. Once a number appears as a card, click its **•••** menu → **Assign Agent** (reads "Reassign Agent" if already connected to something).
6. A dialog titled **"Configure Phone Number"** opens: *"Connect this phone number to a voice agent to start receiving inbound calls."*
7. From the **"Choose an agent…"** dropdown, select your agent (e.g. **Bright Smile Front Desk**).
8. Click **Connect**.

The number now shows a **Connected** status — any call to it is answered live by your voice agent, including the escalation rule from Part 2.

***

## Part 5 — Embed it elsewhere (optional)

1. Back in the agent editor, click the **Deploy** tab.
2. This shows the agent's configuration JSON and ready-to-copy connection snippets for a developer to wire the voice agent into your own website or app over WebRTC.

***

## Quick checklist

* [ ] Knowledge base created and content uploaded (Part 1)
* [ ] Retrieval tested with a real question (Part 1)
* [ ] Voice agent built: greeting, goal, role, instructions set (Part 2)
* [ ] Engine mode, voice, and language selected (Part 2)
* [ ] Knowledge base attached (Part 2)
* [ ] Call escalation configured, if needed (Part 2)
* [ ] Agent saved (Part 2)
* [ ] Tested live in Playground (Part 3)
* [ ] Telephony provider connected with valid credentials (Part 4)
* [ ] Phone number purchased with the provider and assigned to the agent (Part 4)