Salidas estructuradas y ejecución de código
En esta página
Actualizado el 2 de noviembre de 2026. Según la documentación de xAI: con
xai-sdk, las salidas estructuradas se combinan con herramientas creando la conversación (client.chat.create(..., tools=[code_execution()])) y llamando después achat.parse(Schema), lo que devuelve la respuesta y el objeto tipado; el ejemplo anterior llamaba aclient.chat.parse(...)con argumentos de Chat Completions, un método que no existe en ningún SDK. Fuentes: Salidas estructuradas · Ejecución de código.
Ejecutar código y estructurar resultados
Combinar salidas estructuradas con ejecución de código permite al modelo calcular resultados y devolverlos en un formato estructurado. El modelo escribe código, lo ejecuta en un entorno aislado (sandbox) y formatea la salida según tu esquema.
Funcionalidad de Grok 4 y versiones posteriores
Al igual que la búsqueda web, esta combinación está reservada para los modelos Grok 4 y posteriores; es decir, toda la gama actual (Grok 4.5, Grok 4.3, variantes grok-4.20). Los modelos anteriores no admitían combinar herramientas con salidas estructuradas.
Caso de uso habitual: cálculos precisos
La principal ventaja de la ejecución de código con salidas estructuradas es la precisión del cálculo. Los LLM cometen errores aritméticos con frecuencia. Al ejecutar código, los resultados son matemáticamente exactos.
from pydantic import BaseModel
from xai_sdk import Client
from xai_sdk.chat import user
from xai_sdk.tools import code_execution
client = Client() # clave leída de XAI_API_KEY
class FinancialAnalysis(BaseModel):
total_revenue: float
total_cost: float
gross_margin: float
margin_percentage: float
most_profitable_product: str
least_profitable_product: str
chat = client.chat.create(
model="grok-4.20-0309-reasoning",
tools=[code_execution()],
)
chat.append(user("""Aquí tienes las ventas trimestrales:
- Producto A: 150 unidades a 45 €, coste unitario 28 €
- Producto B: 320 unidades a 22 €, coste unitario 15 €
- Producto C: 85 unidades a 120 €, coste unitario 78 €
Calcula el análisis financiero completo."""))
response, parsed = chat.parse(FinancialAnalysis)
print(f"Margen bruto: {parsed.gross_margin} €")
print(f"Margen: {parsed.margin_percentage}%")
print(f"Mejor producto: {parsed.most_profitable_product}")
El modelo escribirá un script de Python para realizar los cálculos, lo ejecutará y formateará después los resultados en el esquema FinancialAnalysis.
Ejemplo: análisis estadístico
class DescriptiveStatistics(BaseModel):
mean: float
median: float
std_dev: float
minimum: float
maximum: float
quartile_1: float
quartile_3: float
value_count: int
chat = client.chat.create(
model="grok-4.20-0309-reasoning",
tools=[code_execution()],
)
chat.append(user("""Calcula las estadísticas descriptivas para estos datos:
[23, 45, 12, 67, 34, 89, 56, 78, 41, 33, 61, 25,
72, 48, 55, 39, 64, 71, 28, 50]"""))
response, parsed = chat.parse(DescriptiveStatistics)
print(f"Media: {parsed.mean}")
print(f"Desviación típica: {parsed.std_dev}")
Combinar búsqueda web y ejecución de código
Puedes activar ambas herramientas simultáneamente:
class MarketAnalysis(BaseModel):
company: str
current_price: float
change_30d: float
avg_volume: float
trend: str
recommendation: str
from xai_sdk.tools import web_search
chat = client.chat.create(
model="grok-4.20-0309-reasoning",
tools=[web_search(), code_execution()],
)
chat.append(user("Analiza la acción de Apple en los últimos 30 días"))
response, parsed = chat.parse(MarketAnalysis)
El modelo recuperará datos recientes de la web y usará después la ejecución de código para calcular variaciones y medias.
Límites de la ejecución de código
- El entorno de ejecución está aislado y es efímero
- Los paquetes comunes de Python vienen preinstalados (NumPy, Pandas, Matplotlib, SciPy)
- El tiempo de ejecución y la memoria tienen límites
- El código ejecutado no tiene acceso a la red
- Los archivos creados no persisten entre llamadas
Puntos clave
- La ejecución de código más salidas estructuradas requiere como mínimo Grok 4; toda la gama actual es compatible
- El modelo escribe y ejecuta código para obtener cálculos precisos
- Activa la herramienta con
code_execution()en el SDK de xAI, o{"type": "code_interpreter"}en la API de Responses, y obtén después el objeto tipado conchat.parse(Schema) - Se puede combinar con
web_searchpara buscar y después calcular - Ideal para análisis financieros, estadísticos y matemáticos
- Los resultados calculados son exactos, a diferencia de las estimaciones de un LLM