Para que um agente de IA leia páginas web e PDF como Markdown, web_fetch do Agents SDK do Cloudflare é suficiente; para apps em JavaScript ou sessões com login, ainda precisa de um navegador de verdade. A ferramenta chegou em agents@0.28.0 no dia 9 de outubro de 2026, e no yoDEV a implantamos em um Worker real para comprovar o que devolve de fato.
yoDEV Tested · 13 de outubro de 2026
Implantamos oweb_fetchdoagents@0.28.0em um Worker real com um binding do Workers AI e o apontamos para sete URLs. Os resultados que apresentamos como nossos vêm desse teste.
A mesma versão também trouxe uma ferramenta browser. Então a pergunta útil não é só como usar web_fetch, mas quando é o suficiente e quando seu agente precisa de um navegador de verdade. Nosso teste responde isso com resultados reais, não com a documentação.
O que é o Agents SDK do Cloudflare?
O Agents SDK é o framework do Cloudflare para construir e implantar agentes de IA sobre Workers. Se publica no npm como agents e se desenvolve no repositório público cloudflare/agents do GitHub. Reúne as peças que um agente precisa: estado, tarefas programadas, WebSockets, clientes MCP e, desde agora, ferramentas prontas para usar como web_fetch e browser, com adaptadores para AI SDK, TanStack AI e o harness Pi do Cloudflare.
O que faz web_fetch?
web_fetch recebe uma URL e devolve seu conteúdo como texto que o modelo pode ler, junto com a URL final, o código HTTP e o tipo de conteúdo. Segundo a documentação oficial:
| Entrada | O que faz web_fetch |
|---|---|
| Página HTML | A converte para Markdown com Workers AI Markdown Conversion |
| Site compatível com Markdown for Agents | Pede Markdown primeiro e pula a conversão |
| PDF e documentos do Office compatíveis | Os converte para Markdown com Workers AI |
| JSON | O formata para ficar legível |
| Conteúdo longo | Devolve uma janela de 20.000 caracteres por padrão, com um offset para continuar |
| Qualquer requisição | Aplica sua lista de hosts permitidos, controles de redirecionamento, limite de bytes e timeout |
Faz requisições GET simples: não executa JavaScript, não envia cookies e não faz login.
O que devolve web_fetch? Testamos em um Worker real
No dia 13 de outubro de 2026 implantamos um Worker temporário na conta do Cloudflare do yoDEV com agents@0.28.0, a função fetchWeb() e um binding de Workers AI, e o apontamos para sete URLs. Sem modelo e sem Durable Object: só a saída da ferramenta. Ao terminar, deletamos o Worker.
| Caso | Resultado | Tempo |
|---|---|---|
| Página de documentação do Cloudflare | 200 · text/markdown → markdown: o site entregou Markdown direto, sem conversão · 13.245 caracteres |
136 ms |
| Página de resumo do arXiv (HTML) | 200 · text/html → markdown via Workers AI · 8.347 caracteres |
692 ms |
| PDF de “Attention Is All You Need” | 200 · application/pdf → markdown · 39.813 caracteres |
~2,0 s |
Mesmo PDF, segunda janela (offset=1480) |
chars 1480–2601 of 39813 |
~1,6 s |
| Excalidraw (app em JavaScript) | 200 OK, só 270 caracteres: título, descrição e imagem, sem o conteúdo da app | 159 ms |
example.com (fora da lista permitida) |
Erro web_fetch_disallowed_url, retryable: false |
77 ms |
localhost |
Erro web_fetch_disallowed_url |
74 ms |
Cada tempo corresponde a uma única execução de um local. Considere-os como referência, não como benchmark.
Três descobertas importam mais que os números:
- Uma app em JavaScript não falha: devolve quase nada. Excalidraw respondeu 200 com um título e uma descrição. Um agente que só olha o código de status acreditará que leu a página. A documentação descreve um erro
web_fetch_blockedpara desafios anti-bot, mas o cascarão vazio de uma app renderizada no cliente não produz nenhum erro. - A saída de um PDF é útil, não perfeita. O Markdown começa com um bloco de metadados do PDF (criador, produtor, datas) antes de
### Page 1, e nas primeiras linhas algumas palavras ficam coladas (“NeedAshish Vaswani”). Serve para que um modelo o leia e o resuma; não para publicá-lo como está. - Cada
offsetvolta a baixar e converter o documento. A segunda janela do PDF custou outros 1,6 segundos de conversão, conforme adverte a documentação. Além disso cortou em uma quebra de linha (2.601 em vez do limite pedido), o que evita partir frases no meio.
Como instalar web_fetch com Cloudflare Workers AI?
Você precisa do Agents SDK 0.28.0 ou superior e um binding de Workers AI. Estes passos saem da documentação do Cloudflare.
Atualize o SDK no seu projeto de Worker:
npm i agents@latest
Adicione o binding de Workers AI a wrangler.jsonc, que web_fetch usa para converter HTML e documentos:
{
"ai": {
"binding": "AI",
"remote": true
}
}
Em desenvolvimento local, as conversões são executadas remotamente contra sua conta do Cloudflare. Markdown, JSON e texto simples não passam por Workers AI.
Depois, adicione a ferramenta à sua chamada existente de AI SDK:
import { streamText } from "ai";
import { webFetchTool } from "agents/webfetch/ai-sdk";
const tools = {
web_fetch: webFetchTool({ binding: env.AI }),
};
const result = streamText({ model, messages, tools });
O SDK também inclui adaptadores em agents/webfetch/tanstack-ai e agents/webfetch/pi.
Como extrair texto de um PDF ou uma página web sem chamar um modelo?
Use fetchWeb() de agents/webfetch. Devolve a página completa já convertida, e windowWebFetchPage() junto com renderWebFetchPage() produzem o mesmo resultado limitado que os adaptadores entregam ao modelo. Não precisa de Durable Object nem navegador. Este é o núcleo do Worker que testamos:
import {
fetchWeb,
renderWebFetchPage,
windowWebFetchPage,
} from "agents/webfetch";
const page = await fetchWeb(
{ url },
{ binding: env.AI, allowedHosts: ["developers.cloudflare.com", "arxiv.org"] },
);
const output = windowWebFetchPage(page, { offset: 0, pageChars: 20_000 });
return new Response(renderWebFetchPage(output));
Isso é o que recebe o modelo (de nosso teste com o PDF):
web_fetch: https://arxiv.org/pdf/1706.03762 · 200 · application/pdf → markdown · chars 0–1480 of 39813 · continue with offset=1480
<untrusted_web_content>
...
</untrusted_web_content>
Se o que você procura é converter PDF para Markdown em sua própria máquina, sem Workers, confira MarkItDown, a ferramenta da Microsoft que converte qualquer documento em contexto para sua IA.
Como ler um PDF longo por partes?
Passe o offset do resultado anterior para obter a próxima janela. Se escrever seu próprio handler, guarde o WebFetchPage que devolveu fetchWeb() e volte a chamar windowWebFetchPage() com o novo offset: assim você lê a próxima parte sem baixar nem converter o documento outra vez. Em nosso teste, pular esse passo significou pagar duas vezes pela conversão do PDF.
Como limitar quais sites seu agente pode ler?
Defina a política de requisições ao criar a ferramenta. O modelo só escolhe url, offset e format; os limites você escolhe:
| Opção | Valor padrão | Efeito |
|---|---|---|
allowedHosts |
Qualquer host público | Hosts que a ferramenta pode ler; *.example.com cobre subdomínios, não example.com |
blockedHosts |
Nenhum | Hosts sempre rejeitados, são verificados primeiro |
pageChars |
20000 | Máximo de caracteres por resultado |
maxBytes |
5000000 | Tamanho máximo da resposta |
timeoutMs |
30000 | Prazo total, incluindo redirecionamentos e conversão |
maxRedirects |
5 | Redirecionamentos que segue (de 0 a 20) |
allowPrivateHosts |
false | Permite hosts locais e privados, para desenvolvimento local |
A fonte integrada também rejeita esquemas que não sejam HTTP, credenciais na URL, URLs com mais de 2.000 caracteres e redirecionamentos de HTTPS para HTTP, e valida novamente cada destino de redirecionamento. Um limite que vale conhecer: bloqueia IPs privados escritos literalmente e nomes de host locais, mas não resolve DNS para comprobar a qual host público aponta. Em um agente que lê URLs arbitrárias, allowedHosts é o controle que realmente reduz a superfície de ataque.
web_fetch ou navegador: qual precisa seu agente?
Use web_fetch quando o conteúdo vem no HTML ou no arquivo que o servidor envia: documentação, blogs, PDF, documentos do Office, APIs JSON. Em nosso teste leu tudo isso entre milissegundos e alguns segundos, sem lançar nenhum navegador.
Use um navegador (a ferramenta browser do Cloudflare, que chegou na mesma versão 0.28.0) quando o agente precisa:
- Conteúdo renderizado com JavaScript. Nosso teste com Excalidraw devolveu 200 sem conteúdo.
- Uma sessão iniciada.
web_fetchnão envia cookies nem credenciais. - Interação ou capturas. Clicar, preencher formulários, ver como fica a página.
- Páginas atrás de um desafio anti-bot, que
web_fetchreporta comoweb_fetch_blocked.
Uma regra prática: teste primeiro com web_fetch, e se o resultado for suspeito mente curto para a página (como 270 caracteres para uma app completa), passe para o navegador. Se quer um Chrome headless como serviço HTTP, já analisamos Browser Run do Cloudflare.
Quais limites tem web_fetch?
- Prompt injection. O conteúdo chega envolvido em
<untrusted_web_content>, que o marca como dados e não como instruções. A documentação do Cloudflare esclarece que isso não garante proteção contra prompt injection. - Custo. A conversão de HTML e documentos é executada em Workers AI e é cobrada em sua conta. No momento de publicar esta nota não tínhamos verificado o preço de Markdown Conversion; verifique antes de processar lotes grandes de PDF.
- Conteúdo não compatível. Não suporta imagens, áudio nem vídeo, e
format: "raw"não pode devolver PDF. - Uma API jovem. No dia 13 de outubro de 2026,
web_fetchrequer o Agents SDK 0.28.0 ou superior, e o pacote segue em versões 0.x. Espere mudanças em imports e opções; verifique a documentação antes de atualizar.
E você? Que tipo de conteúdo precisa ler seu agente: documentação, PDF ou apps web?
- Com um fetch simples ou uma ferramenta como web_fetch
- Com um navegador headless (Playwright, Puppeteer, Browser Run)
- Ainda não dou acesso à web
- Prefiro outra opção (conte qual)
Comente abaixo ou, se este artigo chegou por email, responda direto ao email: sua resposta se publica aqui.
Relacionado: MarkItDown: A Ferramenta da Microsoft que Converte Qualquer Documento em Contexto para sua IA