Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Gestione degli errori

Lezione 10 di 14 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Gli errori sono inevitabili
  2. Non nascondere mai un errore al modello
  3. Un esecutore che non lascia passare nulla
  4. Distingui i fallimenti transitori da quelli permanenti
  5. Anche l’API Mistral può fallire
  6. Vedi cosa sta realmente accadendo
  7. Punti chiave

Gli errori sono inevitabili

In produzione, le funzioni falliscono. Le API esterne vanno offline, gli ID non esistono, i parametri non sono validi e i timeout scadono. La domanda non è «fallirà?», ma «come gestiamo il fallimento con eleganza?». Un tracker di pagamenti che si blocca perché un utente ha digitato T9999 invece di T1001 non è un sistema di produzione: è una demo.

La buona notizia è che disponi di una risorsa assente nelle architetture classiche: il modello Mistral può comprendere i messaggi di errore che gli invii e adattare di conseguenza la sua risposta. Mentre un backend tradizionale deve costruire un messaggio UI per ogni codice di errore, tu puoi lasciare che il modello traduca il fallimento in una frase utile per l’utente. Devi solo fornirgli le informazioni necessarie.

Non nascondere mai un errore al modello

Questa è la regola d’oro di questa lezione. Restituisci un errore nel messaggio tool esattamente come faresti per un risultato normale: come JSON strutturato. Il riflesso opposto—catturare l’eccezione e restituire una stringa vuota o null—fa credere al modello che la funzione abbia avuto successo ma semplicemente nulla da dire. Questo genera le risposte più confuse possibili.

def retrieve_payment_status(df, transaction_id: str) -> str:
    """Recupera lo stato con una gestione completa degli errori."""
    try:
        if transaction_id not in df["transaction_id"].values:
            return json.dumps({
                "error": "transaction_not_found",
                "message": f"La transazione {transaction_id} non esiste nel database."
            })

        status = df[df["transaction_id"] == transaction_id]["payment_status"].values[0]
        return json.dumps({"status": status, "transaction_id": transaction_id})

    except Exception as e:
        return json.dumps({
            "error": "internal_error",
            "message": f"Errore nel recupero dei dati: {str(e)}"
        })

Due campi sono sufficienti: un codice macchina in error e una spiegazione leggibile dall’uomo in message. Il codice permette al tuo sistema di monitoraggio di contare le occorrenze; la spiegazione consente al modello di formulare una risposta utile. Vedi cosa succede con una transazione inesistente.

# L'utente richiede una transazione inesistente
messages = [{"role": "user", "content": "Stato del pagamento T9999?"}]

# Il modello chiama retrieve_payment_status(transaction_id="T9999")
# La tua funzione restituisce: {"error": "transaction_not_found", ...}

# Il modello formula:
# → "Non ho trovato una transazione con ID T9999.
#     Potresti verificare il numero e riprovare?"

Nessuno ha scritto quella frase. Deriva dal codice di errore e suggerisce persino un’azione correttiva all’utente.

Un esecutore che non lascia passare nulla

Proteggere una funzione non basta: il livello che dispatcha le tool_calls ha i suoi modi di fallire, indipendentemente dalla tua logica di business. Il modello potrebbe allucinare un nome di funzione che non esiste nel tuo dizionario. Potrebbe produrre argomenti JSON malformati—un caso raro ma reale con schemi complessi. Potrebbe anche fornire JSON validi le cui chiavi non corrispondono alla firma Python, causando un TypeError durante **function_params. Ciascuno di questi tre casi merita il proprio codice di errore, poiché ciascuno richiede una correzione diversa da parte tua.

def execute_tool_call(tool_call, available_functions):
    """Esegue una tool_call con una gestione completa degli errori."""
    function_name = tool_call.function.name

    # Verifica se la funzione esiste
    if function_name not in available_functions:
        return {
            "role": "tool",
            "name": function_name,
            "content": json.dumps({
                "error": "function_not_found",
                "message": f"La funzione {function_name} non è disponibile."
            }),
            "tool_call_id": tool_call.id
        }

    # Analizza gli argomenti
    try:
        function_params = json.loads(tool_call.function.arguments)
    except json.JSONDecodeError as e:
        return {
            "role": "tool",
            "name": function_name,
            "content": json.dumps({
                "error": "invalid_arguments",
                "message": f"Argomenti JSON non validi: {str(e)}"
            }),
            "tool_call_id": tool_call.id
        }

    # Esegue la funzione
    try:
        result = available_functions[function_name](**function_params)
        return {
            "role": "tool",
            "name": function_name,
            "content": result,
            "tool_call_id": tool_call.id
        }
    except TypeError as e:
        return {
            "role": "tool",
            "name": function_name,
            "content": json.dumps({
                "error": "invalid_params",
                "message": f"Parametri incompatibili: {str(e)}"
            }),
            "tool_call_id": tool_call.id
        }
    except Exception as e:
        return {
            "role": "tool",
            "name": function_name,
            "content": json.dumps({
                "error": "execution_error",
                "message": f"Errore di esecuzione: {str(e)}"
            }),
            "tool_call_id": tool_call.id
        }

Nota che ogni ramo, inclusi quelli di fallimento, restituisce un messaggio tool completo con il suo tool_call_id. Questo è essenziale: l’API rifiuta una cronologia in cui una tool_call rimane senza risposta, e un fallimento silenzioso causerebbe un errore di validazione al turno successivo, lontano dalla causa reale.

Distingui i fallimenti transitori da quelli permanenti

Non tutti gli errori sono uguali. Una transazione mancante sarà ancora mancante al secondo tentativo; ritentare spreca solo tempo. Un timeout di rete o un servizio momentaneamente saturato, invece, spesso si risolve da solo. Per questa seconda categoria, un ritentativo con backoff esponenziale—un secondo, poi due, poi quattro—dà al servizio il tempo di riprendersi senza tempestarlo di richieste. Dopo aver esaurito i tentativi, torni al comportamento usuale: un JSON di errore destinato al modello.

import time

def execute_with_retry(func, params, max_retries=3, base_delay=1.0):
    """Esegue una funzione con ritentativo esponenziale."""
    for attempt in range(max_retries):
        try:
            result = func(**params)
            return result
        except ConnectionError as e:
            if attempt < max_retries - 1:
                delay = base_delay * (2 ** attempt)
                time.sleep(delay)
            else:
                return json.dumps({
                    "error": "service_unavailable",
                    "message": f"Servizio non disponibile dopo {max_retries} tentativi.",
                    "details": str(e)
                })

Anche l’API Mistral può fallire

Tutto quanto sopra riguarda le tue funzioni. La chiamata all’API Mistral stessa è un punto di fallimento distinto, gestito separatamente: qui non c’è alcun modello a cui spiegare il problema, dato che il modello è proprio ciò che risulta irraggiungibile. Un HTTPValidationError segnala solitamente un errore nella struttura dei tuoi messaggi o strumenti, che devi correggere nel codice; altre eccezioni riguardano la rete o il servizio e vengono gestite con la stessa logica di ritentativo vista sopra.

from mistralai.client import Mistral
from mistralai.client.errors import HTTPValidationError

def safe_chat_complete(client, model, messages, tools):
    """Chiamata API Mistral con gestione degli errori."""
    try:
        return client.chat.complete(
            model=model,
            messages=messages,
            tools=tools
        )
    except HTTPValidationError as e:
        print(f"Errore di validazione: {e}")
        return None
    except Exception as e:
        print(f"Errore API: {e}")
        return None

Vedi cosa sta realmente accadendo

Un sistema di function calling è difficile da debuggare a posteriori se non sai quale funzione è stata chiamata, con quali argomenti e cosa ha restituito. Il logging non è un lusso; è il modo in cui scoprirai che una descrizione ambigua spinge il modello a confondere due funzioni, o che un utente su cinque attiva sistematicamente un transaction_not_found. Registra la chiamata prima dell’esecuzione, poi il verdetto, distinguendo il livello info dal livello error affinché i tuoi alert possano filtrare efficacemente.

import logging

logger = logging.getLogger("function_calling")

def execute_and_log(tool_call, available_functions):
    """Esegue e registra il risultato."""
    function_name = tool_call.function.name
    function_params = json.loads(tool_call.function.arguments)

    logger.info(f"Chiamata: {function_name}({function_params})")

    result = execute_tool_call(tool_call, available_functions)
    content = json.loads(result["content"])

    if "error" in content:
        logger.error(f"Fallimento {function_name}: {content['error']} - {content['message']}")
    else:
        logger.info(f"Successo {function_name}: {content}")

    return result

Punti chiave

  • Restituisci sempre gli errori al modello nel messaggio tool: sa come interpretarli
  • Usa codici di errore strutturati (transaction_not_found, invalid_arguments, ecc.)
  • Implementa un ritentativo con backoff per gli errori transitori
  • Gestisci separatamente gli errori nelle tue funzioni e quelli nell’API Mistral
  • Registra ogni chiamata e ogni errore per il monitoraggio in produzione