Extração de documentos

A ferramenta read_file converte formatos de documento comuns em texto legível automaticamente, então o agente inspeciona um PDF ou uma planilha do mesmo jeito que lê código.

Formatos suportados

Formato	Extensões	Conversor	Disponibilidade
Cadernos Jupyter	.ipynb	Embutido (biblioteca padrão)	Sempre
Documentos do Word	.docx	Embutido (biblioteca padrão)	Sempre
Planilhas do Excel	.xlsx	Embutido (biblioteca padrão)	Sempre
PDF	.pdf	Conversor opcional anydoc	Instalado sob demanda*
Office antigo	.doc, .ppt, .xls, .pptx e variantes	Conversor opcional anydoc	Instalado sob demanda*
OpenDocument	.odt, .ods, .odp	Conversor opcional anydoc	Instalado sob demanda*
Texto rico e livros	.rtf, .epub	Conversor opcional anydoc	Instalado sob demanda*

* O conversor opcional é o pacote firecrawl-anydoc, instalado sob demanda onde a instalação é permitida (security.allow_lazy_installs, no config.yaml). Sem ele, os três formatos da biblioteca padrão continuam funcionando; os outros caem na proteção de arquivo binário.

A saída da conversão é Markdown, paginada pela janela normal de offset e limit do read_file. Documentos acima de 50 MB são recusados, para manter os turnos de ferramenta limitados.

A extração funciona com backends de terminal remotos (Docker, Modal, SSH): os bytes do arquivo atravessam a fronteira do backend e a conversão acontece do lado do host, então um documento dentro de um sandbox é lido igual a um local.

PDF escaneado: o aviso de cobertura

A conversão de PDF lê só a camada de texto. Páginas que são imagem escaneada — comuns em documentos jurídicos, pacotes de venda, contratos assinados, fax — não têm camada de texto e viram nada, em silêncio. O sinal típico são cabeçalhos de seção com corpo vazio.

Quando uma fatia relevante das páginas não rende texto (mais de 20% do documento, ou 10 páginas ou mais em números absolutos), o read_file põe um aviso antes da extração. Cada vão ilegível é rotulado com o último texto extraído antes dele — normalmente um divisor de seção — para o agente mirar só nos vãos de que precisa, em vez de passar OCR no documento inteiro:

[EXTRACTION COVERAGE WARNING: 198 of 311 pages in this PDF yielded no
text. ... Unreadable gaps, each labeled with the last text extracted
before it:
  pages 42-77 (36 pages) — after "Antigua Maintenance Corp Bylaws" (p41)
  pages 92-213 (122 pages) — after "... Covenants, Codes and Regulations" (p91)
  page 224 (1 page) — after "... Insurance Declaration Pages" (p223)
Decide which gaps you actually need — do NOT OCR or render everything. ...]

O aviso lista as faixas exatas de página e os caminhos de recuperação:

1. Poucas páginas — renderizar e usar visão. Converta as páginas em imagem e leia com a ferramenta de visão:

   pdftoppm -jpeg -r 150 -f 92 -l 94 documento.pdf /tmp/pagina

   Depois analise cada imagem com vision_analyze. Sem dependência extra (o poppler já é necessário para a própria detecção).

2. Muitas páginas — OCR. A skill ocr-and-documents cobre OCR em massa com o marker-pdf (mais de 90 idiomas, dá conta de equações e tabelas; instalação de 3 a 5 GB).

A detecção usa o pdftotext do poppler para contar o texto de cada página. Sem o poppler instalado, a extração continua funcionando — a checagem de cobertura é pulada em silêncio.

dica

O agente lida com o aviso sozinho — ele vai se oferecer para renderizar ou passar OCR nas páginas que faltam. Se você mesmo está lendo a extração, trate "cabeçalho com corpo vazio" como uma seção escaneada, não como uma seção ausente.