Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Functies definiëren met JSON Schema

Les 3 van 14 Bijgewerkt op 29 juli 2026 Ontwikkelaar
Op deze pagina
  1. Het contract tussen uw code en het model
  2. Anatomie van een toolspecificatie
  3. Ondersteunde JSON Schema-typen
  4. Volledig voorbeeld: twee complementaire functies
  5. Verplichte versus optionele parameters
  6. Best practices voor beschrijvingen
  7. Belangrijkste punten

Het contract tussen uw code en het model

Opdat het Mistral-model uw functies kan aanroepen, moet het weten wat er bestaat en hoe het deze moet gebruiken. Dit is de rol van JSON Schema: een gestandaardiseerd formaat dat elke functie beschrijft—de naam, de werking, de verwachte parameters en welke daarvan verplicht zijn.

Houd tijdens deze les één ding goed voor ogen: het model ziet uw Python-code nooit. Het ziet alleen deze specificatie. Als uw functie probleemloos werkt met ID’s in kleine letters, maar het schema vermeldt dit niet, dan negeert het model die mogelijkheid. Hoe preciezer en beter gedocumenteerd uw schema is, hoe accurater de gegenereerde argumenten zullen zijn.

Anatomie van een toolspecificatie

Elke tool die naar de Mistral API wordt verzonden, volgt dezelfde structuur:

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"]
        }
    }
}
VeldRol
typeAltijd "function" (andere typen kunnen in de toekomst bestaan)
function.nameDe exacte naam van uw Python-functie—dit is wat het model retourneert in tool_calls
function.descriptionEen duidelijke zin die het model helpt de juiste functie te kiezen
function.parametersEen JSON Schema-object dat de verwachte parameters beschrijft
requiredDe lijst met verplichte parameters

Ondersteunde JSON Schema-typen

De vocabulaire van typen die beschikbaar is om parameters te beschrijven, is bewust beperkt gehouden; elk type stuurt het model op een andere manier. Een enum doet meer dan documenteren: het sluit de deur voor verzonnen waarden.

# String — vrije tekst of beperkt
{"type": "string", "description": "Transaction ID"}

# String met enum — beperkte waarden
{"type": "string", "enum": ["asc", "desc"], "description": "Sort order"}

# Integer — geheel getal
{"type": "integer", "description": "Number of results to return"}

# Number — decimaal getal
{"type": "number", "description": "Amount in euros"}

# Boolean — waar/onwaar
{"type": "boolean", "description": "Include canceled transactions"}

# Array — lijst met waarden
{
    "type": "array",
    "items": {"type": "string"},
    "description": "List of transaction IDs"
}

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

Maak een duidelijk onderscheid tussen integer en number: een bedrag in euro’s zoals 125,50 vereist een number, terwijl een aantal terug te geven resultaten een integer is. Als u een bedrag declareert als integer, zal het model dit afronden.

Volledig voorbeeld: twee complementaire functies

Hier volgt een realistisch voorbeeld met twee functies gerelateerd aan betalingen, geïnspireerd op de officiële Mistral-documentatie:

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"]
            }
        }
    }
]

Beide functies verwachten exact dezelfde parameter, transaction_id, toch moet het model een keuze tussen hen maken. Deze keuze berust volledig op de functiebeschrijving. “Is deze betaling geslaagd?” correspondeert met retrieve_payment_status; “Wanneer was dit?” correspondeert met retrieve_payment_date. Als u twee vaag en uitwisselbare beschrijvingen had geschreven, zou het model de helft van de tijd fout zitten—en zou u het model de schuld geven terwijl de fout in het schema ligt.

Verplichte versus optionele parameters

Het onderscheid tussen verplichte en optionele parameters bepaalt wat het model mag weglaten.

{
    "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"]
        }
    }
}

Hier is alleen status verplicht; de andere parameters worden alleen opgenomen als de gebruiker ze noemt. Vergelijk twee formuleringen. Voor “Toon mij mislukte betalingen” genereert het model simpelweg {"status": "failed"}. Voor “Toon mij mislukte betalingen vanaf maart 2026” voegt het zelfstandig date_from en date_to toe. Als die datums verplicht waren gesteld, zou de eerste query falen, of erger nog, zou het model gedwongen worden een datumbereik te verzinnen.

Best practices voor beschrijvingen

De kwaliteit van de beschrijving heeft directe invloed op de nauwkeurigheid van het model. De onderstaande contra-voorbeelden zijn instructiever dan welke abstracte regel dan ook.

# Slecht — te vaag
{"description": "Retrieves data"}

# Goed — precies en contextueel
{"description": "Retrieves the status of a payment (paid, pending, failed) "
                "based on the unique transaction ID"}

# Slecht — geen beschrijving voor de parameter
{"transaction_id": {"type": "string"}}

# Goed — beschrijving met voorbeeld
{"transaction_id": {
    "type": "string",
    "description": "Unique transaction ID (format: T followed by 4 digits, e.g., T1001)"
}}

Een goede beschrijving stelt in één zin wat de functie doet, specificeert het verwachte formaat voor elke parameter en biedt een voorbeeld wanneer dat formaat niet voor de hand ligt—T1001 is beter dan “transactie-ID”. Wanneer de mogelijke waarden beperkt zijn, beschrijf ze dan niet in lopende tekst: declareer ze met enum. Dat is de enige manier om ze bindend te maken.

Belangrijkste punten

  • JSON Schema is het contract tussen uw code en het model—het beschrijft uw functies zonder de code bloot te geven
  • Elke tool heeft een name, een description en getypeerde parameters
  • Ondersteunde typen zijn string, integer, number, boolean, array en object
  • De required-lijst maakt onderscheid tussen verplichte en optionele parameters
  • Precieze beschrijvingen met voorbeelden verbeteren de nauwkeurigheid van het model aanzienlijk