Pular para o conteúdo principal

​
Visão geral

O URLReadTool lê o conteúdo de uma URL e o retorna como texto. Em corpos PDF, DOCX e XLSX o texto é extraído, o HTML é reduzido ao texto visível e os tipos baseados em texto (texto simples, Markdown, JSON, XML, YAML, CSV) são decodificados como estão. Funciona com links pré-assinados de armazenamento em nuvem (S3, R2, Google Drive, OneDrive, SharePoint), mesmo quando o servidor identifica o arquivo como application/octet-stream. A ferramenta não autentica, portanto o link já deve conceder acesso.

​
Instalação

​
Exemplo de Uso

Code

​
Argumentos

O agente fornece estes em tempo de execução:
  • url: A URL a ser lida.
  • start_line: (Opcional) A linha inicial (começando em 1). O padrão é 1.
  • line_count: (Opcional) O número de linhas a retornar. Se omitido, retorna tudo a partir de start_line.
Você define estes ao construir a ferramenta:
  • max_bytes: (Opcional) Maior corpo de resposta aceito. O padrão é 5 MiB.
  • timeout: (Opcional) Tempo limite por requisição, em segundos. O padrão é 30.
  • headers: (Opcional) Cabeçalhos extras da requisição.
  • encoding: (Opcional) Força uma codificação de texto em vez da declarada pelo servidor.
Se a busca falhar, a ferramenta retorna uma falha com o motivo, como um endereço bloqueado ou um erro de conexão.

​
Segurança de rede

Como a URL geralmente é escolhida por um LLM em tempo de execução, as requisições são verificadas contra SSRF:
  • Cada hostname é resolvido e a requisição é rejeitada se algum endereço resolvido for privado, de loopback, link-local ou de outra forma reservado. Isso cobre endpoints de metadados de nuvem e serviços internos.
  • Redirecionamentos não são seguidos automaticamente. Cada salto é verificado novamente e as credenciais são descartadas em saltos entre origens diferentes.

​
Permitir um host interno

Alguns ambientes servem arquivos a partir de um host que resolve para um endereço privado, como uma plataforma auto-hospedada atrás de um balanceador de carga interno. Para permiti-lo, liste o hostname exato em CREWAI_TOOLS_ALLOWED_PRIVATE_HOSTS:
Exemplos do que cada valor permite, para uma requisição a https://files.internal.example.com/report.pdf:
  • As entradas são separadas por vírgula. Cada uma pode ser um hostname simples, host:porta ou uma URL completa. Apenas o hostname é usado, comparado de forma exata e sem diferenciar maiúsculas de minúsculas. Curingas como *.example.com não são suportados.
  • Endereços IP nunca são permitidos por esta lista.
  • Um host listado pode resolver para qualquer endereço privado, então liste apenas hostnames cujo DNS você controla e em que confia.
  • Os redirecionamentos continuam sendo verificados, portanto um redirecionamento para outro host interno também deve estar na lista.
  • A configuração vale para todas as ferramentas do crewai-tools que fazem requisições seguras, não apenas o URLReadTool.
  • Os certificados TLS continuam sendo verificados. Um host que usa uma autoridade certificadora privada deve ter uma cadeia que leve a uma CA em que a ferramenta confie.
Isto é mais restrito que CREWAI_TOOLS_ALLOW_UNSAFE_PATHS=true, que desativa a proteção de caminhos e SSRF em todo o processo e deve ser evitado. A lista de permissões é ignorada enquanto CREWAI_TOOLS_FORCE_SAFE_PATHS=true estiver definido, pois esse bloqueio existe para que uma implantação não possa relaxar essas verificações. Para usar a lista, deixe CREWAI_TOOLS_FORCE_SAFE_PATHS sem definir, defina CREWAI_TOOLS_ALLOWED_PRIVATE_HOSTS e remova CREWAI_TOOLS_ALLOW_UNSAFE_PATHS, pois essa variável volta a ter efeito quando o bloqueio é removido. Faça isso apenas em workers que você opera, não em workers compartilhados ou multi-tenant.