Pular para o conteúdo principal
Adicione uma ferramenta de pesquisa na web a uma solicitação de Responses quando o modelo precisar de informações atuais da web pública. A API MKA1 envia as pesquisas e as solicitações de páginas do modelo ao Serper, uma API de pesquisa de terceiros que retorna resultados de pesquisa do Google. Esta página explica como habilitar a pesquisa na web, o que cada solicitação de saída contém e como limitar a pesquisa na web a domínios específicos.

​
Habilitar a pesquisa na web

Adicione a tools uma ferramenta com tipo web_search. A API também aceita web_search_2025_08_26, web_search_preview e web_search_preview_2025_03_11, que dão ao modelo as mesmas ferramentas. Uma ferramenta de pesquisa na web dá ao modelo três ferramentas. O modelo decide quando chamar cada uma: Verifique os itens web_search_call na saída da resposta para ver cada consulta e cada URL que o modelo solicitou. Esta solicitação faz uma pergunta que precisa de informações atuais:

​
Opções da ferramenta

Para ver o esquema completo, consulte Criar uma resposta.

​
O que o provedor recebe

Todo o tráfego de pesquisa na web vai da plataforma MKA1 ao provedor por HTTPS. Os dispositivos dos seus usuários finais não se comunicam com o provedor, então o provedor não vê os endereços IP deles.

​
Pesquisas

Cada chamada a web_search envia uma solicitação a google.serper.dev com estes campos: O modelo escreve a consulta a partir da conversa. Por isso, uma consulta pode incluir texto da entrada ou das instruções, como um nome, um produto ou um lugar que o usuário mencionou.

​
Leitura de páginas

Cada chamada a scrape ou web_find envia a scrape.serper.dev a URL que o modelo escolheu. O Serper busca a página e retorna o texto dela. Em web_find, a própria plataforma MKA1 compara o padrão com esse texto; o padrão não é enviado ao provedor.

​
Consultas de país

Se o modelo informar um país que não seja um código de duas letras nem um nome de país que a API reconheça, a API envia esse texto à API pública de localizações do SerpApi (serpapi.com/locations.json) para obter o código do país. Essa solicitação contém apenas o texto do país e um limite de 1 resultado. Se a consulta falhar ou não encontrar nada, a pesquisa usa us.

​
O que não é enviado

A plataforma não encaminha a esses provedores seus cabeçalhos de autenticação da MKA1 nem os cabeçalhos de identidade, como X-On-Behalf-Of. Ela não adiciona identificadores de organização, equipe ou usuário do contexto da solicitação aos dados enviados ao provedor. Ela se autentica no Serper com a chave do Serper do próprio cluster, e as consultas de país não levam chave. A plataforma não envia a conversa, as instruções ou os arquivos como dados separados. Porém, o modelo pode copiar o conteúdo deles para uma consulta, uma URL ou um valor de localização, idioma ou país. Esses valores são enviados sem ocultar as credenciais ou os identificadores que contenham. Por exemplo, uma URL de página pode conter um token de acesso ou um ID de usuário nos parâmetros de consulta, mesmo quando seu domínio é permitido. URLs que levam credenciais antes do host (user:password@) são recusadas quando há uma lista de domínios definida. Separadamente do provedor, a plataforma MKA1 registra no cluster cada chamada a uma ferramenta de pesquisa na web. Os argumentos da chamada (consulta, URL, padrão, localização, idioma e país) e a saída dela (resultados de pesquisa, texto da página ou linhas correspondentes) são gravados no log de auditoria da plataforma e, de forma abreviada, nos rastreamentos de solicitação. Os itens web_search_call na saída da resposta carregam a consulta, a URL e o padrão, e são armazenados com a resposta quando ela é armazenada. O Serper vê o endereço IP de saída do cluster, não o dos seus usuários finais.

​
Cache

Os resultados de pesquisa não são armazenados em cache. Cada chamada a web_search envia uma nova solicitação ao provedor. O texto das páginas lidas por scrape e web_find fica no cache da plataforma por 5 minutos. A chave do cache é apenas a URL, então o cache é compartilhado por todos os usuários do cluster. Uma nova leitura da mesma URL dentro desse período não envia uma nova solicitação ao provedor. As verificações da lista de domínios e da política de rede continuam sendo executadas antes da leitura do cache.

​
Uso e cobrança

Cada chamada a web_search conta como uma pesquisa. Cada chamada a scrape ou web_find que não é atendida pelo cache também conta como uma pesquisa. As pesquisas são precificadas pela entrada de preço serper, e o custo delas conta para os orçamentos. As consultas de país não são cobradas.

​
Restringir a pesquisa na web a domínios específicos

Defina filters.allowed_domains para limitar a pesquisa na web a uma lista de domínios. O campo filters está disponível em web_search e web_search_2025_08_26. Uma solicitação que define filters em um tipo web_search_preview falha com HTTP 400. Escreva cada entrada como um nome de host, como python.org, e omita o esquema. Se uma entrada começar com http:// ou https:// ou terminar com /, a API remove essa parte. Cada entrada também cobre os subdomínios dela: python.org cobre docs.python.org, mas não notpython.org. A comparação não diferencia maiúsculas de minúsculas. Uma lista pode ter até 100 entradas. Uma solicitação com uma entrada que contenha um caminho, uma string de consulta, uma porta, credenciais, um endereço IP ou um curinga, ou cujo nome de host não tenha ponto (como localhost), falha com HTTP 400. Um objeto filters com uma chave desconhecida, como allowedDomains, também falha com HTTP 400. Uma lista vazia ou omitida deixa a pesquisa na web sem restrições. Com uma lista de domínios definida:
  • A API remove os resultados de pesquisa que não estão nos domínios listados, então o modelo pode receber menos resultados do que search_context_size solicita.
  • scrape e web_find recusam URLs fora dos domínios listados antes de enviar qualquer coisa ao provedor, e o modelo recebe um erro para essa chamada.
  • A API remove da saída as citações de URL (anotações url_citation) que apontam para fora dos domínios listados.
  • Cada pesquisa executa no máximo 4 pesquisas no provedor, e cada uma conta como uma pesquisa. Uma lista longa é dividida entre essas pesquisas na ordem em que você a informa. Se a lista não couber, a API executa 3 pesquisas restritas aos primeiros domínios mais uma pesquisa sem restrição filtrada com a lista inteira, então os domínios posteriores ainda podem aparecer, mas com menos confiabilidade. Coloque os domínios mais importantes primeiro.
Uma lista de domínios não impede que dados sejam enviados ao provedor: as pesquisas e as leituras de páginas permitidas continuam indo para o Serper, como descrito em O que o provedor recebe. A lista de domínios é verificada em relação à URL que o modelo solicita. A plataforma não vê os redirecionamentos que ocorrem enquanto o provedor busca a página, então, se uma página de um domínio permitido redirecionar para outro domínio, o conteúdo retornado pode vir desse outro domínio. A lista de domínios se aplica apenas a web_search, scrape e web_find. Outras ferramentas na mesma solicitação, como shell, code_interpreter, mcp e ferramentas OpenAPI, ainda podem acessar outros hosts. Use as políticas de rede de saída para restringir onde uma solicitação pode se conectar.

​
Políticas de rede de saída

Se o cluster aplica políticas de rede de saída e sua organização ou equipe tem uma política que restringe destinos, o tráfego de pesquisa na web precisa passar por essa política:
  • Permita google.serper.dev para pesquisas e scrape.serper.dev para leitura de páginas. Permita serpapi.com se o modelo puder precisar de consultas de país.
  • Cada URL que o modelo pedir para ler com scrape ou web_find também precisa ser permitida. Uma URL fora da política falha e o modelo recebe um erro para essa chamada. Com uma política em vigor, URLs com uma porta diferente de 80 ou 443, ou cujo host é um endereço IP, também são recusadas.
  • Se a política não puder ser verificada, as solicitações de saída são recusadas.
Para gerenciar as políticas, use Definir a política de rede do tenant.

​
Disponibilidade em um cluster

A pesquisa na web só fica disponível quando o operador do cluster configura uma chave de API do Serper (SERPER_API_KEY). Em um cluster sem essa chave, uma solicitação de Responses que inclua qualquer ferramenta de pesquisa na web falha com HTTP 400 e o código de erro feature_unavailable. O campo service do erro é web_search e o campo param indica a ferramenta, por exemplo tools[0].type. Solicitações sem ferramenta de pesquisa na web não são afetadas. Em um lote, o item afetado falha com code: feature_unavailable.