Pydantic i definicja narzędzi z xAI SDK
Na tej stronie
Zaktualizowano 3 listopada 2026 r. na podstawie dokumentacji Function calling od xAI oraz
xai-sdkw wersji 1.21.0: SDK nie oferuje ani dekoratora@client.tool(), ani automatycznego wykonywania funkcji; narzędzia budujesz za pomocątool()(korzystając np. ze schematu Pydantic) i zwracasz wyniki przeztool_result. Źródło: Function calling.
Uproszczenie definicji narzędzi
Ręczne pisanie schematów JSON jest rozwlekłe i podatne na błędy. Dwa podejścia pozwalają generować definicje narzędzi bezpośrednio z kodu Pythona: modele Pydantic, które xAI SDK przekształca w narzędzia za pomocą funkcji tool(), oraz prosty własny dekorator odczytujący sygnatury Twoich funkcji.
Podejście z Pydantic
Pydantic to biblioteka Pythona umożliwiająca definiowanie modeli danych z automatyczną walidacją. API Grok może wykorzystać te modele do generowania schematów JSON dla narzędzi.
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"]
)
Ten model Pydantic automatycznie generuje schemat JSON odpowiadający temu, co napisałbyś ręcznie. Korzyści obejmują:
- Sprawdzanie typów: Python weryfikuje typy w czasie wykonywania
- Walidacja: Pydantic automatycznie waliduje dane
- Dokumentacja: wpisy
Field(description=...)służą jako dokumentacja - Wielokrotne użycie: ten sam model działa zarówno do walidacji, jak i dokumentacji API
Złożone modele
Pydantic obsługuje struktury zagnieżdżone, listy i zaawansowane typy:
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"
)
Ograniczenia ge (większe lub równe) i le (mniejsze lub równe) przekładają się na ograniczenia schematu JSON, które model egzekwuje.
Funkcja tool() w xAI SDK
xAI SDK nie przyjmuje klasy Pydantic takiej, jaka jest: oczekuje definicji narzędzia, którą jego funkcja tool() buduje na podstawie nazwy, opisu i schematu JSON. Pydantic dostarcza dokładnie ten schemat poprzez 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(),
),
]
Użycie z SDK
Narzędzie deklarujesz podczas tworzenia konwersacji. SDK nie wykonuje Twoich funkcji: gdy Grok żąda wywołania, Twój kod je wykonuje, dodaje wynik za pomocą tool_result, a następnie wznawia generowanie.
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 sprawdza również, czy argumenty wygenerowane przez model są zgodne ze schematem: brakujący argument lub błędny typ spowodują błąd przed uruchomieniem Twojej funkcji.
Własny dekorator dla szybkości
SDK nie udostępnia dekoratora @tool. Nic jednak nie stoi na przeszkodzie, abyś napisał go w kilku liniach, odczytując sygnaturę funkcji i jej 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)]
Nazwa funkcji staje się nazwą narzędzia, pierwszy akapit docstringu staje się opisem, a parametry bez wartości domyślnych stają się wymagane. Opisy parametrów nie są jednak ekstrahowane: w przypadku niejednoznacznych parametrów wróć do modelu Pydantic z Field(description=...).
Porównanie trzech podejść
| Podejście | Korzyści | Ograniczenia |
|---|---|---|
| Ręczny schemat JSON | Pełna kontrola, brak zależności | Rozwlekłe, literówki pozostają niewykryte |
Model Pydantic + tool() | Walidacja argumentów, opisy dla każdego pola | Jedna klasa na narzędzie |
| Własny dekorator | Najbardziej zwięzłe | Brak opisów dla poszczególnych parametrów, kod do utrzymania |
Najlepsze praktyki dotyczące opisów
Niezależnie od wybranego podejścia, to opis jest tym, co model odczytuje, aby zdecydować, czy wywołać narzędzie. Określ, kiedy go użyć, co zwraca i w jakim formacie mają być parametry:
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(),
)
Kluczowe wnioski
- Pydantic generuje schematy JSON z modeli Pythona, zapewniając walidację argumentów
- xAI SDK buduje narzędzia za pomocą
tool(name=..., description=..., parameters=...) - SDK nie wykonuje Twoich funkcji: robisz to w swoim kodzie, a następnie zwracasz wynik przez
tool_result - SDK nie posiada dekoratora
@tool; własny dekorator jest możliwy, ale kosztem utraty opisów dla poszczególnych parametrów - Dopracuj swoje opisy: model odczytuje je, aby wybrać odpowiednie narzędzie