Skip to main content
The knowledge base is a workspace-wide document library. Add a source once — an uploaded Markdown or plain-text file — and attach it to any number of agents. In conversation, the agent draws on attached sources to answer questions its instructions alone can’t cover: product details, policies, FAQs, procedures.

​
Add sources

Sources come in two scopes:
  • Workspace sources live in the shared library. Add them from the workspace-level Knowledge base page with Add file — choose a .md or .txt file (UTF-8 text, up to 1 MB) and give the source a name and an optional description. Workspace sources can be attached to any number of agents.
  • Agent-private sources belong to a single agent. On your agent’s Knowledge base tab, New private file creates a source that is attached to that agent immediately. It doesn’t appear in the shared library, can’t be attached to other agents, and is not listed by the knowledge-sources API.
To attach a shared source to an agent, open the agent’s Knowledge base tab and click Import from global knowledge base. Every source is plain text and stays editable after upload: open a source to view its content and edit the text in place — you never re-upload a file to make a change.
PDF, Office, and scanned documents are not supported. Convert them to Markdown or plain text first.

​
Upload validation

Files are validated, parsed, and indexed as part of the upload itself — there is no background processing to wait for. When the upload succeeds, the source is immediately available to attached agents. If the file is empty, over 1 MB, or not UTF-8 text, the upload is rejected with an error and nothing is created — fix the file and try again.

​
Folders

Group sources into folders with New folder, and rename sources from the row menu. Deleting a folder never deletes its sources — anything inside moves back to All sources.

​
Share sources across agents

Workspace sources belong to the workspace, not to a single agent (agent-private files offer only Edit and Delete). In the library, the Used by column shows how many agents attach each source, and Manage access lists every agent with a toggle:
  • Attach — turn an agent on to give it access to the source.
  • Detach — turn an agent off. The source stays in the library and remains attached to other agents.
Editing a source propagates to every agent that attaches it — you never update agents one by one. Each attached agent shows the edit as an unpublished draft change.
Delete removes a source from all agents that reference it, not just the one you’re editing. To remove a source from a single agent, detach it with Manage access instead.

​
How your agent uses knowledge

​
Small corpora are inlined

If the total size of an agent’s attached sources is 8 KB or less, the full content is inlined into the agent’s instructions. This is the fastest path: the agent has everything up front, with zero per-turn lookup cost.
Inlined knowledge produces no retrieval events. If your corpus is small and you don’t see retrieval activity, nothing is wrong — the content is already in the prompt.

​
Larger corpora are searched per turn

Above 8 KB, the agent searches attached sources on every turn, using the user’s latest message as the query, and injects the best-matching passages into that turn’s context. The search runs under a fixed time budget: if it can’t complete in time, the turn is answered without retrieved context. Retrieval never delays the agent’s reply.

​
Publishing pins revisions

When you publish an agent, the published version pins the then-current revision of every attached source. Sessions read the pinned revisions, so edits you make mid-call never leak into an in-progress conversation. Publish again to roll updated content out.

​
Limits

Attaching more than 100 sources to one agent is rejected with 422.

​
Manage sources over the API

Knowledge sources are exposed at /v1/agent/knowledge-sources. Only workspace sources appear on this surface — agent-private files are a console-only convenience:
Only the source file part is required on create — name falls back to the uploaded file’s name.
DELETE returns 409 while the source is still attached to any agent — in its draft or its published version. Call the dependents endpoint to see which agents use it, then detach it from each — remove its id from knowledge_base.knowledge_source_ids in an agent update — and republish any agent whose published version still references it. Deleting from the console instead removes the source from all agents at once, after a confirmation.

​
Going further

Agent configuration

Instructions, voice, and everything else your agent is made of.

Versions & publishing

How publishing snapshots your agent — knowledge revisions included.

Preview calls

Talk to your draft and check knowledge answers before publishing.

Conversation history

Review transcripts of past sessions.