O que é o Cloudflare Web Search API

O Web Search API é um serviço da Cloudflare para conectar agentes e aplicações a buscas na internet. A proposta é usar informação atual em vez de depender apenas do corte de treinamento de um modelo.

A Cloudflare anunciou o serviço em 2 de outubro de 2026, em beta. Ele roda por meio do AI Gateway, a camada da empresa para observar e controlar aplicações de inteligência artificial.

Na prática, a API resolve um problema comum em agentes: responder sobre notícias, documentação ou produtos que mudam com frequência. Ela entrega resultados com URL, título e descrição para que a aplicação monte um contexto verificável.

💡
Dica

Trate a busca como coleta de evidências. A resposta final deve distinguir o que veio da fonte do que foi inferido pelo modelo.

Como funciona

O fluxo começa com uma requisição para o endpoint de Web Search do Cloudflare. Você envia uma consulta, escolhe um provedor opcional e define o limite de resultados.

No lançamento, os provedores disponíveis são Ceramic.ai, Exa e Linkup. Se nenhum for informado, o serviço usa Ceramic.ai como padrão.

A resposta contém itens com URL, título e descrição. Também pode trazer a consulta recebida, um identificador da requisição e a latência para ajudar na observabilidade.

Principais recursos

O primeiro recurso é a busca em informação viva. Um agente pode consultar mudanças recentes, documentação ou lançamentos durante a execução.

O segundo é a escolha de provedor. Isso permite testar uma alternativa diferente quando a qualidade ou a cobertura de uma busca não atender ao caso.

O terceiro é a integração com o AI Gateway. As requisições ficam associadas aos registros do gateway e podem usar créditos da plataforma ou uma chave própria.

  • REST: útil para APIs em Python, Node.js, Go ou .NET.
  • Workers: chama a busca dentro de uma aplicação distribuída na rede Cloudflare.
  • Limite: cada requisição pode pedir de 1 a 10 resultados.

Como começar: instalação ou acesso passo a passo

O primeiro requisito é uma conta Cloudflare com acesso ao AI Gateway. Toda conta possui um gateway chamado default, embora seja possível criar outro para separar ambientes.

Carregue créditos do AI Gateway ou configure uma chave de provedor no gateway. A alternativa de chave própria é chamada de BYOK e evita enviar a chave diretamente na aplicação.

Para usar a REST API, crie um token com Account Workers AI Read e Account AI Gateway Read. Guarde o token em uma variável de ambiente e nunca o coloque no frontend.

set CLOUDFLARE_ACCOUNT_ID=seu-account-id
set CLOUDFLARE_API_TOKEN=seu-token
curl https://api.cloudflare.com/client/v4/accounts/%CLOUDFLARE_ACCOUNT_ID/ai/websearch/ --request POST

Na chamada real, adicione os cabeçalhos de autenticação e um corpo JSON com query, provider, limit e options.gateway.id conforme a documentação oficial.

Exemplo prático

Imagine um agente que responde dúvidas sobre versões de bibliotecas. Antes de responder, ele recebe a pergunta, consulta o Web Search API e envia resultados relevantes ao modelo.

Um backend pode montar um corpo semelhante ao exemplo abaixo. O código usa um objeto JavaScript e deve ser adaptado ao cliente HTTP do projeto.

const body = { query: 'Quais mudanças recentes chegaram ao Node.js?', provider: 'exa', limit: 5, options: { gateway: { id: 'default' } } };

Depois da resposta, filtre resultados vazios, preserve as URLs e envie ao modelo somente o contexto necessário. O agente pode citar os links ou recusar a resposta quando não houver evidência suficiente.

Esse fluxo facilita testes: guarde o requestId, compare provedores e observe a latência no AI Gateway.

Comparação com alternativas

Um índice próprio oferece mais controle sobre conteúdo e atualização, mas exige crawler, armazenamento e manutenção.

Uma API de busca contratada diretamente faz sentido quando a equipe já possui contrato ou limites negociados. O Web Search API acrescenta o roteamento pelo AI Gateway.

A busca manual continua adequada para investigação exploratória, mas não escala para cada chamada de um agente. A API é mais interessante quando a consulta é repetível.

  • Web Search API: bom para começar com REST ou Workers e centralizar observabilidade.
  • Índice próprio: melhor quando domínio e atualização são totalmente controlados.
  • Provedor direto: adequado quando já existe integração comercial estabelecida.

Pontos positivos e limitações

O principal ponto positivo é reduzir respostas baseadas em informação desatualizada. A integração pode ser feita por backend REST ou por Worker.

Outro benefício é a escolha entre créditos do AI Gateway e uma chave própria. A plataforma informa que não aplica margem adicional ao preço de lista do provedor quando a cobrança usa créditos do gateway.

A limitação mais importante é o status beta. Cobertura, comportamento e detalhes comerciais podem evoluir. Uma URL retornada também não garante que o conteúdo esteja correto.

⚠️
Atenção

Não transforme o resultado da busca em fato automaticamente. Valide fonte, data e contexto antes de executar uma ação importante.

Casos de uso reais

Em suporte, a API pode pesquisar a documentação mais recente antes de sugerir um comando. Isso reduz o risco de recomendar uma opção removida.

Em pesquisa, a chamada reúne páginas sobre empresa, produto ou padrão técnico. O modelo organiza o material, mas os links ficam disponíveis para conferência.

Em monitoramento, buscas periódicas ajudam a detectar mudanças em changelogs e avisos públicos, com regras para evitar alertas repetidos.

Em educação, o agente pode buscar exemplos recentes e explicar o assunto em português, deixando claro quando o material foi resumido.

Dicas e boas práticas

Comece com consultas específicas. Produto, versão e objetivo costumam gerar resultados mais úteis do que termos genéricos.

💡
Dica

Limite os resultados ao necessário. Cinco páginas bem escolhidas são mais fáceis de revisar do que dez resultados repetidos.

Registre consulta, provedor e requestId sem salvar tokens ou dados pessoais. Esses campos ajudam a investigar falhas sem expor credenciais.

🚀
Pro tip

Use uma etapa de seleção antes do modelo para remover URLs duplicadas, limitar domínios e descartar descrições irrelevantes.

Defina uma política para falhas. Se o provedor estiver indisponível, informe que a busca não foi concluída em vez de inventar uma resposta.

🔴
Cuidado

Nunca coloque CLOUDFLARE_API_TOKEN em código client-side, logs ou exemplos publicados com valor real.

Vale a pena?

O Web Search API vale a pena para equipes que constroem agentes e precisam consultar a internet durante a execução. REST, Workers e AI Gateway reduzem o trabalho inicial.

Ele não é a melhor escolha para quem precisa de um catálogo fechado, controlado e auditado por uma equipe editorial. Nessa situação, um índice próprio oferece mais previsibilidade.

O próximo passo é criar um gateway de teste, executar consultas sem dados sensíveis e medir relevância, latência e custo. Depois, compare Ceramic.ai, Exa e Linkup.