Ir al contenido principal
Español— Elegir un idioma
Menú

Pydantic y definición de herramientas con el SDK de xAI

Lección 7 de 14 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Simplificar la definición de herramientas
  2. Enfoque con Pydantic
  3. La función tool() del SDK de xAI
  4. Un decorador personalizado para ganar velocidad
  5. Comparación de los tres enfoques
  6. Mejores prácticas para las descripciones
  7. Puntos clave

Actualizado el 3 de noviembre de 2026 según la documentación de Llamadas a funciones de xAI y xai-sdk 1.21.0: el SDK no ofrece ni un decorador @client.tool() ni la ejecución automática de funciones; debes construir herramientas con tool() (usando un esquema Pydantic, por ejemplo) y devolver los resultados con tool_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

EnfoqueVentajasLimitaciones
Esquema JSON manualControl total, sin dependenciasProlijo, los errores tipográficos pasan desapercibidos
Modelo Pydantic + tool()Validación de argumentos, descripciones por campoUna clase por herramienta
Decorador personalizadoMás concisoSin 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.