Docs contents

Knowledge files

Knowledge files give a hosted agent reference material on every run, so you don't have to pass the same content in each request. Files live in your workspace Resources; you choose which ones each agent gets.

Adding files to Resources

Open Resources in the sidebar. You can:

Click Upload, or drag and drop a file onto the page
Click New file to write a text file in the editor
Group files into folders with New folder

Uploading a file with the same name as an existing one replaces it.

Format	Notes
`.txt`, `.md`, `.markdown`	Plain text and Markdown
`.csv`, `.json`	Structured data, best for small reference tables
`.xlsx`, `.xls`	Converted to CSV on upload (first sheet only)
`.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`	Stored as files for integrations that attach them, such as posting an image. Agents cannot read image contents, so don't attach images as knowledge

Each file can be up to 10 MB. PDF is not supported: export the text to .txt or .md first.

Attaching files to an agent

Open the agent → Configuration → Knowledge
Toggle on the files the agent should get
Click Save changes in the bar that appears

Attached files are added as text to the agent's system prompt, under a Reference Material section, at the start of every run.

Size budget

Attached files share a budget of 200 KB per run. Files are added in alphabetical order by filename; a file that would push the total over the budget is skipped, and smaller files after it can still fit.

Every attached file is sent with each model call, so large files also raise token costs. To keep runs lean:

Trim files to the parts the agent needs
Split large documents into smaller, topic-focused files and attach only the relevant ones
For large or rarely needed files, don't attach them; let the agent read them on demand (see below)

Reading and writing files during a run

Hosted agents have three built-in tools for Resources:

read_resource reads a file by its filename, only when the agent needs it
write_resource creates or overwrites a file. Files written during a run appear as that run's artifacts
generate_image makes a picture from a prompt with your workspace's OpenAI or Google key and saves it as a new file

Enable them in the agent's Tools tab.

To manage files from code, use the control plane (resources.* and folders.*) or the matching MCP tools (resources_list, resources_get, resources_create, resources_delete, folders_list, folders_create, folders_delete).

Records: structured data

Files are for documents and pictures. For data that changes one item at a time (a queue of items to process, a list of leads, a settings object), use Records: named collections of JSON objects. A collection exists once it has a record.

Agents and scripts have six built-in tools, enabled in the Tools tab:

Tool	Does
`records_list { collection, where?, order?, limit?, after? }`	A page of a collection as `{ records, next }`, newest first by default. `where` keeps records whose top-level fields match the values given (see Matching below). Pass `next` as `after` for the following page.
`records_count { collection, where? }`	How many records a collection holds, or how many match `where`, as `{ count }`.
`records_get { id }` or `{ collection, key }`	One record, by its id or by its key.
`records_create { collection, key?, data }`	Adds a record and returns it with its `id`. With `key`, the record is the only one of its collection with that key.
`records_update { id, set, if? }`	Lays `set` over the record's top-level fields; a `null` removes a field. With `if`, only while the record still matches those values.
`records_delete { id, if? }`	Removes one record. With `if`, only while the record still matches those values.

records_update with if answers { matched: true, record } or { matched: false }; records_delete with if answers { deleted: true, id } or { deleted: false, matched: false }. That is how two runs never take the same item: both ask to move it from open to working, and one is told it did not match.

const { records } = await tools.records_list({ collection: "tickets", where: { status: "open" } });
for (const ticket of records) {
  const taken = await tools.records_update({
    id: ticket.id,
    set: { status: "working" },
    if: { status: "open" },
  });
  if (!taken.matched) continue; // another run has it
  // ... work on the ticket ...
}

Keys. A key is text of up to 320 characters, such as an email address, stored as given and never changed. A second records_create with a key that a record of the collection already has is refused, and the refusal names that record, so a list holds each item once whoever adds it.
Limits. 32 KB a record, 100 records a page, 50,000 records a workspace. A page of large records ends early (about 48 KB), with next set.
Names. A collection name is lowercase letters, digits and underscores, starts with a letter, and is at most 60 characters.
Who. Every member can read records. Owners and admins can change them with a key; a run changes them through its tools, whoever started it.
Matching. where and if compare top-level fields. A string, number or boolean must be the same; a list or object matches when the record's contains it; null matches a field that is null, not one that is absent.
Test runs write nothing: a write tool answers with what it would have done.

From code, use the control plane (records.*) or the MCP tools of the same names.

Removing a file

Toggle the file off in the agent's Knowledge tab and save to detach it. The file stays in Resources and can be attached again later. Deleting a file from Resources removes it for every agent.