Pydantic och verktygsdefinition med xAI SDK
På denna sida
Uppdaterat den 3 november 2026 baserat på xAI:s dokumentation om Function calling och
xai-sdk1.21.0: SDK:t erbjuder varken en@client.tool()-dekorator eller automatisk funktionskörning; du bygger verktyg medtool()(till exempel med ett Pydantic-schema) och returnerar resultat medtool_result. Källa: Function calling.
Förenkla verktygsdefinition
Att skriva JSON-scheman för hand är omständigt och felbenäget. Två metoder låter dig generera verktygsdefinitioner direkt från din Python-kod: Pydantic-modeller, som xAI SDK:t omvandlar till verktyg med sin tool()-funktion, och en enkel anpassad dekorator som läser dina funktionssignaturer.
Pydantic-metoden
Pydantic är ett Python-bibliotek som låter dig definiera datamodeller med automatisk validering. Grok API:t kan använda dessa modeller för att generera JSON-scheman för verktyg.
from pydantic import BaseModel, Field
from typing import Optional
class WeatherParams(BaseModel):
city: str = Field(description="City name")
unit: Optional[str] = Field(
default="celsius",
description="Temperature unit",
enum=["celsius", "fahrenheit"]
)
Denna Pydantic-modell genererar automatiskt det JSON-schema som du annars hade behövt skriva för hand. Fördelarna inkluderar:
- Typkontroll: Python kontrollerar typer vid körning
- Validering: Pydantic validerar data automatiskt
- Dokumentation:
Field(description=...)-poster fungerar som dokumentation - Återanvändbarhet: samma modell fungerar både för validering och API-dokumentation
Komplexa modeller
Pydantic hanterar nästlade strukturer, listor och avancerade typer:
from typing import List, Optional
from pydantic import BaseModel, Field
class Address(BaseModel):
street: str = Field(description="Street number and name")
city: str = Field(description="City")
zip_code: str = Field(description="ZIP code")
country: str = Field(default="FR", description="ISO country code")
class CreateOrderParams(BaseModel):
product_id: str = Field(description="Product identifier")
quantity: int = Field(description="Ordered quantity", ge=1, le=100)
shipping_address: Address = Field(description="Shipping address")
notes: Optional[str] = Field(
default=None,
description="Special delivery instructions"
)
tags: List[str] = Field(
default=[],
description="Tags for order tracking"
)
Begränsningarna ge (större än eller lika med) och le (mindre än eller lika med) översätts till JSON Schema-begränsningar som modellen tillämpar.
xAI SDK:ts tool()-funktion
xAI SDK:t accepterar inte en Pydantic-klass som den är: det förväntar sig en verktygsdefinition, vilket dess tool()-funktion bygger utifrån ett namn, en beskrivning och ett JSON-schema. Pydantic tillhandahåller exakt detta schema via model_json_schema():
from xai_sdk.chat import tool
tools = [
tool(
name="get_weather",
description="Get the current weather for a city",
parameters=WeatherParams.model_json_schema(),
),
]
Användning med SDK:t
Du deklarerar verktyget när du skapar konversationen. SDK:t kör inte dina funktioner åt dig: när Grok begär ett anrop exekuterar din kod funktionen, lägger till resultatet med tool_result och återupptar sedan genereringen.
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("Weather 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} # your implementation
chat.append(tool_result(json.dumps(result)))
response = chat.sample()
print(response.content)
model_validate_json kontrollerar också att argumenten som modellen producerar matchar schemat: ett saknat argument eller felaktig typ utlöser ett fel innan din funktion körs.
En anpassad dekorator för snabbhet
SDK:t tillhandahåller ingen @tool-dekorator. Inget hindrar dig från att skriva en egen på några rader som läser en funktions signatur och docstring:
import inspect
from pydantic import create_model
from xai_sdk.chat import tool
def custom_tool(func):
"""Builds the xAI tool definition from a function's signature and docstring."""
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:
"""Get the current weather for a city (e.g., Paris, Lyon)."""
return {"temp": 22, "unit": unit, "city": city}
tools = [custom_tool(get_weather)]
Funktionsnamnet blir verktygets namn, det första stycket i docstringen blir beskrivningen och parametrar utan standardvärden blir obligatoriska. Parameterbeskrivningar extraheras dock inte: för tvetydiga parametrar bör du återgå till en Pydantic-modell med Field(description=...).
Jämförelse av de tre metoderna
| Metod | Fördelar | Begränsningar |
|---|---|---|
| Manuellt JSON-schema | Total kontroll, inga beroenden | Omständigt, stavfel upptäcks inte |
Pydantic-modell + tool() | Argumentvalidering, beskrivningar per fält | En klass per verktyg |
| Anpassad dekorator | Mest koncis | Inga beskrivningar per parameter, kod att underhålla |
Bästa praxis för beskrivningar
Oavsett vilken metod du väljer är det beskrivningen modellen läser för att avgöra om den ska anropa verktyget. Ange när det ska användas, vad det returnerar och formatet på parametrarna:
class SearchProductsParams(BaseModel):
query: str = Field(description="Search terms: product name or keywords")
category: str = Field(default="all", description="Category: electronics, clothing, food, or all")
max_results: int = Field(default=10, ge=1, le=50, description="Maximum number of results")
search = tool(
name="search_products",
description=(
"Search for products in the e-commerce catalog. Use when "
"the user looks for a product by name, description, or category. "
"Returns a list of products with price, availability, and link."
),
parameters=SearchProductsParams.model_json_schema(),
)
Viktiga punkter
- Pydantic genererar JSON-scheman från Python-modeller med argumentvalidering
- xAI SDK:t bygger verktyg med
tool(name=..., description=..., parameters=...) - SDK:t kör inte dina funktioner: din kod gör det och returnerar sedan resultatet med
tool_result - SDK:t har ingen
@tool-dekorator; en anpassad dekorator är möjlig, men då försvinner beskrivningar per parameter - Förfina dina beskrivningar: modellen läser dem för att välja rätt verktyg