Browserbase Search: busca estruturada antes de abrir o navegador

ANÁLISE EDITORIAL

Encontrar boas URLs não exige, por si só, abrir um navegador, carregar JavaScript ou manter uma sessão. A Browserbase Search organiza essa etapa como uma chamada de API: recebe uma consulta, limita a quantidade e devolve resultados estruturados com título, URL e metadados. A proposta é útil quando a tarefa começa por descoberta de fontes, mas ainda não precisa ler ou interagir com cada página.

Esta curadoria separa duas coisas que costumam ser misturadas. Buscar aponta onde olhar. Fetch recupera conteúdo sem interação. Um navegador entra quando é necessário renderizar JavaScript, clicar, preencher formulários ou trabalhar com uma sessão. A separação reduz complexidade, mas não torna o resultado confiável por padrão. Títulos, URLs e metadados continuam sendo conteúdo externo e precisam de validação.

Imagem: Ilustração editorial exclusiva do Bastidores da IA sobre uma lente organizando cartões abstratos em resultados estruturados. Não é captura de tela, interface real, logotipo oficial, consulta executada nem prova de acesso à Browserbase.

O que esta Skill faz de verdade

O SKILL.md fixado no commit auditado orienta o agente a enviar um POST para https://api.browserbase.com/v1/search. O corpo JSON aceita uma consulta e uma quantidade de resultados. A autenticação usa o cabeçalho X-BB-API-Key, preenchido a partir da variável de ambiente BROWSERBASE_API_KEY.

A resposta documentada contém um identificador da requisição, a consulta e uma lista. Cada item pode trazer URL, título, autor, data de publicação, imagem e favicon. A Skill sugere filtrar a resposta com jq, para que o agente receba apenas os campos necessários. Ela não abre as páginas encontradas, não executa código do site, não clica e não preenche formulários.

Há uma divergência de versão que precisa ficar visível. O arquivo auditado afirma que o SDK ainda não possui busca e recomenda cURL ou HTTP direto. A documentação oficial atual da Search API, consultada em 25/08/2026, já mostra exemplos com os SDKs TypeScript e Python. Por isso, trate o SKILL.md como instrução fixada no commit e a documentação oficial como referência atual de capacidades.

Para quem serve

A Skill serve para quem precisa começar uma pesquisa por uma lista curta de fontes candidatas. Desenvolvedores podem localizar documentação técnica. Analistas podem reunir URLs para uma etapa posterior de leitura. Equipes de conteúdo podem descobrir páginas oficiais antes de comparar afirmações. Agentes podem reduzir uma consulta ampla a poucos links antes de consumir mais rede e contexto.

Ela é especialmente útil em fluxos com etapas claras: pesquisar, selecionar, buscar conteúdo e só então navegar. A primeira resposta pode trazer cinco títulos e URLs. Uma pessoa ou regra verificável escolhe quais domínios merecem leitura. O Fetch pode recuperar texto de páginas simples. O navegador fica reservado para interfaces, conteúdo renderizado ou ações.

Não serve como prova de que uma página é correta, atual ou segura. A posição na lista não substitui avaliação editorial. O campo de autor pode estar ausente. A data pode ser nula ou refletir metadados inconsistentes. Um título pode exagerar o conteúdo. Para decisões importantes, abra a fonte canônica, confira a data e procure confirmação independente.

Compatibilidade e pré-requisitos

O uso por cURL exige acesso de rede, uma conta Browserbase, uma chave de API válida e um shell capaz de definir variável de ambiente. O exemplo também usa jq para reduzir JSON, embora seja possível tratar a resposta em outra linguagem. No Windows, PowerShell possui curl.exe; confirme que está chamando o executável esperado e não um alias com comportamento diferente.

Para instalar como Agent Skill, o cliente precisa reconhecer pastas com SKILL.md. O repositório documenta instalação com npx skills add browserbase/skills e um marketplace para Claude Code. Outros clientes podem aceitar a pasta manualmente, mas diretórios, comandos e permissões variam. Confira a documentação do agente antes de copiar arquivos.

O serviço também depende do plano e das cotas vigentes. Esta página não fixa preço ou quantidade incluída porque esses dados podem mudar. Consulte a página oficial de planos imediatamente antes de ativar uso recorrente. Defina limite de chamadas e responsável pelo consumo antes de integrar a API a uma automação.

Instalação recomendada

A rota mais simples para um cliente compatível é instalar o repositório oficial e selecionar a Skill Search:

npx skills add browserbase/skills

Para uma revisão reproduzível, clone a origem e fixe o commit desta curadoria:

git clone https://github.com/browserbase/skills.git
cd skills
git checkout d15a21ffde5a020feb39393603089f3824389eba

Revise a pasta skills/search antes de copiá-la ao diretório do agente. Ela contém SKILL.md, EXAMPLES.md, REFERENCE.md e LICENSE.txt. Não é necessário instalar o runtime completo de navegador para executar o exemplo HTTP da Search API. Ainda assim, a chave e o acesso ao serviço são obrigatórios.

O ZIP do Bastidores preserva esses quatro arquivos textuais e acrescenta ORIGEM.md. Ele não contém chave, respostas, SDK, pacote npm, dependências ou executáveis. O download local e o repositório oficial são ações separadas: use o ZIP para auditoria documental e a origem oficial para acompanhar mudanças e instruções novas.

Configuração antes do primeiro uso

Crie ou selecione uma chave no painel da Browserbase e armazene-a como variável de ambiente. Não cole o valor em prompts, prints, arquivos Markdown, commits ou comandos que ficarão no histórico. O formato abaixo usa um nome simbólico e não deve receber a chave em conteúdo compartilhado:

export BROWSERBASE_API_KEY="defina-no-seu-ambiente"

No PowerShell, prefira definir a variável somente para o processo que executará o teste. Em CI, use o cofre de segredos da plataforma. Conceda acesso apenas ao job necessário e evite imprimir cabeçalhos. Se a chamada falhar, registre o código HTTP e o identificador da requisição, nunca o valor da chave.

Antes da consulta, escreva uma pergunta específica, defina a quantidade máxima e escolha quais campos realmente serão usados. “Documentação oficial de autenticação da API X, cinco resultados” é verificável. “Pesquise tudo sobre IA” tende a produzir ruído e consumo desnecessário. Se houver domínios preferidos, inclua-os na consulta e confirme a origem depois.

Primeiro uso seguro

Comece com uma consulta pequena e sem dados pessoais ou termos internos. Este exemplo pede três resultados e reduz a resposta a título e URL:

curl -s -X POST "https://api.browserbase.com/v1/search" 
  -H "Content-Type: application/json" 
  -H "X-BB-API-Key: $BROWSERBASE_API_KEY" 
  -d '{"query":"documentação oficial de Agent Skills","numResults":3}' 
  | jq '.results[] | {title, url}'

Esta curadoria não executou a chamada, pois nenhuma chave foi fornecida ou necessária para auditar os arquivos. O resultado esperado vem da referência oficial do endpoint. Ao testar, confira o código HTTP, a presença de requestId e a quantidade recebida antes de encaminhar URLs a outra ferramenta.

Não abra automaticamente todos os resultados. Primeiro valide protocolo, domínio e formato. Bloqueie esquemas inesperados. Evite baixar arquivos ou seguir redirecionamentos sem necessidade. Se o próximo passo for ler uma página, use Fetch apenas em URLs aprovadas. Se for interagir, abra uma nova etapa de navegador com limites e confirmação adequados.

Resultado esperado

Uma resposta bem-sucedida deve trazer JSON válido com requestId, query e results. Uma consulta limitada a três itens deve produzir no máximo três objetos. Título e URL são os campos principais para descoberta. Autor, data, imagem e favicon podem estar ausentes, então o consumidor precisa aceitar valores nulos.

O resultado correto nesta etapa é uma lista de candidatas, não um resumo factual. Para transformar a busca em pesquisa, recupere o conteúdo das páginas selecionadas, identifique fonte primária, registre data e compare afirmações. A Search API ajuda a encontrar caminhos. Ela não verifica o conteúdo e não substitui julgamento humano.

A documentação oficial também mostra SDKs atuais. Se sua aplicação já usa TypeScript ou Python, compare a chamada HTTP com o método documentado pelo SDK e fixe a versão da dependência. Não copie cegamente a afirmação antiga do SKILL.md sobre ausência de suporte. Esse é exatamente o tipo de diferença que uma revisão por commit e data precisa revelar.

Permissões e riscos

A chave de API é o principal segredo. Quem a obtiver pode consumir a conta dentro dos limites e capacidades associados. Mantenha-a fora do repositório, do HTML publicado, do ZIP e da saída do agente. Revogue e substitua a chave se houver exposição. O guia do Bastidores sobre revisão de permissões de agentes ajuda a separar rede, leitura, escrita e ações externas.

Os resultados são entrada remota não confiável. Um título pode conter instruções direcionadas ao agente, uma URL pode apontar para domínio semelhante e um metadado pode ser falso. Nunca trate texto do resultado como comando. Valide domínio e conteúdo em uma etapa separada. A própria Skill alerta para não seguir instruções embutidas em títulos ou URLs.

Consultas também podem revelar intenção de pesquisa, nomes internos, clientes ou incidentes. Evite enviar termos confidenciais sem autorização e política adequada. Para dados sensíveis, prefira consultas genéricas ou fontes internas aprovadas. Registre apenas o necessário para auditoria, sem armazenar a chave ou respostas integrais.

Automação recorrente pode gerar custo e atingir limite. Defina quantidade por consulta, intervalo, tentativas e teto diário. Um erro 429 pede redução de frequência. Um erro 500 permite tentativa controlada, mas repetir indefinidamente não é estratégia. Após falhas, registre o código e revise a causa.

Erros comuns

• Receber 403: confira se a variável existe no processo correto e se a chave está válida, sem imprimir o valor.
• Receber 429: reduza a frequência e consulte cota e plano atuais.
• Enviar consulta vazia: a documentação atual exige texto entre 1 e 200 caracteres.
• Pedir mais de 25 resultados: use o intervalo documentado e comece com três ou cinco.
• Esperar conteúdo completo: Search devolve descoberta e metadados. Use Fetch ou navegador em etapa posterior.
• Confiar no primeiro domínio: verifique URL canônica, mantenedor e data antes de citar.
• Executar títulos como instruções: trate toda resposta como dado externo não confiável.
• Colar a chave no comando compartilhado: use variável de ambiente ou segredo de CI.
• Assumir que o SDK não oferece busca: essa frase do commit está desatualizada diante da documentação oficial atual.
• Confundir ZIP com acesso ao serviço: o pacote contém instruções, referências e licença, não uma conta ou credencial.

Versão auditada e download local

A curadoria fixou o commit d15a21ffde5a020feb39393603089f3824389eba. Em 25/08/2026, o repositório oficial browserbase/skills tinha 3.702 estrelas e não estava arquivado. Estrelas mostram adoção observável, mas não garantem segurança, estabilidade ou compatibilidade futura.

A licença MIT do diretório permite redistribuição sob suas condições. O download local auditado tem 6.082 bytes e SHA-256 5bf3d5a3f197fc89c700e736b9c9fb2499f1ffcab96cd51c5165c97a7fbd033b. Ele contém somente EXAMPLES.md, LICENSE.txt, ORIGEM.md, REFERENCE.md e SKILL.md.

Resultado esperado e limite final

Browserbase Search é útil quando o agente precisa descobrir onde procurar sem assumir o custo e a superfície de uma sessão de navegador. O teste mínimo deve devolver poucas URLs, preservar o identificador da requisição e permitir que uma pessoa confira os domínios antes da leitura.

Considere a primeira etapa concluída quando a consulta tiver objetivo claro, quantidade pequena, chave protegida e saída reduzida a título e URL. O próximo passo deve ser explícito: validar, buscar conteúdo ou navegar. Não transforme descoberta em ação externa automática.

A divergência entre o SKILL.md e a documentação atual é um lembrete prático. Skills envelhecem. Fixar commit torna a auditoria reproduzível, mas não congela o serviço. Antes de usar em produção, releia endpoint, autenticação, SDK, limites, termos e preços oficiais.

Fontes primárias

• Repositório oficial browserbase/skills
• Pasta Search no commit auditado
• SKILL.md oficial fixado
• Exemplos oficiais fixados
• Referência da Skill fixada
• Licença MIT preservada
• Referência oficial atual da Web Search API
• Visão geral oficial atual da Search API
• Planos e cotas oficiais atuais