Pydantic i definicija alata s xAI SDK-om
Na ovoj stranici
Ažurirano 3. studenog 2026. na temelju xAI dokumentacije o Function callingu i
xai-sdkverzije 1.21.0: SDK ne nudi ni dekorator@client.tool()ni automatsko izvršavanje funkcija; alate gradiš pomoćutool()(koristeći, primjerice, Pydantic shemu) i vraćaš rezultate stool_result. Izvor: Function calling.
Pojednostavi definiciju alata
Ručno pisanje JSON shema je opširno i podložno greškama. Dva pristupa omogućuju ti generiranje definicija alata izravno iz Python koda: Pydantic modeli, koje xAI SDK pretvara u alate svojom funkcijom tool(), i jednostavan prilagođeni dekorator koji čita potpise tvojih funkcija.
Pydantic pristup
Pydantic je Python biblioteka koja ti omogućuje definiranje podatkovnih modela s automatskom validacijom. Grok API može koristiti te modele za generiranje JSON shema za alate.
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"]
)
Ovaj Pydantic model automatski generira JSON shemu ekvivalentnu onoj koju bi napisao ručno. Prednosti uključuju:
- Provjera tipova: Python provjerava tipove u vrijeme izvršavanja
- Validacija: Pydantic automatski validira podatke
- Dokumentacija: unosi
Field(description=...)služe kao dokumentacija - Ponovna upotreba: isti model radi i za validaciju i za API dokumentaciju
Složeni modeli
Pydantic rukuje ugniježđenim strukturama, listama i naprednim tipovima:
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"
)
Ograničenja ge (veće ili jednako) i le (manje ili jednako) prevode se u ograničenja JSON sheme koja model nameće.
Funkcija tool() u xAI SDK-u
xAI SDK ne prihvaća Pydantic klasu kakva jest: očekuje definiciju alata, koju njegova funkcija tool() gradi od imena, opisa i JSON sheme. Pydantic osigurava upravo tu shemu putem 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(),
),
]
Korištenje sa SDK-om
Alat deklariraš prilikom stvaranja razgovora. SDK ne izvršava tvoje funkcije: kada Grok zatraži poziv, tvoj kod ga izvršava, dodaje rezultat s tool_result, a zatim nastavlja generiranje.
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 također provjerava odgovaraju li argumenti koje je proizveo model shemi: nedostajući argument ili pogrešan tip podižu grešku prije nego što se tvoja funkcija pokrene.
Prilagođeni dekorator za brzinu
SDK ne nudi dekorator @tool. Ništa te ne sprječava da napišeš vlastiti u nekoliko redaka koji čita potpis funkcije i 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)]
Ime funkcije postaje ime alata, prvi odlomak docstringa postaje opis, a parametri bez zadanih vrijednosti postaju obavezni. Opisi parametara se, međutim, ne izvlače: za dvosmislene parametre vrati se na Pydantic model s Field(description=...).
Usporedba triju pristupa
| Pristup | Prednosti | Ograničenja |
|---|---|---|
| Ručna JSON shema | Potpuna kontrola, bez ovisnosti | Opširno, tipfeleri ostaju neotkriveni |
Pydantic model + tool() | Validacija argumenata, opisi po poljima | Jedna klasa po alatu |
| Prilagođeni dekorator | Najkonciznije | Nema opisa po parametrima, kod za održavanje |
Najbolje prakse za opise
Bez obzira na pristup, opis je ono što model čita kako bi odlučio hoće li pozvati alat. Navedi kada ga koristiti, što vraća i format parametara:
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(),
)
Ključne točke
- Pydantic generira JSON sheme iz Python modela, s validacijom argumenata
- xAI SDK gradi alate s
tool(name=..., description=..., parameters=...) - SDK ne izvršava tvoje funkcije: tvoj kod to radi, a zatim vraća rezultat s
tool_result - SDK nema dekorator
@tool; prilagođeni dekorator je moguć, uz cijenu gubitka opisa po parametrima - Usavrši svoje opise: model ih čita kako bi odabrao alat