Send files in and out
Uploads land read-only in /workspace/files. Anything the agent writes to
/workspace/outputs is saved as an output file you can download.
You need: a deployed runtime (Deploy) and the CLI or an SDK runner (Run tasks from your backend).
1. Tell the agent where files live
Uploads in /workspace/files are read-only; new files you write there are saved.
Write every deliverable to /workspace/outputs. Anything else is lost when the task ends.2. Upload and attach
--file @<path> uploads and attaches in one step; repeat it for more files.
introspection tasks create --runtime support-agent --environment staging \
--file @./contract.pdf --prompt "Review contract.pdf and write report.md"3. List the task’s outputs
Outputs are named tasks/<task-id>/outputs/....
introspection files list --filter task_id=<task-id> --filter category=output -o table4. Download
introspection files content <file-id> --out report.mdVerify
introspection files list --filter task_id=<task-id> -o tableExpect tasks/<task-id>/outputs/report.md. Your own upload carries no task ID, so it is not listed.
Or ask your agent: “Run support-agent on ./contract.pdf in staging and download its report.”
Reuse an upload, SDKs, and file formats
Reuse an upload on any turn by its ID. Attachments stay mounted on later turns.
introspection files upload --file ./contract.pdf --file-type upload --query id -o table
introspection tasks prompt <task-id> --prompt "Compare it with this one" --file <file-id>SDKs:
JavaScript
const f = await runner.files.upload({ file: blob, name: "contract.pdf", file_type: "upload" });
const handle = await runner.tasks.start({ prompt: "Review contract.pdf", files: [{ id: f.id }] });
const bytes = await runner.files.download(f.id);To find a task’s outputs, filter the file list by the tasks/<task-id>/outputs/
name prefix, as the Python tab does.
A browser uploads with its session client (web chat).
Formats. read shows images to a vision model, and the
documents tool reads PDF and Word
files. To read spreadsheets or presentations, or to write PDFs, give the recipe
its own document tools.
Local runs. introspection local has no /workspace/files or
/workspace/outputs: put the file in your current directory and name its path
in the prompt. Eval fixtures work the same way (Add cases to an eval).
Limits
| Limit | Value or workaround |
|---|---|
| Upload size | 50 MB per file. |
| Attached to a task, or saved as an output | 25 MB per file; a task skips larger attachments. Split the file, or fetch it through a storage tool. |
| Attachments per task | 100. Past that, search through a server or fan out (documents). |
| Reading Word, Excel, or PowerPoint uploads | read can’t open them: add document tools to the recipe. |
| Bulk download | Not supported: run files content per ID from files list. |
| Reviewing a file before the user gets it | Have the agent save through your tool instead. |