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
| Necessidade | API | Campos |
|---|---|---|
| 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 de Responses |
| Uso de ferramenta ou pensamento nativo do Claude | /v1/messages | Esquema de ferramenta Anthropic Messages |
| Declarações de função ou ferramentas integradas do Gemini | /v1beta/models/:model:generateContent | tools 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:
- Envie mensagens juntamente com as definições de ferramentas.
- Leia a resposta do modelo para
tool_calls,function_call,tool_useda Anthropic ou partes de chamada de função do Gemini. - Execute a ferramenta em seu próprio backend.
- Anexe o resultado da ferramenta no mesmo formato de API.
- 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ó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 |