Server tools

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:

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

Adicione uma ou mais server tools ao array tools da solicitação.
O modelo escolhe se vai chamar uma ferramenta e fornece os argumentos de runtime.
O AI Gateway executa a ferramenta e retorna o resultado ao modelo.
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.

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" }
    ]
  }'

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);

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

Web search

orq:web_search: pesquisa a web pública em busca de informações atuais.

Web fetch

orq:web_fetch: obtém uma URL pública e extrai o texto dela.

Datetime

orq:datetime: retorna a data e a hora atuais em um fuso horário IANA.

Image generation

orq:image_generation: gera uma imagem com um modelo de imagem configurado. Apenas na Responses API.

Code interpreter

orq:code_interpreter: executa Python em um sandbox isolado.

Shell

orq:shell: executa comandos em um sandbox Linux isolado.

Apply patch

orq:apply_patch: valida alterações em arquivos antes que a aplicação as aplique.

Knowledge bases

orq:retrieve_knowledge_bases e orq:query_knowledge_base: listam e consultam knowledge bases do workspace.

Search models

orq:search_models: pesquisa o catálogo de modelos do Toqan Router por recurso e custo.

Tool search

orq:tool_search: retira grandes bibliotecas de ferramentas do prompt e permite que o modelo pesquise as ferramentas de que precisa.

Subagent

orq:subagent: delega uma tarefa autocontida a outro modelo.

Advisor

orq:advisor: pede conselhos a outro modelo durante uma resposta.

Fusion

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

{
  "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 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

{
  "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)

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

Server tools e function tools

Como as server tools funcionam

Início rápido

Ferramentas disponíveis

Web search

Web fetch

Datetime

Image generation

Code interpreter

Shell

Apply patch

Knowledge bases

Search models

Tool search

Subagent

Advisor

Fusion

Combinar server tools com funções

Relatório de uso

Limitações de Chat Completions

Nomes legados

​Server tools e function tools

​Como as server tools funcionam

​Início rápido

​Ferramentas disponíveis

Web search

Web fetch

Datetime

Image generation

Code interpreter

Shell

Apply patch

Knowledge bases

Search models

Tool search

Subagent

Advisor

Fusion

​Combinar server tools com funções

​Relatório de uso

​Limitações de Chat Completions

​Nomes legados

Server tools e function tools

Como as server tools funcionam

Início rápido

Ferramentas disponíveis

Combinar server tools com funções

Relatório de uso

Limitações de Chat Completions

Nomes legados