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

tool_choice e Controlo de Ferramentas

Aula 10 de 16 Atualizada a 30 de julho de 2026 Programador
Nesta página
  1. Oriente o modelo para as ferramentas certas
  2. Modos de tool_choice
  3. parallel_tool_calls
  4. max_turns
  5. Estratégias de controlo
  6. Pontos-chave

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áriotool_choiceparallelmax_turns
Pesquisa de notíciasrequiredtrue3
Cálculo preciso{"type": "function", "name": "calc"}false1
Conversa livreautotrue5
Resposta sem ferramentanone--

Pontos-chave

  • tool_choice controla se e quais as ferramentas que o modelo utiliza: auto, required, none ou uma função específica
  • parallel_tool_calls (predefinição true) permite chamadas de ferramentas simultâneas
  • max_turns limita os ciclos de ferramentas no servidor — as chamadas do cliente reiniciam o contador
  • Utilize required quando dados atualizados forem essenciais
  • Desative o paralelismo se as suas funções tiverem dependências entre si