Skip to Content
Platform
How-toSend files in and out

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(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

LimitValue or workaround
Upload size50 MB per file.
Attached to a task, or saved as an output25 MB per file; a task skips larger attachments. Split the file, or fetch it through a storage tool.
Attachments per task100. Past that, search through a server or fan out (documents).
Reading Word, Excel, or PowerPoint uploadsread can’t open them: add document tools to the recipe.
Bulk downloadNot supported: run files content per ID from files list.
Reviewing a file before the user gets itHave the agent save through your tool instead.
Last updated on