> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asteragents.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Read File Tool

> Read any file an agent can already reach — sandbox, attachment, knowledge base, or URL — as text or vision

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

<Note>
  **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](/features/build-an-agent#default-on-tools).
</Note>

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

| Parameter | Type    | Required | Description                                                                                                                                                                                      |
| --------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `path`    | string  | Yes      | What to read: a sandbox path (absolute or relative to `/home/user`), `attachment:<filename>`, `kb:<file_id>`, or an `https://…` URL                                                              |
| `offset`  | integer | No       | Where to start — a 1-based **line** for text, or a 1-based **page** when `mode: image`. For paging large files (default: 1)                                                                      |
| `limit`   | integer | No       | How 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                                    |
| `mode`    | string  | No       | For 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

## Related tools

* [Scrape URL](/tools/scrape_url) — extract content from web pages and PDFs by URL
* [Search Knowledge Base](/tools/search_knowledge_base) — semantic search across a knowledge base (vs. reading one known file)
* [Execute Python](/tools/execute_python) — process files programmatically in the sandbox