개요
URLReadTool은 URL의 콘텐츠를 읽어 텍스트로 반환합니다. PDF, DOCX, XLSX 본문은 텍스트가 추출되고, HTML은 보이는 텍스트로 줄여지며, 텍스트 기반 형식(일반 텍스트, Markdown, JSON, XML, YAML, CSV)은 그대로 디코딩됩니다. 서버가 파일을 application/octet-stream으로 표시하더라도 클라우드 스토리지의 사전 서명된 링크(S3, R2, Google Drive, OneDrive, SharePoint)에서 동작합니다.
이 도구는 인증을 수행하지 않으므로 링크 자체가 이미 접근 권한을 부여해야 합니다.
설치
사용 예시
Code
인수
에이전트가 런타임에 제공합니다:url: 읽을 URL입니다.start_line: (선택 사항) 시작할 줄 번호(1부터 시작)입니다. 기본값은1입니다.line_count: (선택 사항) 반환할 줄 수입니다. 생략하면start_line부터 끝까지 반환합니다.
max_bytes: (선택 사항) 허용하는 최대 응답 본문 크기입니다. 기본값은 5 MiB입니다.timeout: (선택 사항) 요청당 제한 시간(초)입니다. 기본값은30입니다.headers: (선택 사항) 추가 요청 헤더입니다.encoding: (선택 사항) 서버가 선언한 인코딩 대신 사용할 텍스트 인코딩입니다.
네트워크 보안
URL은 보통 런타임에 LLM이 선택하므로 요청은 SSRF에 대해 검사됩니다:- 각 호스트 이름을 확인(resolve)하고, 확인된 주소 중 하나라도 사설, 루프백, 링크 로컬 또는 기타 예약된 주소이면 요청을 거부합니다. 클라우드 메타데이터 엔드포인트와 내부 서비스가 이에 포함됩니다.
- 리디렉션은 자동으로 따라가지 않습니다. 모든 단계가 다시 검사되며, 다른 출처로 이동하면 자격 증명이 제거됩니다.
내부 호스트 허용
일부 환경에서는 내부 로드 밸런서 뒤의 자체 호스팅 플랫폼처럼 사설 주소로 확인되는 호스트에서 파일을 제공합니다. 이를 허용하려면 정확한 호스트 이름을CREWAI_TOOLS_ALLOWED_PRIVATE_HOSTS에 나열하세요:
https://files.internal.example.com/report.pdf에 대한 요청에서 각 값이 허용하는 범위의 예시:
- 항목은 쉼표로 구분합니다. 각 항목은 호스트 이름,
host:port또는 전체 URL일 수 있습니다. 호스트 이름만 사용되며 대소문자를 구분하지 않고 정확히 일치해야 합니다.*.example.com과 같은 와일드카드는 지원되지 않습니다. - IP 주소는 이 목록으로 허용되지 않습니다.
- 나열된 호스트는 어떤 사설 주소로도 확인될 수 있으므로, DNS를 직접 관리하고 신뢰할 수 있는 호스트 이름만 나열하세요.
- 리디렉션도 계속 검사되므로 다른 내부 호스트로의 리디렉션도 목록에 있어야 합니다.
- 이 설정은
URLReadTool뿐 아니라 안전한 요청을 사용하는 모든 crewai-tools 도구에 적용됩니다. - TLS 인증서는 계속 검증됩니다. 사설 인증 기관을 사용하는 호스트는 도구가 신뢰하는 CA로 이어지는 체인이어야 합니다.
CREWAI_TOOLS_ALLOW_UNSAFE_PATHS=true보다 범위가 좁습니다. CREWAI_TOOLS_FORCE_SAFE_PATHS=true가 설정되어 있으면 허용 목록은 무시됩니다. 이 잠금은 배포 환경이 이러한 검사를 완화하지 못하도록 하기 위한 것이기 때문입니다. 허용 목록을 사용하려면 CREWAI_TOOLS_FORCE_SAFE_PATHS를 설정하지 않고, CREWAI_TOOLS_ALLOWED_PRIVATE_HOSTS를 설정하며, CREWAI_TOOLS_ALLOW_UNSAFE_PATHS는 제거하세요. 잠금이 해제되면 해당 플래그가 다시 적용되기 때문입니다. 직접 운영하는 워커에서만 사용하고, 공유 또는 멀티 테넌트 워커에서는 사용하지 마세요.