파일 읽기 도구(FileReadTool)

에이전트가 로컬 파일 시스템의 내용을 읽어야 할 때 쓰는 가장 기본적인 도구가 FileReadTool입니다. 텍스트 기반 파일이면 .txt, .csv, .json, .md 가리지 않고 읽어 주는데, 이 글을 작성한 시점에는 안전한 경로(샌드박스) 처리까지 갖추고 있어요.

출처: 공식문서

본문

아직 도구 개선 작업이 진행 중이라, 예상치 못한 동작이나 향후 변경이 있을 수 있습니다.

FileReadTool은 로컬 파일 시스템에서 파일 내용을 읽어 텍스트로 반환합니다. 배치 텍스트 파일 처리, 런타임 구성 파일 읽기, 분석용 데이터 가져오기에 유용해요. .txt, .csv, .json, .md 같은 모든 텍스트 기반 파일 형식을 지원합니다. 내용은 항상 평문으로 반환됩니다 — 파싱(예: .json 파일에 json.loads 적용)은 에이전트나 여러분의 코드 몫이에요.

큰 파일의 경우 start_line과 line_count로 전체 파일을 로드하는 대신 일부 줄만 읽을 수 있습니다.

설치

crewai_tools 패키지를 설치합니다.

pip install 'crewai[tools]'

사용 예제

from crewai_tools import FileReadTool

# Initialize the tool to read any file the agent knows or learns the path for
file_read_tool = FileReadTool()

# OR

# Initialize with a specific file path, so the agent reads that file by default
file_read_tool = FileReadTool(file_path='path/to/your/file.txt')

# Read a window of lines (lines 100-149) instead of the whole file
partial_content = file_read_tool.run(
    file_path='path/to/your/file.txt',
    start_line=100,
    line_count=50,
)

인자

에이전트가 런타임에 제공하는 것:

file_path: (옵션) 읽고 싶은 파일 경로. 절대·상대 경로 모두 허용. 파일이 존재하고 접근 권한이 있는지 확인하세요. 생략하면 생성 시 구성된 기본 파일을 읽습니다. 기본 파일이 없으면 경로가 제공되지 않았다고 알려 줍니다.
start_line: (옵션) 읽기 시작할 줄 번호(1부터 시작). 기본값은 1.
line_count: (옵션) 읽을 줄 수. 생략하면 start_line부터 파일 끝까지 읽습니다.

생성 시 설정하는 것:

file_path: (옵션) 에이전트가 인자 없이 호출했을 때 읽을 기본 파일.
base_dir: (옵션) 런타임 경로가 머물러야 하는 디렉토리. 기본값은 현재 작업 디렉토리.
encoding: (옵션) 파일을 디코딩할 때 쓰는 텍스트 인코딩. 기본값은 utf-8.

허용 경로

파일 경로는 대개 LLM이 런타임에서 고르기 때문에, 읽기는 샌드박스 안으로 한정됩니다.

런타임에 제공된 경로는 base_dir(기본값: 현재 작업 디렉토리) 안에서 해석되어야 합니다. .. 세그먼트와 심볼릭 링크는 검사 전에 해석되므로 이를 이용해 빠져나갈 수 없습니다.
생성자에 전달된 file_path는 개발자가 의도한 것이므로 포함 검사를 항상 통과합니다 — base_dir 밖이라도요. 파일이 없거나, 디렉토리이거나, 허용되지 않으면 읽기 자체는 여전히 실패할 수 있습니다. 도구가 빌드될 때 고정되므로 나중에 작업 디렉토리가 바뀌어도 가리킬 수 없고, 에이전트는 file_path를 생략하거나 도구 설명에 표시된 이름으로 접근할 수 있어요. 하나의 파일을 선언해도 그 형제 파일들은 노출되지 않습니다.

작업 디렉토리 밖의 디렉토리 트리를 에이전트가 읽게 하려면 base_dir을 그곳으로 지정하세요.

# The agent may read anything under /data, and nothing outside it
file_read_tool = FileReadTool(base_dir='/data')

마지막 수단으로 CREWAI_TOOLS_ALLOW_UNSAFE_PATHS=true를 설정하면 경로 검증이 비활성화됩니다. 이는 URL 가져오기 도구의 SSRF 보호를 포함해 모든 crewai-tools 도구에 프로세스 전역으로 적용되므로 base_dir을 선호하세요. 관리형 워커는 CREWAI_TOOLS_FORCE_SAFE_PATHS=true를 설정해 테넌트가 이 탈출구를 내보내 검사를 끄지 못하게 해야 합니다.

파일 읽기 도구(FileReadTool)