Quickstart
Provision the index, create a knowledge base, upload a document, and ask an agent about it.
1. Provision the index, once per tenant
Open Knowledge Bases. If the tenant has never indexed anything, it offers to set up the index first. Accept it.
This creates a knowledge schema in your tenant's database with three tables: the
documents, which knowledge bases each belongs to, and the chunks with their vectors. It is
safe to run again; it creates nothing that exists and deletes nothing that does.
Already-indexed documents survive re-initialisation. The routine only creates what is missing, deliberately, so recovering from a half-finished setup never costs you an index.
2. Create a knowledge base
| Field | Notes |
|---|---|
| Name | For you, and shown to an agent as the source of a passage. |
| Description | Worth writing. An agent choosing between several bases reads it. |
| Alias | Optional stable handle, so a tool can refer to it by something you chose. |
Leave the processing and query settings alone for now. The defaults index reasonably for prose, and Retrieval covers when to change them and which ones actually do something.
3. Upload a document
Drop a file onto the knowledge base. It uploads, then indexes in the background, and the document's status moves through:
pending → processing → completedA document that cannot be read lands on failed with the reason on the row. The chunk
count appears when it finishes, which is the first useful signal: a 40-page PDF that
produced four chunks did not extract properly, whatever its status says.
4. Ask it something
Each knowledge base has a test box. Type a question and it does the whole retrieval, then has a model answer from what came back.
curl -X POST https://service.ensembleapp.dev/api/knowledge-bases/{id}/test \
-H 'Authorization: Bearer <jwt>' \
-H 'Content-Type: application/json' \
-d '{ "query": "What is our refund window?", "topK": 15 }'Read the passages, not just the answer. The answer tells you whether a model could compose something from the passages; the passages tell you whether retrieval found the right material, which is the part you can actually fix.
A confident answer built on the wrong passages is the failure mode to watch for. If the similarity scores are all clustered low, retrieval found nothing good and the model wrote around it.
5. Give an agent access
Create a RAG tool pointed at this knowledge base, then add that tool to the agent. From then on the agent can search, and each search appears in its trace with the passages it got back.
The alternative is attaching the knowledge base to the agent directly, which makes retrieval always-on rather than something the agent chooses. See Retrieval.