A voice agent’s instructions tell it how to behave. They do not hold your pricing sheet, your return policy, or the answer to every question a caller might ask. A knowledge base collection fills that gap: attach one to an agent and it searches your own documents for an answer while the call is happening. After the call, Speak AI also looks back at what the agent got wrong or heard repeatedly, and hands you ready-to-approve fixes instead of leaving you to comb through transcripts.
What is a knowledge base collection?
A collection is a named group of documents. You build it up from three sources: upload files (PDF, TXT, Markdown, Word or CSV), pull pages from a website, or paste text in by hand. Speak AI reads each document and embeds it so it can be searched by meaning, not just by keyword, which is what lets an agent match a caller’s question to the right paragraph even when the wording is different.
A collection is not tied to one agent. The same collection can answer for several agents, and for folder automations too, so you only maintain your return policy or product spec in one place. Collections live on their own Knowledge Base page, separate from any single agent’s editor.
Connect a collection to your agent
- Open the agent in the editor and select the Knowledge tab.
- Under Knowledge collections, either pick an existing collection from the Attach an existing collection… combobox, or select New Collection to create one on the spot and attach it in the same step.
- Each attached collection shows a status: Pending, Processing, Completed or Failed. Completed is the only state the agent can actually search; a collection that just finished uploading still needs a moment to process.
- To remove a collection from this agent, select the X next to it. This only detaches it – the collection and its documents still exist and can be reattached, or attached to another agent, at any time.
An agent can have more than one collection attached, and it searches across all of them.
Add and manage the documents inside a collection
Adding and organizing documents happens on the Knowledge Base page, not inside the agent editor – the Knowledge tab only attaches and detaches collections. Open a collection from that page and you get three ways to add content: Upload files, From website (paste a URL, Speak AI discovers its pages, and you pick which ones to add), and Manual (paste a title and text directly). Every document shows its own status as it moves through the pipeline, and the collection page also lists every agent and automation currently connected to it, so you can see the blast radius before you edit or delete something shared.
How does a voice agent close its own knowledge gaps?
Every call is a chance to find out what the knowledge base is missing. When a caller asks something the agent can only answer with low confidence, or answers with an explicit “I don’t know,” that question becomes a knowledge gap: a pending suggestion with the caller’s question, a confidence score, a severity of low, medium or high, and an AI-drafted title and answer.
Open the agent’s Insights tab to see them under Knowledge gaps. You can edit the drafted title and answer before doing anything with it, then:
- Add to KB writes it into the agent’s connected collection as a new document.
- Dismiss discards it without writing anything.
Nothing is written to your knowledge base automatically. Every gap sits there until a person reads it and chooses one of those two actions.
How do suggested FAQs work?
Suggested FAQs solve a different problem: not what the agent got wrong, but what callers keep asking. When the same question comes up across several calls, worded slightly differently each time, Speak AI clusters those calls into one reusable question-and-answer pair.
These also live on the Insights tab, under Suggested FAQs, and work the same way as knowledge gaps: expand one to read the full drafted answer, select Edit before adding to change the question or answer, then Add to KB to save it as a document or Dismiss to drop it. The suggestion also shows roughly how many times the question was asked and across how many conversations, so you can judge how common it is before deciding whether it belongs in your knowledge base.
How do instruction gaps differ from knowledge gaps?
Instruction gaps are not about the knowledge base at all – they are about the agent’s own instructions, the prompt that tells it how to behave. Under Suggested improvements on the Insights tab, select Analyze now and Speak AI reads the agent’s current instructions and drafts up to three patches for cases they do not cover, each tagged low, medium or high severity.
Select View patch to read the suggested wording before deciding. Apply inserts that patch into the agent’s instructions and saves it immediately; Dismiss just clears the suggestion from the list. As with knowledge gaps and FAQs, nothing changes until you apply it yourself.
Who can review and apply suggestions?
Reviewing what surfaces on the Insights tab does not require special access, but adding a knowledge gap or FAQ to the knowledge base, applying an instruction patch, and running a fresh analysis all need the Owner or Admin role on your Speak AI account.
Related pages
- Voice agent intelligence – the API endpoints behind agent resources, FAQ suggestions, knowledge base gaps and instruction gaps.
- Knowledge base – the API endpoints for creating collections, adding documents, and mapping a collection to an agent or automation.