0Pricing
AI Agents · Lezione

Definire gli schemi degli strumenti (JSON Schema)

Scriva definizioni JSON Schema per i parametri degli strumenti, includendo tipi, descrizioni, enumerazioni e campi obbligatori.

Definire gli schemi degli strumenti (JSON Schema) è una lezione AI Agents gratuita su CoddyKit. Questa è la lezione 2 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento AI Agents, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso AI Agents include 4 lezioni in totale.

Gli schemi degli strumenti sono JSON Schema

OpenAI, Anthropic e la maggior parte degli altri usano JSON Schema per i parametri degli strumenti.

Se ha già usato OpenAPI / Swagger, conosce già il 90% di questo argomento.

I tre campi obbligatori

Ogni definizione di strumento contiene:

  1. name — identificatore univoco (snake_case)
  2. description — cosa fa lo strumento e quando usarlo
  3. parameters — JSON Schema degli input

Uno schema minimo

Un oggetto con un campo stringa obbligatorio:

schema = {
    'name': 'search_orders',
    'description': 'Find orders by customer email',
    'parameters': {
        'type': 'object',
        'properties': {
            'email': {
                'type': 'string',
                'description': 'Customer email address'
            }
        },
        'required': ['email']
    }
}
import json
print(json.dumps(schema, indent=2))

Tipi di JSON Schema

  • string — testo
  • integer, number — numeri
  • boolean — vero/falso
  • array — elenco (richiede anche items)
  • object — dizionario (richiede anche properties)

Enum per insiemi chiusi

Usi enum quando esistono esattamente N valori consentiti:

unit_param = {
    'unit': {
        'type': 'string',
        'enum': ['C', 'F'],
        'description': 'Temperature unit'
    }
}
# The model will only ever output C or F
print(unit_param)
print("Allowed values:", unit_param['unit']['enum'])

Parametri array

Per gli input sotto forma di elenco, imposti items:

tags_param = {
    'tags': {
        'type': 'array',
        'items': {'type': 'string'},
        'description': 'List of tags to filter by'
    }
}
print(tags_param)

Oggetti annidati

Può annidare gli oggetti, ma mantenga gli schemi poco profondi (massimo 2-3 livelli) per garantire l'affidabilità del modello:

filter_param = {
    'filter': {
        'type': 'object',
        'properties': {
            'min_price': {'type': 'number'},
            'in_stock': {'type': 'boolean'}
        }
    }
}
print(filter_param)

I campi description sono fondamentali

Il modello sceglie gli strumenti e compila gli argomenti in base a description. Tratti le descrizioni come documentazione dell'API:

# Bad
bad = {'description': 'gets data'}

# Good
good = {'description': 'Fetch the most recent 50 orders for the given customer email. Returns order_id, status, total. Use this when the user asks about their order history or order status.'}
print("Bad description:", bad['description'])
print("Good description:", good['description'])

Array required

Indichi esplicitamente i campi obbligatori. Il modello li compilerà sempre; i campi facoltativi verranno compilati solo quando pertinenti:

tool_params = {
    'parameters': {
        'properties': {
            'city': {'type': 'string'},
            'unit': {'type': 'string', 'enum': ['C', 'F']}
        },
        'required': ['city']
    }
}
print(tool_params)
print("Required fields:", tool_params['parameters']['required'])

Pydantic -> JSON Schema

Può generare automaticamente gli schemi dai modelli Pydantic:

from pydantic import BaseModel, Field

class SearchArgs(BaseModel):
    email: str = Field(description='Customer email')
    limit: int = Field(50, description='Max orders to return')

schema = SearchArgs.model_json_schema()

Modalità strict (OpenAI Structured Outputs)

L'aggiunta di strict: true e additionalProperties: false garantisce che l'output del modello corrisponda esattamente allo schema:

tools = [{
    'type': 'function',
    'function': {
        'name': 'get_weather',
        'strict': True,
        'parameters': {
            'type': 'object',
            'properties': {'city': {'type': 'string'}},
            'required': ['city'],
            'additionalProperties': False
        }
    }
}]
import json
print(json.dumps(tools, indent=2))

Importanza delle descrizioni

Perché la description di uno strumento è così importante?

Riepilogo

Gli schemi guidano il modello. Buone descrizioni, enum per gli insiemi chiusi, array required e strict mode sono le leve per ottenere affidabilità.

Domande Frequenti

La lezione «Definire gli schemi degli strumenti (JSON Schema)» è gratuita?

Sì — il testo completo di «Definire gli schemi degli strumenti (JSON Schema)» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso AI Agents, passa a CoddyKit PRO. Il corso AI Agents include 4 lezioni in totale.

Cosa imparerò in «Definire gli schemi degli strumenti (JSON Schema)»?

Scriva definizioni JSON Schema per i parametri degli strumenti, includendo tipi, descrizioni, enumerazioni e campi obbligatori. Eserciti AI Agents con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare AI Agents?

Non è richiesta alcuna esperienza precedente. AI Agents su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 2 di 4.

Quanto tempo richiede la lezione «Definire gli schemi degli strumenti (JSON Schema)»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione AI Agents?

Sì. Ogni lezione AI Agents include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

  1. Come funziona il function calling
  2. Definire gli schemi degli strumenti (JSON Schema)
  3. Scegliere gli strumenti a runtime
  4. Restituire i risultati al modello
← Torna a AI Agents