Chamadas Paralelas
Nesta página
Múltiplas Ferramentas numa Única Resposta
Uma das funcionalidades mais poderosas da chamada de funções do Grok é a capacidade de devolver múltiplas chamadas de ferramentas numa única resposta. Em vez de efetuar uma ida e volta para cada função, o modelo identifica toda a informação necessária e gera todas as chamadas em paralelo.
O Parâmetro parallel_tool_calls
As chamadas paralelas estão ativadas por predefinição. O parâmetro parallel_tool_calls controla este comportamento:
# Ativado por predefinição (não é necessário especificar)
response = client.chat.completions.create(
model="grok-4.5",
messages=messages,
tools=tools,
parallel_tool_calls=True # Esta é a predefinição
)
Quando um utilizador pergunta: «Qual está o tempo em Paris e em Lyon?», o modelo devolve duas tool_calls na mesma resposta:
{
"tool_calls": [
{
"id": "call_001",
"function": {
"name": "get_weather",
"arguments": "{\"city\": \"Paris\"}"
}
},
{
"id": "call_002",
"function": {
"name": "get_weather",
"arguments": "{\"city\": \"Lyon\"}"
}
}
]
}
Gestão de Chamadas Paralelas
O seu código deve gerir um vetor de tool_calls, e não apenas uma:
import json
import asyncio
message = response.choices[0].message
if message.tool_calls:
# Executar todas as funções
tool_results = []
for tool_call in message.tool_calls:
args = json.loads(tool_call.function.arguments)
result = execute_function(tool_call.function.name, args)
tool_results.append({
"role": "tool",
"tool_call_id": tool_call.id,
"content": json.dumps(result)
})
# Enviar TODOS os resultados de volta ao modelo
messages = [
{"role": "user", "content": "Qual está o tempo em Paris e em Lyon?"},
message,
*tool_results # Todos os resultados
]
final = client.chat.completions.create(
model="grok-4.5",
messages=messages,
tools=tools
)
Ponto crítico: deve devolver todos os resultados das ferramentas, e não apenas o primeiro. Cada resultado está ligado ao seu tool_call_id correspondente.
Execução Verdadeiramente Paralela no Cliente
O modelo devolve as chamadas em paralelo, mas o seu código deve executá-las em paralelo. Em Python, utilize asyncio ou concurrent.futures:
import concurrent.futures
def execute_parallel(tool_calls):
results = []
with concurrent.futures.ThreadPoolExecutor() as executor:
futures = {}
for tc in tool_calls:
args = json.loads(tc.function.arguments)
future = executor.submit(execute_function, tc.function.name, args)
futures[future] = tc.id
for future in concurrent.futures.as_completed(futures):
call_id = futures[future]
result = future.result()
results.append({
"role": "tool",
"tool_call_id": call_id,
"content": json.dumps(result)
})
return results
A execução paralela reduz significativamente a latência total. Se cada chamada à API demorar 200 ms, duas chamadas sequenciais equivalem a 400 ms, enquanto duas chamadas paralelas equivalem a ~200 ms.
Desativação de Chamadas Paralelas
Em alguns casos, poderá querer chamadas sequenciais:
response = client.chat.completions.create(
model="grok-4.5",
messages=messages,
tools=tools,
parallel_tool_calls=False
)
Desative o paralelismo sempre que a independência das chamadas não estiver garantida. O caso mais óbvio é a dependência de dados: se o resultado de uma ferramenta alimentar os argumentos da seguinte — como procurar um ID de cliente antes de recuperar as suas encomendas —, executá-las em paralelo causará, no melhor dos casos, um erro e, no pior, produzirá um resultado incorreto de forma silenciosa. A ordem da lógica de negócio impõe a mesma restrição: criar um utilizador antes de lhe atribuir uma função é inegociável, e apenas o modo sequencial garante isto. Mais duas razões práticas completam o quadro: uma API externa sujeita a limites de pedidos simultâneos não lidará bem com uma explosão de chamadas paralelas e, durante o desenvolvimento, o modo sequencial torna o rastreio das chamadas infinitamente mais legível — uma chamada, um resultado, um registo, por ordem.
Chamadas Paralelas com Diferentes Ferramentas
O modelo também pode chamar ferramentas diferentes em paralelo:
# Pedido: "Reserve uma mesa e diga-me como estará o tempo esta noite"
# O modelo devolve:
# - tool_call_1 : book_table(restaurant="Le Petit Bistrot", time="20:00")
# - tool_call_2 : get_weather(city="Paris", time="tonight")
Isto é particularmente útil para assistentes versáteis que precisam de recolher informação de diferentes fontes.
Gestão de Erros em Paralelo
Quando uma chamada falha mas outras têm sucesso, devolva ainda assim todos os resultados. O modelo gere os erros individuais:
results = []
for tc in message.tool_calls:
try:
result = execute_function(tc.function.name, args)
results.append({
"role": "tool",
"tool_call_id": tc.id,
"content": json.dumps(result)
})
except Exception as e:
results.append({
"role": "tool",
"tool_call_id": tc.id,
"content": json.dumps({"error": str(e)})
})
Pontos-chave
- As chamadas paralelas estão ativadas por predefinição (
parallel_tool_calls: true) - O modelo devolve múltiplas
tool_callsnuma única resposta - Deve devolver todos os resultados, cada um ligado ao seu
tool_call_id - Implemente a execução paralela no lado do cliente para reduzir a latência
- Desative o paralelismo quando existirem dependências entre chamadas
- Gere os erros individualmente — não bloqueie tudo por causa de uma única falha