Skip to main content

​
What it does

The Read File tool lets an agent open and read a single file from anywhere it already has access: a file in its Python sandbox, a conversation attachment (user-uploaded or tool-generated), a knowledge-base file, or a URL. It’s the agent equivalent of a coding assistant’s “Read” primitive — a safe, read-only way to pull a specific file into context on demand.
Read File is pre-checked when you create an agent in the Control Hub. It’s a read-only baseline that can only reach files the agent could already access, so new agents start with it enabled. It behaves like any other tool — you can uncheck it at any time. See Default-on tools.

​
Key features

  • Four sources, one tool — sandbox paths, attachment:<filename>, kb:<file_id>, and https://… URLs
  • Documents auto-extract to text — PDF, DOCX, XLSX, PPTX, CSV, EML, and MSG are converted automatically
  • Images come back as vision — PNG/JPG/GIF/WebP are returned as images the agent can visually analyze (charts, screenshots, diagrams, scans); oversized images are auto-downscaled
  • Line pagination — all text is paginated with offset/limit so large files never overflow context
  • PDF page images — read a PDF as page images (not just text) to reason over layout, charts, and scanned content

​
Parameters

ParameterTypeRequiredDescription
pathstringYesWhat to read: a sandbox path (absolute or relative to /home/user), attachment:<filename>, kb:<file_id>, or an https://… URL
offsetintegerNoWhere to start — a 1-based line for text, or a 1-based page when mode: image. For paging large files (default: 1)
limitintegerNoHow much to return — max lines of text (default 2000), or max pages in image mode. The result reports the total and the next offset when more remains
modestringNoFor PDFs and knowledge-base files: text (extracted text, default), image (page images for visual analysis), or both. Ignored for plain images (always vision) and plain text (always text)

​
Common use cases

​
Read a conversation attachment

path: "attachment:report.pdf"
Pull a file the user uploaded — or one an earlier tool generated — into the conversation as text.

​
Read a specific knowledge-base file

path: "kb:123"
Open the full extracted text of a knowledge-base file by its file id, line-paginated.

​
Look at a PDF’s pages as images

path: "attachment:deck.pdf"
mode: "image"
Visually analyze charts, diagrams, layout, or scanned pages that text extraction can’t capture.

​
Read a sandbox file

path: ".render/shots/tab-03.png"
Inspect a screenshot or file the agent produced in its sandbox — for example, checking a render screenshot before publishing an app.

​
Image support depends on the model

Returning an image from a tool requires a model whose provider can receive tool-result images as real vision:
  • Supported: Anthropic, OpenAI, Azure OpenAI, and Google (Gemini).
  • Text-only: xAI (Grok). On xAI, image/both requests are automatically downgraded to text (with a note), and image-only files return an error suggesting an Anthropic, OpenAI, Azure, or Google model.
Documents and plain text read the same on every model — only image/vision output is gated.

​
Limitations

  • Reads one file per call (use a separate call per file)
  • Very large images are rejected; oversized readable images are downscaled
  • Image and PDF-page-image output requires a vision-capable provider (see above)
  • Non-PDF Office documents (DOCX/XLSX/PPTX/CSV/email) are text-only — no page images