Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Pydantic e Definição de Ferramentas com o xAI SDK

Aula 7 de 14 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Simplifique a Definição de Ferramentas
  2. Abordagem com Pydantic
  3. A Função tool() do xAI SDK
  4. Um Decorador Personalizado para Rapidez
  5. Comparação das Três Abordagens
  6. Boas Práticas para Descrições
  7. Pontos-chave

Atualizado em 3 de novembro de 2026 com base na documentação de Function calling da xAI e na versão xai-sdk 1.21.0: o SDK não oferece nem um decorador @client.tool() nem execução automática de funções; você constrói ferramentas com tool() (usando um esquema Pydantic, por exemplo) e devolve os resultados com tool_result. Fonte: Function calling.

Simplifique a Definição de Ferramentas

Escrever esquemas JSON à mão é prolixo e propenso a erros. Duas abordagens permitem gerar definições de ferramentas diretamente do seu código Python: modelos Pydantic, que o xAI SDK transforma em ferramentas através da sua função tool(), e um decorador personalizado simples que lê as assinaturas das suas funções.

Abordagem com Pydantic

O Pydantic é uma biblioteca Python que permite definir modelos de dados com validação automática. A API do Grok pode utilizar estes modelos para gerar esquemas JSON para ferramentas.

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 gera automaticamente o esquema JSON equivalente ao que teria escrito manualmente. As vantagens incluem:

  • Verificação de tipos: o Python verifica os tipos em tempo de execução
  • Validação: o Pydantic valida os dados automaticamente
  • Documentação: as entradas Field(description=...) servem de documentação
  • Reutilização: o mesmo modelo serve para validação e documentação da API

Modelos Complexos

O Pydantic lida com estruturas aninhadas, listas e tipos avançados:

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

As restrições ge (maior ou igual) e le (menor ou igual) traduzem-se em restrições do esquema JSON que o modelo impõe.

A Função tool() do xAI SDK

O xAI SDK não aceita uma classe Pydantic tal qual: espera uma definição de ferramenta, que a sua função tool() constrói a partir de um nome, uma descrição e um esquema JSON. O Pydantic fornece exatamente este esquema através de 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(),
    ),
]

Utilização com o SDK

Você declara a ferramenta ao criar a conversa. O SDK não executa as suas funções: quando o Grok solicita uma chamada, o seu código executa-a, adiciona o resultado com tool_result e retoma a geração.

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 também verifica se os argumentos produzidos pelo modelo correspondem ao esquema: um argumento em falta ou um tipo errado gera um erro antes da execução da sua função.

Um Decorador Personalizado para Rapidez

O SDK não fornece um decorador @tool. Nada o impede de escrever um em poucas linhas que leia a assinatura e a docstring de uma função:

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

O nome da função torna-se o nome da ferramenta, o primeiro parágrafo da docstring torna-se a descrição e os parâmetros sem valores predefinidos tornam-se obrigatórios. No entanto, as descrições dos parâmetros não são extraídas: para parâmetros ambíguos, recorra a um modelo Pydantic com Field(description=...).

Comparação das Três Abordagens

AbordagemVantagensLimitações
Esquema JSON manualControlo total, sem dependênciasProlixo, erros de digitação passam despercebidos
Modelo Pydantic + tool()Validação de argumentos, descrições por campoUma classe por ferramenta
Decorador personalizadoMais concisoSem descrições por parâmetro, código para manter

Boas Práticas para Descrições

Independentemente da abordagem, a descrição é o que o modelo lê para decidir se deve chamar a ferramenta. Indique quando a utilizar, o que devolve e o formato dos 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(),
)

Pontos-chave

  • O Pydantic gera esquemas JSON a partir de modelos Python, com validação de argumentos
  • O xAI SDK constrói ferramentas com tool(name=..., description=..., parameters=...)
  • O SDK não executa as suas funções: o seu código fá-lo e devolve o resultado com tool_result
  • O SDK não tem um decorador @tool; é possível criar um personalizado, à custa das descrições por parâmetro
  • Apure as suas descrições: o modelo lê-as para escolher uma ferramenta