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

Definir Funções com JSON Schema

Aula 3 de 14 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. O contrato entre o seu código e o modelo
  2. Anatomia de uma especificação de ferramenta
  3. Tipos JSON Schema suportados
  4. Exemplo completo: duas funções complementares
  5. Parâmetros obrigatórios vs. opcionais
  6. Melhores práticas para descrições
  7. Pontos-chave

O contrato entre o seu código e o modelo

Para que o modelo Mistral possa chamar as suas funções, ele precisa de saber o que existe e como utilizar. É aqui que entra o JSON Schema: um formato padronizado que descreve cada função — o seu nome, o que faz, que parâmetros espera e quais são obrigatórios.

Tenha sempre isto em mente durante esta lição: o modelo nunca vê o seu código Python. Ele vê apenas esta especificação. Se a sua função tratar IDs em minúsculas corretamente, mas o schema não o indicar, o modelo ignorará essa capacidade. Quanto mais preciso e bem documentado for o seu schema, mais precisos serão os argumentos gerados.

Anatomia de uma especificação de ferramenta

Cada ferramenta enviada à API da Mistral segue a mesma estrutura:

tool = {
    "type": "function",
    "function": {
        "name": "function_name",
        "description": "Clear description of what the function does",
        "parameters": {
            "type": "object",
            "properties": {
                "param1": {
                    "type": "string",
                    "description": "Parameter description"
                },
                "param2": {
                    "type": "integer",
                    "description": "Parameter description"
                }
            },
            "required": ["param1"]
        }
    }
}
CampoFunção
typeSempre "function" (outros tipos podem existir no futuro)
function.nameO nome exato da sua função Python — é isto que o modelo devolve em tool_calls
function.descriptionUma frase clara que ajuda o modelo a escolher a função correta
function.parametersUm objeto JSON Schema que descreve os parâmetros esperados
requiredA lista de parâmetros obrigatórios

Tipos JSON Schema suportados

O vocabulário de tipos disponível para descrever parâmetros é intencionalmente restrito, e cada tipo orienta o modelo de forma diferente. Um enum, em particular, faz mais do que documentar: fecha a porta a valores inventados.

# String — texto livre ou restrito
{"type": "string", "description": "Transaction ID"}

# String com enum — valores limitados
{"type": "string", "enum": ["asc", "desc"], "description": "Sort order"}

# Integer — número inteiro
{"type": "integer", "description": "Number of results to return"}

# Number — número decimal
{"type": "number", "description": "Amount in euros"}

# Boolean — verdadeiro/falso
{"type": "boolean", "description": "Include canceled transactions"}

# Array — lista de valores
{
    "type": "array",
    "items": {"type": "string"},
    "description": "List of transaction IDs"
}

# Object — objeto aninhado
{
    "type": "object",
    "properties": {
        "city": {"type": "string"},
        "country": {"type": "string"}
    },
    "description": "Shipping address"
}

Distinga claramente entre integer e number: um valor em euros como 125,50 requer um number, enquanto uma contagem de resultados a devolver é um integer. Declarar um valor monetário como integer fará com que o modelo o arredonde.

Exemplo completo: duas funções complementares

Eis um exemplo realista com duas funções relacionadas com pagamentos, inspirado na documentação oficial da Mistral:

tools = [
    {
        "type": "function",
        "function": {
            "name": "retrieve_payment_status",
            "description": "Retrieves the status of a payment (paid, pending, failed) "
                           "based on the transaction ID.",
            "parameters": {
                "type": "object",
                "properties": {
                    "transaction_id": {
                        "type": "string",
                        "description": "The unique transaction ID (e.g., T1001)"
                    }
                },
                "required": ["transaction_id"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "retrieve_payment_date",
            "description": "Retrieves the date when a payment was made "
                           "based on the transaction ID.",
            "parameters": {
                "type": "object",
                "properties": {
                    "transaction_id": {
                        "type": "string",
                        "description": "The unique transaction ID (e.g., T1001)"
                    }
                },
                "required": ["transaction_id"]
            }
        }
    }
]

Ambas as funções esperam exatamente o mesmo parâmetro, transaction_id, mas o modelo tem de escolher entre elas. Esta escolha depende inteiramente da descrição da função. “Este pagamento foi processado?” mapeia para retrieve_payment_status; “Quando foi efetuado?” mapeia para retrieve_payment_date. Se tivesse escrito duas descrições vagas e intercambiáveis, o modelo erraria metade das vezes — e você culparia o modelo, quando a falha estaria no schema.

Parâmetros obrigatórios vs. opcionais

A distinção entre parâmetros obrigatórios e opcionais determina o que o modelo tem permissão para omitir.

{
    "type": "function",
    "function": {
        "name": "search_transactions",
        "description": "Searches for transactions based on various criteria",
        "parameters": {
            "type": "object",
            "properties": {
                "status": {
                    "type": "string",
                    "enum": ["paid", "pending", "failed"],
                    "description": "Filter by payment status"
                },
                "date_from": {
                    "type": "string",
                    "description": "Start date in YYYY-MM-DD format"
                },
                "date_to": {
                    "type": "string",
                    "description": "End date in YYYY-MM-DD format"
                },
                "min_amount": {
                    "type": "number",
                    "description": "Minimum amount in euros"
                }
            },
            "required": ["status"]
        }
    }
}

Aqui, apenas status é obrigatório; os outros parâmetros são incluídos apenas se o utilizador os mencionar. Compare duas formulações. Para “Mostra-me os pagamentos falhados”, o modelo gera simplesmente {"status": "failed"}. Para “Mostra-me os pagamentos falhados desde março de 2026”, ele adiciona date_from e date_to por iniciativa própria. Tornar essas datas obrigatórias teria quebrado a primeira consulta ou, pior, levado o modelo a inventar um intervalo de datas.

Melhores práticas para descrições

A qualidade da descrição impacta diretamente a precisão do modelo. Os contraexemplos abaixo são mais instrutivos do que qualquer regra abstrata.

# Mau — demasiado vago
{"description": "Retrieves data"}

# Bom — preciso e contextualizado
{"description": "Retrieves the status of a payment (paid, pending, failed) "
                "based on the unique transaction ID"}

# Mau — sem descrição para o parâmetro
{"transaction_id": {"type": "string"}}

# Bom — descrição com exemplo
{"transaction_id": {
    "type": "string",
    "description": "Unique transaction ID (format: T followed by 4 digits, e.g., T1001)"
}}

Uma boa descrição indica numa frase o que a função faz, especifica o formato esperado para cada parâmetro e fornece um exemplo sempre que esse formato não for óbvio — T1001 é melhor do que “ID da transação”. Quando os valores possíveis são limitados, não os descreva em prosa: declare-os com enum. É a única forma de os tornar vinculativos.

Pontos-chave

  • O JSON Schema é o contrato entre o seu código e o modelo — descreve as suas funções sem expor o código
  • Cada ferramenta tem um name, uma description e parameters tipados
  • Os tipos suportados incluem string, integer, number, boolean, array e object
  • A lista required distingue parâmetros obrigatórios de opcionais
  • Descrições precisas com exemplos melhoram significativamente a precisão do modelo