Knowledge / RAG

Retrieval-Augmented Generation (RAG) lets agents answer questions based on your documents. Instead of relying solely on the LLM’s training data, the agent searches a knowledge base and includes relevant passages in its context before generating a response.

How it works

Create a knowledge base and upload documents to it.
On upload, the engine automatically chunks each document, computes embeddings, and stores the chunks + vectors in PostgreSQL (pgvector). No restart or manual indexing step is required.
Link one or more knowledge bases to an agent, and add the Knowledge capability to that agent. The capability automatically injects a knowledge_search tool — you do not assign the tool manually.
When the agent calls knowledge_search, the engine runs a vector similarity search across the agent’s linked knowledge bases and returns the most relevant passages.
The agent uses those passages to generate grounded, accurate responses.

# Indexing + retrieval flow:
#
#   Upload faq.md, returns-policy.pdf  --> chunked, embedded, stored in PostgreSQL
#
#   Agent (with the Knowledge capability + a linked KB) calls
#     knowledge_search("return policy for electronics")
#   --> Engine finds the most relevant chunks from returns-policy.pdf
#   --> Agent answers: "Our electronics return policy..."

Storage model

Knowledge bases are stateless: the searchable knowledge — the chunks and their embeddings — lives entirely in PostgreSQL/pgvector. The engine does not persist the raw uploaded file; the original file name is kept as metadata so it still appears in the file list. This keeps deployments free of a per-pod file volume, so the engine restarts and reschedules cleanly.

Practical implications:

Indexing is automatic on upload. A file moves through uploading → indexing → ready (or error), visible in the Admin Dashboard and the files API.
To re-index a document, re-upload it. There is no separate re-index step — re-uploading replaces the document’s chunks.

Isolation

Each knowledge base is independent, and an agent searches only the knowledge bases linked to it. Link sales materials to the sales agent and HR policies to the HR agent, and neither can read the other’s documents — useful for multi-tenant and role-based setups. One knowledge base can be linked to multiple agents, and one agent can use multiple knowledge bases.

Best practices

Keep documents focused — smaller, topic-specific documents work better than large monolithic ones.
Use clear headings — Markdown headings help the chunking algorithm split documents at logical boundaries.
Update regularly — keep knowledge bases current. Outdated information leads to incorrect agent responses. Re-upload a document to refresh its content.
Tell the agent to cite sources — add instructions in the system prompt to reference which document the answer came from.
Set honest boundaries — instruct the agent to say “I don’t know” rather than hallucinate when the knowledge base does not contain the answer.

Setting up knowledge

Admin Dashboard

Go to Knowledge Bases in the sidebar and create a knowledge base (give it a name and an embedding model).
Upload .txt, .md, .csv, .pdf, or .docx files. Each file indexes automatically; watch the status reach ready.
Open your agent → Capabilities → add the Knowledge capability and link the knowledge base.

knowledge_search is now available to the agent, scoped to its linked knowledge bases.

API

# Create a knowledge base
curl -X POST http://localhost:8443/api/v1/knowledge-bases \
  -H "Authorization: Bearer bb_your_token" \
  -H "Content-Type: application/json" \
  -d '{"name": "product-docs", "description": "Product documentation", "embedding_model_id": "your-embedding-model"}'

# Upload a file (indexed automatically; supported: txt, md, csv, pdf, docx)
curl -X POST http://localhost:8443/api/v1/knowledge-bases/product-docs/files \
  -H "Authorization: Bearer bb_your_token" \
  -F "file=@./docs/faq.md"

# List files and watch indexing status (uploading -> indexing -> ready)
curl http://localhost:8443/api/v1/knowledge-bases/product-docs/files \
  -H "Authorization: Bearer bb_your_token"

# Link a knowledge base to an agent (the agent also needs the Knowledge capability)
curl -X POST http://localhost:8443/api/v1/knowledge-bases/product-docs/agents/sales-bot \
  -H "Authorization: Bearer bb_your_token"

# To re-index a document after its content changes, re-upload it — the same
# upload endpoint above. Knowledge is stateless, so re-upload replaces re-index.