파일 읽기

FileReadTool은 로컬 파일 시스템에서 파일을 읽습니다.

​

개요

도구를 계속 개선하고 있으므로 동작이 변경될 수 있습니다.

FileReadTool은 로컬 파일을 읽고 내용을 텍스트로 반환합니다. 텍스트 파일 처리, 구성 파일 읽기, 분석용 데이터 로드에 사용하세요. .txt, .csv, .json, .md와 같은 모든 텍스트 형식에서 동작합니다. 도구는 항상 일반 텍스트를 반환합니다. 구조화된 데이터(예: JSON)가 필요하면 Agent 또는 사용자 코드에서 파싱하세요.

큰 파일의 경우 Agent가 start_line과 line_count를 전달해 일부 줄만 읽을 수 있습니다. 요청한 줄을 모으면 읽기를 멈추므로 파일의 나머지를 스캔하지 않습니다.

​

설치

uv add 'crewai[tools]'

​

사용 예시

Code

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')

도구를 Agent에 전달하세요. 런타임에 LLM이 file_path를 전달하며, 선택적으로 start_line과 line_count도 전달합니다.

​

인수

Agent가 런타임에 전달할 수 있는 인수:

• file_path: (선택) 읽을 파일 경로입니다. 절대 경로와 상대 경로는 base_dir 샌드박스 안에서 해석될 때만 유효합니다. 상대 경로는 base_dir이 설정된 경우 그 기준이고, 그렇지 않으면 현재 작업 디렉터리(기본 샌드박스)를 기준으로 해석됩니다. 생략하면 생성 시 설정한 기본 파일을 읽습니다. 기본값이 없으면 경로가 제공되지 않았다는 오류를 반환합니다.
• start_line: (선택) 읽기를 시작할 첫 줄입니다. 줄 번호는 1부터 시작합니다. 기본값은 1입니다.
• line_count: (선택) 읽을 줄 수입니다. 생략하면 start_line부터 파일 끝까지 읽습니다.

도구를 만들 때 설정할 수 있는 인수:

• file_path: (선택) Agent가 경로 없이 도구를 호출할 때 읽을 기본 파일입니다. 상대 경로는 base_dir이 제공되면 base_dir을 기준으로, 그렇지 않으면 현재 작업 디렉터리를 기준으로 해석됩니다.
• base_dir: (선택) 런타임 경로가 머물러야 하는 디렉터리입니다. 기본값은 현재 작업 디렉터리입니다. 도구 생성 시 이 경로를 해석하므로, 이후 작업 디렉터리가 바뀌어도 샌드박스는 이동하지 않습니다.
• encoding: (선택) 파일을 디코딩할 때 사용하는 텍스트 인코딩입니다. 기본값은 utf-8입니다. 디코딩에 실패하면 오류를 반환하고 다른 encoding을 전달하도록 안내합니다.

일반적인 실패(파일 없음, 권한 거부, 잘못된 인코딩, 샌드박스 밖 경로)는 예외를 발생시키지 않고 오류 문자열을 반환합니다.

​

허용 경로

LLM이 보통 런타임에 파일 경로를 선택하므로, 읽기는 샌드박스로 제한됩니다.

• 런타임 경로는 base_dir(기본값: 현재 작업 디렉터리) 안에서 해석되어야 합니다. 도구는 경로를 검사하기 전에 .. 세그먼트와 심볼릭 링크를 해석하므로 샌드박스를 벗어날 수 없습니다.
• 생성자에 전달한 file_path는 base_dir 밖이어도 항상 허용됩니다. 파일이 없거나, 디렉터리이거나, 접근할 수 없으면 읽기 자체는 실패할 수 있습니다. 이 경로는 도구 생성 시 고정되므로, 이후 작업 디렉터리가 바뀌어도 가리키는 파일이 바뀌지 않습니다. Agent는 file_path를 생략하거나 도구 설명에 표시된 이름으로 읽을 수 있습니다. 파일 하나를 선언해도 같은 폴더의 다른 파일에는 접근할 수 없습니다.

Agent가 작업 디렉터리 밖의 파일을 읽게 하려면 도구를 만들 때 base_dir을 설정하세요(위 예시 참고).

최후의 수단으로 CREWAI_TOOLS_ALLOW_UNSAFE_PATHS=true를 설정하면 경로 검사가 꺼집니다. 이 설정은 프로세스의 모든 crewai-tools 도구에 적용되며, URL을 가져오는 도구의 SSRF 보호도 포함됩니다. 가능하면 base_dir을 사용하세요.