tool_choice e Controlo de Ferramentas
Nesta página
Oriente o modelo para as ferramentas certas
Por predefinição, o modelo decide livremente quais as ferramentas a utilizar (ou se deve utilizar alguma). O parâmetro tool_choice concede-lhe um controlo mais fino sobre este comportamento.
Modos de tool_choice
auto (predefinição)
O modelo decide livremente. Pode utilizar uma ferramenta, várias ou nenhuma:
{
"model": "grok-4.20-0309-reasoning",
"input": "What is the capital of France?",
"tools": [{"type": "web_search"}],
"tool_choice": "auto"
}
Para esta pergunta factual simples, o modelo responderá provavelmente sem uma pesquisa na web. Para uma questão sobre acontecimentos atuais, iniciará uma pesquisa.
required
Obriga o modelo a utilizar pelo menos uma ferramenta:
{
"model": "grok-4.20-0309-reasoning",
"input": "Give me today's stock market prices.",
"tools": [{"type": "web_search"}],
"tool_choice": "required"
}
Útil quando sabe que a resposta requer dados atualizados e o modelo não deve responder com base na memória.
none
Proíbe a utilização de ferramentas, mesmo que estas estejam declaradas:
{
"model": "grok-4.20-0309-reasoning",
"input": "Explain the concept of recursion.",
"tools": [{"type": "web_search"}, {"type": "code_interpreter"}],
"tool_choice": "none"
}
Prático para forçar uma resposta puramente textual num contexto onde as ferramentas estão normalmente disponíveis.
Função específica
Obriga à utilização de uma função específica:
{
"model": "grok-4.20-0309-reasoning",
"input": "Paris",
"tools": [{
"type": "function",
"name": "get_weather",
"description": "Retrieves the weather",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string"}
},
"required": ["city"]
}
}],
"tool_choice": {"type": "function", "name": "get_weather"}
}
O modelo fica restrito a chamar get_weather com os argumentos apropriados.
parallel_tool_calls
Por predefinição, parallel_tool_calls está definido como true. O modelo pode lançar várias ferramentas em paralelo numa única interação:
{
"model": "grok-4.20-0309-reasoning",
"input": "Compare the weather in Paris and London.",
"tools": [{
"type": "function",
"name": "get_weather",
"description": "Retrieves the weather for a city",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string"}
},
"required": ["city"]
}
}],
"parallel_tool_calls": true
}
O modelo pode chamar get_weather("Paris") e get_weather("Londres") simultaneamente, o que acelera o processamento.
Para desativar este comportamento:
{
"parallel_tool_calls": false
}
Desative as chamadas paralelas se as suas funções tiverem efeitos secundários ou dependências entre si (por exemplo, se a segunda função depender do resultado da primeira).
max_turns
O parâmetro max_turns limita o número de ciclos de interação entre o modelo e as ferramentas no lado do servidor:
{
"model": "grok-4.20-0309-reasoning",
"input": "Perform an in-depth analysis of the AI market in 2026.",
"tools": [{"type": "web_search"}, {"type": "code_interpreter"}],
"max_turns": 5
}
Um “turno” corresponde a um ciclo completo: o modelo chama uma ferramenta, recebe o resultado e decide se necessita de outra chamada. Com max_turns: 5, o modelo pode executar até 5 ciclos de chamadas de ferramentas no servidor antes de produzir a sua resposta final.
Comportamento com ferramentas do cliente
O max_turns aplica-se apenas às ferramentas do servidor. Quando o modelo chama uma função do cliente, o contador reinicia no pedido seguinte. Isto significa que cada ida e volta entre cliente e servidor cria uma nova alocação de turnos.
Estratégias de controlo
| Cenário | tool_choice | parallel | max_turns |
|---|---|---|---|
| Pesquisa de notícias | required | true | 3 |
| Cálculo preciso | {"type": "function", "name": "calc"} | false | 1 |
| Conversa livre | auto | true | 5 |
| Resposta sem ferramenta | none | - | - |
Pontos-chave
tool_choicecontrola se e quais as ferramentas que o modelo utiliza:auto,required,noneou uma função específicaparallel_tool_calls(predefiniçãotrue) permite chamadas de ferramentas simultâneasmax_turnslimita os ciclos de ferramentas no servidor — as chamadas do cliente reiniciam o contador- Utilize
requiredquando dados atualizados forem essenciais - Desative o paralelismo se as suas funções tiverem dependências entre si