Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Opzioni di tool_choice

Lezione 9 di 14 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Decidere chi decide
  2. auto — Lascia decidere al modello
  3. any — Imporre un output strutturato
  4. none — Disabilitare gli strumenti senza rimuoverli
  5. Regolare l’impostazione durante la conversazione
  6. Punti chiave

Decidere chi decide

Passare tools all’API non significa che il modello debba usarle, né tantomeno che gli sia consentito farlo. Tra questi due estremi, il parametro tool_choice funge da arbitro. A seconda del valore che gli assegni, puoi lasciare al modello la libertà di giudicare, costringerlo a produrre una chiamata strutturata o revocargli completamente l’accesso agli strumenti che hai appena dichiarato. È un’impostazione sottile, ma cambia radicalmente il comportamento dello stesso codice di fronte alla stessa domanda.

ValoreComportamentoCaso d’uso
autoIl modello decide liberamente se usare uno strumento o rispondere in testo. Questa è la modalità predefinita.Assistenti conversazionali, chatbot generici
anyIl modello è costretto a chiamare almeno uno strumento. Non può rispondere solo con del testo.Pipeline automatizzate, estrazione di dati strutturati
noneIl modello non può usare strumenti, anche se definiti. Risponde solo in testo.Riassunto dei risultati senza nuove chiamate, riformulazione di una risposta
requiredSinonimo di any. Il modello deve usare almeno uno strumento.Equivalente a any, per compatibilità

auto — Lascia decidere al modello

Questo è il valore predefinito, quello che usi senza rendertene conto ogni volta che ometti il parametro.

response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto"  # Opzionale, questo è il valore predefinito
)

Con auto, il modello valuta la richiesta prima di agire. Se la domanda richiede dati esterni che non possiede, chiama una funzione; se la query è generica o relazionale, risponde direttamente in testo. Questo interruttore è ciò che rende un assistente naturale: l’utente non ha bisogno di sapere che ci sono strumenti dietro le quinte.

# Il modello chiamerà una funzione
messages = [{"role": "user", "content": "Stato del pagamento T1001?"}]
# → tool_call: retrieve_payment_status(transaction_id="T1001")

# Il modello risponderà direttamente
messages = [{"role": "user", "content": "Ciao, come stai?"}]
# → content: "Ciao! Sono un assistente per i pagamenti. Come posso aiutarti?"

Il secondo esempio merita attenzione: forzare una chiamata di funzione su un semplice saluto produrrebbe una retrieve_payment_status con un ID inventato. È esattamente ciò che auto previene, motivo per cui questa modalità rimane la più comune in produzione.

any — Imporre un output strutturato

Al contrario, esistono contesti in cui il testo in forma libera non ha alcun valore per te. Una pipeline di ingestione che elabora diecimila documenti si aspetta JSON utilizzabile, non una frase gentile. Con any, il modello deve chiamare almeno una funzione, anche se la domanda non sembra richiederlo.

response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="any"
)

È interessante notare che il caso d’uso più frequente riutilizza la chiamata di funzione scoprendone l’intento originale: non dichiari una funzione per eseguirla, ma per garantire uno schema di output. Qui, extract_entities non verrà mai chiamata lato server; ciò che conta è il contratto JSON.

# Estrazione strutturata: forza il modello a estrarre dati
tools = [{
    "type": "function",
    "function": {
        "name": "extract_entities",
        "description": "Estrae entità nominate dal testo",
        "parameters": {
            "type": "object",
            "properties": {
                "persons": {"type": "array", "items": {"type": "string"}},
                "organizations": {"type": "array", "items": {"type": "string"}},
                "dates": {"type": "array", "items": {"type": "string"}}
            },
            "required": ["persons", "organizations", "dates"]
        }
    }
}]

messages = [{"role": "user", "content": "Sophia Yang di Mistral ha presentato "
            "la chiamata di funzioni il 15 marzo 2026."}]

response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="any"  # Forza l'estrazione
)

# → extract_entities(persons=["Sophia Yang"],
#                     organizations=["Mistral"],
#                     dates=["15 marzo 2026"])

Nota required per inciso: è un sinonimo di any, incluso per compatibilità con il codice scritto per altre API. Entrambi i valori producono lo stesso comportamento; scegli quello che rende il tuo codice più leggibile e mantienilo.

none — Disabilitare gli strumenti senza rimuoverli

Il terzo valore risponde a un bisogno meno ovvio. Hai già recuperato i tuoi dati tramite diverse tool_call e ora vuoi che il modello li sintetizzi. Se continui la conversazione in modalità auto, nulla impedisce al modello di chiamare nuovamente una funzione “tanto per controllare”, il che aumenta la latenza e può innescare un ciclo infinito. none vieta qualsiasi nuova chiamata mantenendo le definizioni degli strumenti nel contesto, aiutando il modello a parlare accuratamente dei dati che già possiede.

response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="none"
)

Tre casi d’uso ricorrono costantemente: richiedere un riepilogo dopo una serie di chiamate di funzione, riformulare una risposta senza attivare nuove chiamate e testare in sviluppo come si comporta il modello quando viene privato dei suoi strumenti, il che rivela rapidamente le domande che pensa di poter rispondere dalla memoria.

# Dopo aver recuperato dati tramite tool_calls...
# Richiedi un riepilogo senza nuove chiamate
messages.append({
    "role": "user",
    "content": "Riassumi le informazioni di tutti i pagamenti che hai trovato."
})

response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="none"  # Il modello riassume con ciò che ha già
)

Regolare l’impostazione durante la conversazione

Non devi impostare tool_choice una volta sola all’avvio. In produzione, è comune calcolarlo a ogni turno in base al contesto: il primo messaggio della conversazione, l’intento rilevato nella richiesta o il numero di chiamate già consumate. La funzione seguente illustra questa logica nella sua forma più semplice: il modello rimane libero per impostazione predefinita, tranne quando l’utente richiede esplicitamente un riepilogo.

def get_tool_choice(user_input: str, turn_count: int) -> str:
    """Determina tool_choice in base al contesto."""

    # Primo turno: lascia decidere al modello
    if turn_count == 0:
        return "auto"

    # Se l'utente richiede esplicitamente un riepilogo
    if any(word in user_input.lower() for word in ["summarize", "recap", "synthesis"]):
        return "none"

    # Predefinito
    return "auto"

In pratica, mantieni auto come impostazione di base: è la più naturale e flessibile. Riserva any per le pipeline di estrazione di dati strutturati e none per i momenti in cui devi prevenire cicli infiniti di tool_call. Un vincolo è assoluto: non cambiare mai tool_choice nel mezzo dell’elaborazione di una tool_call. Completa prima il ciclo restituendo tutti i messaggi tool attesi, quindi regola il parametro al turno successivo; altrimenti, la cronologia diventa incoerente e l’API rifiuta la richiesta.

Punti chiave

  • tool_choice controlla quando il modello usa le funzioni
  • auto = il modello decide liberamente (predefinito, consigliato per i chatbot)
  • any = il modello è costretto a chiamare uno strumento (pipeline, estrazione strutturata)
  • none = gli strumenti sono disabilitati (riepiloghi, riformulazioni)
  • Adatta tool_choice dinamicamente in base al contesto della conversazione