Przejdź do głównej treści
Polski— Wybierz język
Menu

Pydantic i definicja narzędzi z xAI SDK

Lekcja 7 z 14 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Uproszczenie definicji narzędzi
  2. Podejście z Pydantic
  3. Funkcja tool() w xAI SDK
  4. Własny dekorator dla szybkości
  5. Porównanie trzech podejść
  6. Najlepsze praktyki dotyczące opisów
  7. Kluczowe wnioski

Zaktualizowano 3 listopada 2026 r. na podstawie dokumentacji Function calling od xAI oraz xai-sdk w wersji 1.21.0: SDK nie oferuje ani dekoratora @client.tool(), ani automatycznego wykonywania funkcji; narzędzia budujesz za pomocą tool() (korzystając np. ze schematu Pydantic) i zwracasz wyniki przez tool_result. Źródło: Function calling.

Uproszczenie definicji narzędzi

Ręczne pisanie schematów JSON jest rozwlekłe i podatne na błędy. Dwa podejścia pozwalają generować definicje narzędzi bezpośrednio z kodu Pythona: modele Pydantic, które xAI SDK przekształca w narzędzia za pomocą funkcji tool(), oraz prosty własny dekorator odczytujący sygnatury Twoich funkcji.

Podejście z Pydantic

Pydantic to biblioteka Pythona umożliwiająca definiowanie modeli danych z automatyczną walidacją. API Grok może wykorzystać te modele do generowania schematów JSON dla narzędzi.

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"]
    )

Ten model Pydantic automatycznie generuje schemat JSON odpowiadający temu, co napisałbyś ręcznie. Korzyści obejmują:

  • Sprawdzanie typów: Python weryfikuje typy w czasie wykonywania
  • Walidacja: Pydantic automatycznie waliduje dane
  • Dokumentacja: wpisy Field(description=...) służą jako dokumentacja
  • Wielokrotne użycie: ten sam model działa zarówno do walidacji, jak i dokumentacji API

Złożone modele

Pydantic obsługuje struktury zagnieżdżone, listy i zaawansowane typy:

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"
    )

Ograniczenia ge (większe lub równe) i le (mniejsze lub równe) przekładają się na ograniczenia schematu JSON, które model egzekwuje.

Funkcja tool() w xAI SDK

xAI SDK nie przyjmuje klasy Pydantic takiej, jaka jest: oczekuje definicji narzędzia, którą jego funkcja tool() buduje na podstawie nazwy, opisu i schematu JSON. Pydantic dostarcza dokładnie ten schemat poprzez 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(),
    ),
]

Użycie z SDK

Narzędzie deklarujesz podczas tworzenia konwersacji. SDK nie wykonuje Twoich funkcji: gdy Grok żąda wywołania, Twój kod je wykonuje, dodaje wynik za pomocą tool_result, a następnie wznawia generowanie.

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 sprawdza również, czy argumenty wygenerowane przez model są zgodne ze schematem: brakujący argument lub błędny typ spowodują błąd przed uruchomieniem Twojej funkcji.

Własny dekorator dla szybkości

SDK nie udostępnia dekoratora @tool. Nic jednak nie stoi na przeszkodzie, abyś napisał go w kilku liniach, odczytując sygnaturę funkcji i jej 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)]

Nazwa funkcji staje się nazwą narzędzia, pierwszy akapit docstringu staje się opisem, a parametry bez wartości domyślnych stają się wymagane. Opisy parametrów nie są jednak ekstrahowane: w przypadku niejednoznacznych parametrów wróć do modelu Pydantic z Field(description=...).

Porównanie trzech podejść

PodejścieKorzyściOgraniczenia
Ręczny schemat JSONPełna kontrola, brak zależnościRozwlekłe, literówki pozostają niewykryte
Model Pydantic + tool()Walidacja argumentów, opisy dla każdego polaJedna klasa na narzędzie
Własny dekoratorNajbardziej zwięzłeBrak opisów dla poszczególnych parametrów, kod do utrzymania

Najlepsze praktyki dotyczące opisów

Niezależnie od wybranego podejścia, to opis jest tym, co model odczytuje, aby zdecydować, czy wywołać narzędzie. Określ, kiedy go użyć, co zwraca i w jakim formacie mają być parametry:

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(),
)

Kluczowe wnioski

  • Pydantic generuje schematy JSON z modeli Pythona, zapewniając walidację argumentów
  • xAI SDK buduje narzędzia za pomocą tool(name=..., description=..., parameters=...)
  • SDK nie wykonuje Twoich funkcji: robisz to w swoim kodzie, a następnie zwracasz wynik przez tool_result
  • SDK nie posiada dekoratora @tool; własny dekorator jest możliwy, ale kosztem utraty opisów dla poszczególnych parametrów
  • Dopracuj swoje opisy: model odczytuje je, aby wybrać odpowiednie narzędzie