> ## Documentation Index
> Fetch the complete documentation index at: https://help.agentsy.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# File Search and Retrieval

> Learn how an Agentsy AI assistant uses uploaded knowledge, how retrieval-augmented generation works, and how to improve the reliability of knowledge-based answers.

# File Search and Retrieval

Your AI Experience can use uploaded documents to answer questions about your services, expertise, methodologies, and educational content. **File search** helps the assistant find relevant passages when a visitor asks a question.

The objective is not simply to upload more information. It is to make the **right information easy to find, understand, and use**.

> [!NOTE]
>
> File search supports an assistant's answers; it does not guarantee that every answer is correct. Test important questions before sharing your AI Experience publicly.

## How file search works

A typical knowledge-based response follows this process:

1. **You prepare source documents.** These might include your methodology, service descriptions, FAQs, or educational guides.
2. **You upload the documents to your assistant's knowledge base.** The system prepares the content for retrieval.
3. **A visitor asks a question.** For example: "What should I consider before buying a used boat?"
4. **File search identifies relevant material.** The assistant can use retrieved passages to inform its response.
5. **The AI generates an answer.** It combines the retrieved information with its instructions and the conversation context.

This approach is commonly called **retrieval-augmented generation (RAG)**: retrieving relevant source information to help generate an answer.

> [!NOTE]
>
> The assistant does not necessarily read every uploaded document in full for every message. The quality and relevance of retrieved content matter more than the total number of files.

## File search vs. system instructions

These serve different purposes:

| Component | What it controls | Example |
| - | - | - |
| **System instructions** | How the assistant behaves, responds, and handles boundaries | "Never claim access to current inventory unless a live inventory source is available." |
| **Knowledge documents** | The subject matter and reference information the assistant can use | "Guide to inspecting a used boat before purchase." |
| **Visitor conversation** | The immediate question and relevant context | "I'm looking for a family boat for weekend trips." |

Use system instructions to define *rules and behavior*. Use knowledge documents to provide *substantive information*.

## What makes information easier to retrieve?

### 1. Give each document a clear purpose

Prefer a focused document called **Buying Used Boats: Inspection and Due Diligence** over a single file containing unrelated sales notes, maintenance tips, and marketing copy.

### 2. Use descriptive headings

Organize content under headings that reflect real visitor questions:

* What should I inspect before buying a used boat?
* What does a marine survey cover?
* What costs should I budget beyond the purchase price?
* When should I speak with a broker?

### 3. Write complete, understandable explanations

Avoid isolated bullet points that depend on missing context. Define specialized terms and explain when recommendations apply.

### 4. Separate stable guidance from changing facts

Educational material about boat types may remain useful for years. Available inventory, pricing, regulations, and product terms can change frequently.

Do not imply that a document upload creates a live connection to external systems. If current information is required, use a verified up-to-date source or direct the visitor to a person who can confirm it.

### 5. Remove contradictions and outdated versions

If two documents give conflicting instructions, the assistant may produce inconsistent answers. Keep one authoritative version of each policy or service description where possible.

## Practical example: an insurance education assistant

Imagine an insurance professional who provides educational guidance about life insurance, health insurance, and fixed annuities.

Their knowledge base might contain:

* **Insurance Education Principles** — the assistant's educational scope and explanations of general concepts.
* **Term vs. Permanent Life Insurance** — differences, typical considerations, and terminology.
* **Health Insurance Costs** — premiums, deductibles, copayments, and out-of-pocket maximums.
* **Fixed Annuity Fundamentals** — general features, limitations, and questions to discuss with a licensed professional.

A visitor asks: *"What's the difference between a deductible and an out-of-pocket maximum?"*

The assistant should retrieve relevant educational material and explain the distinction clearly. It should **not** infer the visitor's specific plan benefits, request sensitive health details, or present general education as individualized advice.

> [!WARNING]
>
> For regulated or sensitive topics, retrieval is not a substitute for professional review, current authoritative information, or appropriate privacy safeguards.

## How to test retrieval quality

After uploading or changing documents, test the assistant with questions whose answers you can verify directly against the source material.

| Test | Example question | What to check |
| - | - | - |
| Direct fact | "What are the steps in your advisory methodology?" | Are the steps correct and complete? |
| Paraphrase | "How does your process help someone get started?" | Does the assistant find the same information with different wording? |
| Cross-topic | "How do budget and maintenance affect my decision?" | Does it combine relevant information without inventing details? |
| Missing information | "Which boats are available today?" | Does it acknowledge the lack of live inventory? |
| Contradiction | "Your older guide says something different. Which applies?" | Does it avoid unjustified certainty? |
| Out-of-scope | "Can you guarantee this investment outcome?" | Does it respect the assistant's boundaries? |

> [!TIP]
>
> Start with five to ten representative questions from real prospects. Keep a simple log of the question, expected source, actual answer, and changes needed.

## Troubleshoot common retrieval problems

### The assistant ignores an uploaded document

* Confirm the file was uploaded to the intended assistant and is available for use.
* Check that its content is readable text rather than an image-only scan.
* Give the document a clear title and descriptive headings.
* Try a direct question about a fact that appears explicitly in the file.
* Review whether the assistant's instructions allow it to use uploaded knowledge.

### The assistant answers too generally

* Replace vague notes with specific explanations, examples, and definitions.
* Split unrelated topics into focused documents.
* Test questions that resemble how visitors actually ask for help.
* Review the system instructions for guidance on using knowledge without overclaiming.

### The assistant gives an outdated answer

* Review the underlying source and replace obsolete information.
* Check for duplicate documents containing older versions.
* Add a clear effective date to time-sensitive material when relevant.
* Avoid presenting uploaded documents as live data.

### The assistant invents details

* Make the limits of available information explicit in system instructions.
* Include clear guidance for situations where the source does not contain an answer.
* Test unsupported questions deliberately.
* Route requests requiring current, personal, or verified information to the appropriate human or trusted system.

### The assistant mixes information from different services

* Separate service-specific documents.
* Use unambiguous headings and terminology.
* Explain distinctions between offerings in your source material.
* Test similar questions for each service to identify confusion.

## A simple improvement cycle

1. **Identify** a response that is incomplete, incorrect, or too generic.
2. **Find** the source document that should support it.
3. **Improve** the document's clarity, structure, or accuracy.
4. **Adjust** system instructions if the problem concerns behavior rather than missing facts.
5. **Retest** the original question and a few related variations.
6. **Repeat** as your services and visitor needs evolve.

> [!NOTE]
>
> Do not upload confidential client records, personal health information, credentials, or other sensitive data unless you have established that the intended processing is authorized and appropriate for your use case.

## Related guides

* [Knowledge Base Overview](/knowledge-management/knowledge-base-overview)
* [Upload Documents](/knowledge-management/upload-documents)
* [Organize Your Knowledge](/knowledge-management/organize-your-knowledge)
* [Update Your Knowledge](/knowledge-management/update-your-knowledge)
* [Knowledge Best Practices](/knowledge-management/knowledge-best-practices)
* [Troubleshoot Responses](/knowledge-management/troubleshoot-responses)
* [System Instructions](/create-and-configure/system-instructions)
* [Testing Your Assistant](/create-and-configure/testing-your-assistant)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.