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

# Saídas Estruturadas & Chamada de Ferramentas

> Use o modo JSON, ferramentas de função e rotas de ferramentas nativas sem assumir que todos os modelos suportam o mesmo contrato.

Saídas estruturadas e chamadas de ferramentas são contratos específicos de rota. O TokenLab encaminha vários formatos de API pública, portanto, o padrão de produção mais seguro é manter cada forma nativa da ferramenta do provedor na rota que a possui e validar a saída do modelo em sua própria aplicação.

## Escolha A Rota

| Necessidade                                            | Rota                                    | Use esta forma                                     |
| ------------------------------------------------------ | --------------------------------------- | -------------------------------------------------- |
| Respostas de objeto JSON portáteis                     | `/v1/chat/completions`                  | `response_format: {"type": "json_object"}`         |
| Chamada de função compatível com OpenAI                | `/v1/chat/completions`                  | `tools: [{ "type": "function", "function": ... }]` |
| Ferramentas de Respostas OpenAI                        | `/v1/responses`                         | Campos `tools`, `tool_choice` e `text`             |
| Uso ou pensamento de ferramenta nativa Claude          | `/v1/messages`                          | Esquema de ferramenta Anthropic Messages           |
| Declarações de função Gemini ou ferramentas integradas | `/v1beta/models/:model:generateContent` | `tools` nativos do Gemini e partes de conteúdo     |

Não envie ferramentas integradas nativas do provedor por uma rota diferente e espere que o TokenLab as traduza silenciosamente.

## Modo JSON

Para respostas estruturadas portáteis, comece com o modo JSON de Chat Completions:

```json theme={null}
{
  "model": "gpt-5.4",
  "messages": [
    {
      "role": "user",
      "content": "Retorne um objeto JSON com cidade e clima."
    }
  ],
  "response_format": { "type": "json_object" }
}
```

A validação compartilhada estável para Chat Completions aceita `text` e `json_object`. `json_schema`, `strict` e a aplicação de esquema específica do provedor podem existir para algumas rotas upstream ou caminhos de conversão, mas não são uma promessa geral em todas as rotas e modelos do TokenLab. Verifique-os em relação ao modelo selecionado antes de confiar neles.

Sempre analise e valide o JSON retornado em seu servidor. O modo JSON melhora a forma, mas não substitui a validação de esquema em nível de aplicação.

## Loop de Chamada de Ferramentas

O TokenLab não executa suas funções. Sua aplicação é responsável pelo loop:

1. Envie mensagens mais definições de ferramentas.
2. Leia a resposta do modelo para `tool_calls`, `function_call`, `tool_use` da Anthropic ou partes da chamada de função Gemini.
3. Execute a ferramenta em seu próprio backend.
4. Anexe o resultado da ferramenta no formato exigido pela mesma rota.
5. Continue a conversa até que o modelo retorne uma resposta final.

Mantenha a mesma rota durante todo o loop de ferramentas. Misturar formatos de Chat Completions, Responses, Messages e Gemini em uma conversa geralmente cria bugs sutis de estado e esquema.

## Exemplo de Chat Completions

```bash theme={null}
curl https://api.tokenlab.sh/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "messages": [
      {
        "role": "user",
        "content": "Extraia nome e email como JSON. Se necessário, procure o cliente."
      }
    ],
    "response_format": { "type": "json_object" },
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "lookup_customer",
          "description": "Procure um cliente por email",
          "parameters": {
            "type": "object",
            "properties": {
              "email": { "type": "string" }
            },
            "required": ["email"]
          }
        }
      }
    ]
  }'
```

## Design de Esquema

* Mantenha esquemas pequenos e explícitos. Esquemas grandes e aninhados adicionam tokens e reduzem a confiabilidade.
* Prefira campos obrigatórios para valores que seu produto não pode continuar sem.
* Use enums para conjuntos fechados dos quais sua UI ou backend depende.
* Inclua exemplos no prompt quando o modelo tiver dificuldades com uma forma.
* Trate erros de campo não suportado como feedback de contrato. Remova o campo ou use a rota nativa que o documenta.

## Lista de Verificação de Produção

* Registre rota, modelo, nomes de ferramentas e forma de esquema sanitizada nos logs.
* Valide os argumentos da ferramenta antes de executar qualquer efeito colateral.
* Aplique suas próprias verificações de permissão antes da execução da ferramenta.
* Torne a execução da ferramenta idempotente quando uma nova tentativa do cliente puder repetir a mesma chamada de ferramenta.
* Não registre segredos retornados por ferramentas em mensagens visíveis para o modelo.

## Referência da API

| Tópico                | Referência                                                         |
| --------------------- | ------------------------------------------------------------------ |
| API Multi-Formato     | [API Multi-Formato](/pt/guides/api-formats)                        |
| Criar Chat Completion | [Criar Chat Completion](/pt/api-reference/chat/create-completion)  |
| Criar Resposta        | [Criar Resposta](/pt/api-reference/responses/create-response)      |
| Criar Mensagem        | [Criar Mensagem](/pt/api-reference/messages/create-message)        |
| Gerar Conteúdo Gemini | [Gerar Conteúdo Gemini](/pt/api-reference/gemini/generate-content) |