파일 쓰기 도구(FileWriterTool)
파일 쓰기 도구(FileWriterTool)
에이전트가 결과를 파일로 저장해야 할 때, 운영체제마다 다른 경로 규칙과 인코딩 때문에 의외로 골치아픕니다. FileWriterTool은 이런 크로스플랫폼 파일 쓰기를 한 번에 해결해 주는 도구예요. 기본 UTF-8 쓰기, 디렉토리 자동 생성, 샌드박스 경로 검증까지 갖추고 있습니다.
출처: 공식문서
본문
설명
FileWriterTool은 crewai_tools 패키지의 구성 요소로, 크로스플랫폼 호환(Windows, Linux, macOS)으로 파일에 내용을 쓰는 과정을 단순화합니다. 리포트 생성, 로그 저장, 구성 파일 만들기 등에 특히 유용해요. 이 도구는 운영체제 간 경로 차이를 처리하고, 플랫폼 로케일 인코딩 대신 기본적으로 UTF-8로 쓰고, 디렉토리가 없으면 자동으로 만들어 서로 다른 플랫폼에서 안정적으로 출력을 구성할 수 있게 해 줍니다.
설치
프로젝트에서 FileWriterTool을 쓰려면 crewai_tools 패키지를 설치합니다.
pip install 'crewai[tools]'
예제
from crewai_tools import FileWriterTool
# Initialize the tool
file_writer_tool = FileWriterTool()
# Write content to a file in a specified directory
result = file_writer_tool.run(
filename='example.txt',
content='This is a test content.',
directory='test_directory',
)
print(result)
인자
에이전트가 런타임에 제공하는 것:
filename: 쓸 파일 이름.directory에 상대적입니다. 없으면 생성되는 하위 디렉토리를 포함할 수 있어요.content: 파일에 쓸 텍스트 내용.directory(옵션): 파일이 생성될 디렉토리 경로. 상대 경로는 도구의 허용 디렉토리 —base_dir이 설정되면 그 안, 아니면 현재 작업 디렉토리 — 안에서 해석되고 기본은 그 루트입니다. 디렉토리가 없으면 생성합니다.overwrite(옵션): 파일이 이미 존재할 때 교체할지 여부.true/false를 받습니다(yes/no,on/off,1/0도 가능). 기본값은false로, 기존 내용을 교체하는 대신 오류를 보고합니다.
생성 시 설정하는 것:
base_dir(옵션): 쓰기가 머물러야 하는 디렉토리. 기본값은 현재 작업 디렉토리.encoding(옵션): 파일을 쓸 때 쓰는 텍스트 인코딩. 기본값은utf-8.
허용 경로
디렉토리와 파일 이름 모두 대개 LLM이 런타임에서 고르기 때문에, 쓰기는 샌드박스 안으로 한정됩니다.
- 해석된
directory는base_dir(기본값: 현재 작업 디렉토리) 안에 있어야 합니다. - 해석된 파일은 그
directory안에 있어야 합니다...세그먼트, 절대 경로, 심볼릭 링크는 두 검사 전에 모두 해석되므로 이를 이용해 빠져나갈 수 없습니다.
에이전트가 작업 디렉토리 밖에 쓰게 하려면 base_dir을 대상 트리로 지정하세요.
# The agent may write anywhere under /var/output, and nowhere outside it
file_writer_tool = FileWriterTool(base_dir='/var/output')
이전에는 절대
directory가 프로세스 권한이 닿는 어디든 쓸 수 있었습니다. 이에 의존했다면 허용하려는 트리를base_dir로 설정하세요.CREWAI_TOOLS_ALLOW_UNSAFE_PATHS=true를 설정하면 예전 동작을 복원하지만, 이는 URL 가져오기 도구의 SSRF 보호를 포함해 모든 crewai-tools 도구에 프로세스 전역으로 적용되므로base_dir을 선호하세요.
결론
FileWriterTool을 크루에 통합하면 에이전트가 서로 다른 운영체제에서도 안정적으로 내용을 파일에 쓸 수 있습니다. 출력 데이터 저장, 구조화된 파일 시스템 생성, 크로스플랫폼 파일 작업 처리에 필수적인 도구예요. 표준 Python 파일 연산으로 파일 쓰기 문제를 겪는 Windows 사용자에게 특히 권장됩니다.