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 RotaCopy Anchor Link

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

Modo JSONCopy Anchor Link

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

{
  "model": "gpt-5.6-terra",
  "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 FerramentasCopy Anchor Link

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 CompletionsCopy Anchor Link

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": "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 EsquemaCopy Anchor Link

• 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çãoCopy Anchor Link

• 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 APICopy Anchor Link