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

# Server tool Search models

> Permita que um modelo pesquise o catálogo do Toqan Router por provedor, tamanho de contexto, recurso ou custo de entrada.

A ferramenta `orq:search_models` pesquisa o catálogo de modelos do **Toqan Router** durante uma resposta. Ela é útil quando um modelo precisa escolher outro modelo com base no tamanho de contexto, no suporte a ferramentas, no suporte a visão ou no custo de entrada.

Os resultados vêm do registro público de modelos e dos modelos privados ativados no workspace atual; os resultados públicos não são filtrados pelos modelos ativados no workspace. Apenas modelos de chat são retornados.

## Início rápido

Os exemplos usam a configuração de cliente da [Visão geral das server tools](/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": "Find a model with vision and tool support for a document workflow." }
    ],
    "tools": [
      { "type": "orq:search_models", "max_results": 5 }
    ]
  }'
```

```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:
        'Find a model with vision and tool support for a document workflow.',
    },
  ],
  tools: [{ type: 'orq:search_models', max_results: 5 }] 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": "Find a model with vision and tool support for a document workflow.",
        }
    ],
    tools=[
        {"type": "orq:search_models", "max_results": 5}
    ],
)

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

## Configuração

| Parâmetro | Tipo | Obrigatório | Padrão | Descrição |
| - | - | - | - | - |
| `type` | string | Sim | | Deve ser `orq:search_models`. |
| `max_results` | integer | Não | `5` | Máximo de modelos retornados. Intervalo aceito: de 1 a 20. |

## Filtros fornecidos pelo modelo

O modelo pode combinar estes filtros em uma chamada de ferramenta:

| Filtro | Descrição |
| - | - |
| `query` | Corresponde ao nome do modelo, ao nome de exibição ou à família do modelo. |
| `provider` | Corresponde a um provedor. |
| `min_context_length` | Exige pelo menos essa quantidade de tokens de contexto. |
| `require_tools` | Retorna apenas modelos compatíveis com function calling. |
| `require_vision` | Retorna apenas modelos compatíveis com entrada de imagens. |
| `max_input_cost` | Custo máximo de entrada em USD por 1,000 tokens. |

`query` corresponde ao nome simples do modelo, e não ao id `provider/model`; assim, `gpt-5.4-mini` corresponde e `openai/gpt-5.4-mini` não. Combine `query` com `provider` para restringir a um único provedor.

O resultado contém `models`, `total_results` (todas as correspondências) e `showing` (a quantidade retornada). Cada modelo inclui um campo `id` (`provider/model`, por exemplo, `openai/gpt-5.4-mini`), que é o identificador roteável canônico a ser passado como `model` nas solicitações seguintes, já que o nome simples do modelo não é único entre provedores. Os modelos privados do workspace têm o prefixo `workspaceKey@` (por exemplo, `my-workspace@openai/my-finetune`). Os resultados são ordenados por `id` e incluem os custos do modelo, o tamanho de contexto e as flags de recursos.

## Custo e uso

As pesquisas no catálogo não têm cobrança adicional. O número de pesquisas aparece em `usage.server_tool_use.search_models_requests`.

Combine esta ferramenta com o [Subagent](/docs/pt-BR/ai-gateway/features/server-tools/subagent.md) quando o modelo chamador precisar selecionar um modelo executor antes de delegar uma tarefa.


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