Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Definire gli strumenti in JSON

Lezione 4 di 14 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Dalla teoria alla pratica
  2. Struttura della richiesta con strumenti
  3. Cifre chiave dell’implementazione
  4. Gestire la risposta tool_call
  5. Eseguire e restituire il risultato
  6. Definire più strumenti
  7. Controllare finish_reason
  8. Punti chiave

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

200
Strumenti massimi per richiesta
6
Tipi JSON supportati
3
SDK compatibili
1
Richiesta = intero flusso

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 messages e tools (definizioni)
  • Gli argomenti di tool_call sono una stringa JSON da analizzare
  • Invia il risultato in un messaggio con ruolo tool includendo il tool_call_id
  • Controlla finish_reason per sapere se il modello sta aspettando un risultato
  • Puoi dichiarare più strumenti: il modello sceglie automaticamente