Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Pydantic i definicija alata s xAI SDK-om

Lekcija 7 od 14 Ažurirano 3. studenoga 2026. Programer
Na ovoj stranici
  1. Pojednostavi definiciju alata
  2. Pydantic pristup
  3. Funkcija tool() u xAI SDK-u
  4. Prilagođeni dekorator za brzinu
  5. Usporedba triju pristupa
  6. Najbolje prakse za opise
  7. Ključne točke

Ažurirano 3. studenog 2026. na temelju xAI dokumentacije o Function callingu i xai-sdk verzije 1.21.0: SDK ne nudi ni dekorator @client.tool() ni automatsko izvršavanje funkcija; alate gradiš pomoću tool() (koristeći, primjerice, Pydantic shemu) i vraćaš rezultate s tool_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

PristupPrednostiOgraničenja
Ručna JSON shemaPotpuna kontrola, bez ovisnostiOpširno, tipfeleri ostaju neotkriveni
Pydantic model + tool()Validacija argumenata, opisi po poljimaJedna klasa po alatu
Prilagođeni dekoratorNajkonciznijeNema 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