Server tool Tool search

A ferramenta orq:tool_search adia o carregamento de function tools no prompt até que o modelo as solicite. Marque as function tools com defer_loading: true, e o modelo receberá apenas a ferramenta de busca e as ferramentas não adiadas. Quando o modelo precisa de um recurso, ele pesquisa as ferramentas adiadas com uma expressão regular, e as ferramentas correspondentes passam a poder ser chamadas no turno seguinte. Adiar ferramentas reduz os tokens do prompt e mantém a lista de ferramentas estável para o prompt caching. Isso compensa a partir de aproximadamente dez ferramentas ou 10k tokens de definições de ferramentas. A busca é executada no AI Gateway; portanto, funciona com qualquer modelo compatível com tool calling.

Início rápido

Os exemplos usam a configuração de cliente da Visão geral das server tools.

curl -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.4-mini",
    "input": "Book me a table for four tomorrow night and add it to my calendar.",
    "tools": [
      { "type": "orq:tool_search" },
      {
        "type": "function",
        "name": "book_restaurant",
        "description": "Reserve a restaurant table for a party at a given date and time.",
        "parameters": {
          "type": "object",
          "properties": {
            "party_size": { "type": "integer", "description": "Number of guests." },
            "datetime": { "type": "string", "description": "Reservation time as an ISO 8601 timestamp." }
          },
          "required": ["party_size", "datetime"]
        },
        "defer_loading": true
      },
      {
        "type": "function",
        "name": "create_calendar_event",
        "description": "Add an event to the user'"'"'s calendar.",
        "parameters": {
          "type": "object",
          "properties": {
            "title": { "type": "string", "description": "Event title." },
            "start": { "type": "string", "description": "Start time as an ISO 8601 timestamp." }
          },
          "required": ["title", "start"]
        },
        "defer_loading": true
      }
    ]
  }'

const response = await client.responses.create({
  model: 'openai/gpt-5.4-mini',
  input: 'Book me a table for four tomorrow night and add it to my calendar.',
  tools: [
    { type: 'orq:tool_search' },
    {
      type: 'function',
      name: 'book_restaurant',
      description: 'Reserve a restaurant table for a party at a given date and time.',
      parameters: {
        type: 'object',
        properties: {
          party_size: { type: 'integer', description: 'Number of guests.' },
          datetime: { type: 'string', description: 'Reservation time as an ISO 8601 timestamp.' },
        },
        required: ['party_size', 'datetime'],
      },
      defer_loading: true,
    },
  ] as any,
});

console.log(response.output);

response = client.responses.create(
    model="openai/gpt-5.4-mini",
    input="Book me a table for four tomorrow night and add it to my calendar.",
    tools=[
        {"type": "orq:tool_search"},
        {
            "type": "function",
            "name": "book_restaurant",
            "description": "Reserve a restaurant table for a party at a given date and time.",
            "parameters": {
                "type": "object",
                "properties": {
                    "party_size": {"type": "integer", "description": "Number of guests."},
                    "datetime": {"type": "string", "description": "Reservation time as an ISO 8601 timestamp."},
                },
                "required": ["party_size", "datetime"],
            },
            "defer_loading": True,
        },
    ],
)

print(response.output)

Em Chat Completions, defina defer_loading ao lado de function no objeto da ferramenta.

Como funciona

O modelo vê orq_tool_search e as ferramentas que não foram adiadas.
Quando precisa de um recurso, ele chama orq_tool_search com uma expressão regular, por exemplo, calendar|event.
O AI Gateway compara o padrão, sem diferenciar maiúsculas de minúsculas, com os nomes, as descrições e os nomes e descrições dos parâmetros das ferramentas adiadas. Um padrão weather encontra uma ferramenta cuja única menção a clima está na descrição de um parâmetro.
As ferramentas correspondentes são adicionadas à lista de ferramentas do modelo. O modelo as chama como qualquer outra function tool, e a aplicação trata a chamada normalmente.

Revelar uma ferramenta não altera as ferramentas que já estão na conversa; assim, o prefixo de prompt em cache permanece intacto. Em uma continuação com previous_response_id ou conversation, as ferramentas reveladas em turnos anteriores são oferecidas desde o início.

Configuração

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`type`	string	Sim		Deve ser `orq:tool_search`.
`max_results`	integer	Não	`5`	Máximo de ferramentas reveladas por busca. Intervalo aceito: de 1 a 50.

Defina defer_loading: true em qualquer ferramenta function para ocultá-la. Apenas function tools podem ser adiadas; o próprio orq:tool_search nunca é adiado, para que o modelo sempre tenha uma ferramenta para chamar.

Regras

Uma solicitação com uma ferramenta adiada precisa incluir orq:tool_search; caso contrário, falha com tool_search_required.
tool_choice precisa ser omitido, auto ou none. Forçar uma chamada de ferramenta entra em conflito com o tool search e falha com tool_choice_conflict.
Um padrão tem no máximo 200 caracteres. Um padrão malformado é retornado ao modelo como erro de ferramenta, e não como falha da solicitação.
Uma chamada a uma ferramenta adiada que nenhuma busca revelou é rejeitada como uma ferramenta que não foi oferecida.

Agentes

Os agentes também podem usar o tool search. Adicione orq:tool_search às ferramentas do agente e defina configuration.defer_loading nas ferramentas personalizadas que devem ser ocultadas:

{
  "tools": [
    { "type": "orq:tool_search", "configuration": { "max_results": 5 } },
    { "type": "http", "key": "book_restaurant", "configuration": { "defer_loading": true } },
    { "type": "http", "key": "create_calendar_event", "configuration": { "defer_loading": true } }
  ]
}

Sem orq:tool_search no agente, defer_loading não tem efeito e todas as ferramentas permanecem visíveis.

Custo e uso

As buscas de ferramentas não têm cobrança adicional. O número de buscas aparece em usage.server_tool_use.tool_search_requests. Cada busca é um item de saída orq:tool_search cujo resultado lista as ferramentas reveladas.

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

Início rápido

Como funciona

Configuração

Regras

Agentes

Custo e uso

​Início rápido

​Como funciona

​Configuração

​Regras

​Agentes

​Custo e uso

Início rápido

Como funciona

Configuração

Regras

Agentes

Custo e uso