Introducing connic files: Persistent File Storage for AI Agents

Today we are shipping connic files, file storage built into every connic environment. A report or download that an agent saves today is still there when next month's run or another agent needs it.

Files that outlast the run

Many agent tasks produce or collect a file: a monthly report, an invoice from a supplier portal, a table exported from a web app. Until now, a browser download disappeared when the browser session closed, and connic had no built-in place where the next run, or the next agent, could pick up a file.

With connic files, agents choose the path when they save a file, such as invoices/2026/acme.pdf, and a folder appears as soon as a file lands in it. Files stay until an agent, a team member, or an API client deletes them. Each environment keeps its own tree, so runs in staging never touch production files. File contents are encrypted at rest with a separate key for each environment.

A write never replaces an existing file by accident. When a path is already taken, the new file is stored under a numbered name such as acme (2).pdf, unless the write explicitly asks to overwrite.

Read, write, and organize files

Five file tools give an agent access to the tree: file_list, file_read, file_write, file_update, and file_delete.

An agent can read files of up to 20 MiB with file_read. Text files reach the model in full, never as a shortened excerpt, so their whole length counts against the model's context window. PDFs and PNG, JPEG, GIF, or WebP images arrive as attachments, provided the agent's model accepts that input type; otherwise the model request fails. The model catalog lists the supported inputs for each model. For any other format, the tool returns the file's details with an error, so the agent can pass the path to the browser or a custom tool.

Agents write text files such as Markdown reports, CSV exports, or JSON, and missing folders are created along the way. They also rename and move single files or whole folders, update metadata, and delete what is no longer needed.

Custom tools import the same functions from connic.tools. In custom code, file_read returns the raw bytes of any file, and file_write also accepts bytes, for example a PDF that the tool generated.

See where every file came from

connic records which agent, run, and session wrote each file, and whether it came from an agent, the browser, the dashboard, or the API. The platform sets these fields, and agents cannot change them. A question like "which files did yesterday's failed run write?" becomes a filter instead of a search through logs.

Agents and team members can add their own metadata, such as a customer ID or a processing status. file_list filters on both kinds of fields with the same query operators as the connic database, and sorts and pages through the results. With a status field, an agent can work through a folder in order. This custom tool picks the oldest new invoice and marks it as in progress:

from connic.tools import file_list, file_update

async def next_pending_invoice() -> dict:
    """Return the oldest invoice that still needs processing."""
    result = await file_list(
        "invoices",
        recursive=True,
        filter={"status": "new", "_mime_type": "application/pdf"},
        sort={"_created_at": 1},
        limit=1,
    )
    if not result["files"]:
        return {"done": True}
    invoice = result["files"][0]
    updated = await file_update(invoice["_path"], metadata={"status": "processing"})
    return updated["file"]

Move files in and out of the browser

Agents that work on websites with the browser tools can store what they find. With save_to, a download goes straight into files, up to 100 MiB. The same option saves a page as a PDF, keeps the full result of a script that extracted data from a page, or stores a single network response or a HAR file of the recorded traffic.

It works in the other direction too. web_browser_upload puts a stored file into a website's upload field, in the same run or weeks later. Another agent can then submit an invoice downloaded from one portal to an accounting system. Longer browser scripts can also be stored as files and run from there.

# Save a download straight into files (up to 100 MiB)
await web_browser_download("e12", include_content=False, save_to="invoices/acme/")

# Put a stored file into an upload field
await web_browser_upload("e7", path="contracts/signed/acme.pdf")

Decide what each agent can see

Without further configuration, an agent can use the whole tree. A files block in the agent's YAML narrows that down, the same way agents are already limited to certain database collections or retrieval namespaces:

• Folders: The agent sees only the listed folders and everything below them. Files elsewhere are invisible to it.
• Read-only and no deletes: prevent_write and prevent_delete block changes for the whole agent or for single folders.
• Session only: With session_only, the agent sees only files written in its current session. With a session per customer, files the agent saved for one customer stay out of reach when it serves the next.

Settings on a folder override the agent-wide ones. In this support agent, files the agent saves under cases stay within the current customer's session, while the templates folder is shared and read-only:

session:
  key: input.customer_id

files:
  session_only: true          # only files written in this customer's session
  prevent_delete: true
  folders:
    cases: {}
    templates:
      session_only: false     # shared by every session
      prevent_write: true

connic applies these rules to every file tool call, including calls from custom tools, and to browser transfers. A file an agent cannot see is never replaced: if its path is taken, the new file gets a numbered name instead. The dashboard and the API show the whole tree to team members and API keys with file permissions.

Example: collect and process supplier invoices

Two agents share an invoices folder. A cron connector starts the collector once a month. It opens the supplier portal, downloads the invoice into invoices/<supplier>/, and marks it with the status new. Neither agent can delete invoices or see anything outside the folder.

version: "1.0"

name: invoice-collector
model: connic/claude-sonnet-5.5
description: "Downloads supplier invoices and files them"
system_prompt: |
  Download this month's invoice from the supplier portal and save it
  under invoices/<supplier>/. Mark new invoices with status "new".

tools:
  - web_browser_open
  - web_browser_observe
  - web_browser_act
  - web_browser_download
  - file_list
  - file_update

files:
  folders: [invoices]
  prevent_delete: true

In a later run, the bookkeeper finds the new invoices by their status, reads each PDF, and files it under invoices/processed/. It needs a model that reads PDFs; the example uses Claude Sonnet 5.5.

version: "1.0"

name: invoice-bookkeeper
model: connic/claude-sonnet-5.5
description: "Extracts invoice data and files processed invoices"
system_prompt: |
  Find invoices under invoices/ with status "new". Read each PDF and
  return supplier, invoice number, date and total as JSON. Then set its
  status to "processed" and move it to invoices/processed/<file name>.

tools:
  - file_list
  - file_read
  - file_update

files:
  folders: [invoices]
  prevent_delete: true

Manage files in the dashboard, API, and MCP

The Files page in the dashboard shows the tree of the selected environment. Team members upload files of up to 1 GiB by picking or dropping them, preview images and text files, edit custom metadata, and move, rename, or delete files and folders, individually or in bulk. Filters narrow the list to one source, agent, run, or session, and the details of a run or session link straight to the files it wrote.

The REST API covers the same operations for other systems: listing and filtering, uploads of up to 1 GiB, metadata updates, and short-lived download links. Through connic MCP, a coding agent can upload test inputs, check what an agent wrote, and clean up afterwards from the same chat where it builds the agents.

Limits and billing

Stored files and downloads are billed from Project credit. Downloads are files leaving through the dashboard or the API, and stored files an agent uploads or runs as scripts in the browser. Files that agents read with the file tools are not billed as downloads. Pricing lists the current rates.

Get started

1. 1

   Update the composer SDK. The file tools, the files block, and the browser options in this article need version 0.1.54 or later:

   Copy

   pip install --upgrade connic-composer-sdk

2. 2

   Give an agent the file tools. Add the tools it needs and, if it should not see the whole tree, a files block with its folders. Browser agents save downloads there with save_to.

3. 3

   Deploy and run. Open Files in the dashboard to see what the agent saved, with the agent, run, and source of each file.