Filtragem de Domínios
Nesta página
Controlo das fontes de pesquisa
Por predefinição, a Pesquisa Web explora toda a internet. Isto funciona bem para consultas gerais, mas revela-se frequentemente insuficiente para casos de uso profissionais que exigem fontes fiáveis e controladas. A filtragem de domínios permite restringir ou excluir sites específicos.
Dois parâmetros mutuamente exclusivos
A Pesquisa Web oferece dois parâmetros de filtragem:
allowed_domains: restringe a pesquisa aos domínios especificados (lista de permissões)excluded_domains: exclui domínios específicos dos resultados (lista de bloqueio)
Estes dois parâmetros são mutuamente exclusivos. Não pode utilizar ambos no mesmo pedido. Se tentar, a API devolve um erro.
Cada parâmetro aceita um vetor de até 5 domínios.
Utilização de allowed_domains (lista de permissões)
Utilize este parâmetro quando souber exatamente quais as fontes que pretende consultar. Por exemplo, para investigação académica:
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="What are the latest publications on transformers?",
tools=[{
"type": "web_search",
"allowed_domains": ["arxiv.org", "nature.com", "science.org"]
}]
)
O modelo pesquisa apenas nestes três domínios. Isto garante que os resultados provêm de fontes científicas verificadas.
Casos de uso da lista de permissões
- Investigação académica: limitar a arxiv.org, scholar.google.com, nature.com
- Documentação técnica: limitar a sites oficiais de tecnologia
- Inteligência competitiva: limitar a sites da concorrência
- Conformidade regulamentar: limitar a fontes governamentais ou regulamentares
Utilização de excluded_domains (lista de bloqueio)
Utilize este parâmetro quando pretender uma pesquisa abrangente, mas necessitar de excluir fontes pouco fiáveis ou irrelevantes:
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="What are the best JavaScript frameworks in 2026?",
tools=[{
"type": "web_search",
"excluded_domains": ["reddit.com", "quora.com"]
}]
)
O modelo pesquisa em toda a web, exceto nos domínios excluídos.
Casos de uso da lista de bloqueio
- Excluir fóruns: evitar opiniões não verificadas
- Excluir agregadores: evitar conteúdo duplicado
- Excluir concorrentes: manter o conteúdo destes fora dos seus resultados
- Excluir paywalls: evitar sites com conteúdo inacessível
Sintaxe do SDK
xAI SDK
tools=[client.tools.web_search(
allowed_domains=["arxiv.org", "nature.com"]
)]
OpenAI SDK
tools=[{
"type": "web_search",
"excluded_domains": ["reddit.com"]
}]
Vercel AI SDK
tools: [xai.tools.webSearch({
allowedDomains: ["arxiv.org", "nature.com"]
})]
Note a convenção camelCase (allowedDomains) no SDK de JavaScript.
Limites e boas práticas
O limite de 5 domínios pode parecer restritivo. Na prática, obriga-o a ser seletivo quanto às fontes, o que melhora a qualidade dos resultados. Se necessitar de maior flexibilidade, pode executar vários pedidos com diferentes domínios e agregar os resultados no lado do cliente.
Ao utilizar allowed_domains, assegure-se de que os domínios escolhidos cobrem o tópico solicitado. Um domínio demasiado restritivo pode impedir o modelo de encontrar informações relevantes, o que poderá levá-lo a responder sem dados atualizados.
Pontos-chave
- Dois parâmetros disponíveis:
allowed_domains(lista de permissões) eexcluded_domains(lista de bloqueio) - Mutuamente exclusivos: não pode combiná-los no mesmo pedido
- Máximo de 5 domínios por parâmetro
- A lista de permissões é ideal para fontes controladas e fiáveis
- A lista de bloqueio funciona para pesquisas abrangentes com poucas exclusões