Browse docs
On this page
Attachments
Let users attach files with the paperclip button, drag and drop, or paste. Files upload before the message is sent. Images and PDFs require a model that supports them. With a sandbox enabled, the agent can also use their original bytes for OCR, conversion, and editing. Other files are read through tools or analyzed in a sandbox.
Enable Allow file attachments on the agent and configure file storage when self-hosting. To verify the setup, attach a short text file and ask the assistant to summarize it.
Draft recovery
Uploaded file IDs and metadata stay with the local draft. Reloading restores them without sending. File bytes and signed URLs are never saved locally. Clearing storage removes draft references. Uploads do not expire, but files still uploading cannot be recovered yet.
Options
Pass attachments: false to turn the feature off, or an object to narrow it.
Supported files
How a file reaches the agent
For other file types, the agent receives a handle and reads the contents through tools. File contents, names, and table labels remain user input or tool results, never system instructions.
read_attachmentreads plain text files without a sandbox, in pages of up to 40,000 characters. See Limits.- Results include type and size. Ask the agent to calculate sheet names, column types, row counts, and totals in the sandbox.
- Agents with a sandbox receive the original file at
uploads/<name>when they first use a sandbox tool. - Large files can exceed the sandbox's 30-second transfer timeout, particularly with Docker. Split the file if analysis fails during sandbox startup.
- New Office and data attachments, including CSV and TSV, require a sandbox. Visible thumbnails do not provide their contents to the agent.
- Earlier attachments remain downloadable if sandbox access becomes unavailable. You can continue chatting and reading plain text, but rereading Office and data requires restored access.
- Attachments are agent policy: when the dashboard disables them, the endpoint refuses files and the widget hides the attach button. See Security model.