Pydantic y definición de herramientas con el SDK de xAI
En esta página
Actualizado el 3 de noviembre de 2026 según la documentación de Llamadas a funciones de xAI y
xai-sdk1.21.0: el SDK no ofrece ni un decorador@client.tool()ni la ejecución automática de funciones; debes construir herramientas contool()(usando un esquema Pydantic, por ejemplo) y devolver los resultados contool_result. Fuente: Llamadas a funciones.
Simplificar la definición de herramientas
Escribir esquemas JSON a mano resulta prolijo y propenso a errores. Existen dos enfoques que te permiten generar definiciones de herramientas directamente desde tu código Python: los modelos Pydantic, que el SDK de xAI transforma en herramientas mediante su función tool(), y un decorador personalizado sencillo que lee las firmas de tus funciones.
Enfoque con Pydantic
Pydantic es una biblioteca de Python que te permite definir modelos de datos con validación automática. La API de Grok puede utilizar estos modelos para generar esquemas JSON destinados a herramientas.
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"]
)
Este modelo Pydantic genera automáticamente el esquema JSON equivalente al que habrías escrito manualmente. Entre sus ventajas se incluyen:
- Comprobación de tipos: Python verifica los tipos en tiempo de ejecución.
- Validación: Pydantic valida los datos automáticamente.
- Documentación: las entradas
Field(description=...)sirven como documentación. - Reutilización: el mismo modelo sirve tanto para la validación como para la documentación de la API.
Modelos complejos
Pydantic gestiona estructuras anidadas, listas y tipos avanzados:
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"
)
Las restricciones ge (mayor o igual) y le (menor o igual) se traducen en restricciones del esquema JSON que el modelo hace cumplir.
La función tool() del SDK de xAI
El SDK de xAI no acepta una clase Pydantic tal cual: espera una definición de herramienta, que su función tool() construye a partir de un nombre, una descripción y un esquema JSON. Pydantic proporciona exactamente este esquema mediante 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(),
),
]
Uso con el SDK
Debes declarar la herramienta al crear la conversación. El SDK no ejecuta tus funciones: cuando Grok solicita una llamada, tu código la ejecuta, añade el resultado con tool_result y luego reanuda la generació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("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 también comprueba que los argumentos producidos por el modelo coincidan con el esquema: si falta un argumento o el tipo es incorrecto, se produce un error antes de que se ejecute tu función.
Un decorador personalizado para ganar velocidad
El SDK no proporciona un decorador @tool. Nada te impide escribir uno en pocas líneas que lea la firma y la docstring de una función:
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)]
El nombre de la función se convierte en el nombre de la herramienta, el primer párrafo de la docstring se convierte en la descripción y los parámetros sin valores predeterminados se vuelven obligatorios. Sin embargo, las descripciones de los parámetros no se extraen: para parámetros ambiguos, vuelve a un modelo Pydantic con Field(description=...).
Comparación de los tres enfoques
| Enfoque | Ventajas | Limitaciones |
|---|---|---|
| Esquema JSON manual | Control total, sin dependencias | Prolijo, los errores tipográficos pasan desapercibidos |
Modelo Pydantic + tool() | Validación de argumentos, descripciones por campo | Una clase por herramienta |
| Decorador personalizado | Más conciso | Sin descripciones por parámetro, código que mantener |
Mejores prácticas para las descripciones
Independientemente del enfoque, la descripción es lo que el modelo lee para decidir si debe llamar a la herramienta. Indica cuándo usarla, qué devuelve y el formato de los parámetros:
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(),
)
Puntos clave
- Pydantic genera esquemas JSON a partir de modelos Python, con validación de argumentos.
- El SDK de xAI construye herramientas con
tool(name=..., description=..., parameters=...). - El SDK no ejecuta tus funciones: tu código lo hace y luego devuelve el resultado con
tool_result. - El SDK no tiene un decorador
@tool; es posible crear uno personalizado, a costa de perder las descripciones por parámetro. - Cuida tus descripciones: el modelo las lee para elegir una herramienta.