Mistura de Ferramentas do Servidor e do Cliente
Nesta página
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:
- Utilizar
web_searchpara encontrar informações (execução automática no servidor) - Chamar
save_to_databasepara 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_callao 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