Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Esquemas JSON e Descrições

Aula 2 de 14 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. A Linguagem das Ferramentas: Esquema JSON
  2. Anatomia de uma Definição de Ferramenta
  3. Descrições de Parâmetros
  4. Parâmetros Avançados
  5. Melhores Práticas para Descrições
  6. Pontos-chave

A Linguagem das Ferramentas: Esquema JSON

Para que o Grok possa chamar as suas funções, precisa de saber o que elas fazem e quais os parâmetros que esperam. É essa a função dos esquemas JSON. Cada ferramenta é descrita por um objeto estruturado que contém três elementos essenciais: um nome, uma descrição e um esquema de parâmetros.

Anatomia de uma Definição de Ferramenta

Eis a estrutura completa de uma ferramenta, tal como a API do Grok a espera:

{
  "type": "function",
  "name": "get_weather",
  "description": "Get the current weather for a given city",
  "parameters": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "The city name (e.g., Paris, Lyon)"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "default": "celsius"
      }
    },
    "required": ["city"]
  }
}

Vamos analisar cada campo:

O Campo type

Sempre "function" para funções personalizadas. Existem outros tipos para ferramentas integradas (web_search, code_interpreter), mas para as suas próprias funções, é invariavelmente "function".

O Campo name

O nome técnico da sua função. Deve ser:

  • Único entre todas as ferramentas no pedido
  • Descritivo: get_weather em vez de fn1
  • Em snake_case por convenção: search_products, create_ticket
  • Curto mas explícito: o modelo usa este nome para decidir qual a ferramenta a chamar

O Campo description

Este é o campo mais importante para a qualidade da chamada. O modelo baseia-se principalmente na descrição para decidir quando e como utilizar uma ferramenta. Uma boa descrição:

  • Explica o que a função faz numa frase
  • Especifica quando a utilizar (se não for óbvio)
  • Menciona casos limite, se necessário

Compare estas duas descrições:

❌ "Weather"
✅ "Get the current weather for a city. Returns temperature, humidity, and conditions."

A segunda fornece ao modelo contexto suficiente para saber exatamente quando chamar esta função e o que receberá em retorno.

O Bloco parameters

Os parâmetros seguem o formato JSON Schema. Os tipos suportados incluem:

  • string — cadeias de caracteres
  • number / integer — números
  • boolean — verdadeiro/falso
  • array — listas
  • object — objetos aninhados
  • enum — lista de valores permitidos

O array required lista os parâmetros obrigatórios. Os outros são opcionais — o modelo pode optar por os omitir.

Descrições de Parâmetros

Cada parâmetro deve ter a sua própria description. É isto que permite ao modelo compreender que valor passar:

{
  "date": {
    "type": "string",
    "description": "Date in YYYY-MM-DD format. If omitted, uses today's date."
  }
}

Sem uma descrição, o modelo tem de adivinhar o formato esperado — o que leva a erros.

Parâmetros Avançados

Enums para Restringir Valores

{
  "priority": {
    "type": "string",
    "enum": ["low", "medium", "high", "critical"],
    "description": "Ticket priority level"
  }
}

Os enums são particularmente úteis: indicam ao modelo os valores exatos que pode utilizar, eliminando erros de formato.

Valores Padrão

{
  "limit": {
    "type": "integer",
    "default": 10,
    "description": "Maximum number of results to return"
  }
}

O modelo compreende que pode omitir este parâmetro se o valor padrão for adequado.

Objetos Aninhados

{
  "address": {
    "type": "object",
    "properties": {
      "street": { "type": "string" },
      "city": { "type": "string" },
      "zip": { "type": "string" }
    },
    "required": ["city"]
  }
}

Melhores Práticas para Descrições

A descrição é o único canal através do qual o modelo compreende a sua ferramenta — cada palavra conta. Priorize a especificidade: “Pesquisar produtos por nome ou categoria no catálogo” indica ao modelo exatamente quando esta ferramenta se aplica, enquanto “Pesquisar produtos” deixa-o a adivinhar. Em seguida, os formatos: especificar “Data no formato ISO 8601 (AAAA-MM-DD)” numa descrição de parâmetro elimina metade dos erros de argumentos, porque o modelo replica o formato que lhe mostra. Os limites fazem parte do contrato: “Máximo de 50 resultados por chamada” impede que o modelo prometa ao utilizador uma completude que a ferramenta não fornecerá. E descrever o retorno — “Devolve um objeto com preço, disponibilidade e descrição” — ajuda o modelo a planear antecipadamente: sabe com o que contará antes mesmo de efetuar a chamada.

Pontos-chave

  • Cada ferramenta é definida por um name, uma description e parameters
  • A descrição é o fator nº 1 na qualidade da chamada — invista tempo nela
  • Os nomes devem ser únicos e em snake_case
  • Utilize enum para restringir os valores possíveis
  • Cada parâmetro deve ter a sua própria descrição com o formato esperado
  • O array required distingue os parâmetros obrigatórios dos opcionais