Pydantic a definice nástrojů pomocí xAI SDK
Na této stránce
Aktualizováno 3. listopadu 2026 na základě dokumentace xAI Function calling a verze
xai-sdk1.21.0: SDK nenabízí ani dekorátor@client.tool(), ani automatické spouštění funkcí; nástroje vytváříš pomocítool()(například s schématem Pydantic) a výsledky vracíš prostřednictvímtool_result. Zdroj: Function calling.
Zjednodušení definice nástrojů
Ruční psaní schémat JSON je zdlouhavé a náchylné k chybám. Existují dva přístupy, které ti umožní generovat definice nástrojů přímo z kódu Pythonu: modely Pydantic, které xAI SDK transformuje na nástroje pomocí funkce tool(), a jednoduchý vlastní dekorátor, který čte signatury tvých funkcí.
Přístup s Pydantic
Pydantic je knihovna pro Python, která ti umožňuje definovat datové modely s automatickou validací. API Grok dokáže tyto modely využít k generování schémat JSON pro nástroje.
from pydantic import BaseModel, Field
from typing import Optional
class WeatherParams(BaseModel):
city: str = Field(description="Název města")
unit: Optional[str] = Field(
default="celsius",
description="Jednotka teploty",
enum=["celsius", "fahrenheit"]
)
Tento model Pydantic automaticky vygeneruje ekvivalent schématu JSON, které bys musel jinak napsat ručně. Mezi výhody patří:
- Kontrola typů: Python kontroluje typy za běhu
- Validace: Pydantic automaticky validuje data
- Dokumentace: Položky
Field(description=...)slouží jako dokumentace - Opakované použití: Stejný model funguje pro validaci i dokumentaci API
Složité modely
Pydantic zvládá vnořené struktury, seznamy a pokročilé typy:
from typing import List, Optional
from pydantic import BaseModel, Field
class Address(BaseModel):
street: str = Field(description="Číslo popisné a název ulice")
city: str = Field(description="Město")
zip_code: str = Field(description="PSČ")
country: str = Field(default="FR", description="Kód země podle ISO")
class CreateOrderParams(BaseModel):
product_id: str = Field(description="Identifikátor produktu")
quantity: int = Field(description="Objednané množství", ge=1, le=100)
shipping_address: Address = Field(description="Adresa pro doručení")
notes: Optional[str] = Field(
default=None,
description="Speciální pokyny pro doručení"
)
tags: List[str] = Field(
default=[],
description="Štítky pro sledování objednávky"
)
Omezení ge (větší nebo rovno) a le (menší nebo rovno) se převedou na omezení ve schématu JSON, která model vynucuje.
Funkce tool() v xAI SDK
xAI SDK nepřijímá třídu Pydantic tak, jak je: očekává definici nástroje, kterou jeho funkce tool() sestaví z názvu, popisu a schématu JSON. Pydantic poskytuje přesně toto schéma prostřednictvím model_json_schema():
from xai_sdk.chat import tool
tools = [
tool(
name="get_weather",
description="Získat aktuální počasí pro město",
parameters=WeatherParams.model_json_schema(),
),
]
Použití se SDK
Nástroj deklaruješ při vytváření konverzace. SDK nespouští tvé funkce: když Grok požádá o volání, tvůj kód ji provede, přidá výsledek pomocí tool_result a poté obnoví generování.
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časí 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} # tvá implementace
chat.append(tool_result(json.dumps(result)))
response = chat.sample()
print(response.content)
model_validate_json také kontroluje, zda argumenty vygenerované modelem odpovídají schématu: chybějící argument nebo špatný typ vyvolá chybu ještě před spuštěním tvé funkce.
Vlastní dekorátor pro rychlost
SDK neposkytuje dekorátor @tool. Nic ti však nebrání napsat si vlastní během několika řádků, který přečte signaturu funkce a její docstring:
import inspect
from pydantic import create_model
from xai_sdk.chat import tool
def custom_tool(func):
"""Vytvoří definici nástroje xAI ze signatury funkce 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ískat aktuální počasí pro město (např. Paříž, Lyon)."""
return {"temp": 22, "unit": unit, "city": city}
tools = [custom_tool(get_weather)]
Název funkce se stane názvem nástroje, první odstavec docstringu se stane popisem a parametry bez výchozích hodnot se stanou povinnými. Popisy parametrů se však neextrahují: u nejednoznačných parametrů se vrať k modelu Pydantic s Field(description=...).
Porovnání tří přístupů
| Přístup | Výhody | Nevýhody |
|---|---|---|
| Ruční schéma JSON | Úplná kontrola, žádné závislosti | Ukecané, překlepy zůstanou neodhaleny |
Model Pydantic + tool() | Validace argumentů, popisy pro každé pole | Jedna třída na nástroj |
| Vlastní dekorátor | Nejstručnější | Žádné popisy pro jednotlivé parametry, kód nutno udržovat |
Osvědčené postupy pro popisy
Bez ohledu na zvolený přístup je popis tím, co model čte, aby se rozhodl, zda nástroj zavolat. Uveď, kdy jej použít, co vrací a jaký je formát parametrů:
class SearchProductsParams(BaseModel):
query: str = Field(description="Vyhledávací výrazy: název produktu nebo klíčová slova")
category: str = Field(default="all", description="Kategorie: elektronika, oblečení, potraviny nebo všechny")
max_results: int = Field(default=10, ge=1, le=50, description="Maximální počet výsledků")
search = tool(
name="search_products",
description=(
"Vyhledat produkty v e-commerce katalogu. Použij, když "
"uživatel hledá produkt podle názvu, popisu nebo kategorie. "
"Vrací seznam produktů s cenou, dostupností a odkazem."
),
parameters=SearchProductsParams.model_json_schema(),
)
Klíčové poznatky
- Pydantic generuje schémata JSON z modelů Pythonu včetně validace argumentů
- xAI SDK vytváří nástroje pomocí
tool(name=..., description=..., parameters=...) - SDK nespouští tvé funkce: děláš to ty ve svém kódu a výsledek vracíš přes
tool_result - SDK nemá dekorátor
@tool; vlastní dekorátor je možný, ale za cenu absence popisů jednotlivých parametrů - Vylepši své popisy: model je čte, aby si vybral nástroj