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.