Knowledge bases

A Knowledge base holds the documents an Agent may cite. Vocal ingests each Document into passages, publishes versions of the set, and retrieves passages for a Call either as context in the model request or through the search_knowledge Tool.

On the Phase 0 host. Served since contracts 1.53.0: part of the routes since deploy #60 and the rest since deploy #61, with ingestion running on the host.

Build a Knowledge base

1. POST /v1/knowledge-bases creates the draft and names its embedding Provider and model, which the Compliance profile must allow.
2. POST /v1/knowledge-bases/{knowledge_base_id}/sources adds a Source. An upload Source waits for files; a url Source starts its first sync at once, and its URL passes the egress guard. A connection Source is planned.
3. POST /v1/knowledge-bases/{knowledge_base_id}/documents uploads a file to an upload Source as multipart/form-data. The file is encrypted under the Organization's data key, the Document is created pending, and an Ingestion run starts. Ingestion runs show its progress.
4. POST /v1/knowledge-bases/{knowledge_base_id}/versions freezes the configuration and the latest indexed revision of every Document as the next version. It refuses, in one 422, a pending Document unless exclude_pending is set, a set with no indexed Document, and a failed retrieval-quality gate.
5. Activate the version. Activating an older version is the rollback, and a Call in progress keeps the version it resolved.

Measure retrieval before you publish

The corpus holds the questions a version must answer well: add a query, then evaluate a version or the working set. Once the corpus holds a query, a publish needs a current Evaluation whose gate passed.

Query

POST /v1/knowledge-bases/{knowledge_base_id}/query runs the same hybrid retrieval a Call uses over the active version, or the one version names: semantic and keyword candidates fused by reciprocal rank fusion, cut by min_score, top_k and max_context_tokens. Without include, the passages carry no text and the citations no names, and nothing is audited; include=text or include=names makes the query an audited content read.

Use it in an Agent

knowledge on the Agent draft binds up to 8 Knowledge bases, each with a fixed filter, its limits, and whether passages enter the request as context, through the search_knowledge Tool, or both. Publishing the Agent freezes the bindings into the version. Each retrieval in a Call is the Call event knowledge.retrieved, and the Call trace carries the citations.