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

# Add knowledge

> Upload documents, turn on Knowledge Search, and verify the agent answers from them

After this guide, your agent answers questions from documents you upload, with no code change and no release. Files are uploaded in the admin dashboard; the CLI has no upload command, and its interactive `lua resources` menu creates typed-text resources only. [Knowledge](https://docs.heylua.ai/concepts/knowledge-and-features.md) answers "what does the document say"; for an action against your systems, write a [tool](https://docs.heylua.ai/concepts/skills-and-tools.md) instead.

*Verified against lua-cli 3.33.0.*

**Before you begin**

* An agent, created with `lua init` or in the admin dashboard, and signed in with `lua auth configure` ([Install and sign in](https://docs.heylua.ai/get-started/install.md)).
* The documents, each up to 100 MB: PDF, Word, Excel, PowerPoint, images, email files, HTML, Markdown, plain text, EPUB, or JSON.

**1. Dashboard: Upload the documents**

Open the admin dashboard with `lua admin`, select the agent, and in **Knowledge sources** on its **Overview** tab select **+** › **Upload file** for each file (10 MB at most). A file is processed and then indexed; its badge moves from **Processing** to **Published**, or to **Failed**. A file of another type is refused with `Unsupported file type: <type>. Supported types include PDF, Office documents, images, emails, and more.`

Each resource is split into overlapping chunks and embedded for semantic search, and the platform writes a one-line summary the model sees.

**2. Turn on Knowledge Search**

Knowledge is searched only while the `rag` feature is on. Enabling it adds one tool, `searchKnowledgeBase`, which takes a natural-language `query` and an optional `resourceId`. In the admin dashboard, switch it on under **Features** in the agent's settings menu; from the terminal:

```bash theme={null}
lua features enable --feature-name rag --ci
lua features list --ci
```

```text Output theme={null}
============================================================
🎯 Agent Features
============================================================

1. ✅ Knowledge Search (RAG)
   Name: rag
   Status: Active
…
```

An agent created in the admin dashboard usually starts with `rag` on, because the **Create your agent** dialog pre-selects every capability it lists; `enable` on a feature that is already on prints that it is already enabled.

**3. Terminal: Check the resources**

`lua resources list` prints each resource with a preview, and `view` prints one in full. An uploaded file is listed under its file name, extension included, once processing completes, and that name is what `--resource-name` takes. Resources created in the interactive `lua resources` menu (**Create new resource**) are plain text typed in your editor.

```bash theme={null}
lua resources list --ci
lua resources view --resource-name "refund-policy.pdf" --ci
```

**4. Tell the model when to search**

The prompt lists every resource with its ID and summary, so the model can search all of them or focus on one document when it knows which holds the answer. Add a line to the [persona](https://docs.heylua.ai/concepts/persona.md) that names the documents and says when to use them, for example "Answer refund and delivery questions from the knowledge base, and say so when it has no answer." In code, push it with `lua push agent --force --ci`: a pushed persona is served from the agent's next message, with no version or promote needed. In the admin dashboard's **Persona** tab, select **Publish changes** for the same effect.

**5. Verify**

Knowledge and features are shared between the sandbox and production environments, so a sandbox chat is enough.

```bash theme={null}
lua chat -e sandbox -m "How many days do customers have to request a refund?"
lua logs --type rag --limit 5
```

The reply should carry a fact that exists only in the document; the log shows the `searchKnowledgeBase` call and the passages it returned.

## Options you may need

### Add web search alongside

`lua features enable --feature-name webSearch` adds `searchWeb`, a query-based search that returns an answer with source links; it does not open arbitrary URLs. Use it for public facts that change, and knowledge for your own material.

### Edit what the model is told about a feature

Each feature carries instructions the runtime renders into the prompt. `lua features view --feature-name rag` prints them; the agent's **Features** page in the admin dashboard edits them (**Edit instructions**, then **Save instructions**; **Reset to default** restores the platform text).

### Remove a document

`lua resources delete --resource-name "<name>"` removes a resource from the CLI; in the admin dashboard, open the file in **Knowledge sources** and select **Delete**.

## If it isn't working

> [accordion] The answer ignores the document
>
> **Cause** `rag` is off, or the file is not yet `completed`. **Fix** Check `lua features view --feature-name rag` and the file's status in the admin dashboard; `lua logs --type rag --limit 5` shows whether a search ran at all.

> [accordion] Feature "\<name>" not found
>
> **Cause** Feature names are case-sensitive identifiers such as `rag` and `webSearch`, not their titles. **Fix** Copy the `Name:` value from `lua features list`.

> [accordion] Unsupported file type
>
> **Cause** The admin dashboard accepts documents, images, and email files only. **Fix** Export the content as PDF, Markdown, or plain text and upload that.

## Next steps

> [card] [About knowledge and features](https://docs.heylua.ai/concepts/knowledge-and-features.md)
>
> How knowledge reaches the prompt and the full feature catalog.

> [card] [lua features](https://docs.heylua.ai/reference/cli/features.md)
>
> List, enable, disable, view, and configure.

> [card] [lua resources](https://docs.heylua.ai/reference/cli/resources.md)
>
> List, view, and delete resources.

> [card] [For operators](https://docs.heylua.ai/get-started/for-operators.md)
>
> What you change in the admin dashboard and what needs an engineer.


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