Knowledge bases

Documents, chunked and embedded, retrieved at conversation time.

API

Full parameters and responses: knowledge base reference.

GET    /api/v1/knowledge-bases
POST   /api/v1/knowledge-bases
GET    /api/v1/knowledge-bases/{id}
PATCH  /api/v1/knowledge-bases/{id}
DELETE /api/v1/knowledge-bases/{id}
POST   /api/v1/knowledge-bases/{id}/query
GET    /api/v1/knowledge-bases/{id}/documents
POST   /api/v1/knowledge-bases/{id}/documents
GET    /api/v1/knowledge-bases/{id}/documents/{documentId}
POST   /api/v1/knowledge-bases/{id}/documents/{documentId}/retry
DELETE /api/v1/knowledge-bases/{id}/documents/{documentId}

Ingestion

Upload a file or point at a URL. The document is chunked, embedded and stored in Postgres with pgvector. Ingestion is asynchronous: a document has a status, and a failed one can be retried without re-uploading.

Retrieval

Hybrid: vector similarity plus lexical search, then re-ranked. topK bounds how many chunks reach the prompt — the same trade-off as tool responses, because retrieved text competes with conversation history for the context window and for latency.

Knowledge-only mode

knowledge_only: true is intended to constrain the assistant to what retrieval returned: when nothing relevant comes back it should say so instead of inventing an answer. knowledge_only_plan carries the thresholds (min_passages, min_score) and the action (ask, escalate, transfer, end_call).

The policy class is never called

KnowledgeOnlyPolicy implements exactly the behaviour above. Nothing invokes it — not a controller, not a job, not the gateway. knowledge_only and knowledge_only_plan are validated, stored and resolved into the call snapshot, and no code reads them at run time. Setting knowledge_only: true has no additional runtime effect.

What a caller does experience comes from a different, simpler mechanism: the knowledge tool's own safetyMode, on by default in the gateway's tool executor, which emits knowledge.insufficient when retrieval comes back weak. That is independent of the assistant's flag and is not configurable through knowledge_only_plan.

validate still refuses to publish a knowledge-only assistant with no knowledge base attached — which is a real check on a setting that then does nothing. See What is not built.

As a file

name: Product manual
provider: native
chunkSize: 800
chunkOverlap: 120
topK: 6
documents:
  - name: Returns policy
    source: ./docs/returns.md
  - name: Pricing
    source: https://example.com/pricing

WARNING

callagent apply creates and updates the knowledge base itself. Uploading document content through the CLI is not implemented yet — add documents through the API or the dashboard.

Custom providers

A knowledge base can delegate retrieval to your own endpoint instead of the native store. CallAgent posts the query and conversation context and expects chunks back.

Which backends are implemented

pgvector (the native store) and custom (your endpoint) are the two that work. Qdrant, Pinecone and Weaviate exist as options in the enum so the interface can say "not yet" honestly — they are not implemented.

Embeddings are generated by OpenAI only; no other embedding provider has an adapter.