> ## 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](/concepts/knowledge-and-features) answers "what does the document say"; for an action against your systems, write a [tool](/concepts/skills-and-tools) 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](/get-started/install)).
* The documents, each up to 100 MB: PDF, Word, Excel, PowerPoint, images, email files, HTML, Markdown, plain text, EPUB, or JSON.

<Steps>
  <Step title="Dashboard: Upload the documents">
    Open the admin dashboard with `lua admin`, select the agent, and add each file in the **Knowledge** section. A file is processed and then indexed; its status in the list moves from pending to `completed`, or to a failed state shown there. 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.
  </Step>

  <Step title="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, the agent's **Getting started** dialog switches the feature; 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 Agent** dialog pre-selects it; `enable` on a feature that is already on prints that it is already enabled.
  </Step>

  <Step title="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
    ```
  </Step>

  <Step title="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](/concepts/persona) 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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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** section in the admin dashboard edits them.

### Remove a document

`lua resources delete --resource-name "<name>"` removes a resource from the CLI; the admin dashboard's **Knowledge** section does the same for uploaded files.

## If it isn't working

<AccordionGroup>
  <Accordion title="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>

  <Accordion title="Feature &#x22;<name>&#x22; 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>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Next steps

<Columns cols={2}>
  <Card title="About knowledge and features" href="/concepts/knowledge-and-features">How knowledge reaches the prompt and the full feature catalog.</Card>
  <Card title="lua features" href="/reference/cli/features">List, enable, disable, view, and configure.</Card>
  <Card title="lua resources" href="/reference/cli/resources">List, view, and delete resources.</Card>
  <Card title="For operators" href="/get-started/for-operators">What you change in the admin dashboard and what needs an engineer.</Card>
</Columns>