---
sidebar_position: 2
title: Knowledge Bases (RAG)
description: Build vector Knowledge Bases from documents and websites to ground Firetell Voice AI Agents in verified, real-time company knowledge.
---

# Knowledge Bases (RAG)

Firetell **Knowledge Bases** use **Retrieval-Augmented Generation (RAG)** powered by hybrid semantic vector search and keyword matching to give your [Autonomous Voice AI Agents](/use-guides/voice-ai-and-sms/voice-ai-agents) sub-second access to large company documents, pricing sheets, policies, and live web pages during phone calls.

Instead of cramming thousands of words into an agent's base system prompt—which increases latency and dilutes instruction adherence—attach one or more Knowledge Bases so the Voice Agent retrieves only the most relevant verified passages on demand via Firetell's built-in knowledge retrieval engine.

---

## 1. How RAG Works During a Live Voice Call

```text
Caller asks a question ("What is your cancellation policy for group bookings?")
       │
       ▼
Voice AI Agent formulates a contextual search query
       │
       ▼
Firetell Knowledge Engine searches attached Knowledge Base(s)
  • Hybrid Semantic Vector Search + Keyword Matching
  • Returns top-scoring document chunks & source citations in milliseconds
       │
       ▼
Voice AI Agent synthesizes a concise, natural spoken answer grounded in your docs
  • Retrieved sources & relevance scores are logged in the Call Transcription!
```

---

## 2. Creating & Managing a Knowledge Base

1. Navigate to **Console → Knowledge Bases** and click **New Knowledge Base**.
2. Enter a clear, domain-specific **Name** (for example, `Hotel Policies & Room Rates` or `SaaS Technical Troubleshooting`) and a concise **Description**.
   - **Tip**: Writing an accurate Knowledge Base name and description helps you organize multi-domain repositories (e.g., attaching a `Sales Pricing` KB to your Sales AI Agent while attaching a `Return & Warranty Policy` KB to your Support AI Agent).
3. Click into the Knowledge Base row to open its **Repository Documents** and **RAG Intelligence & Analytics** workspace.

### Repository Limits & Quotas

| Resource | Limit | Notes |
| :--- | :--- | :--- |
| **Documents per Knowledge Base** | Up to **100 documents** | Includes both uploaded files and crawled web URLs. |
| **Max File Upload Size** | **25 MB** per file | Split oversized manuals (> 25 MB) into logical chapters before uploading. |
| **Supported File Extensions** | `.pdf`, `.docx`, `.doc`, `.xlsx`, `.xls`, `.csv`, `.txt`, `.md` | Filtered in Console under `PDF`, `Word`, `Excel / CSV`, and `Text / MD`. |
| **Max Knowledge Bases & Storage** | Plan-dependent | Monitor total repositories and storage capacity under [Workspace Limits & Quotas](/use-guides/administration-and-billing/billing-and-quotas#workspace-limits--quotas). |

---

## 3. Adding Content: File Uploads vs. Website Crawling

Each Knowledge Base supports two ingestion workflows inside the **Repository Documents** tab:

### Option A: Upload Documents (`Upload Document`)
1. Click **Upload Document** in the top-right toolbar.
2. Select a supported file up to **25 MB**:
   - **Documents & Manuals (`.pdf`, `.docx`, `.doc`)**: Product guides, onboarding manuals, legal terms, and SOPs. Ensure PDFs contain selectable text rather than un-OCR'd flat image scans.
   - **Structured Data & Rate Cards (`.xlsx`, `.xls`, `.csv`)**: Room tariffs, SKU catalogs, branch addresses, or FAQ tables. Keep column headers descriptive in Row 1 so each row's meaning is preserved during chunking.
   - **Markdown & Plain Text (`.md`, `.txt`)**: Cleanest format for RAG retrieval—ideal for curated Voice AI FAQs and troubleshooting trees.

### Option B: Crawl Websites & Sitemaps (`Crawl Website`)
1. Click **Crawl Website** to ingest live public help-center articles, pricing pages, or documentation portals.
2. **Automatic Sitemap & URL Discovery**: Enter your root domain or documentation URL (e.g., `https://help.yourcompany.com`). Firetell automatically scans `sitemap.xml` and internal links (discovering up to 500 candidate URLs) so you can pick the exact pages to import.
3. **Automatic URL Deduplication & Re-Crawling**:
   - Submitting a URL that already exists in the Knowledge Base updates and re-indexes the existing document rather than creating duplicates.
   - Whenever your public web page changes, click the **Re-crawl** action on that URL row to refresh its vector chunks with zero downtime.

---

## 4. Document Ingestion Lifecycle

Every uploaded file or crawled URL progresses through four real-time states in the **Status** column:

| Status | Meaning | Recommended Action |
| :--- | :--- | :--- |
| **`PENDING`** | Queued for background parsing and text extraction. | Wait a few seconds; status updates automatically in real time. |
| **`PROCESSING`** | Extracting text, splitting into semantic chunks, and generating vector embeddings. | Large PDFs or multi-sheet Excel files may take 10–30 seconds. |
| **`COMPLETED`** | All chunks are indexed and live for Voice AI retrieval. | Ready for live calls and **Test Call** verification. |
| **`FAILED`** | File was password-protected, corrupted, scan-only (empty text), or URL blocked bots (`403`/`404`). | Hover/inspect the error reason, fix the source file or URL accessibility, delete the failed entry, and re-upload. |

:::warning[Preventing Stale Answers]
If your pricing or business hours change, either **Re-crawl** the updated web URL or **Delete** the outdated file (single delete or checkbox **Bulk Delete**) and upload the revised version. Leaving both `Pricing_2025.pdf` and `Pricing_2026.pdf` in the same Knowledge Base can cause the AI agent to retrieve conflicting figures.
:::

---

## 5. Attaching Knowledge Bases to a Voice AI Agent

1. Open **Console → Voice Agents** and select your target agent.
2. Select the draft version you wish to edit (or create a **New Version**).
3. In the right-hand configuration sidebar, scroll to **Knowledge Bases (RAG)**.
4. Use the multi-select picker to attach one or more Knowledge Bases.
5. Reinforce retrieval behavior in your **System Instructions**, for example:
   ```markdown
   ## Knowledge & Fact Checking
   - Always consult your attached Knowledge Base before answering questions about pricing, refund policies, or room amenities.
   - Never invent prices, URLs, or guarantees not present in the Knowledge Base. If an answer is unavailable, offer to transfer the caller to a specialist.
   ```
6. Click **Save** (or **Update**), run a **Test Call** from your browser to verify spoken answers, and **Publish** the version.

---

## 6. Formatting Best Practices for Voice-First RAG

Documents written for visual reading often contain complex visual tables, footnotes, or "see above" references that lose context when split into chunks. Follow these guidelines for near-100% retrieval accuracy:

- **Make sections self-contained**: Repeat the product or plan name in headings (use `## Enterprise Plan — Cancellation Policy` rather than a generic `## Cancellation` heading 10 pages below `Enterprise Plan`).
- **Write voice-friendly numbers and units**: Write explicit currencies and units (`$49 USD per month`, `check-in starts at 2:00 PM`) rather than ambiguous shorthand (`49/mo`, `14:00*`).
- **Include caller phrasing in Q&A docs**: Phrase headings the way customers actually ask questions over the phone (e.g., `### Can I bring pets or service animals?`).

---

## 7. Auditing Retrieval with RAG Analytics & Transcripts

Firetell gives you visibility into how your Knowledge Bases perform in production:

- **Document Usage & Score**: In the **Repository Documents** table, check the **Usage & Score** column to see which documents are cited most frequently and their average semantic similarity score.
- **RAG Intelligence & Analytics**: Switch to the **RAG Intelligence & Analytics** tab inside a Knowledge Base (or **Workspace RAG Analytics** on the main Knowledge Bases page) to track retrieval volume, hit rates, and unanswered knowledge gaps.
- **Turn-Level Source Citations**: Open **[Call Transcriptions](/use-guides/call-center/call-logs-and-transcriptions#ai-call-transcriptions)** for any Voice AI call—every turn where RAG was invoked records the exact search query, matched document title/URL, and similarity score.
