Knowledge Base

Knowledge Base gives your voice agents searchable company information without placing every document into every prompt. Upload Markdown documents once, choose which agents can access each document, and let an enabled agent search the relevant source material while it handles a caller's question.

The shared tenant document library can serve multiple agents. Access is explicit: an agent can search only documents assigned to it, and only when Knowledge Base is turned on for that agent.

How Knowledge Base works#

When a caller asks a factual question, the agent can use its Knowledge Base search tool. Cartra searches the agent's assigned, ready documents using both semantic meaning and keyword matches, then returns the most relevant document sections to the agent.

To improve matching across languages, Cartra can normalize each searchable section and each caller query into an internal English retrieval form while preserving names, numbers, codes, and product terms. The original Markdown remains the authoritative source shown in previews and downloads. The internal retrieval form is not displayed or editable in the dashboard, and the agent still answers in the caller's language.

The documents are not loaded wholesale into the base prompt. Retrieval happens on demand during the live call, so a lookup can add a short delay before the agent answers.

The agent is instructed to:

Treat retrieved content as the source for its answer.
Give a concise, natural response instead of reading entire source sections.
Avoid adding facts or next steps that the retrieved content does not support.
Say that a requested detail is not available when the search does not answer the question.
Keep the search mechanism and internal source system hidden from the caller.

Search is tool-driven and probabilistic. The agent decides whether to search based on the caller's question, the built-in tool description, your optional tool instructions, and the conversation. Semantic and keyword matching improve recall, but they do not make routing or retrieval deterministic.

Quick start#

In the Cartra dashboard, select Knowledge Base in the main navigation.
Select Upload document.
Choose a non-empty Markdown (.md) file.
Optionally select the agents that should be able to search it. New library uploads default to no agent access.
Select Upload document and wait for the upload to finish.
Open an agent and select its Knowledge Base tab.
Confirm Knowledge Base is On and that the document appears under Assigned documents.
Optionally configure search behavior and select Save search settings.
Place a new test call and ask a question answered by the document.
Ask a nearby question the document does not answer and confirm that the agent does not invent a response.

Knowledge Base changes save through their own controls. There is no agent-level Save Changes step for uploads, assignments, the On/Off switch, or Save search settings.

Manage the tenant library#

The tenant-level Knowledge Base page is the source of truth for shared documents. It shows each filename, size, chunk count, processing status, last update, and assigned agents.

Upload a document#

Library uploads accept one Markdown file at a time. The file must:

Use the .md extension.
Contain non-whitespace text.
Be valid text rather than a binary file.

UTF-8 is recommended. A file that cannot be decoded safely is rejected with a validation message. Cartra does not create an empty or partially searchable document after a failed upload.

During upload, you can give any available tenant agents access. Leaving every agent unchecked keeps the new document unassigned. An unassigned document remains in the library but no agent can search it until access is added.

Preview and download#

Select Preview to inspect the stored Markdown source. The preview shows the document content, not a simulated search result. Select Download to retrieve the current Markdown file.

Edit Markdown#

Select Edit to open the Markdown editor and live preview. Saving validates the new text, splits it into new chunks, and regenerates its search embeddings. The filename and agent assignments stay the same.

If the document is assigned, saving updates the shared source for every assigned agent. Closing a changed editor asks you to confirm before discarding unsaved work.

Replace a document#

Select Replace to upload a different Markdown file into the same document record. Replacement can change the filename and content. It regenerates the chunks and embeddings while preserving agent assignments.

When the document is assigned, the dashboard asks you to confirm that the updated content will be used by those agents.

Manage agent access#

Select Manage access, check every agent that should be able to search the document, and select Save access. Updating access reuses the document's existing chunks and embeddings; the document is not uploaded or processed again.

Removing every assignment leaves the document safely stored as an unassigned tenant resource.

Delete a document#

Deleting an unassigned document permanently removes its source and search chunks from the tenant library.

If the document is still assigned, the first delete attempt is blocked and the dashboard identifies the affected agents. To continue, explicitly select Detach agents and delete. That action removes every assignment and permanently deletes the document. This cannot be undone.

Use Manage access when you only want to stop one or more agents from using a document.

Configure an agent#

Open an agent and select Knowledge Base to control whether it can search and which shared documents it can use.

Turn Knowledge Base on or off#

The On/Off switch saves immediately.

On makes the search tool available for the agent's assigned, ready documents.
Off prevents the agent from using Knowledge Base while preserving all document assignments and search settings.

Turning Knowledge Base back on restores access to the assignments that were already saved. Place a new test call after changing this setting so the call loads the latest agent configuration.

Assign an existing tenant document#

Choose a document from Existing tenant document, then select Add document. The assignment saves immediately and reuses the document already in the tenant library. It does not duplicate, re-upload, re-chunk, or re-embed the document.

The picker shows only tenant documents that are not already assigned to the agent.

Quick upload Markdown#

Select Quick upload Markdown to create a tenant document and immediately assign it to the current agent. The document is still a shared tenant resource: afterward, you can open the tenant library and give other agents access.

Remove access#

Select Remove access beside an assigned document to detach it from the current agent. The shared document remains in the tenant library and stays available to any other assigned agents.

Configure search behavior#

Search settings are saved by selecting Save search settings. Saving trims leading and trailing whitespace from tool instructions. Saving the field as blank removes that customization and restores the built-in behavior.

Tool instructions#

Tool instructions add agent-specific guidance to the Knowledge Base search tool. They can contain up to 4,000 characters.

Use this field to describe when searching is important and how the available documents should be used:

Search the returns policy before answering eligibility, timing, or proof of purchase questions. Do not use product specifications to answer policy questions.

Keep factual content in documents rather than copying it into tool instructions. Avoid telling the agent to skip retrieval and answer from memory.

KB result retention#

KB result retention (caller turns) controls how long the raw search tool call and returned source material remain in the model's working conversation context.

The value must be a whole number from 1 through 20.
The default is 2 caller turns.
The caller turn that caused the lookup counts as turn one.
With the default of 2, the result remains available for the lookup turn and one subsequent caller turn.
When the window expires, Cartra removes only the raw Knowledge Base tool call and result from model context. Caller messages and agent replies remain.
Separate lookups expire independently.

A longer window can help with follow-up questions about the same source. A shorter window reduces the chance that old source text distracts from a later topic.

xAI realtime voice manages its own conversation context and does not use this retention setting. The dashboard disables the field when it is unsupported.

Write searchable Markdown#

Knowledge Base works best when documents are designed for retrieval rather than copied from an unstructured handbook.

Use:

One clear # document title.
Descriptive ## headings for self-contained topics.
Short sections that keep a question and its answer together.
The terms callers are likely to say, along with important product names, policy names, codes, and synonyms.
Clear definitions and common aliases together, especially when callers may use an acronym, transliteration, translated name, or an older product name.
Complete facts with their conditions, dates, exceptions, and units close together.
Lists and tables when they make the source easier to maintain, while keeping the surrounding heading and explanation meaningful.

Avoid:

A single enormous section covering unrelated subjects.
Headings such as “Other” or “Details” that do not identify the topic.
Contradictory copies of the same policy in multiple documents.
Instructions to ignore the agent's safety rules or reveal internal systems.
Passwords, authentication codes, private keys, or other secrets.

Cartra uses headings to create retrieval-friendly chunks. Oversized sections can be split into multiple chunks, and very small adjacent sections can be combined. Write each topic with enough local context to remain understandable if it is retrieved separately.

For example, define “Evidence of Insurance (EOI)” in the same section and keep both forms near the relevant procedure. This is more reliable than maintaining a separate terminology list outside the source document.

Customer-support example#

The following document keeps each policy answer in a focused section and includes likely caller wording.

# Returns and exchanges

## Standard return window

**Topic:** returns, refunds, return period, unopened purchases

Customers may return an unopened item within 30 calendar days of delivery.
The original order number is required. Refunds go to the original payment
method after the return is inspected.

## Damaged item

**Topic:** damaged product, broken item, arrived damaged

Report an item that arrived damaged within 7 calendar days of delivery.
Ask the customer for the order number and a description of the damage.
Do not require the customer to pay return shipping for an approved damaged-item
claim.

## Final-sale items

**Topic:** final sale, clearance, non-returnable

Items explicitly marked Final Sale on the order confirmation cannot be returned
or exchanged unless they arrived damaged.

Use a test call to ask:

“Can I send back an unopened item after three weeks?” The standard return section should support the answer.
“Who pays shipping for a normal return?” The document does not say, so the agent should not invent a policy.
“My final-sale item arrived broken.” Relevant information appears in two sections, so verify that the answer preserves both the final-sale exception and damaged-item guidance.

Processing and document status#

Before a new or changed document becomes available, Cartra:

Validates the Markdown file and text.
Splits the content into heading-aware chunks.
Generates search embeddings for every chunk.
Commits the document and chunks. New uploads also save the requested assignments.

A successful document shows a ready status and a chunk count. Runtime search uses only ready documents assigned to the agent.

If embedding or validation fails during a new upload, no partially usable document is created. If it fails during an edit or replacement, the previously saved document and chunks remain unchanged.

Assigning or removing access does not repeat this processing. Editing or replacing does, because the searchable content changed.

Knowledge Base and Procedures#

Knowledge Base assignments apply to the whole agent, not to individual Procedures. If Knowledge Base is on, the main agent can search its assigned documents during an ordinary conversation or while a Procedure is active.

A Procedure can tell the agent when a source lookup is important, but it does not create the search tool, assign documents, or limit retrieval to a subset of documents. Use agent assignments and search settings for access, and use Procedure content only for situation-specific workflow guidance.

See the Procedures guide for activation, content, and testing guidance.

Prompt Preview#

System Prompt Preview displays an indicator when Knowledge Base context retrieval is enabled. It does not insert document content into the base prompt, run a query, show retrieved chunks, or predict whether the agent will search.

Use a new test call to verify tool selection, retrieval quality, and the spoken answer.

Privacy and safety#

Assigned documents can influence what an agent says to callers. Treat library content as production source material:

Upload only information the assigned agents are allowed to disclose in the conversations they handle.
Give each document access only to agents that need it.
Remove outdated content promptly and avoid conflicting policy copies.
Keep credentials, authentication codes, payment data, private keys, secrets, and unnecessary personal information out of documents.
Allow only trusted tenant users to edit source material. Do not paste untrusted instructions into documents.
Test legal, medical, financial, identity, and other high-impact information with extra care and keep a human review path.

Knowledge Base grounds an answer in your text; it does not independently prove that the text is current, complete, safe to disclose, or applicable to a particular caller.

Authoring practices#

Give each document a clear subject and ownership.
Prefer one authoritative policy source over multiple overlapping copies.
Include effective dates or version information inside time-sensitive sections.
Phrase facts in customer language without removing important conditions.
Keep related exceptions beside the rule they modify.
Use document assignments as access control, not as a substitute for clear content.
Use tool instructions for search behavior, not for storing the knowledge itself.
Review assigned agents before editing or replacing a shared document.
Retest common questions after every material content change.

Test before publishing broadly#

After saving the latest settings, place new calls that cover:

A direct question using the same terms as the source.
A paraphrased question that requires semantic matching.
A question containing an exact product name, code, or policy term.
A question the assigned documents do not answer.
A question near the boundary between two sections or documents.
Conflicting or outdated wording that should be removed before rollout.
The same question with Knowledge Base turned off.
The same question before and after removing the document assignment.
A quick-uploaded document and an existing shared document.
An edited or replaced document used by multiple assigned agents.
A Procedure that asks the agent to consult assigned reference material.
A follow-up inside and outside the configured result-retention window.

Listen for factual accuracy, concise delivery, unsupported additions, and appropriate handling of missing information. Test realistic caller phrasing, not only wording copied from the document.

Troubleshooting#

The agent does not search#

Confirm Knowledge Base is On for the agent.
Confirm the document is assigned to that agent and shows a ready status.
Confirm the question is factual and related to the assigned content.
Add focused tool instructions when the agent should search for a particular class of question.
Place a new call after changing agent search settings.
Remember that tool selection is probabilistic; test several natural phrasings.

The agent says the information is unavailable#

Verify the answer is explicitly present in an assigned document.
Put the question and answer in the same focused section.
Add caller-friendly synonyms, product names, or policy codes.
Check for overly broad headings or a large section that mixes unrelated subjects.
Confirm the document is ready and assigned to the correct agent.
Do not lower expectations by instructing the agent to guess when retrieval has no answer.

The answer is irrelevant or incomplete#

Follow the answer back to the likely document topic and improve its heading and local context.
Split unrelated topics into separate ## sections.
Remove duplicate or contradictory policy copies.
Keep exceptions beside the rule they change.
Shorten broad tool instructions that encourage searching unrelated documents.
Test both semantic paraphrases and exact keyword queries.

An upload, edit, or replacement fails#

Confirm the filename ends in .md.
Confirm the document contains non-whitespace text.
Re-save the file as UTF-8 and try again if its encoding is uncertain.
Remove binary content or invalid text.
Retry after a temporary embedding or processing failure.
A failed edit or replacement leaves the previously saved document in place.

An update does not appear in a call#

Confirm the edit or replacement completed successfully and the document is ready.
Confirm the call's agent still has access to the shared document.
Start a new test call so it loads the current agent configuration.
Ask a focused question that targets the changed section.
Remember that assigning a document does not create a second copy; every assigned agent uses the same updated source.

Removing access deleted nothing#

That is expected. Remove access detaches the document from one agent but keeps it in the tenant library. Open the library to manage other assignments or delete the shared document.

A document cannot be deleted#

Assigned documents require an explicit second confirmation. Review the listed agents. Use Manage access to preserve the document with fewer assignments, or choose Detach agents and delete to remove every assignment and permanently delete it.

Follow-up answers use old source context#

Review KB result retention (caller turns). The lookup turn counts as turn one, and each lookup expires independently. Lower the value when old raw results distract from later topics, or raise it when callers commonly ask several follow-ups about the same source.

Caller and agent messages remain after the raw tool result expires. xAI realtime voice does not use this setting.

Current limitations#

Only Markdown (.md) documents can be uploaded through the dashboard.
Retrieval is live, tool-driven, semantic, and probabilistic—not a deterministic rules engine or exhaustive full-document scan.
Lookup time can add latency to the live conversation.
Prompt Preview does not simulate retrieval or display document content.
Documents are assigned per agent, not per Procedure or caller.
Internal ranking and relevance thresholds are not customer-configurable.
Knowledge Base does not guarantee that the agent will speak filenames, section names, or citations to the caller.
The dashboard documents the supported self-service workflow; it does not expose a public Knowledge Base configuration API.