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

Mistura de Ferramentas do Servidor e do Cliente

Aula 8 de 14 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Duas categorias de ferramentas na mesma plataforma
  2. Combinação de ambas num único pedido
  3. O fluxo híbrido
  4. Exemplos do mundo real
  5. Faturação das ferramentas do servidor
  6. Pontos-chave

Duas categorias de ferramentas na mesma plataforma

A API do Grok distingue dois tipos de ferramentas fundamentalmente diferentes com base na execução. Compreender esta distinção é essencial para conceber arquiteturas robustas.

Ferramentas integradas (lado do servidor)

A xAI executa estas ferramentas automaticamente nos seus servidores. Não gere nada — sem execução local, sem reenvio de resultados. O modelo chama-as e recebe os resultados diretamente.

Ferramenta Identificador Descrição
Pesquisa na Web web_search Pesquisa na web em tempo real
Pesquisa no X x_search Pesquisa no X/Twitter
Interpretador de Código code_interpreter Execução de Python em ambiente isolado (sandbox)
Pesquisa em Coleções collections_search Pesquisa nos seus documentos carregados
MCP Remoto mcp Ligação a servidores MCP externos

Funções personalizadas (lado do cliente)

Estas são as suas próprias funções, definidas através de chamada de funções (function calling). O modelo devolve um tool_call, o seu código executa a função e você envia o resultado de volta. Este é o mecanismo que aprendeu nas lições anteriores.

Combinação de ambas num único pedido

O poder da API do Grok reside na capacidade de misturar ferramentas do servidor e do cliente num único pedido:

tools = [
    # Ferramenta do servidor — executada automaticamente pela xAI
    {"type": "web_search"},

    # Ferramenta do cliente — executada pelo seu código
    {
        "type": "function",
        "function": {
            "name": "save_to_database",
            "description": "Guardar informações na base de dados",
            "parameters": {
                "type": "object",
                "properties": {
                    "key": {"type": "string"},
                    "value": {"type": "string"}
                },
                "required": ["key", "value"]
            }
        }
    }
]

Quando o modelo recebe este pedido, pode:

  1. Utilizar web_search para encontrar informações (execução automática no servidor)
  2. Chamar save_to_database para guardar o resultado (retorna ao cliente)

O fluxo híbrido

O comportamento difere consoante o tipo de ferramenta:

  • Ferramenta do servidor: o modelo chama a ferramenta, a xAI executa-a, o resultado é integrado automaticamente e o modelo continua
  • Ferramenta do cliente: o modelo devolve o tool_call ao cliente, a execução para e retoma quando você envia o resultado de volta

Quando o modelo utiliza ambos os tipos no mesmo pedido, as ferramentas do servidor executam-se primeiro (sem a sua intervenção). Depois, se o modelo também precisar de uma ferramenta do cliente, devolve-lhe o tool_call com os resultados das ferramentas do servidor já integrados no seu contexto.

Exemplos do mundo real

Pesquisa na Web + lógica de negócio

# O utilizador pergunta: "Encontra o preço do Bitcoin e guarda-o"
# O modelo:
# 1. Chama web_search para encontrar o preço (lado do servidor, automático)
# 2. Chama save_price(symbol="BTC", price=68432) (lado do cliente)

Pesquisa no X + notificação

# "Alerta-me para tweets sobre o nosso produto desde ontem"
# O modelo:
# 1. Chama x_search para encontrar tweets (lado do servidor)
# 2. Chama send_notification(count=12, summary="...") (lado do cliente)

Interpretador de Código + armazenamento

# "Calcula a média destes dados e guarda o resultado"
# O modelo:
# 1. Chama code_interpreter para o cálculo (lado do servidor)
# 2. Chama save_result(key="avg", value="42.5") (lado do cliente)

Faturação das ferramentas do servidor

As ferramentas integradas são faturadas de duas formas:

  • Tokens: consumo padrão (entrada + saída)
  • Invocações: custo fixo por chamada de ferramenta

O modelo pode chamar várias ferramentas do servidor num único pedido — os custos acumulam-se. Tenha isto em mente quando ativar o web_search: o modelo pode realizar várias pesquisas para refinar os seus resultados.

Pontos-chave

  • Dois tipos de ferramentas: servidor (automático) e cliente (chamada de função)
  • As ferramentas do servidor (web_search, x_search, code_interpreter) executam-se sem a sua intervenção
  • Pode misturar ambos os tipos num único pedido
  • As ferramentas do servidor executam-se primeiro; depois, o modelo pode chamar as suas funções
  • Cada invocação de uma ferramenta do servidor é faturada (tokens + custo por chamada)
  • As citações são geradas automaticamente para dados provenientes de ferramentas do servidor