Definire gli strumenti in JSON
In questa pagina
Dalla teoria alla pratica
Ora hai compreso il concetto di function calling e la struttura degli schemi JSON. È il momento di passare all’implementazione concreta. In questa lezione, imparerai come costruire una richiesta completa con le definizioni degli strumenti e gestire la risposta del modello.
Struttura della richiesta con strumenti
Ecco una richiesta completa alle API di Grok con uno strumento definito:
from openai import OpenAI
client = OpenAI(
api_key="your-api-key",
base_url="https://api.x.ai/v1"
)
tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get the current weather for a city",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "City name"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"default": "celsius"
}
},
"required": ["city"]
}
}
}
]
response = client.chat.completions.create(
model="grok-4.5",
messages=[
{"role": "user", "content": "What's the weather like in Paris?"}
],
tools=tools
)
Nota la struttura annidata: l’oggetto tools contiene un array, dove ogni elemento ha un type e un oggetto function con i dettagli.
Cifre chiave dell’implementazione
Gestire la risposta tool_call
Quando il modello decide di chiamare una funzione, la risposta contiene un array tool_calls:
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}")
Il campo tool_call.function.arguments è una stringa JSON (non un oggetto Python). Devi analizzarla (parse):
import json
args = json.loads(tool_call.function.arguments)
city = args["city"]
unit = args.get("unit", "celsius")
Eseguire e restituire il risultato
Una volta eseguita la funzione, invii il risultato al modello in una seconda chiamata:
import json
# 1. Esegui la funzione
weather_data = get_weather(city="Paris", unit="celsius")
# 2. Costruisci i messaggi con il risultato
messages = [
{"role": "user", "content": "What's the weather like in Paris?"},
message, # La risposta del modello con tool_calls
{
"role": "tool",
"tool_call_id": tool_call.id,
"content": json.dumps(weather_data)
}
]
# 3. Chiama di nuovo il modello con il risultato
final_response = client.chat.completions.create(
model="grok-4.5",
messages=messages,
tools=tools
)
print(final_response.choices[0].message.content)
Il messaggio con ruolo tool deve contenere:
tool_call_id: l’identificatore univoco del tool_call (per collegarlo alla richiesta)content: il risultato come stringa JSON
Definire più strumenti
Puoi dichiarare quanti strumenti desideri nell’array tools:
tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get the current weather for a city",
"parameters": { ... }
}
},
{
"type": "function",
"function": {
"name": "search_restaurants",
"description": "Search for restaurants by city and cuisine type",
"parameters": { ... }
}
},
{
"type": "function",
"function": {
"name": "book_table",
"description": "Book a table at a restaurant",
"parameters": { ... }
}
}
]
Il modello sceglierà automaticamente lo strumento o gli strumenti pertinenti in base alla richiesta dell’utente.
Controllare finish_reason
Il campo finish_reason nella risposta indica se il modello ha terminato la sua risposta o se sta aspettando un risultato dallo strumento:
finish_reason = response.choices[0].finish_reason
if finish_reason == "tool_calls":
# Il modello sta aspettando il risultato di uno o più strumenti
handle_tool_calls(response)
elif finish_reason == "stop":
# Il modello ha terminato la sua risposta
print(response.choices[0].message.content)
Punti chiave
- La richiesta contiene
messagesetools(definizioni) - Gli argomenti di tool_call sono una stringa JSON da analizzare
- Invia il risultato in un messaggio con ruolo
toolincludendo iltool_call_id - Controlla
finish_reasonper sapere se il modello sta aspettando un risultato - Puoi dichiarare più strumenti: il modello sceglie automaticamente