Fazer com que uma IA leia um documento parece trivial, mas na prática é surpreendentemente doloroso: os PDF precisam de extração de texto, os ficheiros Word precisam de bibliotecas de parsing, e os formatos legados RTF ou EPUB quase não têm ferramentas prontas a usar. O primeiro instinto é normalmente “copiar e colar o conteúdo no chat” — o que deixa de funcionar no momento em que se enfrenta um relatório de 40 páginas, um contrato formatado ou uma folha de cálculo com centenas de linhas.

O Hermes Agent acabou de transformar isto numa operação de um único comando. O read_file, a ferramenta mais utilizada no toolbox do agente, consegue agora ler PDF, Word, Excel, EPUB, RTF e uma dúzia de outros formatos de documentos diretamente, convertendo-os em Markdown limpo para o modelo consumir. Este post baseia-se em verificação prática contra o código upstream mais recente: que formatos são suportados, como funciona por baixo do capô, o que fazer com documentos digitalizados e casos de uso realistas para cada tipo de ficheiro.

O resumo num parágrafo

O read_file inclui extração automática integrada para três formatos — Jupyter notebooks (.ipynb), Word (.docx) e Excel (.xlsx) — sem dependências adicionais.

Além disso, o Hermes introduziu uma dependência opcional, firecrawl-anydoc (núcleo em Rust, importado como anydoc), que alarga a cobertura a PDF, Office legado (.doc/.ppt/.xls), OpenDocument (.odt/.ods/.odp), RTF e EPUB, todos convertidos em Markdown através de um modelo de documento partilhado. Uma vez instalado, ler estes formatos é indistinguível de ler um ficheiro de texto simples.

Matriz completa de formatos

Category	Formats	Extraction path
Notebooks	.ipynb	Built-in (stdlib, no deps)
Word	.docx	Built-in (stdlib, no deps)
Excel	.xlsx	Built-in (stdlib, no deps)
PDF	.pdf	anydoc (optional)
Legacy Office	.doc .docm .ppt .pps .pot .pptx .pptm .ppsx .ppsm .xls .xlsm .xlsb	anydoc (optional)
OpenDocument	.odt .ods .odp	anydoc (optional)
RTF	.rtf	anydoc (optional)
EPUB	.epub	anydoc (optional)

Um pormenor de design que vale a pena notar: os extratores integrados continuam a ser a autoridade para .docx/.xlsx. Mesmo com o anydoc instalado, estes dois formatos passam sempre pelo caminho da stdlib, pelo que o comportamento é idêntico com ou sem anydoc.

Como usar: basta chamar o read_file

Não há novos comandos nem novos parâmetros para o utilizador. Basta entregar um caminho de documento ao read_file:

read_file(path="/tmp/quarterly-report.pdf")

O que devolve é texto Markdown numerado por linhas, com o mesmo suporte para paginação offset/limit, truncamento por orçamento de caracteres e redação de informação sensível de qualquer outro ficheiro. Documentos demasiado grandes são truncados para o orçamento de leitura única, com uma sugestão para continuar via offset — exatamente como ao ler um ficheiro grande de texto simples.

Instalação lazy: instala automaticamente na primeira leitura, nunca bloqueia

O anydoc não é uma dependência obrigatória. Está registado em lazy_deps como tool.doc_extract (firecrawl-anydoc==0.1.6) e é instalado automaticamente na primeira vez que lê um ficheiro desse tipo, com prompt=False para que o read_file nunca bloqueie à espera de confirmação.

Se a instalação falhar ou o ficheiro estiver malformado, o ConvertError do anydoc é mapeado para ExtractionError, e o read_file recua para o tratamento normal de path/binário em vez de crashar. Documentos encriptados, PDF corrompidos e EPUB vazios seguem todos este caminho de recurso seguro.

Exemplo de saída verificado

Tomemos um contrato DOCX real como exemplo. O extrator integrado analisa os parágrafos e os nós de texto de word/document.xml:

  1|Quarterly report: revenue up 23%
  2|Second paragraph with contract terms.

Tabelas, quebras de linha e separadores são preservados; o XLSX é emitido por folha, com as folhas ocultas ignoradas:

  1|# ── Sheet: Q1 ──
  2|region\trevenue\tgrowth
  3|APAC\t$12.4M\t18%
  4|EMEA\t$9.1M\t12%

Documentos digitalizados: o caminho OCR

Os PDF baseados em texto extraem-se sem problemas, mas os PDF digitalizados (baseados em imagem) precisam de OCR. Nesse caso, os caminhos integrado/anydoc não conseguem resolver nenhum texto, e a ferramenta certa é a skill ocr-and-documents (incluída com o Hermes por defeito, v2.3.0).

A skill fornece dois extratores locais:

Capability	pymupdf (lightweight)	marker-pdf (high quality)
Text-based PDF	✅	✅
Scanned PDF (OCR)	❌	✅ (90+ languages)
Tables	✅ (basic)	✅ (high accuracy)
Equations / LaTeX	❌	✅
Code blocks / forms	❌	✅
Reading-order detection	❌	✅
EPUB	✅	✅
Install size	~25MB	~3-5GB
Speed	Instant	~1-14s/page (CPU)

pip install pymupdf pymupdf4llm
python scripts/extract_pymupdf.py scanned.pdf --markdown

Documentos em URL: web_extract primeiro

Se o documento estiver na web (artigos do arXiv, relatórios de empresas, PDF públicos), tente web_extract primeiro — converte PDF em Markdown através do Firecrawl sem dependências locais:

web_extract(urls=["https://arxiv.org/pdf/2402.03300"])

Só quando o ficheiro é local, o web_extract falha, ou é necessário processamento em lote é que se deve optar pelo caminho local. A decisão é clara: URLs → web_extract, documentos de texto locais → read_file, digitalizações/layouts complexos → ocr-and-documents.

Cenários reais

Cenário 1: Rever contratos (Word / RTF)

Alimente o contract.docx ou um contract.rtf legado diretamente ao read_file e peça ao modelo para extrair cláusulas-chave, assinalar termos de risco e comparar duas versões. O RTF é o formato legado mais comum dentro das grandes empresas — e agora já não é preciso convertê-lo manualmente para DOCX primeiro.

Cenário 2: Ler relatórios (Excel)

O read_file emite o .xlsx como texto de tabela por folha, para que o modelo possa calcular totais, detetar anomalias e produzir um resumo de análise diretamente. As folhas ocultas são ignoradas automaticamente, mantendo as áreas de trabalho internas longe do modelo.

Cenário 3: Análise de PDF em lote

Entregue ao Hermes uma lista de caminhos de relatórios PDF e deixe-o chamar read_file a cada um, e depois resumir. Combinado com um script execute_code que percorre um diretório, uma pilha de dezenas de documentos pode ser resumida numa única sessão.

Cenário 4: Ler ebooks (EPUB)

O EPUB é o formato de ebook padrão. Entregue um .epub ao Hermes para resumir capítulos, extrair ideias-chave e construir notas de leitura — tanto o anydoc como o marker-pdf suportam EPUB.

Cenário 5: Artigos de investigação

Artigos baseados em texto vão diretamente para o read_file; os digitalizados passam pelo ocr-and-documents com marker-pdf; qualquer coisa com URL passa pelo web_extract. Três caminhos cobrem todo o pipeline, do download do PDF à leitura aprofundada.

Atualização e disponibilidade

A funcionalidade chega em duas camadas:

• Trio integrado (.ipynb/.docx/.xlsx): disponível com o Hermes desde junho de 2026 — basta hermes update para qualquer versão recente e está pronto.
• Extensão anydoc (PDF/Office legado/ODF/RTF/EPUB): introduzida pelo commit b2598b41e (fundido no main upstream a 2026-08-05), é a capacidade mais recente depois da v0.20.0 e ainda não faz parte de um release com tag. Execute hermes update para obter o main mais recente; ler um ficheiro desse tipo dispara então a instalação lazy do anydoc automaticamente.

Resumo

Where the file is	What to use	Dependencies
Local, .ipynb/.docx/.xlsx	read_file	None
Local, PDF/legacy Office/ODF/RTF/EPUB	read_file + anydoc	Auto lazy-installed
Local, scans/complex layouts	ocr-and-documents skill	pymupdf or marker-pdf
Web URL	web_extract	None

Ler documentos é uma das capacidades mais fundamentais — e mais subestimadas — de um agente de IA. O Hermes reduziu todo este pipeline a um único comando, e a instalação lazy baixa a barreira das capacidades opcionais para zero. Da próxima vez que apanhar um contrato em PDF, um relatório Excel ou um ebook EPUB, basta lê-lo — sem copy-paste.

Quer continuar a explorar as capacidades de ficheiros e dados do Hermes? Consulte o resumo de dicas de produtividade, o guia de otimização de armazenamento ou ponha o Hermes mais recente a funcionar através do guia de instalação.