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

# Server tools

> Permita que os modelos pesquisem na web, executem código, consultem knowledge bases, consultem outros modelos e realizem outras tarefas por meio de ferramentas operadas pelo AI Gateway.

As server tools permitem que um modelo execute ações durante uma solicitação sem um executor de ferramentas separado na aplicação. Adicione uma ferramenta compatível ao array `tools` padrão. O **AI Gateway** a apresenta ao modelo, executa cada chamada de ferramenta e retorna a resposta final do modelo.

As server tools estão disponíveis em:

* [`POST /v3/router/responses`](/docs/pt-BR/reference/responses/create-response)
* [`POST /v3/router/chat/completions`](/docs/pt-BR/reference/chat/create-chat-completion)

`orq:image_generation` está disponível apenas na Responses API. O modelo selecionado precisa ser compatível com tool calling.

## Server tools e function tools

| | Server tool | Function tool |
| - | - | - |
| Quem decide chamá-la | O modelo | O modelo |
| Quem a executa | **Toqan Router** | A aplicação |
| Tipo na solicitação | `orq:*` para a maioria das ferramentas | `function` |
| Chamadas por solicitação | Zero ou mais, dentro dos limites configurados | Zero ou mais |
| Tratamento do resultado | O **AI Gateway** retorna o resultado ao modelo | A aplicação envia o resultado da função |

As server tools podem compartilhar uma solicitação com function tools. Ferramentas hospedadas pelo provedor, como `web_search` ou `file_search`, são diferentes das ferramentas `orq:*` documentadas aqui.

## Como as server tools funcionam

1. Adicione uma ou mais server tools ao array `tools` da solicitação.
2. O modelo escolhe se vai chamar uma ferramenta e fornece os argumentos de runtime.
3. O **AI Gateway** executa a ferramenta e retorna o resultado ao modelo.
4. O modelo pode chamar outra ferramenta ou concluir a resposta.

`limits.max_iterations` limita o loop no servidor. O padrão é 10 chamadas ao modelo, e são aceitos valores de 1 a 100. `max_tool_calls` é aceito nos dois endpoints (de 1 a 30 em Chat Completions) e repetido na resposta, mas não limita o loop no servidor.

O modelo vê cada server tool pelo seu tipo, com `orq:` substituído por `orq_` (por exemplo, `orq:web_search` se torna `orq_web_search`), e os itens de saída usam esse nome. Os nomes das ferramentas precisam ser únicos em uma solicitação; portanto, uma function tool não pode reutilizar o nome de uma server tool.

## Início rápido

Este exemplo dá ao modelo acesso à busca na web e à data atual. O modelo pode usar qualquer uma das ferramentas, as duas ou nenhuma.

Os tipos TypeScript upstream da OpenAI não definem ferramentas `orq:*`; por isso, os exemplos em TypeScript fazem cast do array `tools`.

```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 changed in EU AI Act enforcement this month?"
      }
    ],
    "tools": [
      { "type": "orq:web_search", "max_results": 5 },
      { "type": "orq:datetime", "timezone": "Europe/Amsterdam" }
    ]
  }'
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.chat.completions.create({
  model: 'openai/gpt-5.4-mini',
  messages: [
    {
      role: 'user',
      content: 'What changed in EU AI Act enforcement this month?',
    },
  ],
  tools: [
    { type: 'orq:web_search', max_results: 5 },
    { type: 'orq:datetime', timezone: 'Europe/Amsterdam' },
  ] as any,
});

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

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.chat.completions.create(
    model="openai/gpt-5.4-mini",
    messages=[
        {
            "role": "user",
            "content": "What changed in EU AI Act enforcement this month?",
        }
    ],
    tools=[
        {"type": "orq:web_search", "max_results": 5},
        {"type": "orq:datetime", "timezone": "Europe/Amsterdam"},
    ],
)

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

## Ferramentas disponíveis

> [card] [Web search](/docs/pt-BR/ai-gateway/features/server-tools/web-search.md)
>
> `orq:web_search`: pesquisa a web pública em busca de informações atuais.

> [card] [Web fetch](/docs/pt-BR/ai-gateway/features/server-tools/web-fetch.md)
>
> `orq:web_fetch`: obtém uma URL pública e extrai o texto dela.

> [card] [Datetime](/docs/pt-BR/ai-gateway/features/server-tools/datetime.md)
>
> `orq:datetime`: retorna a data e a hora atuais em um fuso horário IANA.

> [card] [Image generation](/docs/pt-BR/ai-gateway/features/server-tools/image-generation.md)
>
> `orq:image_generation`: gera uma imagem com um modelo de imagem configurado.
> Apenas na Responses API.

> [card] [Code interpreter](/docs/pt-BR/ai-gateway/features/server-tools/code-interpreter.md)
>
> `orq:code_interpreter`: executa Python em um sandbox isolado.

> [card] [Shell](/docs/pt-BR/ai-gateway/features/server-tools/shell.md)
>
> `orq:shell`: executa comandos em um sandbox Linux isolado.

> [card] [Apply patch](/docs/pt-BR/ai-gateway/features/server-tools/apply-patch.md)
>
> `orq:apply_patch`: valida alterações em arquivos antes que a aplicação as
> aplique.

> [card] [Knowledge bases](/docs/pt-BR/ai-gateway/features/server-tools/knowledge-bases.md)
>
> `orq:retrieve_knowledge_bases` e `orq:query_knowledge_base`: listam e
> consultam knowledge bases do workspace.

> [card] [Search models](/docs/pt-BR/ai-gateway/features/server-tools/search-models.md)
>
> `orq:search_models`: pesquisa o catálogo de modelos do **Toqan Router** por recurso e
> custo.

> [card] [Tool search](/docs/pt-BR/ai-gateway/features/server-tools/tool-search.md)
>
> `orq:tool_search`: retira grandes bibliotecas de ferramentas do prompt e permite
> que o modelo pesquise as ferramentas de que precisa.

> [card] [Subagent](/docs/pt-BR/ai-gateway/features/server-tools/subagent.md)
>
> `orq:subagent`: delega uma tarefa autocontida a outro modelo.

> [card] [Advisor](/docs/pt-BR/ai-gateway/features/server-tools/advisor.md)
>
> `orq:advisor`: pede conselhos a outro modelo durante uma resposta.

> [card] [Fusion](/docs/pt-BR/ai-gateway/features/server-tools/fusion.md)
>
> `orq:fusion`: compara respostas de um painel de modelos.

O array `tools` também aceita entradas `orq:function`, `orq:http` e `orq:mcp` com um `tool_id` que referencia uma ferramenta salva no workspace. Essas entradas são referências a ferramentas existentes da plataforma, e não server tools com configuração própria.

## Combinar server tools com funções

As function tools mantêm o formato padrão da OpenAI. O **AI Gateway** executa as ferramentas `orq:*` e retorna as chamadas de função à aplicação.

```json JSON theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "model": "openai/gpt-5.4-mini",
  "messages": [
    { "role": "user", "content": "Find the latest EUR/USD rate and save it." }
  ],
  "tools": [
    { "type": "orq:web_search", "max_results": 3 },
    {
      "type": "function",
      "function": {
        "name": "save_exchange_rate",
        "description": "Save an exchange rate in the application database",
        "parameters": {
          "type": "object",
          "properties": {
            "pair": { "type": "string" },
            "rate": { "type": "number" }
          },
          "required": ["pair", "rate"]
        }
      }
    }
  ]
}
```

Consulte [Tool calling e execução de funções](/docs/pt-BR/ai-gateway/features/tool-calling.md) para o loop de resposta de chamadas de função.

## Relatório de uso

Quando uma server tool contabilizada é executada, a resposta inclui a quantidade de chamadas em `usage.server_tool_use`.

```json JSON theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "usage": {
    "input_tokens": 1200,
    "output_tokens": 300,
    "server_tool_use": {
      "web_search_requests": 2,
      "web_fetch_requests": 1,
      "subagent_requests": 1
    },
    "server_tool_use_details": {
      "tool_calls_executed": 4,
      "tool_calls_requested": 4
    }
  }
}
```

O objeto de uso pode incluir estes contadores:

| Campo | Ferramenta |
| - | - |
| `web_search_requests` | Web search |
| `web_fetch_requests` | Web fetch |
| `datetime_requests` | Datetime |
| `code_interpreter_sessions` | Code interpreter |
| `advisor_requests` | Advisor |
| `subagent_requests` | Subagent |
| `search_models_requests` | Search models |
| `image_generation_calls` | Image generation |
| `fusion_requests` | Fusion |
| `shell_commands` | Shell |
| `tool_search_requests` | Tool search |

As chamadas de recuperação em knowledge bases e de apply patch não adicionam um campo a `usage.server_tool_use`.

`usage.server_tool_use_details` totaliza as mesmas chamadas entre as ferramentas: `tool_calls_requested` conta todas as chamadas de server tools feitas pelo modelo, e `tool_calls_executed` conta as que o gateway executou. Para web search, web fetch, shell e fusion, uma chamada rejeitada por um limite `max_uses` é solicitada, mas não executada. Advisor e subagent contam uma chamada rejeitada como executada. Chat Completions retorna esses contadores, mas não o resultado da ferramenta em si; leia o resultado nos itens de saída da Responses API ou envie `store: true` e recupere a resposta.

## Limitações de Chat Completions

Em `POST /v3/router/chat/completions`, uma solicitação que inclui uma server tool `orq:*` não pode incluir também:

* `n` maior que `1`
* tipos de ferramentas hospedadas pelo provedor, como `web_search` ou `file_search`
* `orq:image_generation`
* `response_format.type` diferente de `text` ou `json_schema`
* `tool_choice` diferente de `auto`, `none`, `required` ou uma seleção de `function`
* um `model` que não esteja no formato `provider/model`

O endpoint retorna `400` para essas combinações. As function tools continuam compatíveis junto com as server tools.

`plugins`, `guardrails` e `evaluators` são aplicados da mesma forma que em solicitações sem server tools: a configuração fornecida pelo chamador, as regras de roteamento e de guardrail correspondentes e os padrões impostos pelo workspace (como o piso de redação de PII) entram em vigor. No modo de streaming, os guardrails de saída são ignorados, e os evaluators de saída continuam sendo executados depois que a resposta é montada, como no comportamento de streaming sem server tools.

Chat Completions não mantém estado, a menos que `store` seja definido como `true`.

## Nomes legados

Os seguintes aliases continuam sendo aceitos:

| Tipo atual | Alias legado |
| - | - |
| `orq:web_search` | `orq:google_search` |
| `orq:web_fetch` | `orq:web_scraper` |
| `orq:datetime` | `orq:current_date` |
| `orq:subagent` | `orq:sidekick` |
| `orq:retrieve_knowledge_bases` | `retrieve_knowledge_bases` (apenas Responses API) |
| `orq:query_knowledge_base` | `query_knowledge_base` (apenas Responses API) |


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