tool_choice e controllo degli strumenti
In questa pagina
Indirizza il modello verso gli strumenti giusti
Di default, il modello decide liberamente quali strumenti utilizzare (o se non usarne affatto). Il parametro tool_choice ti offre un controllo più fine su questo comportamento.
Modalità di tool_choice
auto (default)
Il modello decide liberamente. Può usare uno strumento, diversi o nessuno:
{
"model": "grok-4.20-0309-reasoning",
"input": "What is the capital of France?",
"tools": [{"type": "web_search"}],
"tool_choice": "auto"
}
Per questa semplice domanda fattuale, il modello risponderà probabilmente senza effettuare una ricerca web. Per una domanda sugli eventi attuali, avvierà una ricerca.
required
Forza il modello a utilizzare almeno uno strumento:
{
"model": "grok-4.20-0309-reasoning",
"input": "Give me today's stock market prices.",
"tools": [{"type": "web_search"}],
"tool_choice": "required"
}
Utile quando sai che la risposta richiede dati aggiornati e il modello non dovrebbe rispondere basandosi sulla sua memoria.
none
Vieta l’uso degli strumenti, anche se sono dichiarati:
{
"model": "grok-4.20-0309-reasoning",
"input": "Explain the concept of recursion.",
"tools": [{"type": "web_search"}, {"type": "code_interpreter"}],
"tool_choice": "none"
}
Pratico per forzare una risposta puramente testuale in un contesto dove gli strumenti sono normalmente disponibili.
Funzione specifica
Forza l’uso di una funzione specifica:
{
"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"}
}
Il modello è vincolato a chiamare get_weather con gli argomenti appropriati.
parallel_tool_calls
Di default, parallel_tool_calls è impostato su true. Il modello può lanciare più strumenti in parallelo in un singolo turno:
{
"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
}
Il modello potrebbe chiamare get_weather("Paris") e get_weather("Londres") simultaneamente, accelerando così l’elaborazione.
Per disabilitare questo comportamento:
{
"parallel_tool_calls": false
}
Disabilita le chiamate parallele se le tue funzioni hanno effetti collaterali o dipendenze reciproche (ad esempio, se la seconda funzione dipende dal risultato della prima).
max_turns
Il parametro max_turns limita il numero di turni di interazione tra il modello e gli strumenti lato server:
{
"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
}
Un “turno” corrisponde a un ciclo completo: il modello chiama uno strumento, riceve il risultato, poi decide se ha bisogno di un’altra chiamata. Con max_turns: 5, il modello può eseguire fino a 5 cicli di chiamate agli strumenti lato server prima di produrre la sua risposta finale.
Comportamento con gli strumenti client
max_turns si applica solo agli strumenti server. Quando il modello chiama una funzione client, il contatore si azzera alla richiesta successiva. Ciò significa che ogni andata e ritorno client-server crea una nuova allocazione di turni.
Strategie di controllo
| Scenario | tool_choice | parallel | max_turns |
|---|---|---|---|
| Ricerca notizie | required | true | 3 |
| Calcolo preciso | {"type": "function", "name": "calc"} | false | 1 |
| Conversazione libera | auto | true | 5 |
| Risposta senza strumento | none | - | - |
Punti chiave
tool_choicecontrolla se e quali strumenti usa il modello:auto,required,noneo una funzione specificaparallel_tool_calls(defaulttrue) abilita chiamate simultanee agli strumentimax_turnslimita i cicli degli strumenti server: le chiamate client azzerano il contatore- Usa
requiredquando i dati aggiornati sono essenziali - Disabilita il parallelismo se le tue funzioni hanno dipendenze reciproche