> ## 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 fetch

> Busque texto de URLs públicas durante a resposta de um modelo com a ferramenta de servidor orq:web_fetch.

A ferramenta `orq:web_fetch` recupera texto de uma URL escolhida pelo modelo. O **AI Gateway** verifica a URL antes de buscá-la e retorna o conteúdo extraído ao modelo.

## 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": "Summarize https://docs.example.com/release-notes"
      }
    ],
    "tools": [
      {
        "type": "orq:web_fetch",
        "max_content_tokens": 4000,
        "allowed_domains": ["docs.example.com"]
      }
    ]
  }'
```

```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: 'Summarize https://docs.example.com/release-notes',
    },
  ],
  tools: [
    {
      type: 'orq:web_fetch',
      max_content_tokens: 4000,
      allowed_domains: ['docs.example.com'],
    },
  ] 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": "Summarize https://docs.example.com/release-notes",
        }
    ],
    tools=[
        {
            "type": "orq:web_fetch",
            "max_content_tokens": 4000,
            "allowed_domains": ["docs.example.com"],
        }
    ],
)

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

## Configuração

| Parâmetro | Tipo | Obrigatório | Padrão | Descrição |
| - | - | - | - | - |
| `type` | string | Sim | | Deve ser `orq:web_fetch`. |
| `engine` | string | Não | `auto` | Mecanismo de busca de conteúdo. Os valores aceitos são `auto` e `jina`. |
| `max_uses` | integer | Não | Ilimitado | Número máximo de buscas durante a solicitação. Defina `0` ou omita o campo para não ter limite específico da ferramenta. |
| `max_content_tokens` | integer | Não | Sem limite específico da ferramenta | Trunca o conteúdo extraído para aproximadamente essa quantidade de tokens. Mínimo: 1. |
| `allowed_domains` | string\[] | Não | Todos os domínios | Busca apenas URLs dos hostnames listados e de seus subdomínios. |
| `blocked_domains` | string\[] | Não | Nenhum | Rejeita URLs dos hostnames listados e de seus subdomínios. |

As entradas de domínio devem ser hostnames simples, como `example.com`. Uma entrada com esquema, caminho ou curinga `*.` retorna `400`. Os subdomínios correspondem por sufixo, então `example.com` também abrange `docs.example.com`.

## Restrições de URL

A ferramenta aceita URLs públicas `http` e `https`. Ela rejeita `localhost`, hostnames terminados em `.localhost`, `.local` ou `.internal` e qualquer endereço de loopback, link-local, privado, multicast, não especificado ou que, por outro motivo, não seja roteável globalmente. O hostname deve resolver para um endereço público, e os endereços resolvidos também são verificados. As regras de domínio são verificadas antes da busca.

Quando uma URL é rejeitada, o modelo recebe o motivo e pode escolher outra URL. URLs rejeitadas não consomem uma vaga de `max_uses`.

## Uso

As buscas que passam pela validação de URL e pelo limite de uso aparecem em `usage.server_tool_use.web_fetch_requests`. Não há cobrança separada de ferramenta de servidor para web fetch nesta versão.

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

Use [Web search](/docs/pt-BR/ai-gateway/features/server-tools/web-search.md) quando a URL não for conhecida com antecedência.


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