Busca e extração na web

O Hermes Agent inclui duas ferramentas de web que o modelo pode chamar, apoiadas por vários provedores:

• web_search — busca na web e devolve resultados ranqueados
• web_extract — baixa e extrai o conteúdo legível de uma ou mais URLs

As duas são configuradas por uma única escolha de backend. Os provedores são escolhidos com hermes tools ou definidos direto no config.yaml.

Backends

Provedor	Variável de ambiente	Busca	Extração	Camada gratuita
Firecrawl (padrão)	FIRECRAWL_API_KEY (opcional — sem chave quando selecionado)	✔	✔	500 créditos/mês · nuvem sem chave quando selecionado
SearXNG	SEARXNG_URL	✔	—	✔ Grátis (auto-hospedado)
Brave Search (camada gratuita)	BRAVE_SEARCH_API_KEY	✔	—	2 000 consultas/mês
DDGS (DuckDuckGo)	— (sem chave)	✔	—	✔ Grátis
Tavily	TAVILY_API_KEY (opcional)	✔	✔	✔ Membro do anel sem chave · 1 000 buscas/mês com uma chave grátis
Exa	EXA_API_KEY (opcional)	✔	✔	✔ Membro do anel sem chave · 1 000 buscas/mês com chave
Parallel	PARALLEL_API_KEY (opcional)	✔	✔	✔ Membro do anel sem chave · pago com chave
Keenable	KEENABLE_API_KEY (opcional)	✔	✔	✔ Membro do anel sem chave · pago com chave
xAI (Grok)	XAI_API_KEY ou hermes auth add xai-oauth	✔	—	Pago (SuperGrok ou por token)

Brave Search, DDGS e xAI são só de busca — combine qualquer um deles com Firecrawl/Tavily/Exa/Parallel quando você também precisar do web_extract. O DDGS usa o pacote Python ddgs por baixo; se ele ainda não estiver instalado, rode pip install ddgs (ou deixe o Hermes instalar sob demanda no primeiro uso). O xAI roda a ferramenta web_search do lado do servidor do Grok, na Responses API — os resultados são gerados por LLM em vez de virem de um índice, então títulos, descrições e a escolha das URLs são todos saída de modelo (veja a ressalva sobre o modelo de confiança abaixo).

Divisão por capacidade: você pode usar provedores diferentes para busca e extração, de forma independente — por exemplo, SearXNG (grátis) para busca e Firecrawl para extração. Veja Configuração por capacidade abaixo.

Funciona de cara — rodízio na camada gratuita sem chave

Uma instalação nova, sem nenhuma credencial de web, já tem web_search e web_extract funcionando de cara: as requisições fazem rodízio circular entre as camadas gratuitas públicas de cinco fornecedores — Exa, Parallel, Tavily, Firecrawl e Keenable —, espalhando a carga por igual, e uma requisição barrada por limite de taxa tenta de novo automaticamente no próximo fornecedor do anel (com vários saltos, até um atender ou todos estarem estrangulados). Sem cadastro, sem chave. Esta camada é estritamente último recurso — qualquer backend configurado ou chave de API presente sempre vence — e as requisições não carregam identificadores de usuário (só um id de sessão aleatório por processo, trocado a cada reinício). Para um serviço garantido e sem estrangulamento, configure um provedor com chave. Desligue a camada sem chave por completo com web.keyless_fallback: false.

Escolher grátis ou pago explicitamente: no hermes tools, Exa, Parallel e Keenable aparecem cada um como duas linhas — Free (keyless) e Paid (API key). Escolher Free fixa o endpoint anônimo daquele fornecedor (mesmo se você acrescentar uma chave depois); escolher Paid fixa o caminho com chave (uma chave faltando dá erro em vez de rebaixar em silêncio para a camada gratuita). A escolha é guardada como web.provider_tier.<nome>: free|paid; deixe sem definir para o modo automático (chave presente → pago, senão o anel sem chave).

Assinantes da Nous

Se você tem uma assinatura paga do Nous Portal, busca e extração na web estão disponíveis pelo Tool Gateway via Firecrawl gerenciado — sem precisar de chave de API. Instalações novas podem rodar hermes setup --portal para entrar e ligar todas as ferramentas do gateway de uma vez; instalações existentes podem virar só a web pelo hermes tools.

---

Como o web_extract lida com páginas longas

Os backends devolvem o markdown cru da página, que pode ser enorme (linhas de fórum, sites de documentação, notícias com comentários embutidos). Para manter a sua janela de contexto utilizável, o web_extract aplica um orçamento determinístico de caracteres — nenhuma sumarização por LLM está envolvida:

Tamanho da página (caracteres)	O que acontece
No orçamento ou abaixo dele (padrão: 15 000)	Devolvida inteira — o markdown completo chega ao agente
Acima do orçamento	Janela de começo+fim (~75% do começo / ~25% do fim, cortada em fronteiras de linha do markdown) mais um rodapé [TRUNCATED] explícito. O texto limpo completo é guardado em disco e o rodapé conta ao agente o caminho do arquivo e a chamada exata de read_file para paginar pelo meio omitido
Acima de 2 000 000	O texto guardado é limitado a 2 MB

O orçamento por página é configurável com web.extract_char_limit no config.yaml (padrão 15000, preso entre 2 000 e 500 000), e o agente pode aumentá-lo por chamada com o argumento char_limit da ferramenta.

Quando o corte atrapalha

Se você precisa especificamente do DOM ao vivo em vez do markdown extraído — por exemplo, uma página pesada em JS em que a extração devolve pouco conteúdo — use browser_navigate + browser_snapshot. A ferramenta de navegador devolve a árvore de acessibilidade ao vivo (sujeita ao próprio limite de retrato em páginas enormes).

---

Cache de resultados

Chamadas de web repetidas numa janela curta são servidas pelo cache em vez do backend pago — isso economiza créditos e latência nos dois padrões em que duplicatas são comuns: leques de subagentes (vários agentes delegados pesquisando o mesmo assunto) e o agente reconferindo uma página que leu minutos atrás.

Chamada	Cache	Escopo
web_search — mesma consulta (sem diferenciar maiúsculas/espaços), mesmo provedor	Memo em memória	Por processo
web_extract — mesma URL, mesmo formato, mesmo provedor	Texto completo guardado em ~/.hermes/cache/web/	Compartilhado entre os processos de CLI, gateway, cron e subagentes

Buscas idênticas e concorrentes (um leque paralelo de subagentes disparando a mesma consulta ao mesmo tempo) são fundidas numa única requisição ao backend — quem chega primeiro paga; o resto compartilha a resposta. Os limites de busca pedidos são agrupados em baldes de 10/20/50/100, então requisições quase idênticas (limit=5 versus limit=8) compartilham uma entrada, e cada chamador recebe a quantidade que pediu.

Só respostas bem-sucedidas entram no cache. Falhas sempre tentam o backend de novo, respostas servidas pelo resgate sem chave de uma vez só nunca entram no cache (a próxima chamada tenta o seu backend escolhido de novo), e URLs casadas pela sua security.website_blocklist nunca são servidas do cache. Extrações em cache passam de novo pelo mesmo processo de corte, então um char_limit diferente na segunda chamada trabalha em cima da mesma raspagem guardada.

URLs de desenvolvimento local nunca entram no cache. Qualquer coisa em localhost, 127.0.0.1, *.local, nomes de host de LAN de rótulo único, ou faixas de IP privadas/link-local (192.168.*, 10.*, 172.16-31.*) pula o cache de extração por completo — servidores de desenvolvimento, builds com recarga a quente e prévias de artefato na interface de chat mudam a cada gravação, e uma cópia em cache mostraria um build velho. Toda busca de uma página local é ao vivo. (Essas URLs só são alcançáveis quando o security.allow_private_urls está habilitado.)

Testando pela internet pública? Implantações de homologação e URLs de túnel usam DNS público, então a regra de desenvolvimento local não consegue pegá-las — liste-as em web.cache_exempt_hosts e elas também são sempre buscadas ao vivo. As entradas casam de forma exata, como curinga *., ou como sufixo de domínio (mysite.dev também cobre preview.mysite.dev):

# ~/.hermes/config.yaml
web:
  cache_exempt_hosts:
    - mysite.vercel.app
    - "*.ngrok-free.app"

# ~/.hermes/config.yaml
web:
  cache_enabled: true      # padrão; defina false para desligar os dois caches
  cache_ttl_minutes: 20    # janela de frescor, presa entre 1 e 1440

Se você está pesquisando dados genuinamente ao vivo (placares, preços, notícias de última hora) e precisa que cada chamada seja fresca, baixe o TTL ou defina web.cache_enabled: false.

---

Configuração inicial

Configuração rápida pelo hermes tools

Rode hermes tools, vá até Web Search & Extract e escolha um provedor. O assistente pede a URL ou a chave de API necessária e escreve na sua configuração.

hermes tools

---

Firecrawl (padrão)

Busca e extração completas. Recomendado para a maioria das pessoas.

# ~/.hermes/.env
FIRECRAWL_API_KEY=fc-sua-chave-aqui

Pegue uma chave em firecrawl.dev. A camada gratuita inclui 500 créditos por mês.

Firecrawl auto-hospedado: aponte para a sua própria instância em vez da API na nuvem:

# ~/.hermes/.env
FIRECRAWL_API_URL=http://localhost:3002

Quando FIRECRAWL_API_URL está definida, a chave de API é opcional (desative a autenticação do servidor com USE_DB_AUTHENTICATION=false).

---

SearXNG (grátis, auto-hospedado)

O SearXNG é um motor de metabusca de código aberto que respeita a privacidade e agrega resultados de mais de 70 buscadores. Nenhuma chave de API é necessária — basta apontar o Hermes para uma instância do SearXNG em execução.

O SearXNG é só de busca — o web_extract exige um provedor de extração separado.

Opção A — Auto-hospedar com Docker (recomendado)

Isso te dá uma instância privada sem limites de taxa.

1. Crie um diretório de trabalho:

mkdir -p ~/searxng/searxng
cd ~/searxng

2. Escreva um docker-compose.yml:

# ~/searxng/docker-compose.yml
services:
  searxng:
    image: searxng/searxng:latest
    container_name: searxng
    ports:
      - "8888:8080"
    volumes:
      - ./searxng:/etc/searxng:rw
    environment:
      - SEARXNG_BASE_URL=http://localhost:8888/
    restart: unless-stopped

3. Suba o contêiner:

docker compose up -d

4. Habilite o formato JSON da API:

O SearXNG vem com a saída JSON desligada por padrão. Copie a configuração gerada e habilite:

# Copia para fora do contêiner a configuração gerada automaticamente
docker cp searxng:/etc/searxng/settings.yml ~/searxng/searxng/settings.yml

Abra o ~/searxng/searxng/settings.yml. Se use_default_settings: true estiver presente, o arquivo contém só as suas sobrescritas. Todas as outras configurações são herdadas dos padrões embutidos. Para habilitar respostas JSON para o Hermes, acrescente a seguinte sobrescrita:

search:
  formats:
    - html
    - json

O seu settings.yml deve ficar parecido com:

# Leia a documentação antes de estender os padrões:
# https://docs.searxng.org/admin/settings/

use_default_settings: true

server:
  secret_key: "abcdef12345678"
  image_proxy: true

search:
  formats:
    - html
    - json

5. Reinicie para aplicar:

docker cp ~/searxng/searxng/settings.yml searxng:/etc/searxng/settings.yml
docker restart searxng

6. Verifique se funciona:

curl -s "http://localhost:8888/search?q=test&format=json" | python3 -c \
  "import sys,json; d=json.load(sys.stdin); print(f'{len(d[\"results\"])} results')"

Você deve ver algo como 10 results. Se der 403 Forbidden, o formato JSON ainda está desligado — reveja o passo 4.

7. Configure o Hermes:

# ~/.hermes/.env
SEARXNG_URL=http://localhost:8888

Depois selecione o SearXNG como backend de busca no ~/.hermes/config.yaml:

web:
  search_backend: "searxng"

Ou defina pelo hermes tools → Web Search & Extract → SearXNG.

---

Opção B — Usar uma instância pública

Instâncias públicas do SearXNG estão listadas em searx.space. Filtre pelas instâncias que têm o formato JSON habilitado (mostrado na tabela).

# ~/.hermes/.env
SEARXNG_URL=https://searx.example.com

Instâncias públicas

Instâncias públicas têm limites de taxa, disponibilidade variável e podem desligar o formato JSON a qualquer momento. Para uso em produção, auto-hospedar é fortemente recomendado.

---

Combine o SearXNG com um provedor de extração

O SearXNG cuida da busca; você precisa de um provedor separado para o web_extract. Use as chaves por capacidade:

# ~/.hermes/config.yaml
web:
  search_backend: "searxng"
  extract_backend: "firecrawl"   # ou tavily, exa, parallel

Com esta configuração, o Hermes usa o SearXNG para todas as consultas de busca e o Firecrawl para extrair URLs — combinando busca gratuita com extração de alta qualidade.

---

Tavily

Busca e extração otimizadas para IA. Selecione o Tavily no hermes tools (ou defina web.backend: tavily) para usá-lo sem chave e sem conta (com limite de taxa). Defina uma chave de API quando quiser limites maiores.

# opcional — pule isto para acesso sem chave depois de selecionar o Tavily
# ~/.hermes/.env
TAVILY_API_KEY=tvly-sua-chave-aqui

Pegue uma chave em app.tavily.com. Veja Tavily sem chave.

Instalações vazias mantêm o Firecrawl como padrão nomeado. O Tavily sem chave não é selecionado automaticamente.

---

Exa

Busca neural com entendimento semântico. Boa para pesquisa e para achar conteúdo conceitualmente relacionado.

# ~/.hermes/.env
EXA_API_KEY=sua-chave-exa-aqui

Pegue uma chave em exa.ai. A camada gratuita inclui 1 000 buscas por mês.

---

Parallel

Busca e extração nativas de IA, com capacidade de pesquisa profunda.

# ~/.hermes/.env
PARALLEL_API_KEY=sua-chave-parallel-aqui

Consiga acesso em parallel.ai.

---

xAI (Grok)

Roteia o web_search pela ferramenta web_search do lado do servidor do Grok, na Responses API. O Grok faz a busca de verdade e devolve os melhores resultados como JSON estruturado.

Funciona com qualquer um dos dois caminhos de credencial — sem variáveis de ambiente novas, sem assistente de configuração novo:

# ~/.hermes/.env (caminho por variável de ambiente)
XAI_API_KEY=sk-xai-sua-chave-aqui

ou, para assinantes do SuperGrok:

hermes auth add xai-oauth

Depois selecione o xAI como backend de busca:

# ~/.hermes/config.yaml
web:
  backend: "xai"

Botões opcionais:

web:
  backend: "xai"
  xai:
    model: grok-build-0.1        # modelo de raciocínio exigido pelo web_search (padrão)
    allowed_domains:             # opcional, máximo 5 — exclusivo com excluded_domains
      - arxiv.org
    excluded_domains:            # opcional, máximo 5
      - example-spam.com
    timeout: 90                  # segundos (padrão)

Só de busca — combine com Firecrawl / Tavily / Exa / Parallel se você também precisar do web_extract. Num 401, o provedor faz uma única atualização forçada do token OAuth e tenta de novo (cobre a revogação no meio da janela e tokens opacos que a checagem proativa de validade não consegue decodificar); credenciais por variável de ambiente pulam essa nova tentativa.

Modelo de confiança

Diferente dos provedores apoiados em índice (Brave, Tavily, Exa), que devolvem resultados de buscador na íntegra, o xAI é um LLM escolhendo quais URLs mostrar e escrevendo ele mesmo os títulos e as descrições. O conteúdo da consulta influencia a saída, então uma consulta feita com malícia (por exemplo, injetada por uma entrada não confiável que o agente pegou lá atrás) pode, em princípio, guiar o Grok a emitir URLs escolhidas pelo atacante. Trate as URLs devolvidas do mesmo jeito que você trataria qualquer link gerado por modelo — valide antes de acessar, principalmente se a consulta veio de entrada não confiável.

---

Configuração

Backend único

Defina um provedor para todas as capacidades de web:

# ~/.hermes/config.yaml
web:
  backend: "searxng"   # firecrawl | searxng | brave-free | ddgs | tavily | exa | parallel | xai

Configuração por capacidade

Use provedores diferentes para busca e para extração. Isso deixa você combinar busca gratuita (SearXNG) com um provedor de extração pago, ou o contrário:

# ~/.hermes/config.yaml
web:
  search_backend: "searxng"     # usado pelo web_search
  extract_backend: "firecrawl"  # usado pelo web_extract

Quando as chaves por capacidade estão vazias, as duas caem no web.backend. Só quando nenhuma escolha de web foi escrita alguma vez é que o backend é detectado automaticamente a partir da chave de API/URL presente — uma vez que existe uma escolha, o runtime sempre a usa, e acrescentar uma chave ao .env não redireciona o tráfego de web.

Ordem de prioridade (por capacidade):

1. web.search_backend / web.extract_backend (explícito, por capacidade)
2. web.backend (recuo compartilhado; nous = Tool Gateway gerenciado)
3. Detecção automática a partir das variáveis de ambiente (só em instalações que nunca foram configuradas)

Detecção automática

Se nenhum backend foi selecionado em momento algum (nenhum web.backend / chave por capacidade escrita por você ou pelo hermes tools), o Hermes escolhe o primeiro disponível com base nas credenciais que estão definidas:

Credencial presente	Backend selecionado automaticamente
TAVILY_API_KEY	tavily
EXA_API_KEY	exa
PARALLEL_API_KEY	parallel
FIRECRAWL_API_KEY ou FIRECRAWL_API_URL (ou o Nous Tool Gateway está pronto)	firecrawl
SEARXNG_URL	searxng
BRAVE_SEARCH_API_KEY	brave-free
pacote ddgs importável	ddgs
(nada definido)	anel sem chave: exa / parallel / tavily / firecrawl / keenable (rodízio circular)

Anel de camada gratuita sem chave: quando nenhuma credencial acima está presente, as requisições fazem rodízio entre as camadas gratuitas públicas de cinco fornecedores (Exa, Parallel, Tavily, Firecrawl, Keenable), para as ferramentas de web funcionarem numa instalação nova com zero configuração — e uma requisição barrada por limite de taxa passa automaticamente para o próximo fornecedor do anel. Fixe um fornecedor no hermes tools para parar o rodízio (o anel então só é usado como sucessão de contingência em estrangulamentos). Todas as camadas gratuitas têm limite de taxa do fornecedor sob rajada de carga; o uso normal e contínuo passa numa boa. Defina web.keyless_fallback: false para desligar a camada — com ela desligada e sem credenciais, as ferramentas de web ficam indisponíveis até um provedor ser configurado.

Resgate sem chave, de uma vez só, para backends com chave: quando o backend escolhido/com chave falha numa chamada (chave errada, indisponibilidade, 5xx do servidor), essa chamada específica tenta de novo automaticamente no anel gratuito sem chave em vez de dar erro — o resultado anota qual fornecedor atendeu e por quê (rescued_from / backend_error). A contingência nunca gruda: a próxima chamada de web_search/web_extract tenta o seu backend escolhido de novo. Desligue com web.keyless_rescue: false (também fica desligado sempre que o keyless_fallback está desligado).

A busca na web do xAI não está na cadeia de detecção automática — ter XAI_API_KEY definida (ou estar logado via OAuth do xAI Grok) não roteia o tráfego de web pelo xAI automaticamente, já que essas credenciais também são usadas para inferência / TTS / geração de imagem e a pessoa pode querer outro backend para web. Opte por ele explicitamente com web.backend: "xai".

---

Verifique a sua configuração

Rode hermes setup para ver qual backend de web foi detectado:

✅ Web Search & Extract (searxng)

Ou confira pela CLI:

# Ativa o venv e roda o módulo de ferramentas de web direto
source ~/.hermes/hermes-agent/.venv/bin/activate
python -m tools.web_tools

Isso imprime o backend ativo e o estado dele:

✅ Web backend: searxng
   Using SearXNG (search only): http://localhost:8888

---

Diagnóstico de problemas

O web_search devolve {"success": false}

• Confira se o SEARXNG_URL está alcançável: curl -s "http://localhost:8888/search?q=test&format=json"
• Se der HTTP 403, o formato JSON está desligado — acrescente json à lista formats no settings.yml e reinicie
• Se der erro de conexão, o contêiner pode não estar rodando: docker ps | grep searxng

O web_extract diz "search-only backend"

O SearXNG não consegue extrair o conteúdo de uma URL. Defina o web.extract_backend com um provedor que suporte extração:

web:
  search_backend: "searxng"
  extract_backend: "firecrawl"  # ou tavily / exa / parallel

O SearXNG devolve 0 resultados

Algumas instâncias públicas desligam certos buscadores ou categorias. Tente:

• Uma consulta diferente
• Uma instância pública diferente, de searx.space
• Auto-hospedar a sua própria instância, para resultados confiáveis

Limite de taxa numa instância pública

Mude para uma instância auto-hospedada (veja a Opção A acima). Com Docker, a sua própria instância não tem limites de taxa.

O web_extract devolve conteúdo cortado com um rodapé [TRUNCATED]

Isso é esperado para páginas acima do orçamento de caracteres. O rodapé nomeia o arquivo em disco que guarda o texto limpo completo e a chamada exata de read_file para paginar pelo meio omitido. Para ver mais na própria conversa, aumente o web.extract_char_limit no config.yaml ou passe um char_limit maior na chamada.

---

Skill opcional: searxng-search

Para agentes que precisam usar o SearXNG via curl diretamente (por exemplo, como recurso reserva quando o conjunto de ferramentas de web não está disponível), instale a skill opcional searxng-search:

hermes skills install official/research/searxng-search

Isso acrescenta uma skill que ensina o agente a:

• Chamar a API JSON do SearXNG via curl ou Python
• Filtrar por categoria (general, news, science etc.)
• Lidar com paginação e casos de erro
• Recuar com elegância quando o SearXNG está inalcançável

---