Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Pydantic e definizione degli strumenti con l'SDK xAI

Lezione 7 di 14 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Semplificare la definizione degli strumenti
  2. Approccio con Pydantic
  3. La funzione tool() dell’SDK xAI
  4. Un decoratore personalizzato per velocità
  5. Confronto tra i tre approcci
  6. Migliori pratiche per le descrizioni
  7. Punti chiave

Aggiornato il 3 novembre 2026 sulla base della documentazione Function calling di xAI e della versione xai-sdk 1.21.0: l’SDK non offre né un decoratore @client.tool() né l’esecuzione automatica delle funzioni; devi costruire gli strumenti con tool() (usando ad esempio uno schema Pydantic) e restituire i risultati con tool_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

ApproccioVantaggiLimiti
Schema JSON manualeControllo totale, nessuna dipendenzaVerboso, i refusi passano inosservati
Modello Pydantic + tool()Validazione degli argomenti, descrizioni per campoUna classe per strumento
Decoratore personalizzatoPiù concisoNessuna 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