Skip to main content
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

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

​
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