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

Ferramentas de Servidor e Chamada de Funções

Aula 10 de 12 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Enriquecimento de Lotes com Ferramentas
  2. Ferramentas do Lado do Servidor
  3. Chamada de Funções do Lado do Cliente
  4. Combinação de Ferramentas
  5. Limitações das Ferramentas em Lote
  6. Pontos-chave

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-sdk oficial (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