Programma Lezione 230 di 250 · Progetto: un agente di ricerca che usa strumenti
Progetto: un agente di ricerca che usa strumenti

Registro degli strumenti + smistatore

Ogni "agente IA" di cui hai mai letto si riduce a un componente poco appariscente: un registro degli strumenti. Il modello emette qualcosa come {"tool": "search", "args": {"query": "weather"}}, e il tuo codice deve trovare la funzione Python giusta, controllare che gli argomenti siano sensati, eseguirla, e restituire il risultato. Sbaglia questo strato e tutto l'agente è a un argomento malformato da un crash in produzione. Questa prima lezione del progetto costruisce esattamente quello strato, e riuserai l'idea in ogni lezione successiva.

Stai costruendo lo smistatore per un agente di ricerca. Per cominciare gli servono due strumenti: un search(query) che cerca un fatto, e un calc(op, a, b) che fa aritmetica. Il registro associa al nome di uno strumento una coppia: la funzione, e uno schema degli argomenti (l'insieme dei nomi di argomenti che lo strumento accetta). Lo smistamento è il cancello da cui passa tutto.

class Registry:
    def __init__(self):
        self.tools = {}   # name -> {"fn": callable, "args": set_of_arg_names}

    def register(self, name, fn, args):
        self.tools[name] = {"fn": fn, "args": set(args)}

    def dispatch(self, name, args):
        # 1. unknown tool name      -> raise KeyError
        # 2. args keys != schema    -> raise ValueError (missing OR extra)
        # 3. otherwise              -> call fn(**args) and return the result
        ...

Le regole che dispatch deve imporre (questo è tutto il senso dell'esercizio):

  • Un nome di strumento sconosciuto -> solleva KeyError. L'agente ha chiesto qualcosa che non esiste.
  • Le chiavi del dict args devono corrispondere esattamente allo schema registrato. Un argomento mancante o uno in più -> solleva ValueError. È questo che impedisce a un {"q": ...} allucinato (chiave sbagliata) di non fare niente in silenzio.
  • Una chiamata valida -> esegui fn(**args) e restituisci ciò che restituisce.

Perché un set per lo schema? Perché la validazione diventa una semplice uguaglianza di insiemi: set(args) == self.tools[name]["args"]. Se è falsa, capisci se mancano chiavi o ce ne sono in più e solleva ValueError in entrambi i casi. Chiamare con fn(**args) spalma il dict in argomenti per nome, quindi è la firma della funzione a fare il collegamento finale.

Un responsabile delle assunzioni che legge "ho costruito un agente che usa strumenti" in realtà chiede: hai gestito il percorso infelice? L'agente che viene rilasciato è quello il cui smistatore rifiuta ad alta voce le chiamate sbagliate invece di rovinare un'esecuzione. Premi Run per registrare due strumenti e guardare le chiamate buone riuscire mentre quelle cattive sollevano errori.

Tocca a te

Costruisci una classe Registry. register(name, fn, args) salva la funzione e il suo schema di nomi di argomenti (usa un set). dispatch(name, args) deve: sollevare KeyError per un nome di strumento sconosciuto; sollevare ValueError se le chiavi di args non corrispondono esattamente allo schema (mancanti O in più); altrimenti chiamare fn(**args) e restituire il risultato. Registra uno strumento search(query) e uno calc(op, a, b) così lo smistatore ha qualcosa di vero verso cui instradare.

Hai notato un problema in questa lezione? Segnalalo · Chiedi qualcosa su questa lezione

Questo esercizio si apre presto

Finisci la lezione precedente e questa si sblocca. L'intero corso è gratuito, senza account, e puoi leggere questa lezione subito.