Pydantic et décorateur @tool

Simplifier la définition des outils

Écrire des schémas JSON à la main est verbeux et sujet aux erreurs. Le SDK xAI propose deux approches pour générer automatiquement les définitions d’outils à partir de votre code Python : les modèles Pydantic et le décorateur @tool.

Approche Pydantic

Pydantic est une bibliothèque Python qui permet de définir des modèles de données avec validation automatique. L’API Grok peut utiliser ces modèles pour générer les schémas JSON des outils.

from pydantic import BaseModel, Field
from typing import Optional

class WeatherParams(BaseModel):
    city: str = Field(description="Nom de la ville")
    unit: Optional[str] = Field(
        default="celsius",
        description="Unité de température",
        enum=["celsius", "fahrenheit"]
    )

Ce modèle Pydantic génère automatiquement le schéma JSON équivalent à ce que vous auriez écrit manuellement. Les avantages :

• Type checking : Python vérifie les types à l’exécution
• Validation : Pydantic valide les données automatiquement
• Documentation : les Field(description=...) servent de documentation
• Réutilisabilité : le même modèle sert pour la validation et la documentation API

Modèles complexes

Pydantic gère les structures imbriquées, les listes et les types avancés :

from typing import List, Optional
from pydantic import BaseModel, Field

class Address(BaseModel):
    street: str = Field(description="Numéro et nom de rue")
    city: str = Field(description="Ville")
    zip_code: str = Field(description="Code postal")
    country: str = Field(default="FR", description="Code pays ISO")

class CreateOrderParams(BaseModel):
    product_id: str = Field(description="Identifiant du produit")
    quantity: int = Field(description="Quantité commandée", ge=1, le=100)
    shipping_address: Address = Field(description="Adresse de livraison")
    notes: Optional[str] = Field(
        default=None,
        description="Instructions spéciales de livraison"
    )
    tags: List[str] = Field(
        default=[],
        description="Tags pour le suivi de commande"
    )

Les contraintes ge (greater or equal) et le (less or equal) sont traduites en contraintes JSON Schema que le modèle respecte.

Le décorateur @tool du SDK xAI

Le SDK xAI offre une approche encore plus concise avec le décorateur @tool :

from xai_sdk import Client

client = Client(api_key="votre-cle-api")

@client.tool()
def get_weather(city: str, unit: str = "celsius") -> dict:
    """Obtenir la météo actuelle d'une ville.

    Args:
        city: Nom de la ville (ex: Paris, Lyon)
        unit: Unité de température (celsius ou fahrenheit)
    """
    # Votre implémentation ici
    return {"temp": 22, "unit": unit, "city": city}

Le décorateur extrait automatiquement :

• Le nom de la fonction → get_weather
• La description → la docstring
• Les paramètres → les arguments typés de la fonction
• Les paramètres requis → ceux sans valeur par défaut

C’est l’approche la plus Pythonique et la moins verbeuse.

Utilisation avec le SDK

response = client.chat.create(
    model="grok-3",
    messages=[
        {"role": "user", "content": "Météo à Bordeaux ?"}
    ],
    tools=[get_weather]  # Passer directement la fonction décorée
)

Le SDK gère tout le cycle : envoi de la définition, réception du tool_call, exécution de la fonction, renvoi du résultat.

Comparaison des trois approches

Bonnes pratiques pour les docstrings

Si vous utilisez le décorateur @tool, la qualité de votre docstring est critique :

@client.tool()
def search_products(
    query: str,
    category: str = "all",
    max_results: int = 10
) -> list:
    """Rechercher des produits dans le catalogue e-commerce.

    Utilisez cette fonction quand l'utilisateur cherche un produit
    par nom, description ou catégorie. Retourne une liste de produits
    avec prix, disponibilité et lien.

    Args:
        query: Termes de recherche (nom du produit ou mots-clés)
        category: Filtrer par catégorie (electronics, clothing, food, all)
        max_results: Nombre maximum de résultats (1-50)
    """
    pass

La première ligne de la docstring devient la description principale. Les lignes suivantes enrichissent le contexte. Les descriptions des Args deviennent les descriptions des paramètres.

Points clés à retenir

• Pydantic génère automatiquement les schémas JSON à partir de modèles Python
• Le décorateur @tool du SDK xAI est l’approche la plus concise
• Les docstrings servent de descriptions pour le modèle — soignez-les
• Utilisez Field(description=...) en Pydantic pour documenter chaque paramètre
• Les trois approches (JSON, Pydantic, @tool) produisent le même résultat côté API
• Choisissez selon votre besoin : contrôle total (JSON), validation (Pydantic) ou rapidité (@tool)