> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Ferramenta de servidor Web search

> Dê a um modelo acesso a resultados atuais da web pública com a ferramenta de servidor orq:web_search.

A ferramenta `orq:web_search` permite que um modelo pesquise na web pública durante uma resposta. O **AI Gateway** executa cada pesquisa e retorna os resultados ao modelo, que decide como usá-los na resposta.

## Início rápido

Os exemplos usam a configuração de cliente da [Visão geral das ferramentas de servidor](/docs/pt-BR/ai-gateway/features/server-tools.md).

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://router.toqan.ai/eu/v3/router/chat/completions \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "messages": [
      { "role": "user", "content": "What are the latest changes to the EU AI Act?" }
    ],
    "tools": [
      { "type": "orq:web_search", "max_results": 5, "max_uses": 3 }
    ]
  }'
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const response = await client.chat.completions.create({
  model: 'openai/gpt-5.4-mini',
  messages: [
    { role: 'user', content: 'What are the latest changes to the EU AI Act?' },
  ],
  tools: [{ type: 'orq:web_search', max_results: 5, max_uses: 3 }] as any,
});

console.log(response.choices[0].message.content);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
response = client.chat.completions.create(
    model="openai/gpt-5.4-mini",
    messages=[
        {"role": "user", "content": "What are the latest changes to the EU AI Act?"}
    ],
    tools=[
        {"type": "orq:web_search", "max_results": 5, "max_uses": 3}
    ],
)

print(response.choices[0].message.content)
```

O modelo escreve a consulta de pesquisa. A configuração na entrada da ferramenta controla o mecanismo, a quantidade de resultados, a quantidade de chamadas e os domínios.

## Configuração

| Parâmetro | Tipo | Obrigatório | Padrão | Descrição |
| - | - | - | - | - |
| `type` | string | Sim | | Deve ser `orq:web_search`. |
| `engine` | string | Não | `auto` | Provedor de pesquisa. `auto` e `serper` são executados pelo Serper. |
| `max_results` | integer | Não | `5` | Número máximo de resultados retornados por pesquisa. Intervalo aceito: 1 a 25. |
| `max_uses` | integer | Não | Ilimitado | Número máximo de pesquisas durante a solicitação. Defina `0` ou omita o campo para não ter limite específico da ferramenta. |
| `allowed_domains` | string\[] | Não | Todos os domínios | Restringe os resultados aos domínios listados. |
| `excluded_domains` | string\[] | Não | Nenhum | Exclui resultados dos domínios listados. |

`max_results` é um limite máximo. Se o modelo solicitar menos resultados, o valor menor é usado.

## Custo e uso

Cada pesquisa na web do **Toqan Router** que inicia a execução custa US\$ 0,005. A cobrança é incluída no custo da resposta quando os dados de faturamento estão disponíveis.

O número de pesquisas aparece em `usage.server_tool_use.web_search_requests`. Uma chamada rejeitada por `max_uses` não incrementa esse contador; o modelo recebe uma mensagem de limite de uso como resultado da ferramenta, e a tentativa ainda é contabilizada em `usage.server_tool_use_details.tool_calls_requested`.

`orq:google_search` continua aceito como alias legado. O alias não oferece suporte aos campos de configuração acima.

## Tratamento de dados

O **Toqan Router** executa cada pesquisa pelo Serper, o provedor por trás da configuração `engine`.

Cada pesquisa envia a consulta escrita pelo modelo, além das opções de pesquisa definidas por ele: quantidade de resultados, localização, país, idioma, correção automática e filtro de tempo. O prompt e a conversa permanecem com o provedor de modelo escolhido para a resposta.

A consulta e os resultados aparecem em [**Traces**](/docs/pt-BR/ai-studio/observability/traces.md) com o restante da resposta. A forma como o Serper armazena e retém a consulta segue a [política de privacidade do Serper](https://serper.dev/privacy); para retenção e mascaramento na plataforma, consulte Conformidade de dados.

## Ferramentas relacionadas

Use [Web fetch](/docs/pt-BR/ai-gateway/features/server-tools/web-fetch.md) quando um prompt já contiver a URL a ser lida. O web search encontra páginas; o web fetch recupera uma página específica.

Para web search nativo do provedor em `/responses`, use [Web search na Responses API](/docs/pt-BR/ai-gateway/features/web-search.md) com os tipos de ferramenta `web_search` / `web_search_preview`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.