Pydantic und Tool-Definition mit dem xAI SDK

Aktualisiert am 3. November 2026 basierend auf der xAI-Dokumentation zu Function calling und der xai-sdk Version 1.21.0: Das SDK bietet weder einen @client.tool()-Decorator noch eine automatische Funktionsexekution; Sie erstellen Tools mit tool() (unter Verwendung eines Pydantic-Schemas, beispielsweise) und geben Ergebnisse mit tool_result zurück. Quelle: Function calling.

Tool-Definition vereinfachen

Das manuelle Schreiben von JSON-Schemas ist umständlich und fehleranfällig. Zwei Ansätze ermöglichen es Ihnen, Tool-Definitionen aus Ihrem Python-Code zu generieren: Pydantic-Modelle, die das xAI SDK in Tools mit seiner tool()-Funktion umwandelt, und ein einfacher benutzerdefinierter Decorator, der die Funktionszeichenzeichen Ihrer Funktionen ausliest.

Pydantic-Ansatz

Pydantic ist eine Python-Bibliothek, mit der Sie Datenmodelle mit automatischer Validierung definieren können. Die Grok-API kann diese Modelle verwenden, um JSON-Schemas für Tools zu generieren.

from pydantic import BaseModel, Field
from typing import Optional

class WeatherParams(BaseModel):
    city: str = Field(description="Stadtname")
    unit: Optional[str] = Field(
        default="celsius",
        description="Temperatureinheit",
        enum=["celsius", "fahrenheit"]
    )

Dieses Pydantic-Modell generiert automatisch das JSON-Schema, das dem entspricht, was Sie manuell geschrieben hätten. Vorteile sind:

• Typüberprüfung: Python prüft Typen zur Laufzeit
• Validierung: Pydantic validiert Daten automatisch
• Dokumentation: Einträge mit Field(description=...) dienen als Dokumentation
• Wiederverwendbarkeit: Das gleiche Modell funktioniert für Validierung und API-Dokumentation

Komplexe Modelle

Pydantic verarbeitet verschachtelte Strukturen, Listen und erweiterte Typen:

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

class Address(BaseModel):
    street: str = Field(description="Straßennummer und -name")
    city: str = Field(description="Stadt")
    zip_code: str = Field(description="Postleitzahl")
    country: str = Field(default="FR", description="ISO-Ländercode")

class CreateOrderParams(BaseModel):
    product_id: str = Field(description="Produkt-ID")
    quantity: int = Field(description="Bestellmenge", ge=1, le=100)
    shipping_address: Address = Field(description="Versandadresse")
    notes: Optional[str] = Field(
        default=None,
        description="Spezielle Lieferanweisungen"
    )
    tags: List[str] = Field(
        default=[],
        description="Tags zur Bestellverfolgung"
    )

Die Einschränkungen ge (größer oder gleich) und le (kleiner oder gleich) übersetzen sich in JSON-Schema-Einschränkungen, die das Modell durchsetzt.

Die xAI SDK tool()-Funktion

Das xAI SDK nimmt eine Pydantic-Klasse nicht so weiter: Es erwartet eine Tool-Definition, die seine tool()-Funktion aus einem Namen, einer Beschreibung und einem JSON-Schema erstellt. Pydantic liefert genau dieses Schema über model_json_schema():

from xai_sdk.chat import tool

tools = [
    tool(
        name="get_weather",
        description="Aktuelles Wetter für eine Stadt ermitteln",
        parameters=WeatherParams.model_json_schema(),
    ),
]

Verwendung mit dem SDK

Sie deklarieren das Tool beim Erstellen des Gesprächs. Das SDK führt Ihre Funktionen nicht aus: Wenn Grok einen Aufruf anfordert, führt Ihr Code diese aus, fügt das Ergebnis mit tool_result hinzu und setzt die Generierung fort.

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("Wetter 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}  # Ihre Implementierung
        chat.append(tool_result(json.dumps(result)))
    response = chat.sample()

print(response.content)

model_validate_json prüft ebenfalls, ob die vom Modell erzeugten Argumente dem Schema entsprechen: Ein fehlendes Argument oder ein falscher Typ löst einen Fehler aus, bevor Ihre Funktion ausgeführt wird.

Ein benutzerdefinierter Decorator für Geschwindigkeit

Das SDK bietet keinen @tool-Decorator. Es hindert Sie nichts daran, einen in wenigen Zeilen zu schreiben, der das Funktionszeichen und die Docstring einer Funktion ausliest:

import inspect

from pydantic import create_model
from xai_sdk.chat import tool


def custom_tool(func):
    """Erstellt die xAI-Tool-Definition aus dem Funktionszeichen und der Docstring einer Funktion."""
    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:
    """Aktuelles Wetter für eine Stadt ermitteln (z. B. Paris, Lyon)."""
    return {"temp": 22, "unit": unit, "city": city}


tools = [custom_tool(get_weather)]

Der Funktionsname wird zum Tool-Namen, der erste Absatz der Docstring wird zur Beschreibung, und Parameter ohne Standardwerte werden als erforderlich behandelt. Parameterbeschreibungen werden jedoch nicht extrahiert: Bei mehrdeutigen Parametern greifen Sie auf ein Pydantic-Modell mit Field(description=...) zurück.

Vergleich der drei Ansätze

Best Practices für Beschreibungen

Unabhängig vom Ansatz ist die Beschreibung das, was das Modell liest, um zu entscheiden, ob es das Tool aufruft. Nennen Sie an, wann es verwendet werden soll, was es zurückgibt und das Format der Parameter:

class SearchProductsParams(BaseModel):
    query: str = Field(description="Suchbegriffe: Produktname oder Schlüsselwörter")
    category: str = Field(default="all", description="Kategorie: Elektronik, Kleidung, Lebensmittel oder alle")
    max_results: int = Field(default=10, ge=1, le=50, description="Maximale Anzahl der Ergebnisse")


search = tool(
    name="search_products",
    description=(
        "Produkte im E-Commerce-Katalog suchen. Verwenden Sie dies, wenn "
        "der Nutzer nach einem Produkt sucht, basierend auf Name, Beschreibung oder Kategorie. "
        "Gibt eine Liste von Produkten mit Preis, Verfügbarkeit und Link zurück."
    ),
    parameters=SearchProductsParams.model_json_schema(),
)

Kernaussagen

• Pydantic generiert JSON-Schemas aus Python-Modellen mit Argumentvalidierung
• Das xAI SDK erstellt Tools mit tool(name=..., description=..., parameters=...)
• Das SDK führt Ihre Funktionen nicht aus: Ihr Code tut dies und gibt das Ergebnis mit tool_result zurück
• Das SDK hat keinen @tool-Decorator; ein benutzerdefinierter Decorator ist möglich, auf Kosten von Beschreibung pro Parameter
• Polieren Sie Ihre Beschreibungen: Das Modell liest sie, um ein Tool auszuwählen