Saídas Estruturadas & Chamada de Ferramentas

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:

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

Envie mensagens mais definições de ferramentas.
Leia a resposta do modelo para tool_calls, function_call, tool_use da Anthropic ou partes da chamada de função Gemini.
Execute a ferramenta em seu próprio backend.
Anexe o resultado da ferramenta no formato exigido pela mesma rota.
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

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
Criar Chat Completion	Criar Chat Completion
Criar Resposta	Criar Resposta
Criar Mensagem	Criar Mensagem
Gerar Conteúdo Gemini	Gerar Conteúdo Gemini

​Escolha A Rota

​Modo JSON

​Loop de Chamada de Ferramentas

​Exemplo de Chat Completions

​Design de Esquema

​Lista de Verificação de Produção

​Referência da API