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 in aixplain Desktop and build it in code with the Agents SDK. For what happens behind the scenes, see How knowledge bases work.

Where each step happens

You can also do these steps in code. See Build it with the Agents SDK.

Create a knowledge base in the web app

1. Sign in at 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.

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.

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.

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.
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.

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.

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 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

Get help

• Learn how it works: see 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.