Resposta rápida
A Cloudflare Web Search API permite que um agente consulte informações atuais sem adivinhar URLs. A aplicação envia uma consulta ao endpoint /ai/websearch/ ou ao método websearch() do binding AI, escolhe Ceramic.ai, Exa ou Linkup e recebe resultados normalizados com URL, título e descrição quando disponível.
Toda busca passa por um AI Gateway. Antes de usar em produção, crie ou escolha o gateway, carregue créditos ou armazene uma chave do provedor, aplique autenticação e defina como os logs tratarão consultas e respostas. A API está em beta e não substitui a obrigação de abrir, validar e citar as fontes que sustentam a resposta final do agente.
O que foi lançado em 2 de outubro de 2026
A Cloudflare disponibilizou a Web Search API em beta com três provedores: Ceramic.ai, Exa e Linkup. O serviço usa o AI Gateway como camada de controle, registra as buscas nos logs do gateway e cobra o preço de tabela do provedor quando a conta usa créditos do AI Gateway, sem markup adicional informado pela Cloudflare.
O retorno padronizado reduz código específico por provedor. Trocar provider muda a origem da busca sem exigir outro formato de resposta. Isso facilita fallback e comparação, mas não torna os índices equivalentes: cobertura, trechos, retenção, preço e relevância variam entre os provedores.
Pré-requisitos e permissões mínimas
Para chamar a API por REST, a conta precisa de um AI Gateway e de créditos disponíveis ou uma chave de provedor salva no gateway. O token da Cloudflare usado no endpoint precisa das permissões Account > Workers AI > Read e Account > AI Gateway > Read. Não reutilize um token administrativo amplo só porque ele já funciona no painel.
Em um Worker, adicione o binding AI e chame env.AI.websearch() com gatewayId, query e provider. Armazene IDs e aliases na configuração, mas mantenha tokens e chaves fora do código e do repositório. Para desenvolvimento local, use um segredo separado e revogável.
- Crie ou identifique o AI Gateway que receberá as buscas.
- Escolha entre créditos do AI Gateway e uma chave própria do provedor.
- Gere um token da Cloudflare apenas com Workers AI Read e AI Gateway Read.
- Teste uma consulta sem dados pessoais e confirme resultado, status e custo no gateway.
- Revogue o token de teste se ele foi copiado para terminal, ticket ou log sem proteção.
Como fazer a primeira busca
O endpoint REST recebe POST em https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/websearch/. O corpo mínimo inclui query e options.gateway.id. provider é opcional; quando ausente, a API usa Ceramic.ai. O parâmetro limit aceita de 1 a 10 resultados, e a consulta aceita de 1 a 1.024 caracteres.
No binding do Worker, o método websearch() devolve um objeto Response padrão. Leia o JSON, valide se items é uma lista e trate ausência de campos opcionais. O exemplo oficial mostra items com url, title e description, além de metadata com query, requestId e latencyMs.
- Envie uma consulta curta e específica, sem instruções ocultas ou credenciais.
- Defina limit de acordo com o espaço de contexto que o agente realmente consegue revisar.
- Valide protocolo e domínio antes de buscar o conteúdo de uma URL retornada.
- Preserve requestId para diagnóstico, sem anexar tokens ou chaves ao log.
- Passe ao modelo apenas os resultados necessários e exija links na resposta final.
Ceramic.ai, Exa ou Linkup: como escolher
A página oficial de provedores lista Ceramic.ai como padrão e informa US$ 0,25 por mil requisições, com descrições que podem chegar a 8.000 caracteres. Exa usa o modo auto, retorna destaques relevantes e custa US$ 7 por mil requisições. Linkup usa busca fast com resultados brutos e custa US$ 5 por mil requisições.
Preço não determina qualidade para toda consulta. Compare um conjunto fixo de perguntas reais, registre quais fontes cada provedor retorna e meça quantas respostas úteis chegam ao modelo. Consultas com descrições longas podem consumir mais contexto, enquanto trechos curtos podem exigir que a aplicação abra a página antes de responder.
- Use Ceramic.ai como baseline de custo e latência para consultas frequentes.
- Teste Exa quando destaques diretamente relacionados à pergunta forem importantes.
- Teste Linkup quando o fluxo precisa de resultados rápidos e atribuídos para uma chamada de ferramenta.
- Reavalie preços e condições antes de fixar um provedor em produção.
BYOK sem enviar a chave na requisição
No modo Bring Your Own Key, a chave do provedor fica armazenada no AI Gateway e recebe um alias. A chamada envia provider e byokAlias, não o segredo. A documentação informa que a chave salva é recuperada pelo gateway e criptografada pelo Secrets Store.
Se byokAlias for informado e o alias não existir para aquele provedor, a requisição falha com 400 em vez de consumir créditos do gateway. Quando o alias é omitido, o gateway usa a chave default salva para o provedor; se não houver, a busca é cobrada nos créditos do AI Gateway. Documente essa precedência para não confundir falha de configuração com saldo insuficiente.
Logs, privacidade e uma divergência importante
Os logs do AI Gateway podem incluir consulta, resposta, provedor, status, custo e duração. Para manter metadados sem armazenar o conteúdo bruto, use cf-aig-collect-log-payload: false quando esse header for compatível com a rota usada. Desativar o log inteiro também remove os metadados que ajudam a diagnosticar custo e falha.
As páginas oficiais não estão totalmente alinhadas sobre Zero Data Retention. O anúncio afirma que os três provedores oferecem ZDR para requisições pela Cloudflare, mas a página detalhada de provedores, verificada em 4 de outubro de 2026, marca Ceramic.ai e Linkup como Yes e Exa como No. Para dados sensíveis, siga a tabela detalhada atual, confirme o contrato do provedor e não envie a consulta até a Cloudflare esclarecer a divergência.
Como conectar a busca ao agente com segurança
Trate resultados da web como entrada não confiável. Uma página pode conter instruções maliciosas, texto desatualizado ou alegações sem prova. O agente deve extrair fatos, preservar URLs, comparar fontes e ignorar comandos encontrados dentro do conteúdo recuperado.
A busca deve ser uma ferramenta limitada, não uma autorização ampla de navegação. Restrinja número de chamadas, tamanho da consulta, domínios permitidos quando necessário e tempo máximo. Para decisões médicas, financeiras, jurídicas ou de segurança, exija fontes primárias e revisão humana antes de qualquer ação externa.
- Defina um schema curto para query e rejeite entradas vazias ou acima do limite.
- Imponha teto de buscas por tarefa e orçamento por usuário ou projeto.
- Filtre URLs inseguras antes de qualquer fetch posterior.
- Peça ao modelo que diferencie fato encontrado, inferência e informação ainda não verificada.
- Nunca permita que texto recuperado conceda novas ferramentas, credenciais ou permissões.
Falhas comuns e como diagnosticar
Um 400 com BYOK costuma exigir revisão do provider, do byokAlias e da chave salva no gateway. Respostas 401 ou 403 pedem conferência do token da Cloudflare e das duas permissões mínimas. Resultado vazio não prova indisponibilidade: reformule a consulta, compare provedor e verifique se limit, idioma ou termos ficaram restritivos demais.
Se todas as buscas falharem ao mesmo tempo, consulte o Cloudflare Status antes de rotacionar credenciais. Quando só um provedor falhar, compare logs, requestId, saldo e chave configurada. Não implemente retries sem limite: uma configuração inválida pode repetir custos ou prolongar o incidente.
Limitações e próxima ação útil
Este guia foi verificado em 4 de outubro de 2026. A Web Search API está em beta, limita cada resposta a no máximo dez resultados e depende de índices e políticas de terceiros. Ela retorna candidatos para pesquisa; não garante que uma página esteja correta, atualizada, licenciada para reprodução ou suficiente para sustentar uma conclusão.
Comece com dez consultas representativas e dados não sensíveis. Compare Ceramic.ai, Exa e Linkup por fonte, utilidade, latência, custo e retenção. Em seguida, conecte o melhor fluxo a um agente somente de leitura, preserve as URLs na resposta e monitore os logs sem payload bruto antes de liberar pesquisas reais.
Faça o próximo teste
Fontes consultadas
Os links abaixo servem para conferir conceitos, orientações oficiais e o critério editorial usado neste conteúdo.
- Introducing Web Search APICloudflare Changelog
- How to use Web Search APICloudflare Docs
- About Web Search APICloudflare Docs
- Providers and pricingCloudflare Docs
- AI Gateway loggingCloudflare Docs
- Cloudflare StatusCloudflare