Saídas Estruturadas e Execução de Código
Nesta página
Atualizado a 2 de novembro de 2026. Com base na documentação da xAI: com o
xai-sdk, as saídas estruturadas combinam-se com ferramentas criando a conversa (client.chat.create(..., tools=[code_execution()])) e, em seguida, chamandochat.parse(Schema), que devolve a resposta e o objeto tipado; o exemplo anterior chamavaclient.chat.parse(...)com argumentos de Chat Completions, um método que não existe em nenhum SDK. Fontes: Structured Outputs · Code Execution.
Executar Código e Estruturar Resultados
Combinar saídas estruturadas com execução de código permite ao modelo calcular resultados e devolvê-los num formato estruturado. O modelo escreve código, executa-o num ambiente isolado (sandbox) e formata a saída de acordo com o seu esquema.
Funcionalidade do Grok 4 e Versões Posteriores
Tal como a pesquisa na web, esta combinação está reservada aos modelos Grok 4 e posteriores — ou seja, toda a gama atual (Grok 4.5, Grok 4.3, variantes grok-4.20). Os modelos anteriores não suportavam a combinação de ferramentas com saídas estruturadas.
Caso de Uso Típico: Cálculos Precisos
A principal vantagem da execução de código com saídas estruturadas é a precisão de cálculo. Os LLM cometem regularmente erros aritméticos. Ao executar código, os resultados são matematicamente exatos.
from pydantic import BaseModel
from xai_sdk import Client
from xai_sdk.chat import user
from xai_sdk.tools import code_execution
client = Client() # chave lida 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("""Aqui estão as vendas trimestrais:
- Produto A: 150 unidades a 45 €, custo unitário 28 €
- Produto B: 320 unidades a 22 €, custo unitário 15 €
- Produto C: 85 unidades a 120 €, custo unitário 78 €
Calcule a análise financeira completa."""))
response, parsed = chat.parse(FinancialAnalysis)
print(f"Margem bruta: {parsed.gross_margin} €")
print(f"Margem: {parsed.margin_percentage}%")
print(f"Melhor produto: {parsed.most_profitable_product}")
O modelo escreverá um script Python para realizar os cálculos, executá-lo e, em seguida, formatar os resultados no esquema FinancialAnalysis.
Exemplo: Análise Estatística
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("""Calcule as estatísticas descritivas para estes dados:
[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"Média: {parsed.mean}")
print(f"Desvio padrão: {parsed.std_dev}")
Combinar Pesquisa na Web e Execução de Código
Pode ativar ambas as ferramentas simultaneamente:
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("Analise as ações da Apple nos últimos 30 dias"))
response, parsed = chat.parse(MarketAnalysis)
O modelo irá buscar dados recentes na web e, em seguida, utilizar a execução de código para calcular variações e médias.
Limites da Execução de Código
- O ambiente de execução é isolado e efémero
- Pacotes Python comuns vêm pré-instalados (NumPy, Pandas, Matplotlib, SciPy)
- O tempo de execução e a memória são limitados
- Sem acesso à rede a partir do código executado
- Os ficheiros criados não persistem entre chamadas
Pontos-chave
- A execução de código + saídas estruturadas requer no mínimo o Grok 4 — toda a gama atual é compatível
- O modelo escreve e executa código para cálculos precisos
- Ative a ferramenta com
code_execution()no xAI SDK, ou{"type": "code_interpreter"}na API de Respostas, e obtenha o objeto tipado comchat.parse(Schema) - Combinável com
web_searchpara pesquisar e depois calcular - Ideal para análise financeira, estatística e matemática
- Os resultados calculados são exatos, ao contrário das estimativas dos LLM