Il processo in 5 passaggi
In questa pagina
Un protocollo chiaro tra te e il modello
La chiamata di funzione di Mistral segue un processo ben definito in cinque passaggi. Ciò che rende questo protocollo leggibile è che ogni passaggio ha un unico proprietario: tu (lo sviluppatore), il modello o l’utente. Nessun passaggio è condiviso e nessuno è ambiguo. Prenditi il tempo di memorizzare questa divisione del lavoro prima di scrivere una singola riga di codice: la maggior parte dei bug legati alla chiamata di funzione si verifica quando uno sviluppatore si aspetta che il modello gestisca un passaggio che è invece di sua responsabilità.
Definisci le funzioni (Sviluppatore)
Descrivi ogni funzione disponibile con uno schema JSON: nome, descrizione, parametri, tipi e campi obbligatori. Il modello vede solo questa specifica, non il tuo codice.
L'utente pone una domanda (Utente)
L'utente formula la sua domanda in linguaggio naturale. Tu invii questa richiesta al modello Mistral insieme all'elenco degli strumenti disponibili.
Genera gli argomenti (Modello)
Il modello analizza la richiesta, seleziona la funzione appropriata e genera gli argomenti in formato JSON. Non esegue la funzione: si limita a dirti cosa chiamare e con quali parametri.
Esegui la funzione (Sviluppatore)
Il tuo codice estrae il nome della funzione e gli argomenti dalla risposta del modello, esegue la funzione corrispondente e recupera il risultato.
Genera la risposta finale (Modello)
Invii il risultato della funzione al modello. Questo integra il risultato nel contesto della conversazione e formula una risposta naturale per l'utente.
Il flusso nel dettaglio
Questi cinque passaggi corrispondono direttamente al codice. Esaminiamoli utilizzando un unico esempio volutamente minimale: un utente vuole conoscere lo stato del pagamento T1001. Useremo questo stesso esempio come filo conduttore fino alla fine del blocco “Implementazione in Python”, quindi familiarizza ora con i suoi identificatori.
Passaggio 1: Definisci gli strumenti
tools = [
{
"type": "function",
"function": {
"name": "get_payment_status",
"description": "Retrieves the status of a payment given its transaction ID",
"parameters": {
"type": "object",
"properties": {
"transaction_id": {
"type": "string",
"description": "The unique transaction identifier (e.g., T1001)"
}
},
"required": ["transaction_id"]
}
}
}
]
Qui non c’è nessun codice eseguibile: è solo una descrizione. Il modello apprende che esiste una funzione chiamata get_payment_status, cosa fa e che richiede un transaction_id di tipo stringa. Non apprende mai come la funzione è implementata.
Passaggio 2: L’utente pone la sua domanda
messages = [
{"role": "user", "content": "What is the status of payment T1001?"}
]
Passaggio 3: Il modello genera gli argomenti
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools
)
# The model returns a tool_call:
# function.name = "get_payment_status"
# function.arguments = '{"transaction_id": "T1001"}'
Il modello ha estratto “T1001” dalla frase e lo ha inserito nel campo corretto. Nota che arguments arriva come una stringa, non come un dizionario: gestirai questo dettaglio nel passaggio successivo.
Passaggio 4: Esegui la funzione
import json
tool_call = response.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = get_payment_status(**args)
# → {"status": "paid", "date": "2026-03-15"}
Passaggio 5: Il modello formula la risposta
messages.append(response.choices[0].message)
messages.append({
"role": "tool",
"name": "get_payment_status",
"content": json.dumps(result),
"tool_call_id": tool_call.id
})
final = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools
)
print(final.choices[0].message.content)
# → "Payment T1001 was made on March 15, 2026."
Vengono aggiunti due messaggi alla cronologia, mai uno solo: il messaggio dell’assistente che contiene la richiesta di chiamata, seguito dal messaggio che contiene il risultato. Il tool_call_id collega i due. Se ne ometti anche solo uno, l’API rifiuterà la richiesta oppure il modello risponderà fuori tema.
Pattern di flusso
A seconda della complessità della richiesta, questo flusso può assumere forme diverse. Il caso più semplice è quando non è coinvolta alcuna funzione: l’utente pone una domanda generale – «Cosa sai fare?» – e il modello risponde direttamente senza mai toccare gli strumenti. Poi viene la chiamata semplice che abbiamo appena esaminato: una funzione, un risultato, una risposta.
Le due forme successive sono più interessanti. In una catena sequenziale, il modello chiama una prima funzione, legge il risultato e lo usa per decidere una seconda chiamata – tipicamente recuperando un ID cliente prima di interrogare le sue fatture. In una chiamata parallela, richiede l’esecuzione di più funzioni contemporaneamente perché nessuna dipende dall’altra. Dedicheremo intere lezioni a questi due pattern; per ora, ricorda che entrambi si basano esattamente sui cinque passaggi sopra, semplicemente ripetuti.
Punti chiave
- La chiamata di funzione segue un processo in 5 passaggi con responsabilità chiare
- Il modello non può mai eseguire direttamente una funzione: genera solo gli argomenti
- Il tuo codice è il guardiano: decide se eseguire o meno la funzione
- Il risultato della funzione viene inviato al modello affinché possa formulare una risposta naturale
- Il flusso può essere semplice (una chiamata) o complesso (sequenziale, parallelo)