Setting Up a Knowledge Base

A knowledge base (KB) gives an agent private, searched context. When an agent has a KB attached, the platform retrieves the most relevant passages for each run and adds them to the agent's context (this is retrieval-augmented generation, or RAG). This guide covers creating a KB, getting documents into it, and attaching it to an agent.

Knowledge bases are scoped to a single AI Employee: every KB belongs to exactly one AI Employee, and its documents are only searched by that AI Employee's agents.

Roles. Creating knowledge bases, uploading files, connecting sources, and triggering syncs are admin actions (system admin or builder admin). Builders with the plain builder role pick from the KBs that already exist and scope them at the agent. If you need a new KB or a new source connection, ask an administrator.

Two ways to add documents

A knowledge base gets its content one of two ways:

File upload: drag files (or a folder) straight into the KB. No credentials, no schedule. These are "local file" knowledge bases.
Connected source: point the KB at an external system so documents sync in automatically. Supported connectors are SharePoint, Google Drive, Confluence, Box, and ServiceNow.

A connection holds the credentials and configuration for an external source. Connections are created and owned by admins, separately from KBs, so one connection can back several KBs scoped to different folders or sites.

Step 1: create the knowledge base

Open the AI Employee and go to its Knowledge bases.
Create a knowledge base. Give it a clear name and description (builders see these when attaching it to an agent).
Choose its source: a local-file KB (upload), or a connected source backed by a connection.

When you create a KB you also choose its intent, which selects the ingestion pipeline:

Search (the default): documents are chunked, embedded, and indexed for retrieval. This is what you want for almost every KB.
Extraction: the document's full extracted text is stored as a single LLM-ready artifact and is not chunked or indexed for search. Use this only for the file-upload-and-extract pattern, where an agent reads a whole document rather than searching across many.

Step 2: add documents

By upload

In the KB detail view, drag files or a folder onto the upload area, or use the file picker. You can upload a single file or a batch. Each file kicks off ingestion in the background; the document list shows its status as it moves from queued to processed.

Uploads accept .txt, .md, .csv, .html, .pdf, .docx, .pptx, .xlsx, .png, .jpg, .webp, and .gif, up to 50 MB each. Files of other types are skipped during ingestion.

By connecting a source

For a connected KB, an admin configures the connection's scope (for example, which SharePoint sites, Google Drive folders, Confluence spaces, Box folders, or ServiceNow knowledge bases to pull from) and a sync configuration that controls how often the KB re-syncs (manual or on an interval). You can trigger a sync on demand from the KB's Sync config tab, and review past syncs in Sync logs.

Incremental syncs only re-ingest documents that changed, so repeated syncs are cheap.

Source connectors authenticate per provider. SharePoint, Confluence, Box, and Google Drive use an OAuth consent flow that a Workspace administrator completes once when creating the connection. ServiceNow scopes are entered as URLs and resolved to the right knowledge base, category, article, or attachment automatically.

Step 3: let ingestion process the documents

Once a document arrives (by upload or sync) it runs through the ingestion pipeline:

Text extraction: text is pulled from the file. PDFs, Office documents (.docx, .xlsx, .pptx), HTML, and images are all supported; images are described and OCR'd by a vision model.
Chunking: the extracted text is split into passages sized for retrieval.
Embedding: each chunk is embedded into a vector so it can be matched against a query.
Storage: chunks and their embeddings are stored and indexed.

You don't configure chunk size or the embedding model per KB. The embedding model is a platform-level setting shared across the Workspace. What you control is the source content and, for connected KBs, the sync scope and schedule.

Watch the document list for status:

Processed: chunked, embedded, and searchable.
In progress: still ingesting.
Failed: extraction or processing errored. You can retry a failed document from its row.

The KB shows a processed-document count, which is what builders see when attaching the KB.

Reading PDFs as images (vision extraction)

By default, Ema reads PDFs through their text layer: fast, exact, and free. Handwriting, ticked boxes, stamps, and signatures are not part of a text layer, so they are dropped silently while ingestion reports success. If your PDFs contain any of those, turn on Read PDFs as images in the AI Employee's Configuration tab.

This setting is available on any AI Employee that owns a knowledge base or accepts a file as a workflow input.

Vision extraction costs per page and uploads take considerably longer (roughly 63 seconds per page against sub-second for text extraction). Leave it off for PDFs that are entirely typed text.

When the switch is on, three additional settings appear:

Model: by default, the same model the AI Employee already uses reads the PDF pages (the "Use the AI Employee's model" option). Switch to "Use a different model" to pin a separate vision-capable model for PDF reading only. The AI Employee keeps its own model for everything else.
Page limit (under Advanced settings): the maximum number of pages read as images per PDF. Pages beyond the limit are still extracted as text. Leave the field empty to use the platform default (50 pages).
When a PDF is over the limit (under Advanced settings): choose what happens when a PDF exceeds the page limit.

Option	What happens
Read the first pages as images, the rest as text	Nothing is lost. The pages most likely to carry handwriting are read properly; the rest still arrive as text.
Read the whole file as text	Fastest, no per-page cost. Handwriting and marks in this file are dropped, the same as with the feature off.
Report an error	The file does not arrive and the failure is reported. Use this when an over-length file is a mistake you want to hear about.
Skip the file quietly	The file does not arrive and no error is raised. Use this for a large shared drive where long files are expected.

These settings apply to files uploaded from the point you save them. Documents already in a knowledge base are not re-processed.

Overriding vision extraction for one knowledge base

By default, a KB's PDFs are processed using the text layer. The Read PDFs as images card on the KB's documents tab lets you override this per KB, so PDFs in that KB are processed by looking at every page as an image instead. This is useful for scans, handwriting, stamps, and tick marks that the text layer misses.

Each KB can carry its own override or inherit from its AI Employee. Fields you leave empty follow the AI Employee; set a field to control it for this KB only.

The card lets you configure:

Read PDFs as images: turn vision extraction on or off for this KB. When left empty, the KB follows the AI Employee's setting.
Page limit for one document: the maximum number of pages to process as images per document. Leave empty to inherit from the AI Employee (or from the extraction default when the AI Employee also sets none).
If a PDF is longer than the limit: choose what happens when a document exceeds the page limit: read the first pages as images then use the text layer, use the text layer only, stop and report a failure, or skip the document.
Model: which model to use for vision extraction. For a KB that has an AI Employee, this is opt-in: enable Choose a model for this knowledge base to override the AI Employee's selection. A group-owned KB has no AI Employee to inherit from, so you must choose a model before vision can be turned on.

To save your changes, click Save. To remove all overrides and return the KB to the AI Employee's settings, click Use the AI Employee's settings. This button appears only when the KB has an active override and is hidden for group-owned KBs (which have nothing to fall back to).

Group-owned knowledge bases. A KB that belongs to a group rather than a single AI Employee has no AI Employee to inherit vision settings from. The card works the same way, except that every field must be set explicitly and you must choose a model before turning vision on.

Partial overrides. The override is a partial blob: send only the fields this KB sets. Omitting a field means "inherit from the AI Employee." Setting a field to its default does store that value on the KB. It stops inheriting that field even if the AI Employee later changes it. To stop overriding a field, use Use the AI Employee's settings to clear the whole override, or leave the field empty when you first save.

Step 4: attach the knowledge base to an agent

KBs are searched only when an agent references them. To attach one:

Open the agent in the AI Employee builder. Knowledge base support appears for the agent types that use retrieval: search and respond, document agent, and custom.
In the Knowledge bases section, open the dropdown and select one or more KBs. Each option shows the KB's name, description, and processed-document count.
Save the agent configuration.

At run time the agent's search-and-respond loop retrieves relevant passages from the attached KBs and uses them to answer. For text-output agents, the platform also tracks which sources were used and surfaces citations on the response.

Scoping retrieval

You can narrow what an agent searches without changing the KB itself:

Tag filters: if a KB's documents are tagged (via its taxonomy), select specific tags so the agent only searches documents carrying them.
KB filtering: when an agent has more than one KB attached, you can enable KB filtering and give the agent natural-language instructions for choosing which KB to search per query, plus a per-KB label.
Search settings: under Advanced settings, tune retrieval behavior (such as how many passages to retrieve) for the agent.

An agent searches a KB only if you attach it. Uploading documents to a KB does nothing for an agent until that KB is selected in the agent's Knowledge bases section.

What's next

Writing effective Instructions: tell the agent how to use the searched knowledge.
Build your first workflow: put a knowledge-backed agent into a workflow.
Core concepts: how knowledge bases fit into the platform.