Definir Funções com JSON Schema
Nesta página
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"]
}
}
}
| Campo | Função |
|---|---|
type | Sempre "function" (outros tipos podem existir no futuro) |
function.name | O nome exato da sua função Python — é isto que o modelo devolve em tool_calls |
function.description | Uma frase clara que ajuda o modelo a escolher a função correta |
function.parameters | Um objeto JSON Schema que descreve os parâmetros esperados |
required | A 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, umadescriptioneparameterstipados - Os tipos suportados incluem
string,integer,number,boolean,arrayeobject - A lista
requireddistingue parâmetros obrigatórios de opcionais - Descrições precisas com exemplos melhoram significativamente a precisão do modelo