Chiamare l'API con gli Strumenti
In questa pagina
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
toolsemessagesaclient.chat.complete()per abilitare la chiamata di funzione - Controlla sempre se
message.tool_callsesiste 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