Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Eseguire e restituire il risultato

Lezione 6 di 14 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Il passo che controlli completamente
  2. Eseguire la funzione lato client
  3. Costruire il messaggio Tool
  4. Inviare il risultato e ottenere la risposta finale
  5. Il flusso completo in un unico blocco
  6. Struttura dei messaggi a ogni passo
  7. Fai attenzione al formato del contenuto
  8. Punti chiave

Il passo che controlli completamente

Hai ricevuto un tool_call dal modello. Ti indica quale funzione chiamare e con quali argomenti, niente di più. Ora è il tuo codice a prendere il comando: esegue la funzione, recupera il risultato e lo invia nuovamente al modello come messaggio con il ruolo tool. Questa lezione copre l’intero ciclo di andata e ritorno. È l’unico momento del processo in cui prendi tutte le decisioni.

Eseguire la funzione lato client

Rivediamo il dizionario di dispatch della Lezione 4 e colleghiamolo alla risposta del modello.

import json
from functools import partial

# Funzioni già definite
available_functions = {
    "retrieve_payment_status": partial(retrieve_payment_status, df),
    "retrieve_payment_date": partial(retrieve_payment_date, df),
}

# Il modello ha restituito un tool_call
tool_call = response.choices[0].message.tool_calls[0]
function_name = tool_call.function.name
function_params = json.loads(tool_call.function.arguments)

# Esegui la funzione
if function_name in available_functions:
    result = available_functions[function_name](**function_params)
    print(f"Result: {result}")
    # → '{"status": "paid"}'
else:
    result = json.dumps({"error": f"Function {function_name} not available"})

Qui entrano in gioco due meccanismi. Il primo è **function_params, che scompatta il dizionario dal JSON in argomenti nominati: se il modello ha generato {"transaction_id": "T1001"}, la chiamata è esattamente equivalente a retrieve_payment_status(transaction_id="T1001"). Il secondo è il blocco else. È meno appariscente ma essenziale. Un modello potrebbe allucinare un nome di funzione che non esiste nel tuo dispatch; senza questo controllo, la tua app solleva un KeyError e la conversazione si blocca completamente. Con esso, l’errore diventa un dato che il modello può gestire con grazia.

Costruire il messaggio Tool

Il risultato deve tornare al modello in un formato specifico: un messaggio con il ruolo "tool":

tool_message = {
    "role": "tool",
    "name": function_name,
    "content": result,  # Deve essere una stringa
    "tool_call_id": tool_call.id
}
CampoRuolo
role"tool": identifica il messaggio come risultato di una funzione
nameIl nome della funzione eseguita
contentIl risultato come stringa JSON
tool_call_idL’ID del tool_call originale: permette al modello di associare il risultato alla chiamata corretta

Inviare il risultato e ottenere la risposta finale

Il modello non ha memoria da una chiamata all’altra: non ricorda di averti chiesto nulla. Quindi devi ricostruire per lui l’intera conversazione, inclusa la sua stessa richiesta di chiamata tool, prima di presentare il risultato.

# 1. Aggiungi il messaggio dell'assistente (con il tool_call)
messages.append(response.choices[0].message)

# 2. Aggiungi il risultato della funzione
messages.append({
    "role": "tool",
    "name": function_name,
    "content": result,
    "tool_call_id": tool_call.id
})

# 3. Chiama di nuovo il modello con il contesto completo
final_response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools
)

# 4. Visualizza la risposta finale
print(final_response.choices[0].message.content)
# → "Payment T1001 status is: paid."

L’ordine delle due operazioni append non è negoziabile: il messaggio dell’assistente che contiene il tool_call deve precedere il messaggio tool che vi risponde. Scambiarli crea una cronologia incoerente che l’API rifiuta.

Il flusso completo in un unico blocco

Ecco l’intero processo, dalla domanda dell’utente alla risposta finale:

import os
import json
from mistralai.client import Mistral
from functools import partial

# Configurazione
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
model = "mistral-large-latest"

# Funzioni e strumenti (definiti in precedenza)
available_functions = {
    "retrieve_payment_status": partial(retrieve_payment_status, df),
    "retrieve_payment_date": partial(retrieve_payment_date, df),
}

# Passaggi 1-2: Domanda dell'utente + chiamata API
messages = [
    {"role": "user", "content": "What is the status of payment T1001?"}
]

response = client.chat.complete(
    model=model, messages=messages, tools=tools
)

# Passaggi 3-4: Estrai il tool_call ed eseguilo
message = response.choices[0].message

if message.tool_calls:
    tool_call = message.tool_calls[0]
    function_name = tool_call.function.name
    function_params = json.loads(tool_call.function.arguments)

    # Esecuzione lato client
    result = available_functions[function_name](**function_params)

    # Passaggio 5: Invia il risultato al modello
    messages.append(message)
    messages.append({
        "role": "tool",
        "name": function_name,
        "content": result,
        "tool_call_id": tool_call.id
    })

    final_response = client.chat.complete(
        model=model, messages=messages, tools=tools
    )
    print(final_response.choices[0].message.content)
else:
    print(message.content)

Struttura dei messaggi a ogni passo

Vale la pena ispezionare la lista messages una volta terminato il ciclo, perché è il modo migliore per debuggare un function calling malfunzionante. Contiene quattro messaggi.

# Messaggio 1: La domanda dell'utente
{"role": "user", "content": "What is the status of payment T1001?"}

# Messaggio 2: La risposta del modello con il tool_call
{"role": "assistant", "tool_calls": [{"id": "call_abc123", ...}]}

# Messaggio 3: Il risultato della funzione
{"role": "tool", "name": "retrieve_payment_status",
 "content": '{"status": "paid"}', "tool_call_id": "call_abc123"}

# Messaggio 4 (implicito): La risposta finale del modello
# → "Payment T1001 status is: paid."

Segui l’ID call_abc123: nasce nel Messaggio 2 e riappare nel Messaggio 3. Questo filo collega la richiesta alla sua risposta. Questa struttura è il pattern fondamentale del function calling; ogni variazione che incontrerai in seguito, sia essa multi-turno o parallela, non fa che ripeterlo o duplicarlo.

Fai attenzione al formato del contenuto

Un errore si presenta più spesso di tutti gli altri e riguarda il tipo del campo content: deve essere sempre una stringa.

# Corretto — stringa JSON
{"content": '{"status": "paid"}'}

# Corretto — testo semplice
{"content": "The status is paid"}

# Errato — dizionario Python (causerà un errore)
{"content": {"status": "paid"}}

La differenza tra il primo e il terzo esempio sta nelle virgolette che avvolgono il JSON. Se la tua funzione restituisce un dizionario, convertilo con json.dumps() prima di inviarlo: è proprio per questo che tutte le funzioni nella Lezione 4 terminavano con un json.dumps().

Punti chiave

  • L’esecuzione della funzione avviene lato client, nel tuo codice, mai da parte del modello
  • Il risultato viene inviato in un messaggio con ruolo "tool" e il corrispondente tool_call_id
  • Il content del messaggio tool deve essere una stringa (una stringa JSON)
  • Dopo aver inviato il risultato, chiami di nuovo chat.complete() affinché il modello possa formulare la risposta finale
  • Verifica sempre che la funzione richiesta esista nel tuo dizionario di dispatch