# Send files in and out

Hand the agent a PDF, get a report back as a versioned file you can download.

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](/ship)) and the CLI or an SDK runner
([Run tasks from your backend](/patterns/add-to-your-app)).

## 1. Tell the agent where files live

```md filename="SYSTEM.md"
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.

```bash
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/...`.

```bash
introspection files list --filter task_id=<task-id> --filter category=output -o table
```

## 4. Download

```bash
introspection files content <file-id> --out report.md
```

## Verify

```bash
introspection files list --filter task_id=<task-id> -o table
```

Expect `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.

```bash
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:**

```ts
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(fileId);
```

Python is the same with `files=[{"id": f.id}]`. To find outputs in the JS SDK,
filter `files.list({ task_id })` by the `tasks/<task-id>/outputs/` name prefix.
A browser uploads with its session client ([web chat](/patterns/web-chat#4-attach-files)).

**Formats.** `read` shows images to a vision model, and `pdftotext` reads PDFs.
For Office or PDF output, the agent runs `uvx --with python-docx python ...`
(or `reportlab`, `python-pptx`, `openpyxl`) ([The sandbox](/build/sandbox)).

**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](/improve/eval-cases)).

## 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](/build/mcp). |
| Attachments per task | 100. Past that, search through a server or fan out ([documents](/patterns/documents#4-review-a-large-set)). |
| 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](/patterns/approve-outside) instead. |

Send files in and out

Hand the agent a PDF, get a report back as a versioned file you can download.

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

SYSTEM.md


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 table

4. Download


introspection files content <file-id> --out report.md

Verify


introspection files list --filter task_id=<task-id> -o table

Expect 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:


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(fileId);

Python is the same with files=[{"id": f.id}]. To find outputs in the JS SDK, filter files.list({ task_id }) by the tasks/<task-id>/outputs/ name prefix. A browser uploads with its session client (web chat).

Formats. read shows images to a vision model, and pdftotext reads PDFs. For Office or PDF output, the agent runs uvx --with python-docx python ... (or reportlab, python-pptx, openpyxl) (The sandbox).

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).
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.