> ## Documentation Index
> Fetch the complete documentation index at: https://crewai-cursor-simplify-filereadtool-docs-ac84.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Leitura de Arquivo

> O `FileReadTool` lê arquivos do sistema de arquivos local.

## Visão Geral

<Note>
  Ainda estamos melhorando as ferramentas, então o comportamento pode mudar.
</Note>

O `FileReadTool` lê um arquivo local e retorna o conteúdo como texto.
Use-o para processar arquivos de texto, ler arquivos de configuração ou carregar dados para análise.
Ele funciona com qualquer formato de texto, como `.txt`, `.csv`, `.json` e `.md`.
A ferramenta sempre retorna texto simples. Se você precisar de dados estruturados (por exemplo, JSON), faça o parse no Agent ou no seu próprio código.

Para arquivos grandes, o Agent pode passar `start_line` e `line_count` para ler apenas um intervalo de linhas.
A ferramenta para assim que obtém essas linhas, então não percorre o restante do arquivo.

## Instalação

```shell theme={null}
uv add 'crewai[tools]'
```

## Exemplo de Uso

```python Code theme={null}
from crewai_tools import FileReadTool

# Agent chooses the file path at runtime
tool = FileReadTool()

# OR set a default file the agent can read with no path argument
tool = FileReadTool(file_path='path/to/your/file.txt')

# OR let the agent read any file under a directory
tool = FileReadTool(base_dir='/data')
```

Passe a ferramenta para um Agent. Em tempo de execução, o LLM envia `file_path` e, opcionalmente, `start_line` e `line_count`.

## Argumentos

O Agent pode passar estes argumentos em tempo de execução:

* `file_path`: (Opcional) Caminho do arquivo a ler. Caminhos absolutos e relativos só são válidos quando resolvem dentro do sandbox de `base_dir`. Um caminho relativo resolve em relação a `base_dir` quando definido; caso contrário, em relação ao diretório de trabalho atual (o sandbox padrão). Omita-o para ler o arquivo padrão definido na construção. Se não houver padrão, a ferramenta retorna um erro dizendo que nenhum caminho foi fornecido.
* `start_line`: (Opcional) Primeira linha a ler. A numeração começa em `1`. O padrão é `1`.
* `line_count`: (Opcional) Quantidade de linhas a ler. Se omitido, a ferramenta lê de `start_line` até o fim do arquivo.

Você pode definir estes argumentos ao criar a ferramenta:

* `file_path`: (Opcional) Arquivo padrão a ler quando o Agent chama a ferramenta sem caminho. Um caminho relativo resolve em relação a `base_dir` quando `base_dir` é fornecido; caso contrário, em relação ao diretório de trabalho atual.
* `base_dir`: (Opcional) Diretório dentro do qual os caminhos em tempo de execução devem permanecer. O padrão é o diretório de trabalho atual. A ferramenta resolve este caminho na criação, então uma mudança posterior do diretório de trabalho não move o sandbox.
* `encoding`: (Opcional) Codificação de texto usada para decodificar o arquivo. O padrão é `utf-8`. Se a decodificação falhar, a ferramenta retorna um erro e sugere passar um `encoding` diferente.

Falhas comuns (arquivo ausente, permissão negada, encoding incorreto ou caminho fora do sandbox) retornam uma string de erro. Elas não levantam uma exceção.

## Caminhos permitidos

Um LLM geralmente escolhe o caminho do arquivo em tempo de execução, então as leituras ficam limitadas a um sandbox:

* Os caminhos em tempo de execução devem resolver dentro de `base_dir` (padrão: o diretório de trabalho atual). A ferramenta resolve segmentos `..` e links simbólicos antes de verificar o caminho, então eles não podem escapar do sandbox.
* Um `file_path` passado ao construtor é sempre permitido, mesmo fora de `base_dir`. A leitura ainda pode falhar se o arquivo estiver ausente, for um diretório ou não puder ser acessado. Esse caminho fica fixo quando a ferramenta é criada, então uma mudança posterior do diretório de trabalho não altera o arquivo apontado. O Agent pode lê-lo omitindo `file_path` ou usando o nome mostrado na descrição da ferramenta. Declarar um arquivo não permite acesso a outros arquivos na mesma pasta.

Para permitir que um Agent leia arquivos fora do diretório de trabalho, defina `base_dir` ao criar a ferramenta (veja o exemplo acima).

Como último recurso, defina `CREWAI_TOOLS_ALLOW_UNSAFE_PATHS=true` para desativar as verificações de caminho. Essa configuração se aplica a todas as ferramentas crewai-tools no processo, incluindo proteções SSRF em ferramentas que buscam URLs. Prefira `base_dir`.