Pydantic a definícia nástrojov pomocou xAI SDK
Na tejto strane
Aktualizované 3. novembra 2026 na základe dokumentácie xAI Function calling a verzie
xai-sdk1.21.0: SDK neponúka ani dekorátor@client.tool(), ani automatické spúšťanie funkcií; nástroje buduješ pomocoutool()(napríklad s schémou Pydantic) a výsledky vraciaš ceztool_result. Zdroj: Function calling.
Zjednodušenie definície nástrojov
Ručné písanie schém JSON je zdĺhavé a náchylné na chyby. Existujú dva prístupy, ktoré ti umožnia generovať definície nástrojov priamo z kódu Python: modely Pydantic, ktoré xAI SDK transformuje na nástroje pomocou funkcie tool(), a jednoduchý vlastný dekorátor, ktorý číta signatúry tvojich funkcií.
Prístup s Pydantic
Pydantic je knižnica pre Python, ktorá ti umožňuje definovať dátové modely s automatickou validáciou. API Grok dokáže tieto modely využiť na generovanie schém JSON pre nástroje.
from pydantic import BaseModel, Field
from typing import Optional
class WeatherParams(BaseModel):
city: str = Field(description="Názov mesta")
unit: Optional[str] = Field(
default="celsius",
description="Jednotka teploty",
enum=["celsius", "fahrenheit"]
)
Tento model Pydantic automaticky vygeneruje ekvivalent schémy JSON, ktorú by si inak napísal ručne. Medzi výhody patrí:
- Kontrola typov: Python kontroluje typy počas behu
- Validácia: Pydantic automaticky overuje údaje
- Dokumentácia: Položky
Field(description=...)slúžia ako dokumentácia - Opätovné použitie: Ten istý model funguje pre validáciu aj dokumentáciu API
Zložité modely
Pydantic zvláda vnorené štruktúry, zoznamy a pokročilé typy:
from typing import List, Optional
from pydantic import BaseModel, Field
class Address(BaseModel):
street: str = Field(description="Číslo a názov ulice")
city: str = Field(description="Mesto")
zip_code: str = Field(description="PSČ")
country: str = Field(default="FR", description="Kód krajiny ISO")
class CreateOrderParams(BaseModel):
product_id: str = Field(description="Identifikátor produktu")
quantity: int = Field(description="Objednané množstvo", ge=1, le=100)
shipping_address: Address = Field(description="Adresa doručenia")
notes: Optional[str] = Field(
default=None,
description="Špeciálne pokyny pre doručenie"
)
tags: List[str] = Field(
default=[],
description="Tagy na sledovanie objednávky"
)
Obmedzenia ge (väčšie alebo rovné) a le (menšie alebo rovné) sa prekladajú do obmedzení schémy JSON, ktoré model presadzuje.
Funkcia tool() v xAI SDK
xAI SDK neprijíma triedu Pydantic tak, ako je: očakáva definíciu nástroja, ktorú jeho funkcia tool() zostaví z názvu, popisu a schémy JSON. Pydantic poskytuje presne túto schému prostredníctvom model_json_schema():
from xai_sdk.chat import tool
tools = [
tool(
name="get_weather",
description="Získať aktuálne počasie pre mesto",
parameters=WeatherParams.model_json_schema(),
),
]
Použitie so SDK
Nástroj deklaruješ pri vytváraní konverzácie. SDK nespúšťa tvoje funkcie: keď Grok požiada o volanie, tvoj kód ho vykoná, pridá výsledok pomocou tool_result a potom obnoví generovanie.
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("Počasie v 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} # tvoja implementácia
chat.append(tool_result(json.dumps(result)))
response = chat.sample()
print(response.content)
model_validate_json tiež kontroluje, či argumenty vygenerované modelom zodpovedajú schéme: chýbajúci argument alebo nesprávny typ vyvolá chybu ešte pred spustením tvojej funkcie.
Vlastný dekorátor pre rýchlosť
SDK neposkytuje dekorátor @tool. Nič ti však nebráni napísať si ho v niekoľkých riadkoch tak, aby čítal signatúru funkcie a jej docstring:
import inspect
from pydantic import create_model
from xai_sdk.chat import tool
def custom_tool(func):
"""Vytvorí definíciu nástroja xAI zo signatúry funkcie a docstringu."""
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:
"""Získať aktuálne počasie pre mesto (napr. Paríž, Lyon)."""
return {"temp": 22, "unit": unit, "city": city}
tools = [custom_tool(get_weather)]
Názov funkcie sa stane názvom nástroja, prvý odsek docstringu sa stane popisom a parametre bez predvolených hodnôt sa stanú povinnými. Popisy parametrov sa však neextrahujú: pri nejednoznačných parametroch sa vráť k modelu Pydantic s Field(description=...).
Porovnanie troch prístupov
| Prístup | Výhody | Obmedzenia |
|---|---|---|
| Ručná schéma JSON | Úplná kontrola, žiadne závislosti | Zdĺhavé, preklepy zostanú neodhalené |
Model Pydantic + tool() | Validácia argumentov, popisy pre jednotlivé polia | Jedna trieda na nástroj |
| Vlastný dekorátor | Najstručnejší | Žiadne popisy parametrov, kód na údržbu |
Osvedčené postupy pre popisy
Bez ohľadu na zvolený prístup je popis tým, čo model číta, aby sa rozhodol, či nástroj zavolať. Uveď, kedy ho použiť, čo vracia a aký je formát parametrov:
class SearchProductsParams(BaseModel):
query: str = Field(description="Vyhľadávacie výrazy: názov produktu alebo kľúčové slová")
category: str = Field(default="all", description="Kategória: elektronika, oblečenie, potraviny alebo all")
max_results: int = Field(default=10, ge=1, le=50, description="Maximálny počet výsledkov")
search = tool(
name="search_products",
description=(
"Vyhľadať produkty v e-commerce katalógu. Použi, keď "
"používateľ hľadá produkt podľa názvu, popisu alebo kategórie. "
"Vráti zoznam produktov s cenou, dostupnosťou a odkazom."
),
parameters=SearchProductsParams.model_json_schema(),
)
Kľúčové poznatky
- Pydantic generuje schémy JSON z modelov Python s validáciou argumentov
- xAI SDK buduje nástroje pomocou
tool(name=..., description=..., parameters=...) - SDK nespúšťa tvoje funkcie: robí to tvoj kód a následne vráti výsledok cez
tool_result - SDK nemá dekorátor
@tool; vlastný dekorátor je možný, ale za cenu absencie popisov jednotlivých parametrov - Vylepši svoje popisy: model ich číta, aby si vybral nástroj