# Create and use a knowledge base

A **knowledge base** gives your agents your own documents to search and answer from. This article explains how to create one in the web app, add and edit what's in it, give it to Omni or an agent you built, use it from **[aixplain One](https://www.aixplain.com/support/articles/get-started-with-omni)** in aixplain Desktop and build it in code with the Agents SDK. For what happens behind the scenes, see **[How knowledge bases work](https://www.aixplain.com/support/articles/how-knowledge-bases-work)**.

> Knowledge bases work on every plan. You create and edit them in the web app at app.aixplain.com or with the Agents SDK. In aixplain Desktop, Omni sees your team's knowledge bases, can create one for you and can add one to an agent you build. aixplain Desktop is in early releases (version 0.x), so features can change from one release to the next.

## Where each step happens

| Step | Web app | aixplain Desktop |
| --- | --- | --- |
| Create a knowledge base | **Assets** → **New asset** → **Tool** | Ask Omni |
| Add files | When you create it | Ask Omni, which adds them as text |
| Add, edit and delete records | The **Index data** page | Ask Omni |
| Give it to an agent | **Tools** in chat, or **Add Tool** in Studio | **Add tool or integration** in **Configure** |
| Share it with your team | The **Personal** switch on its page | Shared from the web app |

You can also do these steps in code. See **[Build it with the Agents SDK](#build-it-with-the-agents-sdk)**.

## Create a knowledge base in the web app

1. Sign in at **[app.aixplain.com](https://app.aixplain.com)** and open **Assets**.
2. Select **New asset**, then **Tool**.
3. Find **aiR Knowledge Base** among the integrations and select it.
4. Select **Connect aiR Knowledge Base**, or **Connect new** if you already have one.
5. In **Configure aiR Knowledge Base**, select **Upload files** and choose the files to add. The form shows the file types it accepts and how many files you can add.
6. Give it a **Name** and a **Description**. Say what's inside, such as "Our refund and shipping policies, 2026", so agents know when to search it.
7. Under **Actions**, keep only what the agent needs. An agent that only answers questions needs only search.
8. Select **Connect**. The knowledge base is created and shows in **Assets**, ready to give to an agent.

You can start in other places too:

- **In Chat:** in the message box, select **+**, then **Tools**, and pick **aiR Knowledge Base** in the **Capability Library**. It's created and added to Omni's tools for that chat.
- **In Studio:** in the agent builder, select **Add Tool** and pick **aiR Knowledge Base**.

> **Important:** An agent can do everything its **Actions** allow. If you leave writing or deleting on, the agent can change or remove what's stored. Keep it to search unless the agent is meant to maintain the knowledge base.

## Give a knowledge base to an agent

### Omni on the web

1. In **Chat**, select **+**, then **Tools**.
2. Select **aiR Knowledge Base**, pick your knowledge base and select **Done**.
3. Ask a question it can answer, such as "What's our refund window for damaged items?"

### An agent you build in Studio

1. Open the agent in the agent builder.
2. Under **Tools**, select **Add Tool** and pick your knowledge base.
3. Tell the agent in its instructions when to search it, for example "Search the policy knowledge base before you answer any question about refunds."
4. Test it in the chat beside the builder and read the trace to see the search step.

> **Note:** An agent decides on its own when to use a tool. If it answers without searching, say in its instructions that it must search the knowledge base first.

### Example requests

- "Using the policy knowledge base, what do we owe a customer whose order arrived late?"
- "Find every contract clause about termination notice and quote each one."
- "Search the product catalog for chairs under 300 dollars and name the document for each."

## Browse and edit what's stored

Each knowledge base has its own page, with **Overview**, **Try** and **Integration** tabs. To open it, go to **Assets** and select the knowledge base.

To see and change its records, select the database icon, **Browse and edit index data**, at the top of the page. The **Index data** page shows how many chunks are stored and lists each record with its text and metadata.

- **Search:** type a question, such as "how are invoices issued?", and select **Search**. Results show a **Score** for how closely each one matches.
- **Filter:** select **Filter by metadata**, then **Add condition**, to show only records with a field value you set.
- **Add text:** select **Add record**, enter the **Text** and any **Metadata** as a JSON object, and choose whether to **Split into chunks**. Leave **Record id** empty to generate one.
- **Edit or delete:** select **Edit** or **Delete** on a record. Deleting can't be undone.

> **Note:** Only the knowledge base's owner sees the **Index data** page. Teammates you share it with can use it in their agents.

The **Try** tab runs the knowledge base's actions by hand, so you can test a search without an agent.

## Share or delete a knowledge base

- **Share it:** on its page, turn off the **Personal** switch and confirm **Share with team**. Your team can then give it to their agents. Turn **Personal** back on to make it yours alone.
- **Delete it:** on its page, select **Delete** and confirm. This deletes the knowledge base and everything in it, and can't be undone.

## Use a knowledge base in aixplain Desktop

When you're signed in to aixplain in the desktop app, Omni sees the knowledge bases on your team, along with your agents, models and connections. To see them yourself, open **Omni settings → Your aixplain** and look under **Knowledge bases**.

### Ask Omni

Omni can work with knowledge bases for you in the chat. It asks before any step that uses credits or changes data in your workspace.

- "Which knowledge bases does my team have?"
- "Create a knowledge base from the PDFs in my Contracts folder."
- "Search the policy knowledge base for our refund rules and summarize them."

A knowledge base stores text, so Omni turns your files into text before it adds them.

### Add a knowledge base to an agent you build

1. Open the agent beside the chat and select **Configure**. To build one first, see **[Build and deploy agents with Omni](https://www.aixplain.com/support/articles/build-and-deploy-agents-with-omni)**.
2. Under **Tools**, select **Add tool or integration**.
3. Search for the knowledge base, and under **aixplain tools** select **Add** next to it.
4. Select **Save**, or **Save for team** to share the agent with your team.

> **Important:** A knowledge base added from **Configure** isn't limited to search. To keep the agent read-only, ask Omni to limit the knowledge base to search, or give it to the agent in the web app, where you choose its **Actions**.

Agents that run on your computer, and Koder, don't use knowledge bases.

## Build it with the Agents SDK

In the Agents SDK, a knowledge base is a tool on the aiR integration. Create it, add records, then give it to an agent with search only.

```python
from aixplain import Aixplain

aix = Aixplain(api_key="YOUR_API_KEY")

kb = aix.Tool(
    name="Product catalog",
    description="Product catalog with prices and categories.",
    integration="aixplain/air-knowledge-base/aixplain",
).save()

kb.run(action="upsert", data={"records": [
    {"id": "prod1", "text": "Wireless headphones with noise cancellation. Price: $199.", "metadata": {"category": "electronics", "price": 199}},
    {"id": "prod2", "text": "Ergonomic office chair with lumbar support. Price: $299.", "metadata": {"category": "furniture", "price": 299}},
]})

kb.allowed_actions = ["search"]
agent = aix.Agent(
    name="Product assistant",
    description="Answers questions about the product catalog.",
    instructions="Search the product catalog to answer. Include the price.",
    tools=[kb],
).save()

print(agent.run("What electronics do you sell under $200?").data.output)
```

- **Choose the embedding model:** pass `config={"model": MODEL_ID}` when you create it, with a model ID from the Marketplace.
- **Change the chunking:** pass `chunking` with `split_by`, `split_length` and `split_overlap` when you add records.
- **Filter a search:** pass `filters` with a field, an operator and a value.

The SDK adds text, so turn files into text before you add them. See **[Knowledge base](https://docs.aixplain.com/assets/tools-and-integrations/knowledge-base)** in the docs for every action and option.

## Limitations

- In the web app, files are added when you create a knowledge base. After that, you add text records on the **Index data** page.
- Chat answers don't show source links yet. Ask the agent in its instructions to name the document each fact came from.
- Koder and agents that run on your computer don't use knowledge bases.
- Only the owner can browse and edit records on the **Index data** page.

## Troubleshooting

### The agent answers without searching the knowledge base

Say in the agent's instructions that it must search the knowledge base before answering, and name it. Then check the run's trace for the search step.

### The answer is wrong or missing something I know is in the documents

Search for the same question on the **Index data** page. If the right passage doesn't come up, the question and the document may use different words, or the passage was split across chunks. Add a record with the key passage, or add the document again with longer chunks in the SDK.

### The SDK says an action is not allowed

The knowledge base was limited to search for an agent, and that limit also applies to your own calls. Set `kb.allowed_actions = []` before you run other actions yourself.

### A file wasn't added

A file with no readable text, such as a scan with no text layer, is reported instead of added. Files over 100 MB, or more than 100 documents in one request, are refused. Split the work into smaller batches.

## Frequently asked questions

### Can several agents use the same knowledge base?

Yes. Give it to as many agents as you like. Share it with your team so their agents can use it too.

### Can Omni on the web and Omni in aixplain Desktop use the same knowledge base?

Yes. Both see the knowledge bases on your team when you're signed in. They don't share sessions or settings yet.

### How do I see which documents an answer came from?

Open the run's trace: the search step shows what the knowledge base returned, with each chunk's ID. To have the answer name its sources, say so in the agent's instructions.

## Get help

- **Learn how it works:** see **[How knowledge bases work](https://www.aixplain.com/support/articles/how-knowledge-bases-work)**.
- **Report a problem:** email **care@aixplain.com** with the knowledge base's name, the agent, what you asked and what you expected. Remove credentials and private data first.
- **See what changed:** read the **[release notes](https://www.aixplain.com/release-notes)**.