> For the complete documentation index, see [llms.txt](https://docs.klink.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.klink.cloud/kai-ai-agent-chat/vector-stores-and-file-search.md).

# Vector Stores and File Search

Upload your own files, connect them to Kai with File Search, and write instructions that make Kai answer from them.

A **vector store** is a searchable library of your files (price lists, policies, manuals, store lists and more). When you connect a vector store to Kai with **File Search**, Kai can look inside those files and answer customers with the right passage, word for word where it matters.

This page walks you through the full setup, from uploading a file to writing instructions that make Kai actually use it.

**The full flow at a glance**

1. Create a vector store in **Knowledge Base**.
2. Upload your files to the store.
3. Attach the store to an agent node under **File Search** in AI Agent Studio.
4. Write instructions that tell Kai when to search the files.
5. Test in the **Emulator**, then **Publish**.

## Vector Stores or Knowledge Base articles?

Vector Stores live inside **Knowledge Base**, next to your existing sources (articles, PDFs, website URLs). They work differently, so pick the one that fits your content.

|                                        | Knowledge Base sources (articles, PDF, website)                      | Vector Stores (File Search)                                                                         |
| -------------------------------------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Best for                               | Short help articles, FAQs you write in the editor, your website      | Larger or structured files: price lists, product catalogs, policy documents, branch lists, manuals  |
| How you add content                    | **Create** in Knowledge Base, then write, upload a PDF or sync a URL | Upload files from the File Manager into a vector store                                              |
| File types                             | Text PDF (up to 45 MB), articles, web pages                          | 88 file types, including PDF, DOCX, CSV, TXT, MD and JSON (see [Supported files](#supported-files)) |
| Where you connect it in the agent node | **Knowledge**                                                        | **File Search**                                                                                     |
| How Kai uses it                        | Kai looks up the knowledge you selected                              | Kai decides when to search the files, based on your instructions                                    |

You can use both on the same agent node. For example, keep your short FAQ articles in **Knowledge** and put your 500-row price list in a vector store.

{% hint style="info" %}
**How it works behind the scenes.** When you add a file, it is sent to our AI provider, split into small overlapping passages (about 800 tokens, roughly 600 words each) and indexed. When a customer asks a question, Kai searches the store and reads the most relevant passages before it replies.
{% endhint %}

## Before you start

* You need access to **Knowledge Base** and **Chat AI Agent** in the left sidebar (under **AI & Automation**). These are usually available to admins. If you can't see them, ask your workspace admin to check your role.
* You need at least one Chat AI Agent with an agent node. See [How to setup AI Agent (Step by Step Guide)](https://docs.klink.cloud/kai-ai-agent-chat/how-to-setup-ai-agent-step-by-step-guide).
* Have your files ready. For best results, use the formats in [Which format should I use?](#which-format-should-i-use).

## Step 1. Create a vector store

1. In the left sidebar, open **Knowledge Base**.
2. In the Knowledge Base panel, find the **Vector Stores** section (marked **New**) and click **All**.
3. Click **Create vector store**.
4. Enter a **Name** (required, up to 255 characters). For example: `Product price list` or `Return and refund policy`.
5. Click **Create**.

Your new store appears in the table with **Total Attached Files** set to `0`.

{% hint style="info" %}
The first time you open this page you'll see an **About vector stores** panel with a quick 3-step overview. Click **Got it** to hide it.
{% endhint %}

**Tip:** Group related files in one store (for example, all pricing files together). You can attach several stores to the same agent node.

## Step 2. Upload files to the store

Files are added through the **File Manager**, which is the shared file library for your workspace.

1. In the vector stores table, find your store and click the **Manage files** icon in the **Actions** column.
2. In the **Files in \[store name]** window, click **Open Media Manager**.
3. In the File Manager:
   * To add a new file, click **Upload** and choose files from your computer.
   * To reuse a file you uploaded before, just find it in the list.
4. Select the files you want, then click **Choose (n)**.
5. Back in the **Files in \[store name]** window, check the list (for example "2 files ready"). Click **Add more** to pick more files, or the **x** next to a file to remove it from the queue.
6. Click **Upload & attach (n)**.

Files are processed one at a time. When it finishes you'll see a message such as **Files attached** ("3 files attached"). If some files fail, you'll see **Partial upload** with how many were attached and how many failed.

The attached files now appear in the list at the bottom of the window, each with an **Attached** date and time.

### Supported files

The upload window shows a **Supported formats** hint. Click it to see the full list. If you pick a file type that is not on the list, you'll see **Unsupported file type** and the file is not added.

The upload window accepts these 88 file types:

| Category                     | Extensions                                                                                                                                        |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Documents                    | .pdf, .doc, .docx, .dot, .odt, .rtf, .pages, .hwp, .hwpx                                                                                          |
| Presentations                | .ppt, .pptx, .pps, .pot, .ppa, .pwz, .keynote                                                                                                     |
| Spreadsheets and data        | .csv, .tsv, .xls, .xlsx, .xla, .xlb, .xlc, .xlm, .xlt, .xlw, .json, .xml, .yaml, .yml                                                             |
| Text and markup              | .txt, .text, .md, .markdown, .rst, .html, .htm, .shtml, .mht, .mhtml, .tex, .ltx, .sty, .brf, .srt, .vtt                                          |
| Email, calendar and contacts | .eml, .mail, .nws, .ics, .ifb, .vcf                                                                                                               |
| Code                         | .c, .h, .cpp, .cs, .css, .java, .js, .mjs, .es, .ts, .go, .php, .py, .pkl, .rb, .pl, .pm, .sh, .ksh, .bat, .scala, .hs, .cls, .diff, .patch, .wiz |
| Images                       | .png, .jpg, .jpeg, .gif, .webp, .svg, .svgz, .art                                                                                                 |
| Archives                     | .zip, .tar                                                                                                                                        |

### Which format should I use?

Kai can only search the **text** inside your files. These formats give the most reliable results:

| Format       | Good for                                    | Tips                                                                                    |
| ------------ | ------------------------------------------- | --------------------------------------------------------------------------------------- |
| **PDF**      | Policies, manuals, brochures                | Use a PDF with selectable text. Scanned pages (photos of paper) have no text to search. |
| **DOCX**     | Policies, guides, FAQs                      | Use real headings (Heading 1, Heading 2) so each section is easy to find.               |
| **TXT / MD** | FAQs, scripts, notes                        | Simple and very reliable. Use headings and short paragraphs.                            |
| **JSON**     | Structured product or service data          | Keep field names clear, like `"price_thb"` rather than `"p1"`.                          |
| **CSV**      | Price lists, product catalogs, branch lists | Tested and working with File Search. Keep one header row and one record per row.        |

{% hint style="warning" %}
**Excel files (.xlsx, .xls):** the upload window accepts them, but for the most reliable results, open the sheet and **save it as CSV** (one CSV per sheet) before uploading.

**Images and archives (.png, .jpg, .zip and similar):** these are accepted by the upload window but usually contain no searchable text, so Kai can't answer from them. Put the information in a text document instead.
{% endhint %}

### File size and limits

| Limit                 | Value                                                                                            |
| --------------------- | ------------------------------------------------------------------------------------------------ |
| Maximum file size     | **150 MB per file** (File Manager upload limit)                                                  |
| Maximum text per file | About 5 million tokens (a very large amount of text; most business documents are far below this) |
| Vector store name     | Required, up to 255 characters                                                                   |

Smaller, focused files work better than one huge file. See [Tips for best results](#tips-for-best-results).

### What happens after upload

* When **Upload & attach** finishes, your file has been sent to our AI provider and attached to the store.
* Indexing (splitting the file into passages and making it searchable) then runs in the background. Small files are usually ready within seconds. Large files can take a few minutes.
* The files list shows the **Attached** time for each file. It does not show a separate "indexing" status, so the best way to confirm a file is ready is to ask a question about it in the Emulator (see [Step 5](#step-5.-test-in-the-emulator)).

| Message you may see                         | What it means                                                                                                            |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Files attached**                          | All selected files were uploaded and attached.                                                                           |
| **Partial upload** ("2 attached, 1 failed") | Some files could not be uploaded or attached. Try the failed files again.                                                |
| **Failed to upload file**                   | The file could not be sent for indexing (for example, it is too large or could not be downloaded from the File Manager). |
| **Failed to attach file**                   | The file was uploaded but could not be added to the store. Try again.                                                    |
| **Unsupported file type**                   | The file extension is not on the supported list. Convert it (for example to PDF, DOCX or CSV).                           |

## Step 3. Connect the vector store to Kai (File Search)

File Search is set **per agent node** in AI Agent Studio.

1. In the left sidebar, open **Chat AI Agent** and open your agent in the Studio.
2. Click the agent node (the blue **Conversation Agent** card) to open its editor.
3. In the right-hand panel, find the **File Search** section. Click **Attach** (or the **+** icon next to **File Search**).
4. In the **Attach files to file search** window, choose **Option A** or **Option B** below.
5. When the store shows under **File Search** (with its name and ID), click **Save Changes** at the top of the node editor.

**Option A. Use a store you already created (recommended)**

1. Click **Attach existing vector store**.
2. In **Attach vector store**, tick one or more stores. You can search by store name or ID.
3. Click **Select**.

**Option B. Create a new store from files right here**

1. Click **Open Media Manager**, pick your files (or **Upload** new ones), then click **Choose (n)**.
2. Click **Attach**.

Option B creates a new vector store for you automatically. It is named after the file with "(Store)" at the end (for example `price-list.csv(Store)`), or `Vector store (3 files)(Store)` when you pick several files. You can rename it later in **Knowledge Base**.

{% hint style="info" %}
To open Knowledge Base from the **Attach vector store** window, click **Vector Store Management**. It opens in a new tab.
{% endhint %}

**Good to know**

* You can attach more than one vector store to a node.
* If your flow has several agent nodes, attach the store to every node that should be able to search it.
* To remove a store from a node, hover over it under **File Search** and click the **x**, then click **Save Changes**. This does not delete the store.

## Step 4. Write instructions that use your files

Attaching a store gives Kai the *ability* to search your files. Your **instructions** decide *when* Kai actually does it.

### How File Search gets triggered

* On every customer message, Kai reads the instructions of the current agent node and decides whether it needs to search the attached files.
* There is no separate setting or description for File Search that you need to fill in. The **instructions are the only place** where you tell Kai what is in the files and when to use them.
* If the instructions don't mention the files, Kai may answer from general knowledge instead, which can mean wrong prices or made-up policies.

So your instructions should clearly say:

1. **What is in the files** (for example "our price list and return policy").
2. **When to search** (for example "before answering any question about prices, stock, or returns").
3. **What to do when the answer isn't there** (say so, and offer a human).

You write instructions in the large editor on the left of the agent node (placeholder: "Write instructions or '/' for commands and more..."). You can also open **Generate instruction with AI**, describe your agent, and click **Generate Instruction** to get a first draft, then add the File Search rules below.

### Copy-paste instruction template

Copy this into the instructions editor and replace everything in `[brackets]`.

```markdown
## Role
You are Kai, the customer support assistant for [Company name].
You help customers with [topics, e.g. product prices, orders, returns, and store locations].

## Your files
You can search these attached files:
- [Price list]: [product names, sizes, prices in THB, stock status]
- [Return and refund policy]: [return window, conditions, refund steps]
- [Store list]: [branch names, addresses, phone numbers, opening hours]

## When to search the files
- ALWAYS search the files before answering any question about [prices, products, stock, policies, branches, opening hours].
- Search again when the customer asks about something new (a different product, branch, or date).
- Search with the customer's words and with likely alternatives (for example "refund" and "return", "branch" and "store").

## How to answer
- Answer ONLY with information found in the files. Never guess prices, fees, dates, or policies.
- Copy numbers exactly as written in the files (prices, fees, phone numbers, dates).
- If you can't find the answer in the files, say:
  "Sorry, I don't have that information right now. Would you like me to connect you with our team?"
- When it helps, say where the answer comes from, for example "According to our return policy, ...".
  Do not mention file names or internal notes.
- Keep answers short: 1 to 4 sentences, or a short bullet list when there are several options.

## Language and tone
- Reply in the same language the customer writes in.
- Be friendly, polite, and clear. Avoid technical words.

## When to hand over to a human
Hand over to a human agent when:
- the customer asks for a person,
- the customer is upset or the issue is a complaint,
- the answer is not in the files after you have searched,
- the request needs a decision you can't make (refund approval, account changes, special discounts).
```

{% hint style="info" %}
**Hand over to a human:** the escalation rules work best when your flow has a path to your team. Add one with **Add Transition** on the agent node, and describe in the instructions when to use it. See [How to setup AI Agent (Step by Step Guide)](https://docs.klink.cloud/kai-ai-agent-chat/how-to-setup-ai-agent-step-by-step-guide).
{% endhint %}

### Example 1. Product price list (CSV)

**File:** `price-list.csv`

```csv
SKU,Product name,Size,Price (THB),In stock,Notes
CF-001,Cold Brew Coffee,350 ml,85,Yes,Best seller
CF-002,Cold Brew Coffee,1 L,220,Yes,
TE-010,Thai Milk Tea,350 ml,65,No,Back in stock next week
```

**Add to your instructions:**

```markdown
## Your files
- Price list (CSV): one row per product with SKU, product name, size, price in THB, stock status, and notes.

## When to search the files
- Search the price list for every question about a product, price, size, or stock.
- If the customer doesn't say a size, list all sizes with their prices.
- If "In stock" is "No", say it's out of stock and share the note if there is one.
```

**Try asking:** "How much is cold brew?", "Do you have Thai milk tea?", "What's the price of the 1 litre coffee?"

### Example 2. Return policy (PDF)

**File:** `return-policy.pdf` (a text PDF with headings such as *Return window*, *Conditions*, *How to request a refund*)

**Add to your instructions:**

```markdown
## Your files
- Return and refund policy (PDF): return window, item conditions, non-returnable items, refund method and timing.

## When to search the files
- Search the return policy for any question about returns, exchanges, refunds, damaged items, or warranty.
- Explain the steps in order, as a numbered list.
- Never promise a refund. If the customer wants to start a return, hand over to a human agent.
```

**Try asking:** "Can I return shoes after 10 days?", "How long does a refund take?", "My item arrived broken, what should I do?"

### Example 3. Store and branch list (CSV)

**File:** `branches.csv`

```csv
Branch,Address,District,Phone,Opening hours,Map link
Siam,"123 Rama I Rd",Pathum Wan,02-123-4567,10:00-22:00,https://maps.example.com/siam
Thonglor,"55 Sukhumvit 55",Watthana,02-765-4321,08:00-20:00,https://maps.example.com/thonglor
```

**Add to your instructions:**

```markdown
## Your files
- Branch list (CSV): one row per branch with address, district, phone, opening hours, and map link.

## When to search the files
- Search the branch list for any question about locations, directions, phone numbers, or opening hours.
- If the customer names an area, suggest the branches in or near that district.
- Always include the phone number and map link in your answer.
```

**Try asking:** "Which branch is open late?", "Do you have a store in Thonglor?", "What's the phone number for Siam branch?"

### Do and don't

| Do                                                                  | Don't                                                                |
| ------------------------------------------------------------------- | -------------------------------------------------------------------- |
| Name your files and what they contain in the instructions.          | Attach a store and never mention it in the instructions.             |
| Tell Kai exactly which topics require a search.                     | Write vague rules like "use the files if needed".                    |
| Tell Kai what to say when the answer isn't in the files.            | Let Kai guess prices, fees, or policy details.                       |
| Keep one topic per file and clear headings or column names.         | Mix unrelated topics (prices, HR rules, promotions) in one big file. |
| Ask Kai to copy numbers exactly.                                    | Ask Kai to "round" or "estimate" prices.                             |
| Test with real customer questions, including ones not in the files. | Only test with questions that match your file's wording exactly.     |

## Step 5. Test in the Emulator

The **Emulator** is the chat panel on the right side of AI Agent Studio.

1. Make sure you clicked **Save Changes** in the agent node. The Studio top bar shows **Saving...** and then **Saved**.
2. In the **Emulator**, check that it says **Connected**.
3. Click **Restart chat** (the circular arrow icon) to start a fresh conversation.
4. Type a question in **Type your message...** and send it.
5. Watch for the **file\_search** card above Kai's reply:
   * **Running** means Kai is working on the reply with File Search available.
   * **Completed** means the step finished. Click the card to expand it. Under **Result**, the `calls` list shows the searches Kai made (`queries`) and how many passages it found (`resultsCount`).
   * **Error** means something went wrong. The card opens automatically and shows the error.
6. Check the answer against your file.

**Sample test plan**

| Type of question  | Example                                       | What a good answer looks like                             |
| ----------------- | --------------------------------------------- | --------------------------------------------------------- |
| Exact fact        | "How much is the 1 L cold brew?"              | Correct price, copied exactly.                            |
| Different wording | "What does a big bottle of cold coffee cost?" | Still finds the right row.                                |
| Follow-up         | "And is it in stock?"                         | Searches again and answers about the same product.        |
| Not in the files  | "Do you sell birthday cakes?"                 | Says it doesn't have that information and offers a human. |
| Other language    | Ask the same question in Thai                 | Replies in Thai with the same facts.                      |

When the answers look right, click **Publish** in the Studio top bar, enter a **Version name** (for example `1.1`), and click **Publish** so the change goes live for your customers.

{% hint style="info" %}
Changed your files or instructions? Click **Restart chat** in the Emulator before testing again, so the old conversation doesn't affect the new answers.
{% endhint %}

## Manage stores and files

Open **Knowledge Base**, then **Vector Stores** > **All**.

| Task                       | How                                                                                                |
| -------------------------- | -------------------------------------------------------------------------------------------------- |
| Find a store               | Type in **Search vector stores** at the top of the table.                                          |
| See what's inside          | Click **Manage files** in the **Actions** column.                                                  |
| Add files                  | **Manage files** > **Open Media Manager** > choose files > **Upload & attach**.                    |
| Remove a file from a store | **Manage files**, then click the trash icon (**Detach file**) next to the file.                    |
| Rename a store             | Click **Rename** (pencil icon), change the **Name** in **Edit vector store**, then click **Save**. |
| Delete a store             | Click **Delete** (trash icon) and confirm in **Delete vector store**.                              |

The table shows each store's **Name**, **Total Attached Files**, and **Created** date.

### Update a file after you edit it

Files in a store are not updated automatically when you change the original. To update one:

1. Open **Manage files** for the store.
2. Click **Detach file** next to the old version.
3. Upload the new version with **Open Media Manager** > **Upload** > **Choose** > **Upload & attach**.
4. Test the change in the Emulator.

Tip: put a date or version in the file name (for example `price-list-2026-10.csv`) so you can see which version is attached.

### Deleting a store

{% hint style="warning" %}
Deleting a vector store removes the store and all of its file attachments. **This can't be undone.** Your original files stay in the File Manager.

If an agent node still has the deleted store under **File Search**, it shows as **(unknown vector store)**. Remove it from the node and click **Save Changes**.
{% endhint %}

## Tips for best results

* **One topic per file.** A "Return policy" file and a "Price list" file work better than one "Everything" file.
* **Use clear headings.** In PDF, DOCX and MD files, use headings like "Return window" or "Delivery fees". Kai finds sections faster when they are clearly labelled.
* **Spreadsheets: one header row, one record per row.** No merged cells, no blank rows in the middle, no notes floating to the side of the table. Use clear column names like `Price (THB)`.
* **Save Excel sheets as CSV.** One CSV per sheet gives the most reliable results.
* **Use text, not pictures of text.** Scanned PDFs and screenshots can't be searched.
* **Keep files a sensible size.** Stay well under 150 MB and about 5 million tokens per file. Split very long documents by topic.
* **Write it the way customers ask it.** Include common words and synonyms customers use (for example "refund" and "money back").
* **Remove old versions.** Detach outdated files so Kai doesn't find two different prices.
* **Re-upload after edits.** Changes to the original file don't update the store until you upload the new version.

## Troubleshooting and FAQ

**I uploaded a file but Kai can't answer questions about it.**

* Wait a minute and try again. Large files can take a few minutes to become searchable.
* Check that the store is attached under **File Search** on the agent node that is handling the conversation, and that you clicked **Save Changes**.
* Check your instructions. Make sure they say what is in the files and when to search them (see [Step 4](#step-4.-write-instructions-that-use-your-files)).
* Expand the **file\_search** card in the Emulator. If the `calls` list under **Result** is empty, Kai answered without searching. Make the "when to search" rules in your instructions more specific.
* If `resultsCount` is `0`, the search found nothing. Check that the file contains the information as text, and try wording closer to the file.

**The upload failed or shows "Partial upload".**

* Check the file is under 150 MB and on the supported list.
* Try uploading the failed files again from **Manage files**.
* If a file keeps failing, convert it to PDF (with selectable text), DOCX, TXT or CSV and try again.

**Kai gives a general answer instead of the one in my file.**

Add a rule like "Answer ONLY with information found in the files. If it isn't there, say you don't have that information." Also add "ALWAYS search the files before answering questions about \[topic]."

**The Emulator shows "Retrying without knowledge search".**

Kai couldn't use File Search for that message (for example, the attached store was deleted), so it answered without your files. Check that every store under **File Search** still exists in **Knowledge Base**, remove any **(unknown vector store)** entries, and click **Save Changes**.

**Does Kai search all my vector stores?**

No. Kai only searches the stores attached under **File Search** on the agent node that is handling the conversation.

**Which formats work best?**

PDF with selectable text, DOCX, TXT, MD, JSON and CSV. For Excel files, saving as CSV gives the most reliable results. See [Which format should I use?](#which-format-should-i-use).

**Can I see which page or row Kai used?**

In the Emulator, the **file\_search** card shows the search queries and how many passages were found. Kai's reply itself is written for your customer.

## Privacy note

* When you add a file to a vector store, a copy of the file is sent to our AI provider, where it is stored and indexed so your agents can search it.
* Vector stores belong to your workspace. Only agents in your workspace that have the store attached under **File Search** can search it.
* Detaching a file or deleting a store stops your agents from searching that content. The original file stays in your File Manager until you delete it there.
* Only upload information you are comfortable with Kai sharing with customers. Avoid files with passwords, payment card details, or personal data that customers shouldn't see.

## Related

* [Knowledge base](https://docs.klink.cloud/kai-ai-agent-chat/knowledge-base)
* [How to setup AI Agent (Step by Step Guide)](https://docs.klink.cloud/kai-ai-agent-chat/how-to-setup-ai-agent-step-by-step-guide)
* [Recipe: Let Kai answer first](https://docs.klink.cloud/advanced-setup/workflow-automation/recipe-let-kai-answer-first)