andre/crewAI
1
0
Fork 0
mirror of https://github.com/crewAIInc/crewAI.git synced 2026-09-01 13:38:00 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs: simplify FileReadTool documentation

Browse Source 
Rewrite the English FileReadTool page in clearer, shorter technical English while keeping the same API coverage and security guidance.

Co-authored-by: Rip&Tear <theCyberTech@users.noreply.github.com>
This commit is contained in:
Cursor Agent
2026-08-12 01:11:59 +00:00
parent 7642e615a3
commit 4a651677a2
1 changed files with 25 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
docs/edge/en/tools/file-document/filereadtool.mdx
View File

@@ -1,6 +1,6 @@
---
title: File Read
description: The `FileReadTool` is designed to read files from the local file system.
description: The `FileReadTool` reads files from the local file system.
icon: folders
mode: "wide"
---
@@ -8,19 +8,19 @@ mode: "wide"
## Overview
<Note>
We are still working on improving tools, so there might be unexpected behavior or changes in the future.
We are still improving tools, so behavior may change.
</Note>
The `FileReadTool` reads the contents of a file from the local file system and returns it as text.
It is useful for batch text file processing, reading runtime configuration files, and importing data for analytics.
It supports any text-based file format, such as `.txt`, `.csv`, `.json`, and `.md`.
Content is always returned as plain text — parsing it (for example, `json.loads` on a `.json` file) is up to the agent or your own code.
The `FileReadTool` reads a local file and returns its content as text.
Use it to process text files, read config files, or load data for analysis.
It works with any text format, such as `.txt`, `.csv`, `.json`, and `.md`.
The tool always returns plain text. If you need structured data (for example, JSON), parse it in your agent or your own code.
For large files, `start_line` and `line_count` read just a window of lines instead of loading the whole file.
For large files, use `start_line` and `line_count` to read only a range of lines instead of the full file.
## Installation
To utilize the functionalities previously attributed to the FileReadTool, install the crewai_tools package:
Install the crewai tools package:
```shell
pip install 'crewai[tools]'
@@ -28,20 +28,18 @@ pip install 'crewai[tools]'
## Usage Example
To get started with the FileReadTool:
```python Code
from crewai_tools import FileReadTool
# Initialize the tool to read any file the agent knows or learns the path for
# Let the agent choose the file path at runtime
file_read_tool = FileReadTool()
# OR
# Initialize with a specific file path, so the agent reads that file by default
# Set a default file path when you create the tool
file_read_tool = FileReadTool(file_path='path/to/your/file.txt')
# Read a window of lines (lines 100-149) instead of the whole file
# Read only lines 100-149
partial_content = file_read_tool.run(
file_path='path/to/your/file.txt',
start_line=100,
@@ -51,30 +49,30 @@ partial_content = file_read_tool.run(
## Arguments
The agent supplies these at runtime:
The agent can pass these at runtime:
- `file_path`: (Optional) The path to the file you want to read. Accepts absolute and relative paths. Ensure the file exists and you have the necessary permissions to access it. Omit it to read the default file configured at construction; if there is no default, the tool reports that no path was provided.
- `start_line`: (Optional) The line number to start reading from (1-indexed). Defaults to `1`.
- `line_count`: (Optional) The number of lines to read. If omitted, reads from `start_line` to the end of the file.
- `file_path`: (Optional) Path to the file to read. Absolute and relative paths are both valid. The file must exist, and the process must have permission to read it. If you omit this argument, the tool reads the default file set at construction. If there is no default, the tool reports that no path was provided.
- `start_line`: (Optional) First line to read. Line numbers start at `1`. Default is `1`.
- `line_count`: (Optional) How many lines to read. If omitted, the tool reads from `start_line` to the end of the file.
You set these when constructing the tool:
You can set these when you create the tool:
- `file_path`: (Optional) A default file to read when the agent calls the tool with no arguments.
- `base_dir`: (Optional) The directory that runtime paths must stay inside. Defaults to the current working directory.
- `encoding`: (Optional) Text encoding used to decode the file. Defaults to `utf-8`.
- `file_path`: (Optional) Default file to read when the agent calls the tool with no arguments.
- `base_dir`: (Optional) Directory that runtime paths must stay inside. Default is the current working directory.
- `encoding`: (Optional) Text encoding used to decode the file. Default is `utf-8`.
## Allowed paths
Because the file path is usually chosen by an LLM at runtime, reads are confined to a sandbox:
An LLM usually chooses the file path at runtime, so reads are limited to a sandbox:
- Paths supplied at runtime must resolve inside `base_dir`, which defaults to the current working directory. `..` segments and symlinks are resolved before the check, so they cannot be used to escape.
- A `file_path` passed to the constructor is developer-declared intent, so it is always allowed past the containment check — even outside `base_dir`. The read itself can still fail if the file is missing, is a directory, or is not permitted. It is pinned when the tool is built, so a later change of working directory cannot repoint it, and the agent can address it either by omitting `file_path` or by using the name shown in the tool's description. Declaring one file does not expose its siblings.
- Runtime paths must resolve inside `base_dir` (default: the current working directory). The tool resolves `..` segments and symlinks before it checks the path, so they cannot escape the sandbox.
- A `file_path` you pass to the constructor is always allowed, even if it is outside `base_dir`. The read can still fail if the file is missing, is a directory, or cannot be accessed. That path is fixed when the tool is created, so a later change of working directory does not change which file it points to. The agent can read it by omitting `file_path`, or by using the name shown in the tool description. Declaring one file does not allow access to other files in the same folder.
To let an agent read a directory tree outside the working directory, point `base_dir` at it:
To let an agent read files outside the working directory, set `base_dir` to that directory:
```python Code
# The agent may read anything under /data, and nothing outside it
# The agent can read anything under /data, and nothing outside it
file_read_tool = FileReadTool(base_dir='/data')
```
As a last resort, setting `CREWAI_TOOLS_ALLOW_UNSAFE_PATHS=true` disables path validation. This applies process-wide to every crewai-tools tool, including the SSRF protections on URL-fetching tools, so prefer `base_dir`.
As a last resort, set `CREWAI_TOOLS_ALLOW_UNSAFE_PATHS=true` to turn off path checks. This setting applies to every crewai-tools tool in the process, including SSRF protections on URL-fetching tools. Prefer `base_dir` instead.