Guias principais

Structured Outputs & Tool Calling

Retorne JSON ou permita que um modelo chame funções em sua aplicação

O Structured output (saída estruturada) solicita JSON a um modelo. O Tool calling (chamada de ferramenta) permite que o modelo solicite uma função que sua aplicação executa. Os campos disponíveis dependem do formato da API e do modelo, portanto, mantenha um único formato durante toda a conversa e valide cada valor produzido pelo modelo em sua aplicação.

Escolha um formato de API

NecessidadeAPICampos
Respostas de objeto JSON portáteis/v1/chat/completionsresponse_format: {"type": "json_object"}
Chamada de função compatível com OpenAI/v1/chat/completionstools: [{ "type": "function", "function": ... }]
Ferramentas de respostas OpenAI/v1/responsesCampos tools, tool_choice e text de Responses
Uso de ferramenta ou pensamento nativo do Claude/v1/messagesEsquema de ferramenta Anthropic Messages
Declarações de função ou ferramentas integradas do Gemini/v1beta/models/:model:generateContenttools e partes de conteúdo nativas do Gemini

Use ferramentas integradas apenas com o formato de API que as documenta; o TokenLab não converte essas ferramentas entre formatos.

Modo JSON

Para um objeto JSON que funcione em vários modelos de chat, use o modo JSON de Chat Completions:

{
  "model": "gpt-5.6-terra",
  "messages": [
    {
      "role": "user",
      "content": "Return a JSON object with city and weather."
    }
  ],
  "response_format": { "type": "json_object" }
}

Modelos que suportam o modo JSON listam json-mode em capabilities em GET /v1/models. O Chat Completions aceita text e json_object. json_schema e strict são específicos do modelo e do formato; use-os apenas quando o modelo selecionado documentar suporte.

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

Conclua uma chamada de ferramenta

O TokenLab retorna o nome da função e os argumentos; sua aplicação a executa:

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

Mantenha o mesmo formato de API até que a chamada da ferramenta e a resposta final estejam concluídas. Os quatro formatos representam o estado da ferramenta de maneiras diferentes.

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.6-terra",
    "messages": [
      {
        "role": "user",
        "content": "Extract name and email as JSON. If needed, look up the customer."
      }
    ],
    "response_format": { "type": "json_object" },
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "lookup_customer",
          "description": "Look up a customer by email",
          "parameters": {
            "type": "object",
            "properties": {
              "email": { "type": "string" }
            },
            "required": ["email"]
          }
        }
      }
    ]
  }'

Escreva um esquema útil

  • Mantenha os esquemas pequenos e explícitos. Esquemas aninhados grandes adicionam tokens e reduzem a confiabilidade.
  • Prefira campos obrigatórios para valores sem os quais seu produto não pode continuar.
  • Use enums para conjuntos fechados dos quais sua UI ou backend dependem.
  • Inclua exemplos no prompt quando o modelo tiver dificuldade com um formato.
  • Se um campo não for suportado, remova-o ou use um formato de API que o documente.

Antes de executar uma ferramenta

  • Registre o formato da API, o modelo, os nomes das ferramentas e os nomes dos campos do esquema.
  • 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 ao modelo.

Referência da API

TópicoReferência
API Multi-FormatoAPI Multi-Formato
Criar Chat CompletionCriar Chat Completion
Criar RespostaCriar Resposta
Criar MensagemCriar Mensagem
Gerar Conteúdo GeminiGerar Conteúdo Gemini

Nesta página