File Helpers 툴킷

File Helpers 툴킷은 에이전트에게 파일 유틸리티를 제공합니다: base64 페이로드를 스토리지에 저장, 지능형 텍스트 추출로 파일 읽기, 텍스트 인코딩 변경, MIME 타입 감지. 연결이나 API 키가 필요 없습니다.

에이전드 Toolkits 탭에 추가한 다음, 에이전트가 파일을 처리해야 할 때 성격 프롬프트에서 @로 도구를 참조하세요.

전제 조건

편집할 수 있는 에이전트
Read File, Change File Encoding, Check File Type의 경우: 이전 저장 단계가 반환한 파일시스템 경로(또는 로컬 파일 경로를 쓰는 다른 도구)

도구	설명
Save Base64 File	base64 내용(`data:…;base64,` 접두사 포함)을 디코딩하여 저장합니다. 선택적 MIME 타입과 파일명. 파일 id, 경로, 이름, 크기, MIME 타입, 다운로드 URL을 반환합니다.
Read File	로컬 경로의 파일을 읽고 일반적인 형식(PDF, DOCX, PPTX, XLSX, CSV, JSON, TXT, 이메일 형식 등)에서 텍스트를 추출합니다.
Change File Encoding	텍스트 파일을 재인코딩(예: utf-8 ↔ latin-1)하고 새 파일을 씁니다.
Check File Type	확장자와 파일 내용에서 MIME 타입을 감지합니다. 선택적으로 허용된 MIME 타입 목록과 대조 검증할 수 있습니다.

전형적인 흐름:

Save Base64 File — 예: 이메일 첨부 또는 통합 페이로드에서
반환된 파일 경로를 Read File, Check File Type, Change File Encoding과 함께 사용

Read File은 서버 파일시스템 경로가 필요합니다. 공개 URL이나 지식 베이스 이름만으로는 사용할 수 없습니다 — 먼저 경로를 저장하거나 확보하세요.

이메일 또는 웹훅 단계의 base64 첨부를 영속화한 다음 텍스트로 읽기
파일을 다른 툴킷으로 라우팅하기 전에 MIME 타입 검사
분석 전에 CSV나 로그 파일의 인코딩 정규화
PDF 전용 페이지 이미지나 PDF 생성이 필요할 때 PDF 툴킷과 페어링 (File Helpers의 Read File은 여러 형식 중 하나로 PDF 텍스트를 추출할 수 있음)

저장할 때 명확한 파일명을 선호하여 이후 단계에서 파일을 식별할 수 있게 하세요.
특정 형식만 허용하는 하류 도구 전에 Check File Type을 사용하세요.
이 툴킷이 저장한 파일은 Python 샌드박스 내에서 자동으로 사용할 수 없습니다. Python Code Execution으로 분석하려면 흐름이 필요할 때 샌드박스에 별도로 업로드하세요.
채팅 내 마크다운 문서(생성/편집/나열)에는 Document Manager를 사용하세요.

증상	확인할 사항
Read File 실패	URL이나 KB 표시 이름이 아니라 Save Base64 File(또는 다른 쓰기 도구)이 반환한 `file_path`를 전달했는지 확인
읽기 후 잘못된 문자	올바른 소스 및 대상 인코딩으로 Change File Encoding 사용
Check File Type이 파일 거부	허용된 MIME 목록을 조정하거나 파일이 예상한 타입인지 확인
PDF 툴킷과 혼동	File Helpers는 일반적인 저장/읽기/인코딩/검사; PDF 툴킷은 전체 페이지 추출, 페이지-이미지 변환, PDF 생성 추가