Ferramentas de Servidor e Chamada de Funções
Nesta página
Curso atualizado a 2 de novembro de 2026 com base na documentação da xAI: o desconto para lotes é de 20% em modelos de texto elegíveis (não 50%), os exemplos seguem a API REST e o
xai-sdkoficial (client.batch.*; a API de Lotes da xAI não utiliza o formato da OpenAI, pelo que o SDK da OpenAI não se aplica), e a API de Respostas tem precedência sobre a de Conclusões de Chat, um endpoint legado na xAI. Fontes: Batch API · REST Reference · Batch Pricing.
Enriquecimento de Lotes com Ferramentas
Os pedidos em lote não se limitam a texto simples. As ferramentas de servidor e a chamada de funções funcionam também em modo assíncrono, com uma distinção fundamental: as primeiras são executadas durante o processamento pela xAI, enquanto a segunda devolve o controlo ao utilizador.
Ferramentas do Lado do Servidor
As ferramentas de servidor são executadas durante o processamento do lote, exatamente como em tempo real: o Grok chama a ferramenta, recebe o resultado, integra-o no seu raciocínio e o lote devolve a resposta final. Funcionam com a API de Respostas.
Pesquisa na Web
{"custom_id": "news-1", "method": "POST", "url": "/v1/responses", "body": {"model": "grok-4.3", "input": [{"role": "user", "content": "What are the latest developments in quantum computing?"}], "tools": [{"type": "web_search"}]}}
No modo de lote, a pesquisa na web serve para enriquecimento de dados: verificação de informações, recolha de factos recentes e comparação de perfis com fontes online.
Pesquisa no X
A ferramenta x_search consulta publicações no X, sendo útil para monitorizar o sentimento sobre um tópico ou marca:
{"custom_id": "x-1", "method": "POST", "url": "/v1/responses", "body": {"model": "grok-4.3", "input": [{"role": "user", "content": "What is the dominant sentiment on X regarding this product launch?"}], "tools": [{"type": "x_search"}]}}
Execução de Código
O Grok pode escrever e executar código Python num ambiente isolado. Na API de Respostas, a ferramenta chama-se code_interpreter (o SDK da xAI designa-a por code_execution):
{"custom_id": "calc-1", "method": "POST", "url": "/v1/responses", "body": {"model": "grok-4.3", "input": [{"role": "user", "content": "Calculate the 3-point moving average for this data: [12, 15, 18, 14, 22, 19, 25, 28, 30, 27]"}], "tools": [{"type": "code_interpreter"}]}}
A execução de código é relevante para cálculos exatos, estatísticas e transformações de dados que o modelo trataria com menos fiabilidade recorrendo apenas à memória.
Servidores MCP Remotos
A ferramenta mcp liga o Grok a um servidor MCP remoto, descrito no próprio pedido: não é necessária configuração prévia de conta. Os campos server_url e server_label são obrigatórios; allowed_tools restringe as ferramentas expostas e authorization passa um token para o servidor. Apenas os transportes Streamable HTTP e SSE são aceites.
{"custom_id": "mcp-1", "method": "POST", "url": "/v1/responses", "body": {"model": "grok-4.3", "input": [{"role": "user", "content": "What does the xai-sdk-python repository do?"}], "tools": [{"type": "mcp", "server_label": "deepwiki", "server_url": "https://mcp.deepwiki.com/mcp"}]}}
Sem allowed_tools, todas as definições de ferramentas do servidor são injetadas no contexto do modelo e faturadas como tokens de entrada em cada pedido de lote: num volume de 50.000 pedidos, restringir a lista compensa rapidamente.
Chamada de Funções do Lado do Cliente
A chamada de funções é uma ferramenta do lado do cliente: o Grok produz uma chamada de função estruturada, mas é o seu código que a executa. No modo de lote, o modelo devolve estas chamadas nos seus resultados para processamento offline.
Definições de Função
Na API de Respostas, declare a função de forma plana, com name, description e parameters ao nível superior. tool_choice: "required" força o modelo a chamar pelo menos uma ferramenta, o que é adequado para extração:
{"custom_id": "extract-1", "method": "POST", "url": "/v1/responses", "body": {"model": "grok-4.3", "input": [{"role": "user", "content": "Extract the contact: Jean Dupont, 01 23 45 67 89, [email protected]"}], "tools": [{"type": "function", "name": "save_contact", "description": "Saves a contact extracted from text", "parameters": {"type": "object", "properties": {"name": {"type": "string"}, "phone": {"type": "string"}, "email": {"type": "string"}}, "required": ["name"]}}], "tool_choice": "required"}}
Processamento de Resultados
Com o SDK, leia as chamadas de função em tool_calls de cada resultado bem-sucedido:
import json
for r in page.succeeded:
for call in r.response.tool_calls:
if call.function.name == "save_contact":
contact = json.loads(call.function.arguments)
save_to_database(r.batch_request_id, contact)
A chamada de funções em lote é ideal para extração estruturada: define o esquema de dados, o Grok lê os documentos e produz as chamadas, e o utilizador processa-as em massa.
Combinação de Ferramentas
Pode combinar várias ferramentas de servidor num único pedido:
{"custom_id": "multi-1", "method": "POST", "url": "/v1/responses", "body": {"model": "grok-4.3", "input": [{"role": "user", "content": "Find the Bitcoin closing price for the last seven days and calculate its change"}], "tools": [{"type": "web_search"}, {"type": "code_interpreter"}]}}
O Grok utiliza as ferramentas pela ordem que considera relevante: neste caso, pesquisa na web para obter os dados e, em seguida, execução de código para o cálculo.
Limitações das Ferramentas em Lote
- As ferramentas de servidor aumentam o tempo de processamento de cada pedido e, consequentemente, do lote
- Os pedidos com pesquisa dependem do que as fontes publicam no momento do processamento, não no momento do envio
- A chamada de funções realiza apenas uma ida e volta por pedido: para continuar, submeta um novo pedido de lote contendo a conversa e os resultados da sua função
- Definições de ferramentas MCP não filtradas incham cada pedido
Pontos-chave
- As ferramentas de servidor (web, X, código, MCP) são executadas pela xAI durante o processamento, através da API de Respostas
- Descreva um servidor MCP no pedido (
server_url,server_label), sem configuração prévia - A chamada de funções devolve chamadas estruturadas que o utilizador executa do lado do cliente
- Uma troca multi-turno exige um novo pedido de lote por turno
- Restrinja as ferramentas expostas para evitar pagar pelas suas definições em cada pedido