Skip to main content

​
Visão Geral

Ainda estamos melhorando as ferramentas, então o comportamento pode mudar.
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

​
Exemplo de Uso

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