Pydantic e definizione degli strumenti con l'SDK xAI
In questa pagina
Aggiornato il 3 novembre 2026 sulla base della documentazione Function calling di xAI e della versione
xai-sdk1.21.0: l’SDK non offre né un decoratore@client.tool()né l’esecuzione automatica delle funzioni; devi costruire gli strumenti contool()(usando ad esempio uno schema Pydantic) e restituire i risultati contool_result. Fonte: Function calling.
Semplificare la definizione degli strumenti
Scrivere schemi JSON a mano è verboso e soggetto a errori. Due approcci ti permettono di generare le definizioni degli strumenti direttamente dal tuo codice Python: i modelli Pydantic, che l’SDK xAI trasforma in strumenti tramite la sua funzione tool(), e un semplice decoratore personalizzato che legge le firme delle tue funzioni.
Approccio con Pydantic
Pydantic è una libreria Python che ti consente di definire modelli di dati con validazione automatica. Le API di Grok possono utilizzare questi modelli per generare schemi JSON per gli strumenti.
from pydantic import BaseModel, Field
from typing import Optional
class WeatherParams(BaseModel):
city: str = Field(description="Nome della città")
unit: Optional[str] = Field(
default="celsius",
description="Unità di temperatura",
enum=["celsius", "fahrenheit"]
)
Questo modello Pydantic genera automaticamente lo schema JSON equivalente a quello che avresti scritto manualmente. I vantaggi includono:
- Controllo dei tipi: Python verifica i tipi a runtime
- Validazione: Pydantic valida i dati automaticamente
- Documentazione: le voci
Field(description=...)fungono da documentazione - Riutilizzabilità: lo stesso modello funziona sia per la validazione che per la documentazione delle API
Modelli complessi
Pydantic gestisce strutture nidificate, liste e tipi avanzati:
from typing import List, Optional
from pydantic import BaseModel, Field
class Address(BaseModel):
street: str = Field(description="Numero civico e nome della via")
city: str = Field(description="Città")
zip_code: str = Field(description="Codice postale")
country: str = Field(default="FR", description="Codice paese ISO")
class CreateOrderParams(BaseModel):
product_id: str = Field(description="Identificativo del prodotto")
quantity: int = Field(description="Quantità ordinata", ge=1, le=100)
shipping_address: Address = Field(description="Indirizzo di spedizione")
notes: Optional[str] = Field(
default=None,
description="Istruzioni speciali per la consegna"
)
tags: List[str] = Field(
default=[],
description="Tag per il tracciamento dell'ordine"
)
I vincoli ge (maggiore o uguale) e le (minore o uguale) si traducono in vincoli dello schema JSON che il modello impone.
La funzione tool() dell’SDK xAI
L’SDK xAI non accetta una classe Pydantic così com’è: si aspetta una definizione di strumento, che la sua funzione tool() costruisce a partire da un nome, una descrizione e uno schema JSON. Pydantic fornisce esattamente questo schema tramite model_json_schema():
from xai_sdk.chat import tool
tools = [
tool(
name="get_weather",
description="Ottieni il meteo attuale per una città",
parameters=WeatherParams.model_json_schema(),
),
]
Utilizzo con l’SDK
Dichiari lo strumento quando crei la conversazione. L’SDK non esegue le tue funzioni: quando Grok richiede una chiamata, il tuo codice la esegue, aggiunge il risultato con tool_result, quindi riprende la generazione.
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("Meteo a 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} # tua implementazione
chat.append(tool_result(json.dumps(result)))
response = chat.sample()
print(response.content)
model_validate_json verifica anche che gli argomenti prodotti dal modello corrispondano allo schema: un argomento mancante o un tipo errato solleva un errore prima che la tua funzione venga eseguita.
Un decoratore personalizzato per velocità
L’SDK non fornisce un decoratore @tool. Nulla ti impedisce di scriverne uno in poche righe che legga la firma e il docstring di una funzione:
import inspect
from pydantic import create_model
from xai_sdk.chat import tool
def custom_tool(func):
"""Costruisce la definizione dello strumento xAI dalla firma e dal docstring di una funzione."""
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:
"""Ottieni il meteo attuale per una città (es. Parigi, Lione)."""
return {"temp": 22, "unit": unit, "city": city}
tools = [custom_tool(get_weather)]
Il nome della funzione diventa il nome dello strumento, il primo paragrafo del docstring diventa la descrizione e i parametri senza valori predefiniti diventano obbligatori. Le descrizioni dei parametri, tuttavia, non vengono estratte: per parametri ambigui, torna a un modello Pydantic con Field(description=...).
Confronto tra i tre approcci
| Approccio | Vantaggi | Limiti |
|---|---|---|
| Schema JSON manuale | Controllo totale, nessuna dipendenza | Verboso, i refusi passano inosservati |
Modello Pydantic + tool() | Validazione degli argomenti, descrizioni per campo | Una classe per strumento |
| Decoratore personalizzato | Più conciso | Nessuna descrizione per parametro, codice da mantenere |
Migliori pratiche per le descrizioni
Indipendentemente dall’approccio, la descrizione è ciò che il modello legge per decidere se chiamare lo strumento. Specifica quando usarlo, cosa restituisce e il formato dei parametri:
class SearchProductsParams(BaseModel):
query: str = Field(description="Termini di ricerca: nome del prodotto o parole chiave")
category: str = Field(default="all", description="Categoria: elettronica, abbigliamento, alimentari o tutti")
max_results: int = Field(default=10, ge=1, le=50, description="Numero massimo di risultati")
search = tool(
name="search_products",
description=(
"Cerca prodotti nel catalogo e-commerce. Usa quando "
"l'utente cerca un prodotto per nome, descrizione o categoria. "
"Restituisce un elenco di prodotti con prezzo, disponibilità e link."
),
parameters=SearchProductsParams.model_json_schema(),
)
Punti chiave
- Pydantic genera schemi JSON da modelli Python, con validazione degli argomenti
- L’SDK xAI costruisce strumenti con
tool(name=..., description=..., parameters=...) - L’SDK non esegue le tue funzioni: lo fa il tuo codice, che poi restituisce il risultato con
tool_result - L’SDK non ha un decoratore
@tool; è possibile crearne uno personalizzato, al costo di perdere le descrizioni per parametro - Curare le descrizioni: il modello le legge per scegliere lo strumento