Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Ricerca strumenti: strumenti dinamici

Lezione 15 di 20 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Ricerca strumenti: strumenti dinamici
  2. Il problema dei grandi cataloghi di strumenti
  3. Abilitare la Ricerca strumenti
  4. Organizzare il catalogo delle funzioni
  5. Migliori pratiche per le descrizioni
  6. Combinare la Ricerca strumenti con strumenti fissi
  7. Pattern: sistema multi-dominio
  8. Punti chiave

Lezione aggiornata il 2 novembre 2026 sulla base della documentazione OpenAI: lo strumento Code Interpreter richiede ora un parametro container (aggiunto a tutti gli esempi), le parti di testo in input sono tipizzate come input_text e la ricerca web utilizza lo strumento web_search (web_search_preview è ora uno strumento legacy senza filtri di dominio). I file generati vengono recuperati utilizzando le funzioni fichiers_generes e telecharger della Lezione 10. Fonti: Code Interpreter · Ricerca web.

Ricerca strumenti: strumenti dinamici

Quando hai decine o centinaia di funzioni, dichiararle tutte in ogni chiamata diventa controproducente: il modello perde precisione e i costi esplodono. La Ricerca strumenti risolve questo problema permettendo al modello di cercare lo strumento giusto in un catalogo indicizzato.

Il problema dei grandi cataloghi di strumenti

Il costo di un ampio catalogo di strumenti è invisibile in due modi. Primo, finanziariamente: ogni definizione di funzione viene inviata con ogni richiesta, incluse le novantotto che non verranno utilizzate. Su larga scala, questo finisce per superare il costo delle risposte stesse. Secondo, e più seriamente, qualitativamente: oltre alcune decine di strumenti con ambiti sovrapposti, il modello fa scelte peggiori. Troppe opzioni degradano il processo decisionale, qui come altrove.

# 5 funzioni = ~500 token di contesto
# 50 funzioni = ~5000 token di contesto
# 200 funzioni = impossibile da gestire in modo efficiente

# Il modello perde precisione quando ci sono troppe funzioni
# A volte sceglie la funzione sbagliata o allucina parametri

Abilitare la Ricerca strumenti

La Ricerca strumenti ribalta la logica: invece di presentare tutto al modello, indichi il catalogo e mostri solo ciò che corrisponde alla richiesta corrente. Il meccanismo si basa sulla ricerca semantica sulle descrizioni, motivo per cui la prossima sezione non è solo un consiglio di stile; è un requisito affinché il sistema funzioni.

from openai import OpenAI

client = OpenAI()

# Dichiara un gran numero di funzioni
all_functions = [
    {
        "type": "function",
        "name": "create_invoice",
        "description": "Crea una nuova fattura per un cliente",
        "parameters": {"type": "object", "properties": {"client_id": {"type": "string"}}, "required": ["client_id"]}
    },
    {
        "type": "function",
        "name": "cancel_invoice",
        "description": "Annulla una fattura esistente",
        "parameters": {"type": "object", "properties": {"invoice_id": {"type": "string"}}, "required": ["invoice_id"]}
    },
    # ... dozzine di altre funzioni
]

# Usa la Ricerca strumenti per permettere al modello di trovare la funzione giusta
response = client.responses.create(
    model="gpt-5.6-terra",
    input="Annulla fattura FAC-2026-0042",
    tools=[{
        "type": "tool_search",
        "tool_search": {
            "tools": all_functions
        }
    }]
)

Il modello riceve nel suo contesto solo le funzioni rilevanti per la richiesta, non l’intero catalogo.

Organizzare il catalogo delle funzioni

Due principi sono sufficienti per strutturare un catalogo che rimanga navigabile. Prefissa i nomi per dominio (crm_, billing_, inventory_): la lettura della traccia di esecuzione diventa immediata e le collisioni di nomi scompaiono. E assegna a ogni funzione un ambito chiaro: due funzioni le cui descrizioni si sovrappongono produrranno scelte instabili, sia che a fare la chiamata sia un umano o un motore vettoriale.

crm_catalog = [
    {
        "type": "function",
        "name": "crm_search_customer",
        "description": "Cerca un cliente nel CRM per nome, email o ID. "
                       "Usa per trovare informazioni su un cliente esistente.",
        "parameters": {
            "type": "object",
            "properties": {
                "term": {"type": "string", "description": "Termine di ricerca"},
                "field": {"type": "string", "enum": ["name", "email", "id"]}
            },
            "required": ["term"],
            "additionalProperties": False
        },
        "strict": True
    },
    {
        "type": "function",
        "name": "crm_create_customer",
        "description": "Crea un nuovo cliente nel CRM. "
                       "Usa quando un cliente non esiste ancora.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string"},
                "email": {"type": "string"},
                "company": {"type": "string"}
            },
            "required": ["name", "email", "company"],
            "additionalProperties": False
        },
        "strict": True
    }
]

billing_catalog = [
    {
        "type": "function",
        "name": "bill_create_invoice",
        "description": "Crea una fattura. Richiede un cliente esistente.",
        "parameters": {
            "type": "object",
            "properties": {
                "client_id": {"type": "string"},
                "lines": {"type": "array", "items": {"type": "object", "properties": {
                    "description": {"type": "string"},
                    "amount": {"type": "number"}
                }}}
            },
            "required": ["client_id", "lines"],
            "additionalProperties": False
        },
        "strict": True
    }
]

# Unisci tutti i cataloghi
full_catalog = crm_catalog + billing_catalog

Migliori pratiche per le descrizioni

Scrivi descrizioni per la ricerca, non per la documentazione. «Recupera dati cliente» non verrà mai trovato da una query su «storico ordini» o «dettagli contatto fatturazione»: le parole che i tuoi utenti digitano realmente devono apparire nel testo indicizzato. Una descrizione utile nomina casi d’uso e vocabolario aziendale, non dettagli implementativi.

# Sbagliato: troppo generico
{"name": "get_data", "description": "Recupera dati"}

# Corretto: specifico con contesto d'uso
{
    "name": "hr_check_leave_balance",
    "description": "Controlla il saldo ferie di un dipendente (vacanze, permessi personali, malattia). "
                   "Restituisce i giorni rimanenti per tipo di permesso. "
                   "Usa quando un dipendente chiede quanti giorni gli restano."
}

# Corretto: con sinonimi per migliorare la ricerca
{
    "name": "acct_reconcile_bank",
    "description": "Riconciliazione bancaria: confronta le scritture contabili "
                   "con le transazioni bancarie. Riconciliazione conti. "
                   "Usa per verificare la coerenza tra i registri contabili "
                   "e gli estratti conto bancari."
}

Combinare la Ricerca strumenti con strumenti fissi

La combinazione è la modalità operativa standard in produzione. Alcuni strumenti trasversali—ora, utente corrente, ricerca documenti—rimangono dichiarati permanentemente perché servono quasi ogni richiesta, mentre il catalogo aziendale rimane dinamico. Questo mantiene il contesto leggero senza costringere il modello a cercare ogni volta ciò di cui ha bisogno.

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Cerca sul web le vendite di questo mese e crea la fattura corrispondente",
    tools=[
        # Strumenti sempre disponibili
        {"type": "web_search"},
        {"type": "code_interpreter", "container": {"type": "auto"}},
        # Catalogo dinamico
        {
            "type": "tool_search",
            "tool_search": {
                "tools": full_catalog  # 200+ funzioni
            }
        }
    ]
)

Pattern: sistema multi-dominio

class MultiDomainSystem:
    def __init__(self):
        self.client = OpenAI()
        self.catalogs = {}

    def register_domain(self, name: str, functions: list[dict]):
        """Registra un catalogo di funzioni per un dominio."""
        self.catalogs[name] = functions

    def full_catalog(self) -> list[dict]:
        """Unisce tutti i cataloghi."""
        result = []
        for functions in self.catalogs.values():
            result.extend(functions)
        return result

    def execute(self, query: str) -> str:
        """Esegue una query con la Ricerca strumenti su tutti i domini."""
        response = self.client.responses.create(
            model="gpt-5.6-terra",
            input=query,
            tools=[{
                "type": "tool_search",
                "tool_search": {
                    "tools": self.full_catalog()
                }
            }]
        )

        # Elabora le chiamate di funzione
        for item in response.output:
            if item.type == "function_call":
                result = self.dispatcher(item.name, item.arguments)
                # ... ciclo di chiamata funzione

        return response.output_text

    def dispatcher(self, name: str, arguments: str):
        """Instrada la chiamata al servizio corretto."""
        # La tua logica di instradamento
        pass

# Utilizzo
system = MultiDomainSystem()
system.register_domain("crm", crm_catalog)
system.register_domain("billing", billing_catalog)
system.register_domain("hr", hr_catalog)
system.register_domain("support", support_catalog)

# Il modello trova automaticamente la funzione giusta
# tra centinaia di possibilità
result = system.execute("Quanti giorni di ferie restano a Marie Dupont?")

Punti chiave

  • La Ricerca strumenti risolve il problema dei grandi cataloghi di funzioni
  • Il modello riceve nel suo contesto solo le funzioni rilevanti
  • Descrizioni ricche e specifiche sono essenziali per la precisione
  • Prefissa i nomi delle funzioni per dominio per la leggibilità
  • Combina la Ricerca strumenti con strumenti integrati sempre disponibili