LlamaIndex: Context-Augmented LLM Applications

Ciao, sono Alex di DEV STORIES DOT EU. LlamaIndex: Applicazioni LLM Context-Augmented, episodio 1 di 14. I modelli pre-addestrati sono fantastici, ma non sanno assolutamente nulla dei documenti privati che hai creato stamattina. Chiedi a un LLM di fare un summary del tuo nuovissimo slide deck finanziario del Q3, e lui o tira a indovinare alla cieca o ti dice che non può aiutarti. L'imperativo della Context Augmentation è come risolvi questo problema. I Large Language Model possiedono incredibili capacità di ragionamento, ma la loro conoscenza è congelata nel tempo e limitata ai dati pubblici. Non hanno accesso ai tuoi wiki interni, ai tuoi ticket del customer support o ai tuoi report finanziari privati. LlamaIndex esiste proprio per colmare questa esatta lacuna. Funge da tessuto connettivo tra i foundation model e i tuoi dati privati e localizzati. Quando chiedi a un modello di fare un summary di quello slide deck del Q3, non puoi semplicemente inviare la domanda. Hai bisogno di un sistema che trovi le slide pertinenti, estragga il testo e fornisca quelle informazioni specifiche al modello insieme al tuo prompt. Questo processo è la Context Augmentation. Stai dando al modello il contesto esatto di cui ha bisogno per applicare le sue capacità di ragionamento ai tuoi dati privati. LlamaIndex fornisce l'infrastruttura per fare ingestion, organizzare e recuperare i tuoi dati in modo che la Context Augmentation avvenga in modo affidabile. Fare il fetch del testo e rispondere a una singola domanda è solo la base. Le applicazioni moderne richiedono maggiore autonomia. Questo ci porta alle applicazioni agentic. Un'applicazione agentic non si limita a seguire una linea retta da una domanda a un database e poi a una risposta. Prende decisioni lungo il percorso per gestire intenti complessi dell'utente. Il primo elemento di tutto questo è il routing. Quando un utente fa una domanda, il sistema deve decidere quale data source o tool sia appropriato. Se l'utente chiede un summary aziendale ad alto livello, il router indirizza la query all'index dello slide deck del Q3. Se l'utente chiede l'esatta ripartizione numerica delle vendite regionali, il router potrebbe invece inviare la query a un database SQL strutturato. Il routing garantisce che il modello utilizzi il tool giusto per il lavoro in base all'input. Il secondo elemento è il prompt chaining. Spesso, i task complessi falliscono quando chiedi a un modello di gestirli con un unico, enorme prompt. Il prompt chaining scompone un obiettivo complesso in task più piccoli e sequenziali. Il sistema potrebbe lanciare un prompt per estrarre i dati di fatturato dallo slide deck, passare questi dati a un secondo prompt che li confronta con i dati storici e inviare quell'output a un terzo prompt che redige un executive summary. L'output di uno step diventa il contesto esatto per lo step successivo. È qui che la cosa si fa interessante. Anche con i dati giusti e una chain strutturata, i modelli commettono errori. Questo introduce la reflection. La reflection è uno step automatizzato di controllo qualità. Prima di consegnare all'utente il summary finale del deck del Q3, l'applicazione agentic utilizza un prompt separato per valutare la propria bozza. Verifica se il testo generato è pienamente supportato dalle slide recuperate. Se lo step di reflection rileva un'hallucination o una metrica chiave omessa, rifiuta la bozza e innesca una correzione. Il vero potere delle applicazioni context-augmented non sta semplicemente nel dare a un LLM un documento da leggere, ma nel fornirgli un workflow strutturato e autocorrettivo per ragionare in modo sicuro sui tuoi dati privati. Se vuoi aiutarci a far andare avanti lo show, puoi cercare DevStoriesEU su Patreon e supportarci lì. Questo è tutto per questo episodio. Grazie per l'ascolto e continua a sviluppare!

Ciao, sono Alex di DEV STORIES DOT EU. LlamaIndex: Context-Augmented LLM Applications, episodio 2 di 14. Non puoi semplicemente buttare un PDF di 500 pagine nella context window di un LLM e aspettarti una risposta precisa. Il modello perderà il filo, avrà delle allucinazioni, o semplicemente rifiuterà il payload per aver superato i suoi limiti. Per rendere utili questi file enormi, devi farli a pezzi e tradurli in un formato matematico che la macchina possa cercare. Questo processo è esattamente ciò di cui parliamo oggi in Data Ingestion: Documents e Nodes. Pensa di dover elaborare un enorme manuale HR per i dipendenti. Il testo si trova in un PDF gigantesco, che si estende per decine di capitoli complessi. Il primo passo in una pipeline di Retrieval-Augmented Generation è la fase di loading. È qui che entrano in gioco i Data Connectors, spesso chiamati Readers. Un connector prende la tua sorgente dati grezza, che sia un PDF locale, una tabella di un database remoto o la response di un'API esterna, e la incapsula in una struttura dati chiamata Document. Le persone spesso fanno confusione su questo termine. In questo framework, un Document non significa un file Word o un PDF. Un Document è semplicemente un contenitore generico per qualsiasi sorgente dati di cui hai fatto l'ingestion. Contiene il testo grezzo insieme ad alcune properties di base. Tuttavia, un singolo Document che rappresenta un manuale di 500 pagine è completamente inutile per una ricerca precisa e veloce. Devi scomporlo. Questo ci porta ai Nodes. Un Node è la vera unità atomica di dati in LlamaIndex. È un chunk più piccolo e gestibile di un Document padre, magari un singolo paragrafo che descrive la policy sul congedo parentale. Quando elabori il manuale HR, il framework prende l'enorme Document e lo affetta in migliaia di Nodes. Ecco il punto chiave. I Nodes non contengono solo testo isolato. Portano con sé metadata ricchi e relazioni strutturali. Un Node sa esattamente da quale Document padre proviene. Sa anche quale Node lo precede logicamente e quale Node lo segue. Questa struttura collegata è ciò che permette al sistema di sintetizzare un context più ampio in un secondo momento, se un singolo chunk non contiene l'intera risposta. Una volta che hai spezzettato i tuoi dati in Nodes precisi, passi alla fase di indexing. Ti serve un modo robusto per trovare il Node corretto quando un utente, in seguito, fa una domanda. Questo richiede la traduzione del linguaggio umano in un formato numerico chiamato embedding. Un embedding è un array di numeri in virgola mobile che rappresenta il significato semantico del testo all'interno del Node. Passi ogni Node attraverso un modello di embedding. Il modello legge il chunk e restituisce un vector ad alta dimensionalità. Se due Nodes trattano argomenti concettualmente simili, come il congedo per malattia e le ferie retribuite, i loro vectors numerici si troveranno matematicamente vicini nello spazio. Con questi vectors generati, costruisci un Index. L'Index è il componente strutturale principale che organizza i tuoi Nodes in modo che possano essere interrogati. Per la maggior parte delle applicazioni, questo Index è supportato da un Vector Store. Il Vector Store funge da database specializzato, progettato esplicitamente per contenere queste rappresentazioni matematiche ed eseguire calcoli di similarità altamente efficienti su di esse. Il flusso logico è altamente prevedibile. Per prima cosa, configuri un Data Connector per puntare al tuo manuale HR. Il connector legge il file e restituisce in output un singolo oggetto Document. Successivamente, un parser prende quel Document e lo divide in un array di oggetti Node indipendenti. Infine, passi quell'array di Nodes a un Index, che coordina la creazione dei vector embeddings e li salva nel Vector Store. L'intera pipeline di ingestion esiste per risolvere un limite fondamentale. I Large Language Models non possono leggere in modo affidabile interi libri in una sola volta, ma possono calcolare all'istante la distanza matematica tra due array di numeri. Tradurre i tuoi file grezzi in Documents, affettarli in Nodes collegati e codificarli in vector indexes è ciò che colma questa lacuna. Questo è tutto per questo episodio. Grazie per l'ascolto, e continua a sviluppare!

Ciao, sono Alex di DEV STORIES DOT EU. LlamaIndex: Context-Augmented LLM Applications, episodio 3 di 14. Prendi il chunk di documento giusto, lo mandi al language model e ottieni comunque una risposta sbagliata perché era sepolto sotto dieci chunk irrilevanti. Trovare il testo è solo metà dell'opera. Fare filtering, ranking e decidere come fare il fetch fin dall'inizio è ciò che determina davvero il successo o il fallimento del sistema. Oggi vediamo la fase di execution della RAG, nello specifico la Query Pipeline: Retriever e Router. A questo punto, i tuoi dati sono già caricati e indicizzati. Un utente invia una query. Il primo componente a intercettare questa query è spesso un router. Un router è un motore decisionale. Guarda la domanda in arrivo e determina quale tool o index sottostante sia il più adatto per rispondere. Mettiamo che un utente faccia una domanda complessa su uno specifico evento storico che include anche acronimi molto specifici. Una vector search standard potrebbe cogliere il significato semantico dell'evento, ma perdersi gli acronimi. Una keyword search centrerà in pieno gli acronimi, ma si perderà il context più ampio. Il router valuta la query e decide di mandarla su due percorsi contemporaneamente. Fa il routing della richiesta sia a una vector search che a una keyword search. Questo ci porta ai retriever. Un retriever ha il compito di definire esattamente come fare il fetch del context rilevante da un index. Non genera risposte. Fa solo il fetch dei dati. Tornando al nostro scenario, il vector retriever converte la query dell'utente in un embedding e tira fuori i node matematicamente più simili, che sono semplicemente dei chunk dei tuoi documenti sorgente. Allo stesso tempo, il keyword retriever tira fuori i node che contengono exact match testuali per quegli acronimi. Ora hai due pile distinte di node. Non puoi semplicemente fare l'append di tutti quanti alla cieca nel prompt del tuo language model. Le context window sono limitate e i model si distraggono facilmente con dati irrilevanti. È qui che entrano in gioco i node postprocessor. Ecco il punto chiave. I node postprocessor fanno da gatekeeper tra i retriever e il language model. Applicano logiche di trasformazione, filtering o re-ranking ai node estratti. Per esempio, un postprocessor può applicare un similarity cutoff, scartando tutti i node con uno score sotto una certa soglia. Può deduplicare i node se la vector search e la keyword search hanno per caso tirato fuori l'esatto stesso paragrafo. Può anche fare il re-ranking dei node rimanenti, in modo che il chunk in assoluto più rilevante si trovi in cima alla context window. Una volta che il postprocessor ha pulito e ordinato i dati, il sistema li passa al response synthesizer. Il synthesizer ha un solo compito. Prende la lista ripulita di node e la query originale dell'utente, li combina in un prompt strutturato e li manda al language model. Il language model genera quindi la risposta finale human-readable basandosi esclusivamente su quel context fornito. La fase di execution della query è a tutti gli effetti una pipeline. Fai il routing della query, fai il retrieve dei node grezzi, filtri e fai il ranking di quei node con un postprocessor, e infine sintetizzi il testo. Se controlli quello che vede il language model, controlli la qualità dell'output. Grazie per aver passato qualche minuto con me. Alla prossima, stammi bene.

Ciao, sono Alex di DEV STORIES DOT EU. LlamaIndex: Context-Augmented LLM Applications, episodio 4 di 14. Stai creando un agent che gestisce i ticket di supporto IT, ma metà delle segnalazioni sono solo foto di spie di errore lampeggianti scattate con lo smartphone. L'elaborazione text-only ti costringe a creare pipeline di vision separate o a rinunciare completamente al contesto visivo. Oggi parliamo di interfacciamento con gli LLM e di input multi-modal, che risolvono questo problema direttamente al layer del modello. In LlamaIndex, l'interazione con un LLM passa attraverso la classe base LLM. Questa funge da interfaccia unificata. Che tu stia chiamando un modello OpenAI, un modello Anthropic o un provider diverso, i metodi principali che usi sono identici. Questa astrazione protegge la logica della tua applicazione dai cambiamenti delle API specifici del provider. Quando vuoi una risposta dal modello, puoi scegliere tra due metodi principali. Il primo è il metodo complete. Gli passi una singola string contenente il tuo prompt, e lui ti restituisce una singola risposta testuale. Questo è pensato per task semplici e single-shot, come riassumere un documento o estrarre un dato specifico. Il secondo è il metodo chat. È progettato per conversazioni o interazioni strutturate. Invece di una singola string, passi una lista di oggetti chat message. A ogni messaggio è associato un ruolo specifico, in genere system, user o assistant. Passando una lista, il metodo chat fornisce al modello il contesto completo di uno scambio di battute prima di generare la risposta successiva. Sia complete che chat aspettano che il modello finisca l'intera generazione prima di restituire l'output. Se il modello sta scrivendo una risposta lunga, la tua applicazione rimane inattiva. Per risolvere questo problema, usi lo streaming. Chiami invece stream complete o stream chat. Questi metodi restituiscono un generator. Man mano che il modello produce token, il tuo codice li riceve in piccoli chunk. Fai un loop su questo generator per stampare la risposta su una user interface in real-time, eliminando la percezione di latenza. Ora, la seconda parte riguarda la gestione dei dati non testuali. Ed è qui che la cosa si fa interessante. I moderni LLM analizzano le informazioni visive, e LlamaIndex lo supporta tramite i content block. Invece di passare una semplice string di testo dentro un user chat message, puoi passare una lista di block. Ripensa al ticket di supporto IT con il server rack guasto. Hai bisogno che il modello guardi la foto e legga le tue istruzioni diagnostiche. Per prima cosa, crei un ImageBlock. Fornisci a questo block i dati dell'immagine. LlamaIndex ti permette di passare un file path locale, un URL diretto, o byte raw codificati in base64. Successivamente, crei un TextBlock. Gli passi il tuo prompt di testo, chiedendo al modello di identificare il guasto hardware mostrato nella foto. Metti sia l'ImageBlock che il TextBlock in un'unica lista, e alleghi quella lista a un nuovo user chat message. Quando passi questo messaggio al metodo chat di un modello vision-capable, l'LLM elabora il layout visivo del server rack insieme alle tue istruzioni di testo. Restituisce una diagnosi basata su entrambi gli input combinati. Ecco il punto chiave. La vera forza di questa architettura è la sua coerenza. Che tu stia inviando una string di una sola riga, facendo lo streaming di una risposta in real-time, o passando un array complesso di text e image block, il pattern di interazione con la classe LLM rimane completamente standardizzato in tutta la tua codebase. Per questo episodio è tutto. Alla prossima!

Ciao, sono Alex di DEV STORIES DOT EU. LlamaIndex: Context-Augmented LLM Applications, episodio 5 di 14. Niente manda in tilt una production pipeline più velocemente di un LLM che decide di aggiungere "Certo, ecco il tuo JSON" proprio prima del data payload effettivo. Chiedi un output machine-readable, ottieni del filler conversazionale e il tuo parser va in crash all'istante. Colmare il divario tra il linguaggio naturale non strutturato e dei programmatic types affidabili è esattamente ciò che risolve la Structured Data Extraction con Pydantic. Prendi lo scenario in cui devi fare il parsing di una inbox email disordinata, piena di messaggi di fornitori, solleciti di pagamento e ricevute non strutturate. Il tuo sistema deve estrarre dati strutturati delle fatture da questo testo. Se ti affidi alla text generation standard, ottieni risultati imprevedibili. Una response potrebbe usare il camel case per le keys, un'altra potrebbe formattare le date in modo diverso, e i prezzi spesso vengono restituiti come string con i simboli delle valute attaccati. Finisci per scrivere infinita logica di string manipulation solo per ottenere un numero utilizzabile dalla response. Invece di chiedere al modello un JSON e sperare che lo rispetti, definisci i tuoi requisiti esatti usando un base model di Pydantic. Crei una classe Python chiamata Invoice. All'interno di questa classe, dichiari i data types precisi che la tua applicazione si aspetta. Definisci la data come string, gli articoli acquistati come una lista di string, e il prezzo totale rigorosamente come float. Ecco il punto chiave. LlamaIndex prende la tua classe Pydantic e la serializza automaticamente in uno strict JSON schema. Quando invii il testo dell'email al modello, LlamaIndex allega questo schema e innesca lo structured output o l'API di function-calling del modello sottostante. Lo schema funge da hard boundary. L'LLM non genera più freeform text. È vincolato a popolare i campi del JSON schema specificamente con i tipi che hai richiesto. Puoi anche guidare il ragionamento del modello direttamente all'interno delle tue data structures. Allegando una field description a un attributo, fornisci istruzioni mirate all'LLM. Per l'attributo price, potresti aggiungere una field description che indichi di estrarre il costo totale finale, ignorando le spese di spedizione. L'LLM legge questa descrizione come parte della schema definition e applica quella logica durante la fase di extraction. Quando la response viene restituita, LlamaIndex non ti consegna una raw string o un dictionary generico. Processa la response tramite Pydantic e restituisce un oggetto Invoice completamente istanziato. I dati sono già validati. Poiché il framework sfrutta le feature native di structured output, il modello sa in anticipo che deve fornire un float effettivo per il price, non una sua rappresentazione a string. Puoi accedere immediatamente all'attributo invoice punto price nel tuo codice ed eseguire operazioni matematiche su di esso. Non c'è bisogno di ripulire il filler conversazionale, rimuovere i simboli del dollaro o fare il cast delle string a numeri. La transizione dal linguaggio naturale alla application logic avviene in modo fluido all'extraction layer. Spingendo il tuo data schema direttamente nel processo di extraction, costringi l'LLM ad adattarsi al tuo application code, anziché scrivere application code fragile per tollerare il comportamento imprevedibile dell'LLM. Questo è tutto per questo episodio. Grazie per l'ascolto, e continua a sviluppare!

Ciao, sono Alex di DEV STORIES DOT EU. LlamaIndex: Applicazioni LLM Context-Augmented, episodio 6 di 14. Cosa succederebbe se la tua applicazione potesse decidere quali funzioni eseguire in base all'intento dell'utente, anziché usare un set rigido di istruzioni condizionali? Questa è l'idea centrale alla base della creazione di Autonomous Function Agents. Quando costruisci una query pipeline standard, sei tu a dettare il percorso di esecuzione. Un agent ribalta questo paradigma. Tu fornisci un set di tool, e un motore di ragionamento automatico usa un Large Language Model per decidere quali tool chiamare, e in quale ordine, per risolvere un problema. Prima di andare avanti, dobbiamo chiarire un malinteso comune. L'LLM di per sé non esegue il tuo codice Python. Si limita a generare una richiesta di testo strutturata dicendo che vuole chiamare una funzione specifica con argomenti specifici. Il framework dell'agent di LlamaIndex intercetta quella richiesta, esegue il tuo codice Python in locale, e poi restituisce il risultato all'LLM. Per far funzionare questo routing autonomo, ti servono dei tool. Un tool è essenzialmente una funzione Python standard wrappata in una classe di LlamaIndex chiamata FunctionTool. Ma dato che l'LLM deve sapere quando e come usare la tua funzione, i metadati del tuo codice diventano una parte fondamentale del sistema. Il framework estrae il nome della funzione, i type hint e la docstring, e li passa all'LLM come istruzioni. Vediamo uno scenario concreto. Vuoi che il tuo agent risolva dei problemi matematici testuali. Scrivi due funzioni Python, una chiamata add e una chiamata multiply. Per la funzione multiply, i tuoi type hint specificano che accetta due interi e restituisce un intero. Cosa fondamentale, scrivi una docstring che dice chiaramente che questa funzione moltiplica due numeri tra loro. Wrappi entrambe le funzioni in dei tool e le passi in una lista, insieme all'LLM che hai scelto, per inizializzare l'agent. Ed è qui che la cosa si fa interessante. Chiedi all'agent: quanto fa due più due, moltiplicato per tre. L'agent entra in un reasoning loop. Per prima cosa, l'LLM analizza il prompt e guarda i tool disponibili. Legge le tue docstring e decide che prima deve fare un'addizione. Genera in output una richiesta per chiamare il tool add con gli argomenti due e due. Il framework esegue la tua funzione Python in locale e restituisce il risultato, quattro, all'agent. L'agent non ha finito. Guarda il risultato intermedio e il suo obiettivo originale. Decide che ora deve moltiplicare. Richiede il tool multiply, passandogli il quattro che ha appena ricevuto e il tre del tuo prompt originale. Il framework esegue la moltiplicazione e restituisce dodici. Infine, l'LLM riconosce che il problema è risolto e genera una risposta conversazionale per l'utente. Qui non ci sono regole hardcoded o logiche di routing esplicite. L'agent ha capito le dipendenze e l'ordine delle operazioni in modo completamente autonomo, basandosi sui tool disponibili. Questo significa che il modo in cui scrivi le tue definizioni Python detta direttamente quanto sarà intelligente il tuo agent. I tuoi type hint e le tue docstring non sono più solo per altri sviluppatori, sono il prompt letterale che guida la logica autonoma dell'agent. Se stai trovando utili questi episodi e vuoi supportare lo show, puoi cercare DevStoriesEU su Patreon. Per questo episodio è tutto. Grazie per l'ascolto, e continua a sviluppare!

Ciao, sono Alex di DEV STORIES DOT EU. LlamaIndex: Context-Augmented LLM Applications, episodio 7 di 14. Stai creando un agent che deve controllare i prezzi delle azioni, recuperare messaggi da Slack o fare query su un database. Potresti passare giorni a leggere la documentazione delle API, gestire gli schemi di autenticazione e scrivere codice boilerplate di integrazione. Oppure, potresti semplicemente prendere il lavoro già completato e verificato da uno sviluppatore della community. Questo episodio tratta l'estensione degli agent con i tool di LlamaHub. Gli agent si affidano ai tool per interagire con il mondo esterno. Anche se puoi scrivere ogni integrazione manualmente, LlamaHub esiste proprio per eliminare questo lavoro ridondante. Funziona come un vasto registry open-source di tool spec pre-costruite. Una tool specification, o tool spec, è essenzialmente una classe Python che raggruppa più chiamate API correlate in un unico package. Importandole direttamente nel tuo progetto, salti l'intero processo di scrittura della logica sottostante per i servizi di terze parti. Per usare una di queste integrazioni, installi il suo package specifico. Se vuoi che il tuo agent risponda a domande sul prezzo delle azioni di un'azienda, non scrivi una richiesta HTTP custom all'API di Yahoo. Invece, usi il tuo package manager standard per installare il package dei tool Yahoo Finance di LlamaIndex. Una volta installato, importi la classe Yahoo Finance Tool Spec nel tuo script. Ecco il punto chiave. Non passi la classe tool spec direttamente all'agent. Dato che una tool spec è un bundle di diverse funzionalità, devi prima farne l'unpack. Lo fai creando un'istanza della Yahoo Finance Tool Spec, e poi chiamando un metodo specifico su di essa chiamato to_tool_list. Questo metodo scompone il bundle e restituisce un array flat standard di singoli tool che l'agent può leggere ed eseguire. Questo design modulare significa che non sei limitato a usare solo tool esterni o solo tool interni. Puoi combinarli senza problemi. Supponiamo che tu abbia già un function tool locale e custom che formatta i numeri delle valute specificamente per la dashboard interna della tua azienda. Ti basta creare una list Python standard. All'interno di quella list, inserisci il tuo tool custom per la formattazione della valuta, e fai l'append anche dei tool estratti dalla tool list di Yahoo Finance. Poi prendi questo array combinato e lo passi direttamente al tuo agent durante l'inizializzazione, assegnandolo al parametro tools. Quando passi un prompt all'agent con una domanda sul prezzo corrente di un'azione, l'agent valuta la request dell'utente confrontandola con le descrizioni di tutti i tool in quella list combinata. Riconosce che il tool Yahoo Finance è la scelta corretta per recuperare i dati di mercato. Estrae il ticker dell'azienda dal prompt dell'utente, esegue il tool Yahoo Finance, recupera il prezzo in tempo reale e, opzionalmente, può fare il chain di quel risultato raw nel tuo tool di formattazione locale prima di restituire la risposta finale all'utente. Hai appena dato alla tua applicazione complesse funzionalità di ricerca finanziaria installando un package, istanziando una classe e chiamando un metodo di unpack. Questo pattern architetturale si applica a centinaia di integrazioni su LlamaHub, dalla lettura di documenti di Google Drive alle query su Wikipedia. Il vero vantaggio di un agent autonomo non si trova solo nella capacità di ragionamento del language model sottostante, ma nell'enorme ampiezza di sistemi esterni a cui può accedere istantaneamente tramite tool spec pre-costruite. Questo è tutto per questo episodio. Grazie per l'ascolto, e continua a costruire!

Ciao, sono Alex di DEV STORIES DOT EU. LlamaIndex: Context-Augmented LLM Applications, episodio 8 di 14. Dai in pasto a un language model un unico, enorme prompt chiedendogli di fare ricerca su un argomento, scrivere un report e revisionare criticamente il proprio lavoro. E fallisce. La context window si incasina, i tool vengono usati male e l'output è un compromesso superficiale. La soluzione è spezzare quell'enorme prompt in uno sciame di specialisti usando i Multi-Agent Swarms con AgentWorkflow. Un singolo agent troppo carico fa fatica perché ha troppi tool e istruzioni in conflitto tra loro. Deve decidere quando cercare, quando buttare giù una bozza e quando editare, il tutto gestendo un enorme context interno. AgentWorkflow risolve il problema permettendoti di definire un network di agent iper-focalizzati. Ogni agent opera con un system prompt molto specifico, un set limitato di tool e un unico obiettivo. Pensa a una pipeline di generazione di contenuti. Invece di un unico mega-agent, creiamo tre FunctionAgent distinti. Primo, il Researcher. Dotiamo questo agent di un tool di web search e gli diamo istruzioni rigide per raccogliere solo i fatti. Non scrive prosa. Poi, definiamo il Writer. Gli togliamo completamente i tool di ricerca per evitare che si distragga. Il suo unico compito è prendere i fatti grezzi e scrivere paragrafi puliti. Infine, definiamo il Reviewer. Gli diamo delle linee guida sul tono e sull'accuratezza dei fatti, istruendolo a fare una review del testo. Ecco il punto chiave. Avere più agent è inutile se non riescono a coordinarsi, ma dargli carta bianca per parlare con chiunque crea solo caos. Devi collegarli esplicitamente tra loro. In AgentWorkflow, lo fai definendo i permessi di handoff. Quando configuri i tuoi agent, specifichi una property chiamata can handoff to. Questa accetta una lista di altri agent. Per la nostra pipeline, diamo al Researcher il permesso di fare handoff al Writer. Diamo al Writer il permesso di fare handoff al Reviewer. Diamo anche al Reviewer il permesso di fare handoff di nuovo al Writer se il testo ha bisogno di revisioni. Questo crea un grafo orientato e rigoroso di agent. Il framework fa rispettare questi confini. Il Researcher non può bypassare il Writer e mandare gli appunti grezzi direttamente al Reviewer. Semplicemente, non ha l'autorizzazione. Per eseguire il tutto, passi la tua lista di agent a un'istanza di AgentWorkflow. Avvii il processo eseguendo il workflow con una user query iniziale, puntandola al Researcher per dare il via al tutto. Il framework del workflow gestisce automaticamente lo shared state e il routing. Il Researcher esegue i suoi search tool, compila i dati e decide internamente che il suo lavoro è finito. Quindi usa il suo handoff tool per passare il controllo, insieme ai dati raccolti, al Writer. Il Writer prende quel context, butta giù il report e fa handoff al Reviewer. Se il Reviewer nota un difetto, innesca un handoff di ritorno al Writer con dei feedback. Questo loop continua finché un agent non decide che il lavoro è completo e restituisce una risposta finale all'utente invece di innescare un altro handoff. Vincolare un agent a un singolo ruolo e definirne esplicitamente i percorsi di comunicazione è il modo più affidabile per tirare fuori ragionamenti complessi e multi-step dai language model. Questo è tutto per questo episodio. Grazie per l'ascolto, e continuate a sviluppare!

Ciao, sono Alex di DEV STORIES DOT EU. LlamaIndex: Applicazioni LLM Context-Augmented, episodio 9 di 14. Se permetti agli agenti autonomi di passarsi il controllo peer-to-peer, finisci facilmente in loop infiniti o perdi il context. A volte non puoi fare affidamento sugli agenti che si passano il controllo a vicenda. Hai bisogno di un manager centrale che si occupi dell'intera operazione. Questo è il pattern Orchestrator Agent. In un sistema multi-agent, permettere agli agenti di parlare direttamente tra loro sembra una soluzione potente, ma diventa rapidamente un incubo di debugging. Perdi traccia di chi è al comando e gestire il global state dell'applicazione diventa incredibilmente complesso. Il pattern Orchestrator risolve questo problema imponendo rigorosamente un modello hub-and-spoke. C'è un orchestrator agent top-level e tutti gli altri agenti vengono trattati esclusivamente come tool a disposizione di quell'orchestrator. Vediamo uno scenario in cui il tuo sistema deve generare un briefing tecnico con molta ricerca alle spalle. Imposti un orchestrator agent che agisca da manager rigoroso. Questo manager possiede il global state. Ricorda il prompt originale dell'utente, mantiene il master context e tiene traccia di ciò che è stato completato finora. Non fa lui stesso il lavoro pesante. Invece, gli fornisci dei tool. Questi tool non sono semplici API wrapper o calcolatrici di base. Sono sub-agent completamente separati e del tutto funzionali. Potresti creare un sub-agent dedicato alla ricerca, dotato di funzionalità di vector search e web scraping. Potresti creare un secondo sub-agent dedicato alla scrittura, dotato di linee guida stilistiche e logica di formattazione. In LlamaIndex, prendi questi sub-agent ed esponi i loro metodi run come tool. Facendo questo, stai wrappando i loro interi reasoning loop interni dietro un'interfaccia tool standard con un nome e una descrizione. Per l'orchestrator, questi sub-agent sembrano esattamente delle normali funzioni Python. Quando l'utente chiede il briefing, l'orchestrator valuta l'obiettivo generale basandosi sulle descrizioni dei tool che gli hai fornito. Decide di chiamare prima il tool di ricerca e gli passa i parametri necessari. Il controllo passa temporaneamente al sub-agent di ricerca. Questo sub-agent esegue il suo loop autonomo. Potrebbe fare tre o quattro tool call interne per raccogliere dati, sintetizzare i fatti e formulare una risposta. Una volta che il research agent ha finito, condensa tutto quel lavoro in una string di testo finale e la restituisce. Ecco il punto chiave. L'orchestrator non cede mai davvero il controllo del processo principale. Aspetta semplicemente che il tool restituisca un valore. L'orchestrator riceve il riepilogo della ricerca, lo aggiunge al proprio context e valuta il passo successivo. Si rende conto che le informazioni devono essere scritte in un documento, quindi chiama il tool di scrittura, passando la nuova ricerca come parametro di input. Il sub-agent di scrittura prende il controllo, fa la sua elaborazione interna e restituisce il testo finito. L'orchestrator vede che l'obiettivo finale è stato raggiunto e consegna la risposta all'utente. Questa rigorosa separation of concerns rende il tuo sistema altamente prevedibile. Il research agent non ha bisogno di sapere che il writing agent esiste. Nessun sub-agent deve preoccuparsi di passare il context, formattare la risposta finale per l'utente o decidere quando il lavoro complessivo è finito. L'orchestrator centralizza tutta la logica decisionale di alto livello. Costringendo i sub-agent a operare puramente come tool isolati all'interno del loop di un manager centrale, puoi costruire sistemi multi-agent estremamente capaci che rimangono del tutto prevedibili e facili da debuggare. Questo è tutto per questo episodio. Alla prossima!

Ciao, sono Alex di DEV STORIES DOT EU. LlamaIndex: Context-Augmented LLM Applications, episodio 10 di 14. L'agent orchestration built-in è ottima finché la tua business logic non inizia ad assomigliare a un piatto di spaghetti. Quando gli hand-off standard non riescono a gestire le tue regole di scheduling altamente specifiche, le astrazioni diventano un blocker. È proprio in questi casi che hai bisogno dei Custom Multi-Agent Planner. Un custom planner è la tua via di fuga da power-user. Ti permette di costruire il tuo orchestration loop da zero usando un Workflow standard di LlamaIndex. Invece di affidarti a un supervisor pre-built per stabilire quale agent debba agire dopo, controlli l'intero processo di scheduling in modo imperativo in Python. Sei tu a dettare l'ordine di esecuzione, il data routing e lo state management. Il processo di solito inizia all'interno di una custom class, spesso chiamata PlannerWorkflow. La prima fase è il planning. Quando un utente invia una request, il tuo workflow invia un prompt a un Large Language Model. Questo prompt include la user query e una descrizione rigorosa dei tool o degli agent che hai a disposizione. Istruisci esplicitamente il language model a generare un piano step-by-step in un formato altamente strutturato. Ad esempio, potresti dire al modello di racchiudere ogni azione all'interno di un blocco XML usando dei tag step, oppure di formattarlo come un array JSON. Quando il modello risponde, fai il parsing di quell'output strutturato. Usi una libreria come Pydantic per validare l'XML o il JSON e convertirlo in una lista concreta di task su cui il tuo codice può iterare. Ora entri nella fase di esecuzione. Questa parte dipende interamente dalla tua custom logic. Il tuo workflow itera attraverso la lista di step parsati, uno alla volta. Per ogni step, verifica l'azione richiesta. Usi della logica condizionale standard per decidere cosa fare dopo. Se lo step parsato specifica un task di ricerca, il tuo codice chiama esplicitamente il tuo research agent. Se lo step successivo richiede un calcolo, triggeri il tuo math agent. Ecco il punto chiave. Dato che stai scrivendo il loop tu stesso, mantieni la completa ownership dello state. In genere, crei un dictionary di contesto condiviso che vive per tutta la durata della run del workflow. Quando il tuo research agent finisce il suo task, il tuo workflow prende il risultato e lo scrive direttamente in quel dictionary. Quando lo step successivo triggera il math agent, la tua custom logic può passargli i dati esatti richiesti da quel dictionary condiviso. Non devi sperare che un orchestrator black-box passi le variabili giuste. Sei tu a mappare esplicitamente gli output di un agent agli input del successivo. Una volta che il loop ha completato tutti gli step del tuo piano validato, il tuo workflow esegue l'eventuale formattazione finale e restituisce la risposta. Costruire un custom planner significa scambiare la comodità out-of-the-box per il controllo totale. Se un agent fallisce, puoi scrivere una custom retry logic per quello specifico step. Se uno step ha bisogno di una validazione API esterna, puoi mettere in pausa il loop. Stai scrivendo del codice imperativo standard che, per puro caso, usa i language model come funzioni. Il valore finale di un custom planner è la prevedibilità. Forzando il language model a generare un piano XML rigido ed eseguendolo con loop e dictionary Python standard, elimini completamente il guesswork della black-box orchestration. Questo è tutto per questo episodio. Grazie per l'ascolto, e keep building!

Ciao, sono Alex di DEV STORIES DOT EU. LlamaIndex: Applicazioni LLM Context-Augmented, episodio 11 di 14. Costruisci un agent per gestire la tua infrastruttura, e decide che il modo migliore per risolvere un errore è eliminare un database di produzione. Non lasciare mai che un agent autonomo esegua un'azione distruttiva senza prima aver chiesto esplicitamente il permesso a un umano. Per evitare questo, hai bisogno dei workflow Human-in-the-Loop. L'Human-in-the-loop è un meccanismo event-driven che mette in pausa un agent, richiede un input esterno e riprende l'esecuzione in base alla risposta. Invece di lasciare che l'agent esegua ininterrottamente il suo ciclo di pensiero e azione, intercetti le operazioni ad alto rischio. Ottieni questo nei workflow di LlamaIndex utilizzando tre componenti specifici: l'InputRequiredEvent, il metodo wait_for_event e l'HumanResponseEvent. Considera un tool pericoloso progettato per eliminare una risorsa cloud. L'agent decide di dover utilizzare questo tool e attiva il corrispondente step del workflow. Se il tool viene eseguito immediatamente, la risorsa è persa. Invece, lo step del workflow intercetta l'esecuzione. Prima di eliminare qualsiasi cosa, lo step crea un InputRequiredEvent. Questo evento trasporta un payload contenente i dettagli sull'azione, come il nome della risorsa di destinazione e un prompt che chiede all'utente di confermare l'eliminazione. Lo step emette questo evento verso l'applicazione principale. Ecco il punto chiave. Lo step del workflow non può semplicemente rimanere in un loop attivo in attesa di una risposta. Devi sospendere il suo stato. Lo fai chiamando wait_for_event sul context del workflow, specificando che lo step è ora in ascolto di un HumanResponseEvent. Questa azione restituisce il controllo all'ambiente. Il workflow engine mette completamente in pausa lo step, congelando l'agent nel suo stato attuale senza consumare risorse di calcolo durante l'attesa. Al di fuori del workflow, il tuo application layer intercetta l'InputRequiredEvent. Leggi il payload e mostri il prompt di conferma all'utente sulla sua command-line interface. L'umano legge l'avviso e digita sì o no. Ora devi riattivare l'agent. La tua applicazione prende l'input dell'utente e lo incapsula all'interno di un HumanResponseEvent. Invii questo nuovo evento direttamente al workflow engine in esecuzione. L'engine riconosce il tipo di evento e lo instrada all'esatto step che era stato sospeso. Il metodo wait_for_event si risolve, restituendo la string di risposta umana alla logica del tool. Il tool valuta la risposta. Se l'umano ha digitato sì, il tool procede con la chiamata API per eliminare la risorsa cloud. Se l'umano ha digitato no, il tool annulla l'eliminazione. In entrambi i casi, il tool restituisce un messaggio di stato finale all'agent. L'agent elabora questo risultato, capisce se l'azione ha avuto successo o è stata bloccata dall'utente, e decide la sua prossima mossa. Utilizzando gli eventi per mettere in pausa e riprendere l'esecuzione, il tuo agent mantiene l'intero context di ragionamento e la memoria mentre aspetta ore o addirittura giorni che un umano prenda una decisione. Questo è tutto per questo episodio. Grazie per l'ascolto, e continua a sviluppare!

Ciao, sono Alex di DEV STORIES DOT EU. LlamaIndex: Applicazioni LLM context-augmented, episodio 12 di 14. Quando un agent autonomo commette un errore, spulciare tra i print standard di Python per trovare il problema è un vero incubo. Fai una domanda semplice, ottieni una risposta allucinata, e lo stack trace standard non ti dice assolutamente nulla sul perché il modello abbia mentito. Per risolvere questo problema, hai bisogno di un modo per guardare dentro la black box. Questo episodio parla di Observability e Tracing. I tool di debug tradizionali non bastano con i Large Language Model. Uno stack trace ti dice dove il codice è andato in crash, ma i bug degli LLM di solito sono logici. Il codice gira perfettamente, ma il sistema recupera il documento sbagliato o interpreta male un prompt. Il logging standard di Python è la tua prima linea di difesa. Impostando il livello di logging su debug, LlamaIndex restituisce un feed raw di tutto ciò che fa. Vedrai i prompt esatti inviati al language model e le risposte HTTP raw. Questo è utile per controllare se una chiamata di rete è fallita, ma per un workflow agent multi-step, leggere un muro di testo non strutturato è incredibilmente noioso. Ecco il punto chiave. Non ti serve solo un log degli eventi; devi vedere il call graph. Hai bisogno di una vista strutturata di come i dati fluiscono dalla query iniziale, attraverso i retriever, dentro al language model, e di nuovo fuori. LlamaIndex gestisce tutto questo usando un sistema di callback. I callback sono degli hook che scattano in punti specifici del ciclo di esecuzione. Il framework fornisce un tool built-in chiamato Llama Debug Handler. Inizializzi questo handler e lo attacchi ai tuoi global settings. Da quel momento in poi, registra silenziosamente ogni operazione. Mettiamo che fai girare un query engine, e ti restituisce un fatto completamente inventato. Senza tracing, non hai idea se il modello ha allucinato o se il tuo database gli ha passato informazioni sbagliate. Con il debug handler attaccato, puoi chiedergli di fare il print del trace dopo che la query è finita. Il trace rivela l'esatta sequenza degli eventi. Vedi la query iniziale. Vedi lo step di retrieval. Cosa fondamentale, vedi gli esatti text node che il retriever ha tirato fuori dal tuo index. Ispezioni quei node nel trace e scopri che è stato recuperato un documento obsoleto. Il language model non ha allucinato; ha solo letto dati sbagliati. Sistemi l'index, e il bug è risolto. I trace a terminale sono ottimi per il local development, ma non scalano bene quando hai agent complessi che fanno decine di step di ragionamento. Per la produzione, LlamaIndex offre quella che chiama one-click observability. Impostando una specifica variabile d'ambiente o aggiungendo una singola riga di configurazione, puoi instradare tutti quei dati di callback verso una piattaforma di observability dedicata. Queste piattaforme fanno l'ingest dei dati di trace e generano delle dashboard visive. Puoi navigare in un albero visivo del workflow del tuo agent, ispezionando l'esatta latenza, l'utilizzo dei token e il payload per ogni singolo step. Non devi strumentare manualmente ogni funzione; i callback nativi del framework fanno il lavoro pesante. La differenza tra un prototipo fragile e un'applicazione in produzione affidabile sta nel poter spiegare esattamente perché il sistema ha generato una risposta specifica. Se hai trovato utile questo episodio e vuoi supportare lo show, puoi cercare DevStoriesEU su Patreon. Per questo episodio è tutto. Grazie per l'ascolto, e continua a sviluppare!

Ciao, sono Alex di DEV STORIES DOT EU. LlamaIndex: Context-Augmented LLM Applications, episodio 13 di 14. Cambi il tuo modello di embedding e improvvisamente le tue risposte sembrano un po' strane, ma non riesci a capire bene il perché. Se guardi gli output solo a occhio per verificarne la qualità, la tua pipeline sta andando alla cieca. Per smettere di affidarti alle sensazioni e prevenire regressioni in produzione, hai bisogno delle RAG Evaluation Metrics. Creare un'applicazione RAG è facile, ma renderla robusta è difficile. Dovrai costantemente modificare le dimensioni dei chunk, i prompt e le strategie di retrieval. Se ti affidi alla revisione umana per testare ogni modifica, finirai per rallentare lo sviluppo o fare il deploy di regressioni. Hai bisogno di misurazioni automatizzate e oggettive. Dato che la RAG si compone di due fasi distinte, trovare le informazioni giuste e generare una risposta basata su di esse, devi valutare entrambe le fasi separatamente. Guardiamo prima la generazione. Questa viene chiamata Response Evaluation. La metrica principale qui è la faithfulness. L'obiettivo è intercettare le allucinazioni. Una risposta faithful è quella in cui il language model si basa interamente sul context recuperato, anziché inventare fatti dai propri dati di pre-training. In LlamaIndex, gestisci questa cosa con il FaithfulnessEvaluator. Questo tool utilizza un language model sotto il cofano per fare da giudice. Inizializzi l'evaluator, poi gli passi la query originale, l'array dei nodi di context recuperati e il testo finale generato. L'evaluator restituisce un oggetto evaluation che contiene un boolean binario, pass o fail, che ti dice se la risposta è strettamente supportata dal context fornito. Fornisce anche una stringa di reasoning che spiega il motivo della decisione del giudice. Se il tuo punteggio di faithfulness scende dopo un aggiornamento, il tuo prompt o il tuo language model potrebbero essere diventati troppo creativi. Ora, la seconda parte. Anche il miglior language model non può generare una risposta faithful se gli passi i documenti sbagliati. È qui che entra in gioco la Retrieval Evaluation. Ecco il punto chiave. Valuti il retrieval verificando se il sistema ha recuperato esattamente i source node che ti aspettavi per una data query, ignorando completamente il testo finale generato. Gestisci questo processo con il RetrieverEvaluator. Immagina uno scenario in cui vuoi testare un nuovo modello di embedding. Invece di farne il deploy e tirare a indovinare se sia migliore, costruisci un evaluation dataset. Questo dataset contiene una lista di query associate agli specifici identificatori dei documenti che contengono le risposte corrette. Fai girare il tuo intero batch di query attraverso il RetrieverEvaluator. L'evaluator calcola due metriche cruciali: Hit Rate e MRR. L'Hit Rate è semplice. Controlla se il documento atteso è apparso da qualche parte tra i tuoi top result recuperati. Se recuperi cinque documenti, e quello corretto è tra questi, quello è un hit. Misura la recall pura. Ma la posizione conta. Se il documento corretto è sempre il quinto, il tuo language model potrebbe ignorarlo a causa dei limiti di context o dell'attention decay. È qui che entra in gioco il Mean Reciprocal Rank, o MRR. L'MRR guarda la posizione del primo documento rilevante. Se il documento corretto è in cima, lo score è uno. Se è secondo, lo score è un mezzo. Se è terzo, un terzo. L'evaluator fa la media di queste frazioni su tutto il tuo dataset. Un MRR più alto significa che il tuo retriever sta costantemente spingendo le informazioni più rilevanti in cima alla context window. Confrontando l'Hit Rate e l'MRR del tuo vecchio modello di embedding con quello nuovo, ottieni la prova matematica di quale modello performa meglio. Puoi tracciare questi numeri nel tempo e far girare questa pipeline automaticamente a ogni pull request. La singola cosa più preziosa che puoi fare per la tua pipeline RAG è separare l'evaluation di ciò che recuperi da come generi la risposta finale. Grazie per aver passato qualche minuto con me. Alla prossima, stammi bene.

Ciao, sono Alex di DEV STORIES DOT EU. LlamaIndex: Applicazioni LLM Context-Augmented, episodio 14 di 14. Smetti di copiare e incollare la stessa API e lo stesso boilerplate React ogni volta che vuoi testare una nuova idea di Retrieval-Augmented Generation. Conosci già le meccaniche del framework, ma configurare un'interfaccia pulita per usare davvero i tuoi modelli richiede ancora ore di lavoro ripetitivo. Oggi parliamo degli starter tool che ti permettono di fare scaffolding per la produzione in pochi secondi. Costruire un'applicazione funzionante richiede molto più di un semplice index e di un query engine. Hai bisogno di un server backend per gestire le request in entrata in modo sicuro. Hai bisogno di API route per scambiare messaggi. Hai bisogno di un client frontend per mostrare la chat history, renderizzare i loading state e fare il parsing delle risposte. Scrivere questa infrastruttura da zero per ogni nuovo dataset o prototipo ti fa perdere un sacco di tempo. Per risolvere questo problema, LlamaIndex fornisce una utility da riga di comando chiamata create-llama. Questo tool genera un'applicazione web full-stack completa, preconfigurata con le best practice di LlamaIndex. Apri il terminale ed esegui il comando create-llama. Il tool poi ti guida attraverso una serie di scelte. Ti chiede se vuoi un backend Python con FastAPI, o un backend Node con Express. Ti chiede se vuoi un frontend Next JS per dare ai tuoi utenti un'interfaccia web curata. Poi, ti chiede la tua data source. Puoi puntare il tool direttamente a una cartella locale che contiene i tuoi file PDF. Una volta finiti i prompt, create-llama prende il controllo. Installa tutte le dipendenze necessarie. Fa lo scaffolding della struttura delle directory. Scrive lo script di ingestion per fare il parsing dei tuoi PDF. Collega gli API endpoint in modo che il tuo frontend possa parlare con il tuo retrieval engine. Infine, imposta le variabili d'ambiente. Esegui un solo comando di start, e hai subito un'interfaccia chat stilizzata che gira nel tuo browser. Puoi digitare una domanda, e l'interfaccia chiamerà il backend generato, recupererà il context dai tuoi PDF, e farà lo streaming della risposta sul tuo schermo. Passi da una cartella vuota a un prototipo full-stack funzionante in circa trenta secondi. Questo gestisce le applicazioni web. Ma a volte un web server e un'interfaccia grafica sono un overkill. Se hai appena scaricato una lunga specifica tecnica e hai bisogno di farle delle query immediatamente senza uscire dalla tua command line, usi la RAG CLI. La RAG CLI è un tool creato puramente per l'interazione con i documenti da terminale. La installi, poi esegui un comando per puntarla alla tua directory locale di documenti. La CLI esegue automaticamente il processo di ingestion. Fa il chunking del testo, genera gli embedding, e li salva in un vector database locale proprio lì sulla tua macchina. Quando l'ingestion è finita, esegui il comando chat. Il tuo prompt del terminale standard si trasforma in una sessione chat. Fai una domanda, la CLI recupera i dati rilevanti, fa una query al language model, e stampa la risposta generata direttamente sulla tua console. Non ci sono componenti visivi o web route da configurare. È in assoluto il modo più veloce per parlare con i tuoi dati in locale. Ecco il punto chiave. Ora capisci le meccaniche profonde delle applicazioni context-augmented, dal chunking dei documenti alla creazione di complessi agent router. Questi tool di scaffolding esistono così puoi smettere di lottare con l'infrastruttura di base e dedicare il tuo tempo al tuning di quelle strategie di retrieval fondamentali. Dato che questo è l'ultimo episodio della nostra serie su LlamaIndex, il miglior passo successivo è andare sulla documentazione ufficiale e provare a costruire queste pipeline hands-on. Se hai un'idea per uno stack tecnologico completamente diverso che vuoi che trattiamo, visita devstories dot eu per suggerire un argomento. Questo è tutto per questo episodio. Grazie per l'ascolto, e continua a sviluppare!