Skip to main content

​
Overview

We are still improving tools, so behavior may change.
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, the agent can pass start_line and line_count to read only a range of lines. The tool stops once it has those lines, so it does not scan the rest of the file.

​
Installation

​
Usage Example

Code
Give the tool to an agent. At runtime the LLM passes file_path, and optionally start_line and line_count.

​
Arguments

The agent can pass these at runtime:
  • file_path: (Optional) Path to the file to read. Absolute and relative paths are both valid only when they resolve inside the base_dir sandbox. A relative path resolves against base_dir when set, otherwise against the current working directory (the default sandbox). Omit it to read the default file set at construction. If there is no default, the tool returns an error saying 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 can set these when you create the tool:
  • file_path: (Optional) Default file to read when the agent calls the tool with no path. A relative path resolves against base_dir when base_dir is provided, otherwise against the current working directory.
  • base_dir: (Optional) Directory that runtime paths must stay inside. Default is the current working directory. The tool resolves this path when the tool is created, so a later change of working directory does not move the sandbox.
  • encoding: (Optional) Text encoding used to decode the file. Default is utf-8. If decoding fails, the tool returns an error and suggests passing a different encoding.
Common failures (missing file, permission denied, wrong encoding, or a path outside the sandbox) return an error string. They do not raise an exception.

​
Allowed paths

An LLM usually chooses the file path at runtime, so reads are limited to a sandbox:
  • 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 files outside the working directory, set base_dir when you create the tool (see the example above). 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.