Pydantic en tool-definitie met de xAI SDK
Op deze pagina
Bijgewerkt op 3 november 2026 op basis van de xAI-documentatie over Function calling en
xai-sdk1.21.0: de SDK biedt noch een@client.tool()-decorator, noch automatische functie-uitvoering. U bouwt tools mettool()(bijvoorbeeld met een Pydantic-schema) en retourneert resultaten mettool_result. Bron: Function calling.
Tool-definitie vereenvoudigen
Het handmatig schrijven van JSON-schema’s is omslachtig en foutgevoelig. Er zijn twee benaderingen om tool-definities automatisch te genereren vanuit uw Python-code: Pydantic-modellen, die de xAI SDK met de tool()-functie omzet in tools, en een eenvoudige custom decorator die uw functiesignaturen uitleest.
De Pydantic-benadering
Pydantic is een Python-bibliotheek waarmee u datamodellen definieert met automatische validatie. De Grok API kan deze modellen gebruiken om JSON-schema’s voor tools te genereren.
from pydantic import BaseModel, Field
from typing import Optional
class WeatherParams(BaseModel):
city: str = Field(description="Stadsnaam")
unit: Optional[str] = Field(
default="celsius",
description="Temperatuureenheid",
enum=["celsius", "fahrenheit"]
)
Dit Pydantic-model genereert automatisch het JSON-schema dat u anders handmatig had moeten schrijven. De voordelen zijn:
- Typecontrole: Python controleert types tijdens runtime
- Validatie: Pydantic valideert gegevens automatisch
- Documentatie:
Field(description=...)-items dienen als documentatie - Herbruikbaarheid: hetzelfde model werkt voor validatie en API-documentatie
Complexe modellen
Pydantic verwerkt geneste structuren, lijsten en geavanceerde types:
from typing import List, Optional
from pydantic import BaseModel, Field
class Address(BaseModel):
street: str = Field(description="Straatnaam en huisnummer")
city: str = Field(description="Stad")
zip_code: str = Field(description="Postcode")
country: str = Field(default="FR", description="ISO-landcode")
class CreateOrderParams(BaseModel):
product_id: str = Field(description="Productidentificatie")
quantity: int = Field(description="Bestelde hoeveelheid", ge=1, le=100)
shipping_address: Address = Field(description="Verzendadres")
notes: Optional[str] = Field(
default=None,
description="Speciale leveringsinstructies"
)
tags: List[str] = Field(
default=[],
description="Tags voor ordertracking"
)
De beperkingen ge (groter dan of gelijk aan) en le (kleiner dan of gelijk aan) worden vertaald naar JSON Schema-beperkingen die het model afdwingt.
De tool()-functie van de xAI SDK
De xAI SDK accepteert geen Pydantic-klasse als zodanig: deze verwacht een tool-definitie, die de tool()-functie samenstelt op basis van een naam, een beschrijving en een JSON-schema. Pydantic levert precies dit schema via model_json_schema():
from xai_sdk.chat import tool
tools = [
tool(
name="get_weather",
description="Haal het huidige weer voor een stad op",
parameters=WeatherParams.model_json_schema(),
),
]
Gebruik met de SDK
U declareert de tool bij het aanmaken van de conversatie. De SDK voert uw functies niet uit: wanneer Grok een aanroep verzoekt, voert uw code deze uit, voegt het resultaat toe met tool_result en hervat vervolgens de generatie.
import json
from xai_sdk import Client
from xai_sdk.chat import tool_result, user
client = Client(api_key="your-api-key")
chat = client.chat.create(model="grok-4.5", tools=tools)
chat.append(user("Weer in Bordeaux?"))
response = chat.sample()
if response.tool_calls:
chat.append(response)
for call in response.tool_calls:
args = WeatherParams.model_validate_json(call.function.arguments)
result = {"temp": 22, "unit": args.unit, "city": args.city} # uw implementatie
chat.append(tool_result(json.dumps(result)))
response = chat.sample()
print(response.content)
model_validate_json controleert ook of de door het model geproduceerde argumenten overeenkomen met het schema: een ontbrekend argument of verkeerd type leidt tot een fout voordat uw functie wordt uitgevoerd.
Een custom decorator voor snelheid
De SDK biedt geen @tool-decorator. Niets weerhoudt u ervan er in een paar regels zelf een te schrijven die de signatuur en docstring van een functie uitleest:
import inspect
from pydantic import create_model
from xai_sdk.chat import tool
def custom_tool(func):
"""Bouwt de xAI tool-definitie op basis van de signatuur en docstring van een functie."""
fields = {
name: (p.annotation, ... if p.default is inspect.Parameter.empty else p.default)
for name, p in inspect.signature(func).parameters.items()
}
schema = create_model(func.__name__, **fields).model_json_schema()
description = (inspect.getdoc(func) or func.__name__).split("\n\n")[0]
return tool(name=func.__name__, description=description, parameters=schema)
def get_weather(city: str, unit: str = "celsius") -> dict:
"""Haal het huidige weer voor een stad op (bijv. Parijs, Lyon)."""
return {"temp": 22, "unit": unit, "city": city}
tools = [custom_tool(get_weather)]
De functienaam wordt de tool-naam, de eerste alinea van de docstring wordt de beschrijving, en parameters zonder standaardwaarde worden verplicht. Parameterbeschrijvingen worden echter niet geëxtraheerd: bij dubbelzinnige parameters kunt u beter terugvallen op een Pydantic-model met Field(description=...).
Vergelijking van de drie benaderingen
| Benadering | Voordelen | Beperkingen |
|---|---|---|
| Handmatig JSON-schema | Volledige controle, geen afhankelijkheden | Omslachtig, typefouten worden niet gedetecteerd |
Pydantic-model + tool() | Argumentvalidatie, beschrijvingen per veld | Één klasse per tool |
| Custom decorator | Meest beknopt | Geen beschrijvingen per parameter, code om te onderhouden |
Best practices voor beschrijvingen
Ongeacht de gekozen benadering is de beschrijving wat het model leest om te beslissen of het de tool moet aanroepen. Vermeld wanneer deze gebruikt moet worden, wat deze retourneert en het formaat van de parameters:
class SearchProductsParams(BaseModel):
query: str = Field(description="Zoektermen: productnaam of trefwoorden")
category: str = Field(default="all", description="Categorie: elektronica, kleding, voeding, of all")
max_results: int = Field(default=10, ge=1, le=50, description="Maximaal aantal resultaten")
search = tool(
name="search_products",
description=(
"Zoek naar producten in de e-commercecatalogus. Gebruik dit wanneer "
"de gebruiker zoekt naar een product op naam, beschrijving of categorie. "
"Retourneert een lijst met producten inclusief prijs, beschikbaarheid en link."
),
parameters=SearchProductsParams.model_json_schema(),
)
Belangrijkste punten
- Pydantic genereert JSON-schema’s vanuit Python-modellen, inclusief argumentvalidatie
- De xAI SDK bouwt tools met
tool(name=..., description=..., parameters=...) - De SDK voert uw functies niet uit: uw code doet dit en retourneert het resultaat met
tool_result - De SDK heeft geen
@tool-decorator; een custom decorator is mogelijk, maar gaat ten koste van beschrijvingen per parameter - Verfijn uw beschrijvingen: het model leest deze om een tool te kiezen