phaseo:web_search para que o modelo possa pesquisar na web quando precisar de informações atuais ou com fontes. O modelo escreve a consulta e pode pesquisar várias vezes em uma solicitação; o Phaseo retorna URLs, títulos, trechos, destaques e, opcionalmente, o texto das páginas, e o modelo escreve uma resposta fundamentada.
tools em /v1/responses e /v1/messages.
Parâmetros
O que o modelo envia
Cada chamada tem umaquery. O modelo também pode enviar max_results, engine, search_context_size, as listas de domínios, include_text, include_highlights, max_characters e estas indicações de localização:
Os valores que o modelo envia substituem os padrões da ferramenta naquela chamada.
max_results continua limitado ao que resta de max_total_results; quando esse total se esgota, as chamadas seguintes retornam max_total_results_reached.
Escolha um mecanismo
Se um mecanismo gerenciado não estiver habilitado, a chamada retorna
search_not_configured ao modelo.
Com engine: "native" em /v1/chat/completions ou /v1/responses, a solicitação vai apenas para provedores que executam a pesquisa na web por conta própria. Se nenhum deles atender o modelo, o Phaseo executa o mecanismo padrão no lugar e cobra como pesquisa gerenciada.
Os provedores que executam a pesquisa na web por conta própria nesses endpoints são a OpenAI, as implantações do Azure OpenAI em /v1/responses, a xAI e a DeepSeek em deepseek/deepseek-v4.1-flash-1017. A DeepSeek pesquisa por conta própria apenas quando a pesquisa na web é a única ferramenta da solicitação, sem listas de domínios nem localização do usuário, sem saída JSON e sem um tool_choice forçado. A API dela rejeita listas de domínios, localização e saída JSON, desativa a pesquisa na web quando a solicitação tem outras ferramentas e não consegue forçar uma pesquisa. As demais solicitações a esse modelo usam a pesquisa da Phaseo, que funciona junto com as suas próprias ferramentas. Com o raciocínio ativado, a DeepSeek executa uma pesquisa mais profunda, que abre e lê páginas em várias etapas.
Enviar a ferramenta própria da OpenAI { "type": "web_search" } funciona da mesma forma que engine: "native". Defina native somente na definição da ferramenta: se o modelo pedir native em uma chamada, a chamada retorna unsupported_search_engine, porque a ferramenta do provedor precisa ser escolhida antes de a solicitação ser enviada.
Filtre por domínio
Useallowed_domains quando a resposta precisar vir de um conjunto fixo de fontes, e excluded_domains para tirar sites específicos de uma pesquisa aberta.
- Perplexity aceita uma das listas, não as duas, com até 20 domínios. Os domínios excluídos são enviados no formato de lista de bloqueio dele.
- Firecrawl aceita uma das listas, não as duas.
- TinyFish aceita as duas e as transforma nos operadores
site:e-site:na consulta. - DeepSeek aceita as duas e as transforma nos operadores
site:e-site:. As consultas dela são limitadas a 128 caracteres, então a consulta é encurtada para abrir espaço para os operadores. Se apenas as listas de domínios já passarem do limite, a chamada retornasearch_query_too_long.
O que a ferramenta retorna
Um resultado JSON com o mecanismo, a consulta e um arrayresults. Cada resultado tem title, url, snippet ou highlights, e text quando o texto da página foi solicitado e o mecanismo o fornece.
Uso e preços
Cada pesquisa soma valores emusage.server_tool_use:
server_tool_web_search_requests e server_tool_web_search_extra_results. Buscas com falha não são cobradas, e o TinyFish Search é gratuito nos planos publicados, então engine: "tinyfish" não adiciona cobrança de busca. Buscas em mecanismos pagos exigem créditos mesmo quando o modelo é gratuito. A busca nativa é cobrada com native_web_search_requests pelo preço publicado do provedor: por exemplo, $10 por 1,000 buscas na OpenAI e na Anthropic e $0.75 por 1,000 na DeepSeek, onde só contam as buscas que retornam resultados. A DeepSeek também cobra cada leitura de página, em que lê uma URL com a ferramenta de leitura de links, a $0.75 por 1,000, como native_web_fetch_requests. Com o raciocínio ativado, uma única resposta da DeepSeek pode executar uma dúzia de buscas ou mais, e os resultados lidos somam-se aos tokens de entrada.