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

# Server tools de knowledge base

> Liste e consulte knowledge bases durante uma resposta para que um modelo possa responder com base nos documentos do workspace.

Duas server tools dão a um modelo acesso às knowledge bases do workspace atual:

* `orq:retrieve_knowledge_bases` lista as knowledge bases disponíveis e as respectivas chaves.
* `orq:query_knowledge_base` recupera conteúdo de documentos de uma knowledge base.

As duas ferramentas estão disponíveis em `POST /v3/router/responses` e `POST /v3/router/chat/completions`. Use as duas quando a chave da knowledge base ainda não for conhecida.

Os nomes sem prefixo `retrieve_knowledge_bases` e `query_knowledge_base` continuam sendo aceitos como aliases legados apenas na Responses API. Com os aliases, o modelo vê as ferramentas pelos nomes simples, em vez de `orq_retrieve_knowledge_bases` e `orq_query_knowledge_base`.

## 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/responses \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "input": "What is the refund policy in the support knowledge base?",
    "tools": [
      { "type": "orq:retrieve_knowledge_bases" },
      { "type": "orq:query_knowledge_base" }
    ]
  }'
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const response = await client.responses.create({
  model: 'openai/gpt-5.4-mini',
  input: 'What is the refund policy in the support knowledge base?',
  tools: [
    { type: 'orq:retrieve_knowledge_bases' },
    { type: 'orq:query_knowledge_base' },
  ] as any,
});

console.log(response.output_text);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
response = client.responses.create(
    model="openai/gpt-5.4-mini",
    input="What is the refund policy in the support knowledge base?",
    tools=[
        {"type": "orq:retrieve_knowledge_bases"},
        {"type": "orq:query_knowledge_base"},
    ],
)

print(response.output_text)
```

## Como funciona a recuperação

1. `orq:retrieve_knowledge_bases` retorna a chave e a descrição de cada knowledge base do workspace.
2. O modelo seleciona uma chave e chama `orq:query_knowledge_base` com uma consulta de busca.
3. A ferramenta de consulta retorna ao modelo os chunks correspondentes. Cada resultado contém `text`, `chunk_id`, `file_name`, `file_type` e `score`, além de `page_number` e `metadata` quando disponíveis. Uma chave desconhecida retorna ao modelo uma mensagem de não encontrado.

A ferramenta de listagem retorna metadados, e não o conteúdo dos documentos. Um modelo precisa chamar a ferramenta de consulta antes de poder responder com base em uma knowledge base.

## Argumentos fornecidos pelo modelo

As entradas das ferramentas não têm campos de configuração além de `type`. O modelo fornece estes argumentos ao chamá-las. Todos os argumentos são obrigatórios no schema da ferramenta.

| Ferramenta | Argumento | Tipo | Descrição |
| - | - | - | - |
| `orq:retrieve_knowledge_bases` | `include_descriptions` | boolean | Aceito por compatibilidade de schema. As descrições são sempre incluídas. |
| `orq:query_knowledge_base` | `query` | string | Consulta de busca. |
| `orq:query_knowledge_base` | `knowledge_base_key` | string | Chave retornada por `orq:retrieve_knowledge_bases`. |
| `orq:query_knowledge_base` | `include_metadata` | boolean | Inclui os metadados dos documentos nos resultados. |

As chamadas de knowledge base não são incluídas em `usage.server_tool_use`.


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