Eseguire e restituire il risultato
In questa pagina
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
}
| Campo | Ruolo |
|---|---|
role | "tool": identifica il messaggio come risultato di una funzione |
name | Il nome della funzione eseguita |
content | Il risultato come stringa JSON |
tool_call_id | L’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 corrispondentetool_call_id - Il
contentdel 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