Files

Agents generate files during runs: CSV reports, JSON exports, markdown summaries. Instruct the agent to write files, then download them through the API. Any text-based format works (CSV, JSON, Markdown, HTML, code, plain text).

Generate files

Tell the agent what to produce in the task instructions, then poll for completion:

Upload files to a run

Attach files for the agent to work on: a CSV to analyze, a PDF to summarize. Pass files= to runs.create (a path, a (filename, bytes) tuple, or an open binary file); every other argument works the same:

The payload form field carries the same JSON as POST /runs (teammate_id is the wire name for the agent id; the SDK accepts agent_id alike). Uploaded files land in the run's working directory and their names are appended to the prompt, so the agent finds them without extra instructions. Limits: 20 files, 100MB per file, 500MB per request.

List and download files

Need live progress while files are written? See the streaming tracker below; otherwise just call list_files after the run completes.

Advanced: track file writes via streaming

Tool arguments stream as JSON fragments on tool-call-delta events; tool-call-start carries only tool_name and tool_call_id. To see filenames in real time, accumulate the deltas for each Write call and parse them on tool-call-end:

Python

Example: weekly report pipeline

Combine file generation with scheduling for recurring reports:

Python

See examples/file-report.py for the full pipeline: streaming progress, scheduled generation, and download.

Tips: reliable file output

Be specific in your task instructions. Name the file, the format, and the columns:

Python

For multiple files, number them in one message ("1. Write a summary to report.md, 2. Export metrics.csv, ...") as in the streaming example above.

Next: Runs · Streaming & Events · Scheduling