Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Chiamare l'API con gli Strumenti

Lezione 5 di 14 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Inviare gli Strumenti all’API Mistral
  2. La Prima Richiesta
  3. Comprendere la Risposta del Modello
  4. Analizzare la Risposta ed Estrarre tool_calls
  5. Quando il Modello Richiede Informazioni Mancanti
  6. Gestire il Messaggio di Sistema
  7. Codice Completo per i Passaggi 2–3
  8. Punti chiave

Inviare gli Strumenti all’API Mistral

Hai definito le tue funzioni e le loro specifiche JSON. Ora devi inviarle all’API Mistral e, cosa più importante, capire cosa restituisce il modello. Siamo ora ai passaggi 2 e 3 del processo: il modello riceve la richiesta dell’utente insieme agli strumenti e produce una chiamata di funzione, oppure decide di non farne alcuna, il che è altrettanto istruttivo.

La Prima Richiesta

import os
import json
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

# Strumenti definiti nella lezione precedente
tools = [
    {
        "type": "function",
        "function": {
            "name": "retrieve_payment_status",
            "description": "Retrieves the status of a payment based on the transaction ID.",
            "parameters": {
                "type": "object",
                "properties": {
                    "transaction_id": {
                        "type": "string",
                        "description": "Unique transaction identifier (e.g., T1001)"
                    }
                },
                "required": ["transaction_id"]
            }
        }
    }
]

# Messaggio dell'utente
messages = [
    {"role": "user", "content": "What is the status of payment T1001?"}
]

# Chiamata API con gli strumenti
response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools
)

Comprendere la Risposta del Modello

La risposta contiene un oggetto message che può assumere due forme, e il tuo codice deve gestirle entrambe fin dal primo giorno. Nel primo caso, il modello risponde direttamente perché non è necessaria alcuna funzione: content contiene il testo e tool_calls è None.

# response.choices[0].message.content contiene la risposta testuale
# response.choices[0].message.tool_calls è None
print(response.choices[0].message.content)
# → "Hello! How can I help you?"

Nel secondo caso, il modello vuole chiamare una funzione. La situazione si inverte: content è vuoto o nullo, mentre tool_calls contiene il payload.

# response.choices[0].message.content è None o vuoto
# response.choices[0].message.tool_calls contiene le chiamate
message = response.choices[0].message

if message.tool_calls:
    for tool_call in message.tool_calls:
        print(f"Function: {tool_call.function.name}")
        print(f"Arguments: {tool_call.function.arguments}")
        print(f"ID: {tool_call.id}")

Output tipico:

Function: retrieve_payment_status
Arguments: {"transaction_id": "T1001"}
ID: call_abc123xyz

Analizzare la Risposta ed Estrarre tool_calls

Ecco il codice completo per estrarre correttamente le informazioni da una chiamata di strumento:

message = response.choices[0].message

if message.tool_calls and len(message.tool_calls) > 0:
    tool_call = message.tool_calls[0]

    # Estrai il nome della funzione
    function_name = tool_call.function.name

    # Analizza gli argomenti JSON in un dizionario Python
    function_params = json.loads(tool_call.function.arguments)

    # Recupera l'identificatore univoco della chiamata
    tool_call_id = tool_call.id

    print(f"The model wants to call: {function_name}")
    print(f"With parameters: {function_params}")
    print(f"Call ID: {tool_call_id}")
else:
    # Il modello ha risposto direttamente
    print(f"Response: {message.content}")

Da questo blocco emergono tre informazioni, e la terza è quella che tutti dimenticano. Il nome della funzione serve per lo smistamento, gli argomenti analizzati servono per l’esecuzione della chiamata, ma il tool_call_id è ciò che permette al modello di associare il tuo risultato alla chiamata corretta quando glielo rimandi. Se lo perdi, il turno di conversazione diventa irrecuperabile.

Quando il Modello Richiede Informazioni Mancanti

A volte l’utente non fornisce informazioni sufficienti. Il modello ha una via d’uscita elegante: non chiamare affatto una funzione, ma porre invece una domanda di chiarimento.

messages = [
    {"role": "user", "content": "What is the status of my payment?"}
]

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

message = response.choices[0].message
print(message.content)
# → "I need the transaction ID to check the status.
#     Could you please provide the transaction number?"

Questo comportamento è esattamente ciò che desideri. Il modello sa che transaction_id è elencato in required; invece di inventare un ID plausibile e attivare una richiesta su dati inesistenti, cede la parola all’utente. Questa è anche la migliore dimostrazione dell’utilità del campo required trattato nella lezione precedente.

Gestire il Messaggio di Sistema

Il messaggio di sistema ti permette di inquadrare questo comportamento invece di sperare che accada spontaneamente.

messages = [
    {
        "role": "system",
        "content": "You are a payment tracking assistant. "
                   "Respond in English. "
                   "Use the available tools to answer questions "
                   "about transactions. If the user does not provide "
                   "the transaction ID, ask for it politely."
    },
    {
        "role": "user",
        "content": "What is the status of payment T1001?"
    }
]

Leggilo riga per riga: la prima frase stabilisce il ruolo, la seconda definisce il tono e la lingua dell’assistente, la terza specifica quando usare le funzioni e l’ultima fornisce un’istruzione esplicita per un caso limite: le informazioni mancanti. Questi sono i tre casi d’uso per i quali si raccomanda un messaggio di sistema, e nella maggior parte dei casi sono sufficienti.

Codice Completo per i Passaggi 2–3

Ecco il codice completo e riutilizzabile per inviare una richiesta con gli strumenti. Incapsula tutto quanto visto sopra e normalizza la risposta in un dizionario con due forme, risparmiandoti di disseminare controlli if message.tool_calls in tutta la tua applicazione.

import os
import json
from mistralai.client import Mistral

def call_mistral_with_tools(
    messages: list,
    tools: list,
    model: str = "mistral-large-latest",
    tool_choice: str = "auto"
) -> dict:
    """Invia una richiesta a Mistral con gli strumenti e restituisce la risposta analizzata."""
    client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

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

    message = response.choices[0].message

    if message.tool_calls and len(message.tool_calls) > 0:
        return {
            "type": "tool_call",
            "message": message,
            "tool_calls": [
                {
                    "id": tc.id,
                    "function_name": tc.function.name,
                    "arguments": json.loads(tc.function.arguments)
                }
                for tc in message.tool_calls
            ]
        }

    return {
        "type": "text",
        "message": message,
        "content": message.content
    }

Nota che la list comprehension itera su tutti i tool_calls, non solo sul primo. Il modello può produrne diversi contemporaneamente; una lezione successiva tratterà questo aspetto, ma la tua funzione di utilità è già pronta a gestirli.

Punti chiave

  • Invia tools e messages a client.chat.complete() per abilitare la chiamata di funzione
  • Controlla sempre se message.tool_calls esiste prima di tentare l’analisi
  • Il tool_call_id è obbligatorio per inviare il risultato al modello
  • Gli argomenti sono una stringa JSON che deve essere analizzata con json.loads()
  • Il modello può scegliere di rispondere direttamente se non ha bisogno di una funzione o se mancano informazioni