Knowledge collections
A prompt tells an agent how to behave. A collection tells it what is true about your business: the contracts, the product docs, the pricing page that changed last week. It searches them when it needs them, and pays nothing for them when it does not.
A named set of reference material
A collection groups documents an agent can search as one body. It carries a name, an optional description, its chunking settings, and a refresh schedule that decides how often URL-backed documents are re-indexed.
Manual is the default and means re-index only when asked. A file's content never changes, so the schedule only changes anything for URL-backed documents. Split collections by what an agent should be allowed to see rather than by topic: the collection is the unit you attach to an agent, so it is also the unit of access.
Three ways in, four states
A document arrives as an uploaded file, as a web URL, or captured from an email triage rule when an attachment lands in a watched mailbox. Whichever way it arrives, indexing runs in the background.
| Status | Meaning |
|---|---|
pending | Queued. Nothing has been read yet. |
indexing | Being extracted, chunked and embedded. |
ready | Searchable. Only ready documents are returned by a search. |
error | The run failed. The document carries the reason. |
indexing is asynchronous
indexing and you poll until it reaches ready. Telling someone the knowledge base is live while it is still queued is how an agent ends up searching an empty collection.Individual documents can be re-synced or deleted without touching the rest of the collection. Indexing consumes embedding credits, so a re-sync of a large document is not free.
The page is the source of truth
For a URL document, the indexed chunks are only a retrieval index. The document records where it came from and when it was last synced, and every search match from one is flagged live, with the instruction to re-read the source before relying on the detail. The agent then reads the live page rather than the stored copy — so a price that changed this morning is the price it quotes, even though the index was built last week.
Uploaded files are the opposite and are meant to be: a file is a snapshot, which is what you want for a signed contract.
The Documents card is the switch
Creating a collection does not give any agent access to it. The Documents card on an agent's Config tab is what puts a collection in that agent's search scope, and attaching one is what grants the agent its document tools. A search outside its bound collections is rejected.
From an MCP client the same binding is a config patch: agnt_agents_update_config with document_collection_ids. See building an agent.
The knowledge family
Six tools cover the whole loop: create a collection, add sources, wait for them to index, and check that the collection answers the questions the agent will be asked before you wire it on.
| Tool | What it does |
|---|---|
agnt_knowledge_list_collections | The workspace's collections with their chunking config and refresh schedule. Read-only. |
agnt_knowledge_create_collection | Creates a collection. Chunking defaults suit prose; raise the chunk size for reference tables and dense technical documents. |
agnt_knowledge_list_documents | The documents in a collection with their indexing status and last error. This is the poll target after adding one. |
agnt_knowledge_add_document | Adds a source and starts indexing it. Returns before indexing finishes. |
agnt_knowledge_ingest | Re-indexes a document that already exists, after its source changed or a previous run errored. |
agnt_knowledge_search | Semantic search over one collection, returning the best-matching chunks with their source document and similarity. |
- 01
Create, then add
Create the collection, then add each source to it by id. A URL document needs its URL; a file document needs a workspace file id from an upload. - 02
Poll before you trust it
List the documents until every one you added readsready. - 03
Search it yourself first
Run the questions your agent will be asked. If the chunks coming back are wrong, fix the chunking or the sources now, not after the agent has answered a customer with them.
The Knowledge module
Document collections, ingestion and retrieval. It is sold as a module on the builder plans, from $19/mo, with a 7-day free trial. The feature plans include it.
| Tier | Price | Allowance |
|---|---|---|
| starter | $19/mo | 3 collections · 500 documents · 2 GB |
| growth | $39/mo | 15 collections · 5,000 documents · 20 GB |
| scale | $79/mo | 50 collections · 25,000 documents · 100 GB |
published allowances
Indexing consumes embedding credits, and a search embeds its query, so it consumes a small amount too. See plans and Toolkit modules and credits and wallets.