Knowledge collections

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.

Each workspace's collections live on the Documents page in the superagnt app: create one there, then upload files or add URLs to it. A file can be a PDF, a DOCX, a CSV, or text such as Markdown or JSON. Mail is covered below.

Individual documents can be re-synced or deleted without touching the rest of the collection.

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 document tools are agnt_documents_search and agnt_documents_read, and only deployed agents have them; an MCP client searches with agnt_knowledge_search instead. Search is semantic, over one bound collection, and returns the best-matching chunks, each with its similarity score and the document it came from: id, name, kind, and the URL of a URL document. Read returns one document's current content by id, fetching a URL document's live page or extracting a file document's stored file, and refuses a document outside the agent's collections. It reads in three modes, so an agent loads only the lines it needs.

Each fits a different question: search for what the documents say about something, grep for an exact figure, name or clause, and read a window only when a passage has to be read in order. The rest of a deployed agent's tools are on agent tools.

Filed, read in place, or sent

An email triage rule with the Save attachments action files a matching message's attachments into the collection the rule names. Each PDF, DOCX, CSV or text attachment, up to ten per message, is saved as a workspace file and added to the collection as a file document, then indexed like an upload. The email body is never saved. The action combines with the rule's others, which run in a fixed order: label, save attachments, archive, escalate.

Pick the collection in the rule editor on the Email page in the superagnt app. Over MCP, agnt_email_triage_create_rule (in the opt-in email family) takes save_to_documents among its actions with a document_collection_id, and agnt_email_triage_context lists the collections a rule can target. Attachments that would take the organization past a knowledge cap are skipped, and the rule's other actions still run.

Connecting a mailbox writes its starting triage rules, which take effect once you turn triage on for it. They include a rule that saves document attachments into a collection named Email Attachments, and your superagnt and the Inbox Manager are attached to that collection, so they can search whatever triage files. Retarget or delete that rule like any other.

An agent with a mailbox's tools can also read an attachment without filing it. connection_gmail_list_attachments and connection_outlook_list_attachments list a message's file attachments, and connection_gmail_read_attachment and connection_outlook_read_attachment read a PDF, DOCX, CSV or text attachment in the same three modes as agnt_documents_read.

Sending goes the other way. The save_draft, send_email, reply_all and forward_message tools of both mailboxes (connection_gmail_* and connection_outlook_*) take attachment_file_ids, the ids of workspace files: from agnt_files_upload for a new file, or from agnt_files_list for one already in the workspace, an attachment triage saved included. A message carries up to 20 files and 25 MB in all. A forward keeps the original's attachments and adds yours; on Gmail, when both together pass 25 MB, the original's are left off and listed in the result's omittedAttachments. On a deployed agent a send asks for approval by default, and the request names every attached file with its size.