Uma ferramenta de pesquisa na web para agentes de IA que traz de volta o texto da página

Por que um agente precisa do texto da página e não apenas dos snippets?

Porque a resposta raramente está no snippet. Uma página de resultados traz um título e uma ou duas linhas escolhidas pelo mecanismo de busca. O número, a data ou a regra que seu usuário perguntou está mais abaixo na página.

Um agente que só vê snippets tem duas opções ruins. Ele pode responder a partir de um fragmento e correr o risco de errar, ou chamar uma segunda ferramenta para buscar cada página. A segunda opção dobra as idas e voltas e as definições de ferramentas.

Com LLMWebSearch, as primeiras páginas já chegam lidas. Navegação, anúncios e banners de cookies são removidos, então o modelo gasta seus tokens com conteúdo. Os resultados restantes ainda trazem seus snippets, que ajudam o modelo a decidir se deve pesquisar de novo.

Como a ferramenta de pesquisa deve ser definida?

Mantenha o schema enxuto: um query obrigatório e, no máximo, um ou dois switches. Modelos chamam ferramentas simples com mais confiabilidade. O exemplo abaixo expõe uma flag recent que mapeia para time_range=month; todo o resto fica fixo no seu código.

A função retorna texto puro, não JSON. Cada fonte começa com um número, um título e uma URL, seguidos do seu Markdown. Esse layout torna citações como [2] naturais para o modelo.

Se seu agente já inclui uma ferramenta chamada web_search, como fazem o Claude Code e o OpenClaw, dê outro nome à sua, como search_web. Duas ferramentas com o mesmo nome confundem o modelo.

Quando um agente deve pesquisar, e com que frequência?

Pesquise quando a resposta depende de fatos que mudam ou que o modelo não pode saber. Preços, versões, leis, horários e eventos recentes se enquadram. Definições e conhecimento estável geralmente não.

Escreva essa regra no system prompt e adicione um orçamento. Três hábitos ajudam:

• Planeje antes de pesquisar. Peça ao modelo que escreva suas consultas primeiro. Duas consultas precisas valem mais que cinco vagas.
• Limite as chamadas. Permita, digamos, quatro pesquisas por turno do usuário. Aumente o limite apenas para tarefas de pesquisa.
• Pare quando as fontes concordarem. Se três páginas independentes dizem a mesma coisa, o agente pode responder.

Como mantenho a janela de contexto sob controle?

Três parâmetros decidem quanto texto chega ao modelo. read define quantas páginas são lidas, de 0 a 10. max_chars limita cada página, de 500 a 50.000 caracteres. max_results define quantos resultados são listados, de 1 a 20.

Para um agente de chat, read=3 com max_chars=4000 retorna cerca de 12.000 caracteres de texto de página por pesquisa. Isso deixa espaço para várias pesquisas em uma conversa. Para um trabalho de pesquisa que resume à medida que avança, páginas mais longas são adequadas.

O campo word_count informa qual era o tamanho da página completa antes do corte. O agente pode usá-lo para decidir se busca mais com o endpoint de extração.

O que acontece quando uma página não pode ser lida?

O resultado ainda volta, com título, URL e snippet, mas sem conteúdo. Um campo content_status explica o motivo.

• blocked_by_robots: o robots.txt do site não permite nosso leitor.
• blocked_by_site_policy: Um site que define Content-Signal: ai-input=no no seu robots.txt mantém as suas páginas fora do conteúdo dos seus resultados.
• target_refused: o site respondeu com uma recusa; o status está em target_status.
• fetch_failed ou fetch_timeout: a página não carregou a tempo.

Quando um site recusa o nosso leitor, o resultado volta sem conteúdo e com o status do site: nunca resolvemos CAPTCHAs, não entramos em contas nem contornamos um bloqueio ou um paywall. Instrua o agente a usar o snippet, ou outra fonte, quando uma página voltar vazia. A pesquisa em si continua custando um crédito, aconteça o que acontecer com cada página.

Por que não usar a ferramenta de pesquisa integrada ao modelo?

Ferramentas integradas são práticas, mas dão menos controle. Em 22 de outubro de 2026, a ferramenta web_search da OpenAI custa $10 por 1.000 chamadas mais o conteúdo de pesquisa cobrado como tokens de entrada. A pesquisa na web do Claude, da Anthropic, também custa $10 por 1.000 pesquisas mais custos de tokens. O grounding do Gemini 3 inclui 5.000 pesquisas gratuitas por mês no plano pago, depois custa $14 por 1.000.

Essas ferramentas geralmente retornam uma resposta escrita com citações, não as páginas brutas. Elas também vinculam sua pesquisa a um único fornecedor de modelo. Uma ferramenta independente funciona com qualquer modelo e permite definir o tamanho de cada página. A comparação de ferramentas integradas tem a tabela completa.

Quanto custa rodar um agente com LLMWebSearch?

Um crédito por pesquisa quando read é 3 ou menos. Um assistente usado por uma equipe, respondendo 100 perguntas por dia com 4 pesquisas cada, roda cerca de 12.000 pesquisas por mês. 25.000 pesquisas a US$ 41,25 cobre esse mês e a maior parte do próximo.

Um agente de programação usado por um desenvolvedor pode pesquisar 20 vezes por dia, ou cerca de 600 vezes por mês. 5.000 pesquisas a US$ 9,25 então dura vários meses, porque os créditos nunca expiram. O guia de custos mostra a aritmética para cargas de trabalho maiores.