Guides

Set up a knowledge base

Create a knowledge base, upload documents, and attach it to an agent for Agentic-RAG.

1. Configure an embedding provider

A knowledge base needs an embedding provider (see Connect a provider — the same provider mechanism is used for embeddings as for chat models). It is required when the knowledge base is created and cannot be changed afterwards.

2. Create the knowledge base

Create it in the app (Project → Knowledge) or with the Consumer API:

POST /v1/projects/{project_id}/knowledge
{
  "name": "Product Docs",
  "embed_provider_config_id": "<provider_config_id>"
}

The name cannot be blank, and if you set chunk_size / chunk_overlap (characters, not tokens) the overlap must be smaller than the chunk size.

This provisions a dedicated, isolated storage partition for the knowledge base — scoped per organization, project, and knowledge base so no cross-tenant access is possible at the storage layer.

3. Upload documents

POST /v1/knowledge/{kb_id}/documents   (multipart/form-data)

PDF, TXT, MD, DOCX and CSV files up to 3 MB are accepted; anything else is refused right away. Uploads are processed asynchronously: chunking → embedding → storage. Check GET /v1/knowledge/{kb_id}/documents to see ingestion status — a document that could not be indexed is failed and its failure_reason tells why.

To send several files in one request, use the batch endpoint (up to 20 files, repeat the multipart field files):

POST /v1/knowledge/{kb_id}/documents/batch   (multipart/form-data)

It answers 202 with one entry per file in results, each accepted (with the document) or rejected (with the reason): a refused file never blocks the others. POST /v1/knowledge/{kb_id}/documents/text/batch does the same for up to 20 Markdown or plain-text documents ({"documents": [{"title": "…", "content": "…"}]}), and MCP clients have the add_text_documents tool. The dashboard's upload button also accepts several files at once.

4. Test retrieval directly (optional)

POST /v1/knowledge/{kb_id}/search
{ "query": "How do I connect a provider?", "top_k": 5, "score_threshold": 0.4 }

Each result has a similarity (0–1); score_threshold drops weaker matches. This is useful for sanity-checking retrieval quality before wiring the knowledge base into an agent. The knowledge base page in the dashboard has the same check behind its Search button, and MCP clients can use the search_knowledge tool.

5. Attach it to an agent

In the agent's configuration, attach the knowledge base and choose how the agent uses it:

  • When required (on_demand) — the agent decides for itself when to retrieve (recommended default)
  • Each input (always) — retrieval runs before every generation, unconditionally

In a flow, a RAG Retrieval step always retrieves; an Agent step uses the agent's own setting when Use Agent Knowledge is on.

6. Run the agent

Ask a question the agent can only answer from your uploaded documents, and confirm retrieved context appears in the inference-steps panel before the final answer.

On this page