JSON e chamadas de função

Receba conteúdo em JSON ou conecte funções da sua aplicação aos modelos HINOW.

Atualizado em 09 de ago. de 2026

Use modo JSON quando sua aplicação precisa receber um objeto em vez de texto livre. Use chamadas de função quando o modelo precisa selecionar uma operação e fornecer seus argumentos.

Modo JSON — response_format: {"type": "json_object"} solicita uma resposta em JSON válido. Os campos e valores esperados continuam sendo definidos nas instruções e validados pela aplicação.
Chamada de função — tools descreve operações e parâmetros em JSON Schema. O modelo pode solicitar uma função; sua aplicação valida os argumentos, executa a ação e decide como continuar. Esse mecanismo também é usado por Agents.

Modo JSON

Defina response_format: {"type": "json_object"} e descreva no system os campos, tipos e valores permitidos:

curl https://api.hinow.ai/v1/chat/completions \
  -H "Authorization: Bearer $HINOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hinow/higenesis",
    "temperature": 0,
    "messages": [
      {"role": "system", "content": "Extraia o evento. Responda apenas com JSON no formato {\"nome\": string, \"dia\": string, \"participantes\": string[]}."},
      {"role": "user", "content": "Alice e Bob vão à feira de ciências na sexta-feira."}
    ],
    "response_format": {"type": "json_object"}
  }'

from openai import OpenAI
import os, json

client = OpenAI(base_url="https://api.hinow.ai/v1", api_key=os.environ["HINOW_API_KEY"])

resposta = client.chat.completions.create(
    model="hinow/higenesis",
    temperature=0,
    messages=[
        {
            "role": "system",
            "content": 'Extraia o evento. Responda apenas com JSON no formato '
            '{"nome": string, "dia": string, "participantes": string[]}.',
        },
        {"role": "user", "content": "Alice e Bob vão à feira de ciências na sexta-feira."},
    ],
    response_format={"type": "json_object"},
)

evento = json.loads(resposta.choices[0].message.content)

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.hinow.ai/v1',
  apiKey: process.env.HINOW_API_KEY,
});

const resposta = await client.chat.completions.create({
  model: 'hinow/higenesis',
  temperature: 0,
  messages: [
    {
      role: 'system',
      content:
        'Extraia o evento. Responda apenas com JSON no formato ' +
        '{"nome": string, "dia": string, "participantes": string[]}.',
    },
    { role: 'user', content: 'Alice e Bob vão à feira de ciências na sexta-feira.' },
  ],
  response_format: { type: 'json_object' },
});

const evento = JSON.parse(resposta.choices[0].message.content);

A resposta desta chamada, como veio da API:

{
  "nome": "feira de ciências",
  "dia": "sexta-feira",
  "participantes": ["Alice", "Bob"]
}

O modo JSON evita uma resposta de texto livre, mas não aplica automaticamente o esquema descrito no prompt. Faça o parse, valide os campos e trate respostas incompletas, valores fora do domínio e gerações interrompidas por limite.

Chamada de função

Declare cada operação em tools, com nome, descrição e parâmetros em JSON Schema. Quando o modelo decidir usar uma ferramenta, a resposta incluirá tool_calls:

curl https://api.hinow.ai/v1/chat/completions \
  -H "Authorization: Bearer $HINOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hinow/higenesis",
    "temperature": 0,
    "messages": [
      {"role": "user", "content": "Registre o evento: Alice e Bob vão à feira de ciências na sexta-feira."}
    ],
    "tools": [{
      "type": "function",
      "function": {
        "name": "registrar_evento",
        "description": "Registra um evento extraído do texto",
        "parameters": {
          "type": "object",
          "properties": {
            "nome": {"type": "string"},
            "dia": {"type": "string"},
            "participantes": {"type": "array", "items": {"type": "string"}}
          },
          "required": ["nome", "dia", "participantes"]
        }
      }
    }],
    "tool_choice": "auto"
  }'

from openai import OpenAI
import os, json

client = OpenAI(base_url="https://api.hinow.ai/v1", api_key=os.environ["HINOW_API_KEY"])

resposta = client.chat.completions.create(
    model="hinow/higenesis",
    temperature=0,
    messages=[
        {"role": "user", "content": "Registre o evento: Alice e Bob vão à feira de ciências na sexta-feira."},
    ],
    tools=[{
        "type": "function",
        "function": {
            "name": "registrar_evento",
            "description": "Registra um evento extraído do texto",
            "parameters": {
                "type": "object",
                "properties": {
                    "nome": {"type": "string"},
                    "dia": {"type": "string"},
                    "participantes": {"type": "array", "items": {"type": "string"}},
                },
                "required": ["nome", "dia", "participantes"],
            },
        },
    }],
    tool_choice="auto",
)

chamada = resposta.choices[0].message.tool_calls[0]
argumentos = json.loads(chamada.function.arguments)

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.hinow.ai/v1',
  apiKey: process.env.HINOW_API_KEY,
});

const resposta = await client.chat.completions.create({
  model: 'hinow/higenesis',
  temperature: 0,
  messages: [
    { role: 'user', content: 'Registre o evento: Alice e Bob vão à feira de ciências na sexta-feira.' },
  ],
  tools: [{
    type: 'function',
    function: {
      name: 'registrar_evento',
      description: 'Registra um evento extraído do texto',
      parameters: {
        type: 'object',
        properties: {
          nome: { type: 'string' },
          dia: { type: 'string' },
          participantes: { type: 'array', items: { type: 'string' } },
        },
        required: ['nome', 'dia', 'participantes'],
      },
    },
  }],
  tool_choice: 'auto',
});

const chamada = resposta.choices[0].message.tool_calls[0];
const argumentos = JSON.parse(chamada.function.arguments);

A resposta vem com finish_reason: "tool_calls" e a chamada montada:

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "",
        "tool_calls": [
          {
            "id": "call_00_tYbEz310...",
            "type": "function",
            "function": {
              "name": "registrar_evento",
              "arguments": "{\"nome\": \"Feira de Ciências\", \"dia\": \"sexta-feira\", \"participantes\": [\"Alice\", \"Bob\"]}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}

arguments é uma string

Os argumentos chegam como uma string JSON. Faça o parse e valide o resultado contra o esquema antes de executar a função. Nunca use argumentos gerados pelo modelo como autorização para uma ação sensível.

A declaração informa ao modelo quais operações existem; ela não executa código. Sua aplicação recebe a solicitação, valida permissões e argumentos, executa a função e devolve o resultado quando o fluxo exigir. Para orquestração pronta, consulte Agents.

Qual via escolher

	Modo JSON	Chamada de função
Onde o esquema vive	No `system`, em texto	Em `tools`, como JSON Schema
O que a API entrega	Conteúdo em JSON	Nome da função e argumentos em JSON
Validação	Obrigatória na aplicação	Obrigatória antes de executar
Vários formatos na mesma chamada	Não — um formato por prompt	Sim — uma ferramenta por formato
Quando usar	Extração e classificação simples	Ações, múltiplos formatos, agentes

Exemplos

Triagem de chamados

Neste exemplo, a aplicação espera uma categoria fechada, uma urgência numérica e um resumo curto:

system.txt

Você classifica chamados de suporte.

Responda apenas com JSON no formato:
{"categoria": string, "urgencia": number, "resumo": string}

categoria: uma de "cobranca", "tecnico", "conta".
urgencia: inteiro de 1 a 5.
resumo: no máximo 15 palavras.

// user: "meu cartão foi cobrado duas vezes esse mês e ninguém me responde faz 3 dias"

{
  "categoria": "cobranca",
  "urgencia": 5,
  "resumo": "Cobrança duplicada no cartão, sem resposta há 3 dias."
}

Valores permitidos reduzem variações de rótulo e tornam a validação objetiva. Ainda assim, rejeite qualquer categoria fora da lista antes de gravar ou encaminhar o chamado.

Justificativa verificável

Quando uma decisão precisa ser revisada, solicite uma justificativa curta e as evidências usadas. Isso é mais útil para auditoria do que pedir uma transcrição extensa do raciocínio interno.

system.txt

Classifique o pedido e informe a decisão.

Responda apenas com JSON no formato:
{"decisao": string, "justificativa": string, "evidencias": string[]}

A justificativa deve ter no máximo duas frases. Em evidencias,
inclua somente trechos presentes na entrada.

Valide do seu lado

Trate a resposta do modelo como entrada externa. Um fluxo robusto segue três etapas:

Faça o parse com json.loads ou JSON.parse e trate falhas.
Valide contra um esquema com Zod, Pydantic ou o validador usado pelo projeto. Rejeite campos faltantes, tipos incorretos e valores fora de enum.
Valide a regra de negócio — o esquema aceita urgencia: 5; se o seu fluxo só abre plantão a partir de 4, essa decisão pertence ao código.

Quando a validação falhar, registre o motivo e aplique uma política explícita: tentar novamente com o erro de validação, usar um modelo mais capaz, solicitar revisão humana ou encerrar o fluxo.

Streaming

JSON parcial não pode ser validado como documento completo. Se usar stream: true, acumule os delta e faça parse apenas após o evento final. Em pipelines de backend, receber a resposta inteira costuma simplificar validação, repetição e tratamento de erro.

Boas práticas

Use temperatura baixa quando a tarefa tiver uma resposta esperada e pouca margem para variação.
Enumere os valores possíveis de todo campo de categoria.
Nomes que dizem o que o campo é — o modelo lê os nomes; resumo_uma_linha orienta mais que texto2.
Defina o caso sem resposta — "quando um campo não puder ser determinado, use null" evita valores inventados.
Um formato por chamada no modo JSON; se a mesma rota precisa de formatos diferentes, use chamada de função com uma ferramenta por formato.

Próximos passos

Geração de textoPapéis de mensagem e o caminho do teste à produção.Abrir AgentsQuando as funções executam ações de verdade, em laço.Abrir HiGenesis em detalheO modelo de extração em escala, com prompt inicial pronto.Abrir

Esta página foi útil?