Skip to main content

​
What is a Knowledge Base?

A knowledge base is a collection of simple text files that your voice AI agent reads to answer customer questions. Think of it like a cheat sheet — when a caller asks something, the agent searches these files and returns the best (typically 5 by default) matches to find the right answer before speaking it back naturally. Each file usually covers one question or topic but can cover more if these topics/questions are inter-related. The files are written in a format called Markdown, which is just plain text with a few symbols for formatting. You don’t need any coding experience — if you can write an email, you can write a knowledge base file. Learn how markdown works: https://www.markdownguide.org/cheat-sheet/

​
The Golden Rule: You’re Writing for a Voice, Not a Screen

Your AI agent will speak these answers out loud to real callers. Everything you write should sound natural when read aloud. Before saving any file, read your answer out loud to yourself. If it sounds robotic or awkward, rewrite it. Avoid:
  • Bullet-point heavy answers (the agent may literally say “one…do this. two….do that.”)
  • Abbreviations that are specific to your organization and may not be understood by customers
  • Long, dense paragraphs — break things into short, conversational sentences

​
File Naming Convention

Every file should be named clearly so you (and the AI agent) can find them easily. Suggested Format: Q + short description of the question, written in PascalCase (capitalize the first letter of each word, no spaces), saved as .md Examples: 
QHowDoIMakeAPaymentOnline.md
QCanIUpdateTheMortgageCompany.md
QDoYouAcceptChequePayments.md
QIsThereAnAdditionalCostToExpediteAClaim.md
Tips:
  • Start every filename with Q so it’s clear this is a question-and-answer file
  • Keep it short but descriptive enough that you know the topic at a glance
  • Don’t use spaces, special characters, or apostrophes in filenames
  • Use .md as the file extension when saving (this stands for Markdown)

​
File Structure Template

Below is the basic template every knowledge base file should follow. Copy this and fill it in for each new topic. 
# Q: [Write the customer's question exactly as they would ask it]

**A:** [Write the answer the agent should give, in a natural, conversational tone]
That’s it at its simplest. A question and an answer.

​
Template Variations

Depending on the type of question, you’ll use slightly different structures. Here are the main patterns you’ll need.

​
1. Simple Q&A (Direct Answer)

Use this when there’s a straightforward answer the agent can just say. 
# Q: Do you accept cheque payments?

**A:** Yes, we do accept cheque payments. To make sure we're able to verify
everything correctly, we recommend calling back during business
hours so we can walk you through the process.

​
2. Step-by-Step Walkthrough

Use this when the caller needs to be guided through a process on a website or portal. Number each step and keep instructions short. 
# Q: How do I make a payment online?

**A:** You can make payments online by logging into your account
at mystrada.com/myaccount/login.

For one-time payments, you'll need to pay by credit card.

Once you log in, click on "See Policies." Then look for the word
"Payments" in the menu across the top and click on it. If money
is due, you'll see a "Make A Payment" button. You can update your
card information there and submit the payment.

You'll also be able to view your payment history on that same page.

​
3. Conditional Response (If/Then)

Use this when the answer changes depending on what the caller says. Write the default answer first, then add the condition with angle brackets or a clear label. 
# Q: What are escrow payments?

**A:** Escrow payments come from the lender on file. They typically
mail us a check on behalf of the customer.

<If the customer says they need to pay directly>
Redirect them to the customer portal to add their payment
information. We don't offer direct billing — all payments are
auto-pay through either ACH or a card.

​
4. Information Collection/Calling an action (Raise a Ticket)

Use this when the agent needs to gather details from the caller before creating a support ticket. List each question the agent should ask, one by one. 
# Q: Can I update the mortgage company on my policy?

**A:** Let the customer know that you can raise a ticket for them.
Then collect the following information by asking these questions
one at a time:

1. Would you like to add an additional mortgage to the policy?

<Collect Response>

2. How many mortgages are currently on the policy?

<Collect Response>

3. Are you replacing the current policy?

<Collect Response>

4. Would you like a copy of the new Evidence of Insurance?

<Collect Response>

Include all of this information on the ticket and raise it.

​
5. Short Deflection or Policy Statement

Use this when the answer is brief and the service isn’t offered. 
# Q: Is there an additional cost to expedite a claim?

This is not a service we offer. Any costs associated with an
approved claim will be applied to the claim itself and discussed
directly with the adjuster.

​
6. Question with Alternative Phrasings

Use this when callers might ask the same thing in different ways. List the alternate phrasings so the AI can match any of them. 
# Q: I'm looking for a document summarizing claim history on an expired policy?

Alternative Questions:
- I'm looking for loss runs?
- I'm looking for letters of experience?

<If someone inquires about this, collect the policy number and
the email they want it sent to and raise a ticket.>

​
Writing Tips for Voice AI

​
Do This

  • Write the way a helpful human agent would talk. Use natural phrasing like “You’ll want to…” or “Go ahead and…” instead of “The user shall proceed to…”
  • Keep sentences short. The AI agent speaks these out loud. Long, complex sentences become confusing over the phone.
  • Spell out anything that could be mispronounced.
  • Use one file per question. Don’t bundle multiple topics into a single file. If two questions are related but different, make two files.
  • Include the exact words callers use. Write the question the way a real customer would phrase it, not in formal or internal-jargon language.

​
Don’t Do This

  • Don’t write internal notes without marking them clearly. If something is an instruction for the agent’s behavior (not to be spoken), wrap it in angle brackets: <This is an internal instruction>.
  • Don’t include URLs unless the caller needs them. If you do include a URL, write it in a speakable way: “mystrada dot com slash my account” rather than just pasting the link.
  • Don’t leave placeholder text. Every file should have a complete, usable answer.

​
Markdown Basics You Need to Know

You only need four things:
What you wantWhat you typeWhat it does
A heading / the question# Q: Your question hereMarks the main question — always start the file with this
Bold label for the answer**A:**Marks the start of the answer
A numbered list1. First step then 2. Second stepCreates ordered steps for walkthroughs
An internal instruction<Your instruction here>Signals that this text is a direction for the agent, not something to say to the caller
That’s all the Markdown you need!

​
Checklist Before Publishing a File

Run through this list for every file before adding it to your knowledge base:
  • The filename starts with Q and ends with .md
  • The file starts with # Q: followed by the question
  • The answer is written in a natural, conversational tone
  • You’ve read the answer out loud and it sounds like something a real person would say on the phone
  • Each file covers only one topic or question
  • Any alternative phrasings of the question are listed
  • Internal instructions (things the agent should do but not say) are wrapped in angle brackets < >
  • Step-by-step instructions are numbered and clear
  • There are no leftover placeholders or incomplete answers
  • URLs are written in a speakable format if the caller needs them

​
Blank Template (Copy and Paste This)

# Q: [Customer's question in their own words]

**A:** [Your conversational answer here]

​
With Alternative Phrasings

# Q: [Primary question]

Alternative Questions:
- [Another way the customer might ask this]
- [Yet another phrasing]

**A:** [Your conversational answer here]

​
With Conditional Responses

# Q: [Customer's question]

**A:** [Default answer here]

<If the customer says [condition]>
[Alternative response here]

​
With Information Collection

# Q: [Customer's question]

**A:** Let the customer know you can help with this. Collect the
following information one question at a time:

1. [First question to ask the caller]

<Collect Response>

2. [Second question to ask the caller]

<Collect Response>

3. [Third question to ask the caller]

<Collect Response>

[What to do with the collected information]