Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Pydantic a definice nástrojů pomocí xAI SDK

Lekce 7 z 14 Aktualizováno 3. listopadu 2026 Vývojář
Na této stránce
  1. Zjednodušení definice nástrojů
  2. Přístup s Pydantic
  3. Funkce tool() v xAI SDK
  4. Vlastní dekorátor pro rychlost
  5. Porovnání tří přístupů
  6. Osvědčené postupy pro popisy
  7. Klíčové poznatky

Aktualizováno 3. listopadu 2026 na základě dokumentace xAI Function calling a verze xai-sdk 1.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ím tool_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řístupVýhodyNevýhody
Ruční schéma JSONÚplná kontrola, žádné závislostiUkecané, překlepy zůstanou neodhaleny
Model Pydantic + tool()Validace argumentů, popisy pro každé poleJedna třída na nástroj
Vlastní dekorátorNejstruč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