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

2. Create the knowledge base

POST /api/v1/projects/{id}/knowledge-bases
{
  "name": "Product Docs",
  "embed_provider_config_id": "<provider_config_id>"
}

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 /api/v1/knowledge-bases/{id}/documents   (multipart/form-data)

Uploads are processed asynchronously: chunking → embedding → storage. Check GET /api/v1/knowledge-bases/{id}/documents to see ingestion status.

4. Test retrieval directly (optional)

POST /api/v1/knowledge-bases/{id}/query
{ "query": "How do I connect a provider?", "top_k": 5 }

This is useful for sanity-checking retrieval quality before wiring the knowledge base into an agent.

5. Attach it to an agent

In the agent's configuration, attach the knowledge base. Decide the retrieval mode when using it inside a flow's RAGNode:

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

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.