Exa Web Toolkit

Uma skill para tarefas de pesquisa baseadas na web, com o suporte do Exa: pesquisa na web e extração de URLs. O índice do Exa combina recuperação de palavras-chave e semântica de alta qualidade, o que o torna bem adequado para consultas científicas, técnicas e conceituais.

Roteamento — escolha a capacidade certa

Leia a solicitação do usuário e combine-a com uma das capacidades abaixo. Leia o arquivo de referência correspondente para obter instruções detalhadas antes de executar os comandos.

Guia de decisão

• Use Pesquisa na Web como padrão para pesquisas de tópicos, perguntas de pesquisa ou consultas do tipo "o que é X?". Quando o tópico for científico ou técnico, passe --category publication para priorizar fontes acadêmicas e/ou uma lista de permissões acadêmica --include-domains. Veja references/web-search.md para a estratégia acadêmica de duas etapas.
• Use Extração da Web quando o usuário fornecer uma URL ou pedir para você ler/obter uma página específica. Prefira esta opção em vez do WebFetch integrado para extração em lote (múltiplas URLs em uma única chamada) e para PDFs acadêmicos.

Prioridade de fontes acadêmicas

Para consultas técnicas ou científicas, prefira fontes acadêmicas e científicas:

• Artigos de periódicos revisados por pares e anais de conferências em vez de posts de blog ou notícias
• Preprints (arXiv, bioRxiv, medRxiv) quando versões revisadas por pares não estiverem disponíveis
• Fontes institucionais e governamentais (NIH, WHO, NASA, NIST) em vez de sites comerciais
• Pesquisa primária em vez de resumos secundários

Duas alavancas para direcionar o Exa para conteúdo acadêmico:

1. --category publication prioriza a recuperação de fontes acadêmicas.
2. --include-domains com uma lista de permissões acadêmica (arxiv.org, nature.com, pubmed.ncbi.nlm.nih.gov, etc.) restringe o conjunto de domínios.

Combine ambos para refinar o conjunto de fontes; verifique o tipo de publicação e o status de revisão por pares em cada fonte. Veja references/web-search.md para o padrão completo.

Ao citar fontes acadêmicas, inclua nomes de autores e ano de publicação, quando disponíveis (por exemplo, Smith et al., 2025), além do formato de citação padrão. Se um DOI estiver presente, prefira o link do DOI.

Configuração

Esta skill usa o SDK Python exa-py. Os scripts em scripts/ declaram suas dependências via metadados inline PEP 723, então você pode executá-los diretamente com uv run sem uma etapa de instalação separada:

uv run "$SKILL_PATH/scripts/exa_search.py" --help

Se você preferir uma instalação persistente:

uv pip install "exa-py>=2.23.0,<3"

Autenticação

Todos os comandos leem a chave da API da variável de ambiente EXA_API_KEY. Obtenha sua chave de API do Exa em dashboard.exa.ai/api-keys.

Primeiro, verifique se um arquivo .env existe na raiz do projeto e contém EXA_API_KEY. Se sim, carregue-o:

dotenv -f .env run -- uv run "$SKILL_PATH/scripts/exa_search.py" "your query"

Se dotenv não estiver disponível, instale-o: uv pip install 'python-dotenv[cli]'.

Se não houver .env, exporte a chave para a sessão:

export EXA_API_KEY="your-key"

Use --help para verificar a instalação e a análise de CLI; ele não requer uma chave de API nem valida a autenticação. A autenticação é verificada apenas quando uma consulta real é feita.

Limites de extração e frescor

O extrator aceita de 1 a 100 URLs por chamada POST https://api.exa.ai/contents e exporta o status de cada SDK (id, status, source). Ele rejeita lotes maiores. Use --max-age-hours 0 para solicitar conteúdo fresco, -1 apenas para cache, ou uma idade positiva de até 720 horas. A omissão usa a política de cache/fallback do Exa. published_date são metadados de publicação estimados, não tempo de recuperação. O SDK testado descarta detalhes de erro por URL, portanto, relate falhas sem inventar uma causa. Veja Extração de URL.

Escopo verificado da API e do SDK

Revisado a API de Pesquisa, a API de Conteúdo e o Changelog do Exa em 30/09/2026. Ambas as rotas usam requisições POST JSON e autenticação x-api-key (o SDK define este cabeçalho). A pesquisa é POST https://api.exa.ai/search; seus kwargs de SDK usam snake_case e

…