Web search na Responses API

Casos de uso

Responder a perguntas sobre eventos posteriores à data de corte do treinamento do modelo.
Fundamentar respostas em dados em tempo real (preços, disponibilidade, notícias de última hora).
Assistentes de pesquisa que precisam citar fontes verificáveis e atualizadas.
Bots de suporte ao cliente que consultam a documentação ou as políticas atuais no momento da consulta.

Visão geral

Use POST /responses no AI Gateway com o mesmo formato de solicitação da OpenAI Responses API: model, input e um array tools que inclua uma entrada de web search integrado. O AI Gateway encaminha a pesquisa para o recurso nativo de cada provedor quando o modelo oferece suporte a ele. Consulte Responses API para ter uma visão geral do endpoint e saber quando escolhê-lo em vez de Chat Completions. Não há uma ferramenta separada do Perplexity ou do Parallel no AI Gateway; o contrato compatível são as ferramentas web_search / web_search_preview no estilo da OpenAI em /responses, mapeadas para a Anthropic e o Google quando aplicável.

Prefira modelos cujos metadados indiquem suporte a web search. Consulte Modelos compatíveis e a lista de modelos do workspace.

Outras formas de pesquisar

Chat Completions acessa o web search por um contrato diferente, executado pelo gateway: a ferramenta de servidor orq:web_search, em que o AI Gateway executa cada pesquisa e retorna os resultados ao modelo, configurada com max_results, max_uses, engine e allowed_domains / excluded_domains.

Início rápido

Use o SDK da OpenAI com a URL base do AI Gateway e chame a Responses API diretamente.

curl -sS -X POST "https://router.toqan.ai/eu/v3/router/responses" \
  -H "Authorization: Bearer ${TOQAN_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.6-sol",
    "input": "What are the latest changes to the OpenAI Responses API?",
    "tools": [{ "type": "web_search_preview" }]
  }'

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const response = await client.responses.create({
  model: "openai/gpt-5.6-sol",
  input: "What are the latest changes to the OpenAI Responses API?",
  tools: [{ type: "web_search_preview" }],
});

console.log(response.output_text);

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

response = client.responses.create(
    model="openai/gpt-5.6-sol",
    input="What are the latest changes to the OpenAI Responses API?",
    tools=[{"type": "web_search_preview"}],
)

print(response.output_text)

Endpoint: POST https://router.toqan.ai/eu/v3/router/responses

Definições de ferramentas

As entradas de tools da solicitação usam o campo discriminador type, de acordo com o schema do gateway.

`web_search_preview`

Campo	Tipo	Descrição
`type`	`"web_search_preview"`	Identifica a ferramenta de web search em versão preview.
`domains`	string[]	Lista opcional de domínios permitidos para restringir a pesquisa.
`search_context_size`	string	Opcional. Um entre `low`, `medium`, `high`. Controla quanto contexto é recuperado por resultado.
`user_location`	object	Opcional. Indicações para resultados localizados (`type`, `city`, `country`, `region`, `timezone`).

`web_search`

Campo	Tipo	Descrição
`type`	`"web_search"`	Tipo estável da ferramenta de web search.
`search_context_size`	string	Opcional. `low`, `medium`, `high`.
`user_location`	object	Opcional. Mesmo formato descrito acima.
`filters`	object	Opcional. Por exemplo, `allowed_domains` (array anulável) para restringir domínios.

O AI Gateway aceita o objeto completo da ferramenta em /responses. As solicitações para a OpenAI repassam as ferramentas para a Responses API upstream. Os caminhos da Anthropic e do Google mapeiam web_search / web_search_preview para as ferramentas nativas de web search; campos não compatíveis com a API upstream podem ser ignorados.

`include` (opcional)

Você pode solicitar campos adicionais nos itens de saída do web search, de acordo com o include da OpenAI Responses:

Valor	Significado
`web_search_call.results`	Inclui resultados de pesquisa detalhados, quando disponíveis.
`web_search_call.action.sources`	Inclui URLs e títulos das fontes na ação.

Exemplo de corpo da solicitação:

{
  "model": "openai/gpt-5.6-sol",
  "input": "Summarize today’s headlines in finance.",
  "tools": [{ "type": "web_search_preview" }],
  "include": ["web_search_call.action.sources"]
}

Saída: `web_search_call`

As respostas podem conter itens de saída com "type": "web_search_call":

Campo	Descrição
`id`	ID do item.
`type`	`"web_search_call"`.
`status`	Status do ciclo de vida da chamada.
`action`	Opcional. `type` pode ser `search`, `open_page` ou `find`, além de campos como `query`, `url`, `pattern` e `sources` (url + título).

O formato exato do payload corresponde ao que o provedor retorna; o streaming usa o mesmo modelo de eventos dos outros streams de /responses.

Comportamento dos provedores

OpenAI

Envie tools e include no corpo da solicitação com o ID do modelo (por exemplo, openai/gpt-5.6-sol). Use os mesmos parâmetros que a OpenAI documenta para web search na Responses API.

OpenAI

Configure sua chave de API da OpenAI para usar o GPT-5.6 Sol com web search.

Anthropic

web_search e web_search_preview em tools são mapeados para a ferramenta de web search da Anthropic no caminho Messages usado em /responses.

Anthropic

Configure sua chave de API da Anthropic para usar o Claude com web search.

Google Gemini

Os mesmos tipos de ferramenta habilitam o Google Search grounding (googleSearch) nos modelos Gemini compatíveis.

Google AI

Configure sua chave de API do Google AI para usar os modelos Gemini com Google Search grounding.

`tool_choice`

Você pode direcionar o modelo para o web search usando a forma estruturada de tool_choice, por exemplo:

{
  "tool_choice": { "type": "web_search_preview" }
}

Os valores de tool_choice.type compatíveis com ferramentas integradas são definidos no schema da API (incluindo web_search, web_search_preview e literais relacionados). As strings none, auto e required funcionam normalmente.

Streaming

Defina "stream": true no mesmo corpo JSON. O servidor responde com text/event-stream e eventos no formato de stream de resposta no estilo da OpenAI.

curl -sS -N -X POST "https://router.toqan.ai/eu/v3/router/responses" \
  -H "Authorization: Bearer ${TOQAN_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "model": "openai/gpt-5.6-sol",
    "input": "What is the current phase of the moon for San Francisco?",
    "tools": [{ "type": "web_search_preview" }],
    "stream": true
  }'

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const stream = await client.responses.create({
  model: "openai/gpt-5.6-sol",
  input: "What is the current phase of the moon for San Francisco?",
  tools: [{ type: "web_search_preview" }],
  stream: true,
});

for await (const event of stream) {
  console.log(event);
}

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

stream = client.responses.create(
    model="openai/gpt-5.6-sol",
    input="What is the current phase of the moon for San Francisco?",
    tools=[{"type": "web_search_preview"}],
    stream=True,
)

for event in stream:
    print(event)

No streaming com cURL, -N desativa o buffer para que as linhas SSE apareçam à medida que chegam. Analise as linhas data: do corpo da resposta da mesma forma que faria com o stream da Responses da OpenAI.

Exemplos de código

Defina TOQAN_API_KEY (ou passe a chave explicitamente) para que o cabeçalho Authorization seja resolvido.

curl -sS -X POST "https://router.toqan.ai/eu/v3/router/responses" \
  -H "Authorization: Bearer ${TOQAN_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.6-sol",
    "input": "What is the current phase of the moon for San Francisco?",
    "tools": [{ "type": "web_search_preview" }],
    "include": ["web_search_call.action.sources"]
  }'

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const response = await client.responses.create({
  model: "openai/gpt-5.6-sol",
  input: "What is the current phase of the moon for San Francisco?",
  tools: [{ type: "web_search_preview" }],
  include: ["web_search_call.action.sources"],
});

console.log(response.output_text);

for (const item of response.output ?? []) {
  if (item.type === "web_search_call") {
    console.log("web_search_call", item.action);
  }
}

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

response = client.responses.create(
    model="openai/gpt-5.6-sol",
    input="What is the current phase of the moon for San Francisco?",
    tools=[{"type": "web_search_preview"}],
    include=["web_search_call.action.sources"],
)

print(response.output_text)

for item in response.output or []:
    if item.type == "web_search_call":
        print("web_search_call", item.action)

Veja também

Responses API: o endpoint em que o web search é executado e quando escolhê-lo em vez de Chat Completions
API compatível com OpenAI: URL base e /responses
Raciocínio: reasoning para modelos da OpenAI pela Responses API; thinking para Anthropic e Google Gemini por Chat Completions
Chamada de ferramentas: ferramentas de função em /chat/completions e /responses
Ferramenta de servidor Web search: o contrato orq:web_search executado pelo gateway em Chat Completions

Toqan Router

Visão geral

APIs

MCP Portal

Roteamento

Segurança e privacidade

Recursos dos modelos

Ferramentas de servidor

Cenários comuns

Configuração de provedores

Visão geral

Outras formas de pesquisar

Início rápido

Definições de ferramentas

`web_search_preview`

`web_search`

`include` (opcional)

Saída: `web_search_call`

Comportamento dos provedores

OpenAI

OpenAI

Anthropic

Anthropic

Google Gemini

Google AI

`tool_choice`

Streaming

Exemplos de código

Veja também

​Visão geral

​Outras formas de pesquisar

​Início rápido

​Definições de ferramentas

​web_search_preview

​web_search

​include (opcional)

​Saída: web_search_call

​Comportamento dos provedores

​OpenAI

OpenAI

​Anthropic

Anthropic

​Google Gemini

Google AI

​tool_choice

​Streaming

​Exemplos de código

​Veja também

Visão geral

Outras formas de pesquisar

Início rápido

Definições de ferramentas

`web_search_preview`

`web_search`

`include` (opcional)

Saída: `web_search_call`

Comportamento dos provedores

OpenAI

Anthropic

Google Gemini

`tool_choice`

Streaming

Exemplos de código

Veja também