Knowledge Bases

A knowledge base (KB) is a private collection of documents that an AI Employee's agents can search at run time. When an agent needs grounding (answering from your policies, your product docs, your help center) it retrieves the most relevant passages from its attached knowledge bases and reasons over them. This is retrieval-augmented generation (RAG): the model's answer is grounded in your content, and it can cite the exact sources it used.

A knowledge base belongs to exactly one AI Employee. It is scoped by ai_employee_id, so a KB's content is only ever searched by the AI Employee that owns it.

How a knowledge base works

Documents flow through an ingestion pipeline, then become searchable:

1. Connect or upload. A KB draws its documents from a connector (SharePoint, Google Drive, Confluence, Box, ServiceNow) or from direct file uploads.
2. Extract. The pipeline extracts text from each document, including PDFs and Office files (.docx, .xlsx, .pptx).
3. Chunk. The text is split into overlapping chunks (by default about 1024 tokens per chunk with 128 tokens of overlap) so each chunk is small enough to embed and large enough to carry meaning. Overlap keeps context from being cut at chunk boundaries.
4. Embed. Each chunk is turned into a vector embedding by EmaFusion™. The embedding model is a platform-level setting shared by all Workspaces.
5. Store. Chunks and their embeddings are stored in a vector index, with the document's folder path kept alongside for filtering.

Once a document finishes ingesting, its chunks are immediately searchable.

Vision PDF extraction

By default, the pipeline reads the text layer inside a PDF. That is fast and exact, but handwriting, drawn tick marks, stamps, and signatures are not in a text layer, so they are dropped silently while ingestion reports success.

Read PDFs as images renders every PDF page and reads it with a vision model instead, recovering content that the text layer cannot see. Turn it on when your PDFs contain handwriting, ticked boxes, stamps, or scanned pages.

This setting is on the AI Employee's Configuration tab. It appears only when the AI Employee receives documents — either through a workflow input of type file or through an attached knowledge base. The setting is stored as vision_extraction_enabled on the workflow config and applies to files uploaded from that point on; documents already in a knowledge base are not re-read.

What is configurable

When vision extraction is on, the Configuration tab exposes additional settings saved to vision_extraction_config:

Advanced fields — concurrency, DPI, and per-page token limit — are bounded by the platform and cannot be set in the UI. Values written via the API are clamped: concurrency to 25, DPI to 400, and max tokens to 32768. A value outside the bound is replaced with the platform default rather than failing the extraction.

The config blob preserves any keys not managed by the UI (prompts, block_layout, cache_read_enabled, and others) so saving settings from the Configuration tab does not overwrite API-only fields.

Retrieval at run time (RAG)

When an agent with attached knowledge bases runs, the platform performs a vector search:

1. The agent's query is embedded with the same model used for the documents.
2. The platform runs an approximate-nearest-neighbor search (an HNSW index) over the KB's chunks using cosine similarity (similarity = 1 − distance).
3. Chunks scoring below the agent's min_score floor (default 0.15) are dropped, and the top top_k matches that remain are ranked by similarity and injected into the agent's context with numbered source labels so the model can cite them.

Retrieval is tunable per agent through its type_config. Values outside the valid range are ignored and fall back to the default:

For new search-and-answer workflows, use a Custom Agent with a Knowledge Base attached. Write Instructions to answer from the retrieved documents and cite the sources it uses.

Folders and the folder filter

Documents carry a folder path from their source. You can scope an agent's retrieval to a subset of a knowledge base with a folder filter (a path prefix the search must match).

The folder filter is applied at search time, not at ingestion time. That has two practical consequences:

• Adding or changing a folder filter on an agent takes effect on the next run, with no re-ingestion.
• One knowledge base can serve several agents, each scoped to a different folder.

For example, a single "Company Docs" KB might back an HR agent filtered to policies/hr/ and a finance agent filtered to policies/finance/, with no duplicate ingestion.

Document Library folder scoping

When a knowledge base is connected to a Document Library source, you can scope it to one or more specific folders using a browse-by-name interface. Open the KB's source settings and use the folder picker to select folders by name; the KB will only ingest and search documents within the selected folders.

This scoping is set at the KB level (not the agent level) and takes effect on the next sync. It works alongside the agent-level folder filter described above (the KB only ingests the selected folders, and agents can further narrow retrieval within that set).

Search and extraction knowledge bases

A knowledge base has an intent that determines how its content is prepared:

• Search (the default): content is chunked, embedded, and indexed for vector retrieval. This is what RAG agents query.
• Extraction: the full extracted text is stored as a single LLM-ready document, with no chunking or embedding. Use this when an agent needs the whole document (for example, an Extraction agent reading an uploaded file) rather than retrieved passages.

Vision extraction configuration

By default, PDF ingestion uses the MarkItDown pipeline. Vision extraction (which converts pages as images for an LLM to read) can be enabled per knowledge base, overriding the AI Employee's setting on a per-key basis.

How the override works

Vision extraction config is a partial override, not a snapshot. Each key you set on a knowledge base wins over the same key on the AI Employee's config; keys you leave absent keep inheriting from the AI Employee. Sending {"enabled": true, "max_pages": 7} overrides only those two keys; every other setting (model selection, DPI, prompts) still comes from the AI Employee.

A knowledge base with no vision config set (the default) has config: null, which means inherit, not off. The knowledge base resolves exactly as it did before this option existed.

To clear an override and go back to inheriting, send PUT /knowledge-bases/{id}/vision-extraction-config with {"config": null}. There is no separate DELETE.

The override applies in both directions: a knowledge base can turn vision on under an AI Employee that has it off, or turn it off under one that has it on.

Connector-synced PDFs

PDFs synced from connectors (SharePoint, Google Drive, Confluence, Box) now honor the vision_extraction_enabled flag. Previously, connector-synced PDFs always used the MarkItDown pipeline regardless of the AI Employee's vision settings. Both manual uploads and connector syncs now use the same config resolution.

Configuring vision extraction per knowledge base

Use the standalone routes, not any AI Employee-nested path. A knowledge base may be owned by a group rather than an AI Employee, and group-owned knowledge bases can only be addressed through the standalone path.

Get the current override:

GET /knowledge-bases/{id}/vision-extraction-config

Returns {"config": null} when no override is set (the knowledge base inherits from its AI Employee).

Set or replace the override:

PUT /knowledge-bases/{id}/vision-extraction-config
Content-Type: application/json

{"config": {"enabled": true, "max_pages": 7}}

Send only the keys this knowledge base overrides. Absent keys continue to inherit from the AI Employee.

Clear the override (inherit everything from the AI Employee):

PUT /knowledge-bases/{id}/vision-extraction-config
Content-Type: application/json

{"config": null}

Access control: GET requires use tier. PUT requires edit tier.

Configurable keys

Unknown keys (DPI, system prompt, temperature, concurrency, and others added by the extraction service) are stored untouched and passed through to extraction.

Who can access the Knowledge Bases card

The Knowledge Bases card on the AI Employee configuration page is visible to:

• Any user with a workspace-level builder (or higher) role.
• Any user holding a per-AI-Employee Admin grant, even if their workspace role is not a builder role.

This matches the underlying API, which admits both groups.

How a knowledge base stays current

• Connector sync keeps a KB aligned with its source. Sync runs on a schedule (or on demand) and uses incremental change detection so unchanged documents aren't re-processed.
• Document triggers can run a workflow when a document finishes ingesting in an attached KB (useful for pipelines that act on newly added content). The run executes against the AI Employee's live published version.
• Version snapshots capture which documents a workflow version searched, so reverting a published version reconciles the KB back to that state. See Workflows.

Where to go next

• Agents — how a Custom Agent uses Knowledge Bases.
• Integrations and data — connecting sources and managing knowledge bases.
• EmaFusion™ — the model layer that embeds documents and queries.