Langflow: una guida con progetto demo

Come installare Langflow?

Possiamo usare Langflow gratuitamente, sia sul loro sito ufficiale tramite l'interfaccia web, sia installandolo in locale.

In questo tutorial useremo un setup locale con Docker. Non devi conoscere Docker per seguire. Ma se vuoi saperne di più, dai un'occhiata a questa guida Docker per principianti e a questo corso su Docker.

Docker è uno strumento che consente di eseguire applicazioni in ambienti isolati chiamati container, rendendo semplice sviluppare, testare e distribuire software in modo coerente. Nel nostro caso usiamo Docker perché offre più flessibilità per creare componenti personalizzati con Python: potremo usare un database locale senza doverci collegare a un servizio esterno.

Langflow fornisce un esempio preconfigurato pronto all'uso, quindi non dovremo impostarlo da zero.

Eseguire Langflow in locale con Docker

Per eseguire Langflow in locale con Docker, segui questi passaggi:

1. Installa Docker seguendo i passaggi qui.
2. Clona o scarica il repository ufficiale di Langflow.
3. Apri un terminale nella cartella docker_example.
4. Esegui il comando docker compose up.

Ora Langflow dovrebbe essere in esecuzione sulla nostra macchina locale. Dovremmo vedere questo messaggio nel terminale:

Possiamo aprire l'applicazione visitando l'URL mostrato nel terminale, http://0.0.0.0:7860 nell'esempio sopra.

Esplorare il Simple Agent con Langflow

In questa sezione esploriamo come funziona Langflow esaminando il template del suo semplice agente AI. Per farlo, selezioniamo "Simple Agent" nella prima schermata.

Questo creerà un workflow di agente come questo:

Il componente principale in questo workflow è il componente "Agent" al centro:

Questo componente agente utilizza il modello gpt-4.1 di OpenAI. Per usarlo, dobbiamo incollare una chiave API di OpenAI. Se non ne hai ancora una, puoi crearla qui.

A sinistra del componente agente, vediamo gli input e gli strumenti a sua disposizione (vedi l'immagine sotto). In questo caso, ha due strumenti e un input:

• Un Chat Input che usa come input un messaggio dell'utente nell'interfaccia chat.
• Uno strumento Calculator usato per eseguire calcoli.
• Uno strumento URL usato per recuperare informazioni da un URL specifico.

L'input della chat significa che, quando eseguiamo il workflow, possiamo usare l'interfaccia chat integrata di Langflow per inviare messaggi al modello. In alto a ogni strumento vediamo una descrizione. Il modello usa queste informazioni per decidere se chiamare o meno ciascuno strumento.

A destra vediamo gli output. In questo caso, c'è un solo componente di output, che è un componente Chat Output, a indicare che la risposta dell'Agente deve essere inviata alla chat.

Capire i componenti

Prima di eseguire il Simple Agent, usiamo il componente URL per capire in generale come funzionano i componenti. Creiamone una copia per fare qualche prova.

1. Seleziona il componente URL.
2. Copia e incolla il componente.
3. Non collegarlo a nulla.

In alto nel nuovo componente c'è l'interruttore "Tool Mode"; disattivalo.

Nel campo URLs, inserisci, per esempio, https://en.wikipedia.org/wiki/Data_science, la pagina Wikipedia di Data Science. Esegui il componente cliccando sulla freccia di esecuzione in alto a destra.

Il componente verrà eseguito e caricherà il contenuto dall'URL fornito. Possiamo visualizzarlo cliccando l'ispettore accanto ai collegamenti di output. Ognuno rappresenta un diverso formato di output.

Dietro le quinte, ogni nodo è uno script Python. Ne sapremo di più quando costruiremo i nodi personalizzati più avanti. Possiamo ispezionare il codice cliccando il pulsante "Code" in alto:

Nel workflow originale Simple Agent, il nodo URL è configurato come strumento. Questo significa che è pensato per essere usato da un Agente. In questo caso, gli URL non sono forniti esplicitamente: sarà l'agente a fornirli.

Eseguire il Simple Agent

Tornando al Simple Agent, possiamo eseguirlo cliccando il pulsante "Playground" in alto a destra. Si aprirà l'interfaccia chat, così da poter parlare con l'Agente.

Chiediamogli di riassumere la pagina Wikipedia su Data Science:

Se espandiamo il riquadro in alto alla risposta, vedremo i passaggi che sono stati eseguiti nel workflow.

Qui vediamo, per esempio, che utilizza la funzione fetch_content_text(), definita nello strumento URL che abbiamo fornito all'agente.

Possiamo testare l'uso dello strumento Calculation chiedendogli di eseguire un calcolo. L'espressione verrà analizzata e inviata allo strumento per la valutazione. Questo fornisce una risposta più affidabile rispetto al fare affidamento solo sull'LLM.

Creare un componente personalizzato in Langflow con Python

In questa sezione impariamo a creare componenti personalizzati. Per iniziare, clicca il pulsante "New Custom Component" in basso a sinistra:

Per impostazione predefinita, questo crea un componente che prende un valore di testo in input e restituisce lo stesso testo. L'input predefinito è "Hello, World!" e, se lo eseguiamo e ispezioniamo l'output, vediamo che è proprio quello che otteniamo.

Ispezionando il codice, vediamo quanto segue:

1. Questi campi sono valori di configurazione per il componente. La descrizione è importante perché viene usata dagli agenti AI per sapere quando utilizzare questo componente se fornito come strumento. Il campo della documentazione è un URL opzionale alla documentazione del componente, quindi qui non è necessario preoccuparsene.
2. L'elenco inputs specifica i tipi di input disponibili per il componente. In questo caso include un singolo input di classe MessageTextInput chiamato input_value, che corrisponde al campo di testo. Il nome deve essere un nome di variabile Python valido perché diventa un attributo della classe. Quando un componente è impostato come strumento, questi input vengono compilati automaticamente dall'agente AI. Utilizza il campo info per determinare quale debba essere l'input. Langflow supporta diversi tipi di input. Ecco l'elenco completo degli input supportati.
3. Questa parte definisce gli output. Il campo method specifica la funzione che viene eseguita per generare l'output. La funzione ha accesso all'input tramite self. Per esempio, l'input in questo caso si chiama input_value, quindi possiamo accedervi con self.input_value. Il valore di ritorno deve essere una classe tra le classi di output supportate.

Per ulteriori informazioni sulla creazione di un componente personalizzato, consulta la documentazione ufficiale dei componenti di Langflow.

Ecco un esempio di come possiamo creare un componente che somma due numeri:

from langflow.custom import Component
from langflow.io import MessageTextInput, Output
from langflow.schema import Data

class AddNumbers(Component):
    display_name = "Add Numbers"
    description = "This component adds two numbers together"
    icon = "code"
    name = "AddNumbers"

    inputs = [
        IntInput(
            name="number1",
            display_name="First Number",
            info="The first number to add",
        ),
        IntInput(
            name="number2",
            display_name="Second Number",
            info="The second number to add",
        ),
    ]

    outputs = [
        Output(display_name="Output", name="output", method="add_numbers"),
    ]

    def add_numbers(self) -> Data:
        result = self.number1 + self.number2
        data = Data(value=result)
        return dataOfferto da

Creare un tutor linguistico con Langflow

Costruiamo un agente AI che ci aiuti a esercitare le abilità di lettura mentre impariamo una nuova lingua.

Per esperienza, quando si impara una nuova lingua uno dei modi per migliorare è leggere. Ovviamente, all'inizio si conoscono poche parole, quindi leggere un libro è impossibile. Perciò vogliamo avere materiali di lettura che si concentrino sul vocabolario che conosciamo già.

Useremo un LLM per generare piccole storie da leggere. Tuttavia, per un'esperienza di apprendimento personalizzata, vogliamo che le storie generate si concentrino sul vocabolario che già conosciamo.

Ecco cosa ci serve:

1. Un database del vocabolario noto.
2. L'agente AI deve avere accesso al database per recuperare il vocabolario noto e generare una storia.
3. L'agente AI deve avere accesso al database per aggiungere nuove parole.

Componente di setup del database

Quando usiamo Docker per eseguire Langflow, viene avviato un database Postgres. Possiamo accedervi usando il pacchetto psycopg2. Per saperne di più su Postgres, consulta questo tutorial su PostgreSQL.

Creeremo un nodo in cui possiamo caricare un file CSV con le parole note per inizializzare il database. Il mio file CSV è così:

Ho creato un componente con due input.

1. Un nome di colonna per specificare la colonna che contiene le parole da includere.
2. Un input file per fornire il CSV con le parole.

Ecco il codice del componente:

from langflow.custom import Component
from langflow.io import MessageTextInput, Output
from langflow.schema import Message
import psycopg2
import csv

def connect_to_database():
    # Connect to the Postgres database provided by the Docker setup
    conn = psycopg2.connect(
        dbname="langflow",
        user="langflow",
        password="langflow",
        host="postgres",
        port="5432"
    )
    conn.autocommit = True    
    return conn.cursor()

def add_word(cursor, word):
    # Add a word to the database
    cursor.execute(
        "INSERT INTO words (word) VALUES (%s) ON CONFLICT (word) DO NOTHING;",
        (word,)
    )

def initialize_database(cursor):
    # Initialize the database by creating the word table if it doesn't yet exist
    create_table_query = """
        CREATE TABLE IF NOT EXISTS words (
            word TEXT PRIMARY KEY
        );
    """
    cursor.execute(create_table_query)    

class UploadWordFile(Component):
    display_name = "Upload Word File"
    description = "Upload a CSV file of words to the database."
    icon = "code"
    name = "UploadWordFile"

    inputs = [
        StrInput(
            name="column_name",
            display_name="Column Name",
            info="The name of the column containing the words",
        ),
        FileInput(
            name="csv_file",
            display_name="CSV file",
            info="CSV input file",
            file_types=["csv"]
        ),
    ]

    outputs = [
        Output(display_name="Output", name="output", method="load_words_into_database"),
    ]

    def load_words_into_database(self) -> Message:
        try:
            cursor = connect_to_database()
            initialize_database(cursor)
            with open(self.csv_file, "rt") as f:
                rows = list(csv.reader(f))
            headers = list(map(lambda header: header.lower(), rows[0]))
            column_index = headers.index(self.column_name)
            for row in rows[1:]:
                add_word(cursor, row[column_index])
            return "Success"
        except Exception as e:
            return f"Error: {str(e)}"Offerto da

Il componente appare così:

È progettato per essere usato da solo e non collegato ad altri componenti. Possiamo usarlo per caricare manualmente parole nel database.

Strumento per aggiungere parole

Qui creiamo uno strumento che l'agente AI può usare per aggiungere nuove parole al database. In questo modo l'utente può aggiungere facilmente nuove parole inviando un messaggio all'agente.

Questo codice riutilizza le funzioni connect_to_database() e add_word() del nodo precedente. Con un setup Docker migliore potremmo evitare di ripetere il codice, ma per questo tutorial manterremo le cose semplici.

Ecco il codice di questo strumento:

# from langflow.field_typing import Data
from langflow.custom import Component
from langflow.io import MessageTextInput, Output
from langflow.schema import Message

def connect_to_database():
    # Connect to the Postgres database provided by the Docker setup
    conn = psycopg2.connect(
        dbname="langflow",
        user="langflow",
        password="langflow",
        host="postgres",
        port="5432"
    )
    conn.autocommit = True    
    return conn.cursor()

def add_word(cursor, word):
    # Add a word to the database
    cursor.execute(
        "INSERT INTO words (word) VALUES (%s) ON CONFLICT (word) DO NOTHING;",
        (word,)
    )

class AddWordTool(Component):
    display_name = "Add word tool"
    description = "Use this tool to add a new word"
    icon = "code"
    name = "AddWordTool"

    inputs = [
        MessageTextInput(
            name="word",
            display_name="Word",
            info="The word to add",
            tool_mode=True,
        ),
    ]

    outputs = [
        Output(display_name="Output", name="output", method="add_new_word"),
    ]

    def add_new_word(self) -> Message:
        cursor = connect_to_database()
        add_word(cursor, self.word)
        return f"Added word: {self.word}"Offerto da

Nota che questo strumento presuppone che il database sia stato creato in precedenza. Non funzionerà senza aver eseguito almeno una volta il componente precedente.

Ricorda di impostarlo in modalità strumento:

Strumento creatore di storie

Per creare una storia, usiamo un componente agente AI. Ecco la struttura:

Nelle istruzioni dell'agente, invece di aggiungere il prompt direttamente nel componente, abbiamo usato un componente Prompt perché ci permette di aggiungere parametri al prompt. Questo è il prompt che abbiamo usato:

Create a story in {language} using only words from the following list:

{words}Offerto da

Il prompt ha due parametri, {language} e {words}. Quando si aggiungono parametri in questo modo, viene aggiunto un campo per ciascuno di essi al componente.

Per il valore della lingua, l'abbiamo semplicemente impostato nel campo di testo. Le parole devono essere caricate dal database, quindi abbiamo creato un componente personalizzato che carica tutte le parole dal database e collegato l'output di quel nodo al campo words.

Ecco il codice del componente word loader:

from langflow.custom import Component
from langflow.io import MessageTextInput, Output
from langflow.schema import Message
import psycopg2

def load_words():
    conn = psycopg2.connect(
        dbname="langflow",
        user="langflow",
        password="langflow",
        host="postgres",
        port="5432"
    )    
    cursor = conn.cursor()
    cursor.execute("""
        SELECT * FROM words;
    """)
    rows = cursor.fetchall()
    return map(lambda row: row[0], rows)

class WordLoader(Component):
    display_name = "Word Loader"
    description = "Load words from the database"
    icon = "code"
    name = "WordLoader"

    outputs = [
        Output(display_name="Output", name="output", method="build_output"),
    ]

    def build_output(self) -> Message:
        return str(", ".join(load_words()))Offerto da

Successivamente, impostiamo l'agente come strumento. In questo modo l'agente principale (che abbiamo creato dopo) potrà usare questo per generare una storia quando necessario.

Infine, rinominiamo l'agente e cambiamo la descrizione dello strumento per far capire all'AI quando usare questo tool:

Agente linguistico

Per l'agente principale, usiamo un normale nodo agente AI collegato ai due strumenti che abbiamo creato. Questo agente utilizza un componente di input chat e uno di output chat, in modo da poter interagire tramite l'interfaccia di chat.

Ecco l'architettura finale:

Il prompt che abbiamo usato era:

You will help the user practice their language skills. You will either be asked to create a story or to add a new word to the vocabulary.

- If the user asks you to create a story, use the story generation tool.  
- If the user asks you to add a word, use the word add tool.  

When using a tool, your answer should just be the result from the tool and nothing else.Offerto da

Possiamo eseguire l'intero workflow cliccando il pulsante “Playground”. Ecco un esempio di interazione:

Conclusione

Abbiamo esplorato gli aspetti fondamentali di Langflow e come può essere usato per costruire un workflow di agente AI che aiuta gli utenti a esercitarsi nella lettura. Usando Python per creare componenti personalizzati, sblocchiamo ulteriori possibilità. 

Questo approccio ibrido unisce il meglio di entrambi i mondi: la flessibilità degli script Python, che permettono di eseguire qualsiasi attività desiderata, e l'interfaccia grafica intuitiva di Langflow, che semplifica la costruzione dei workflow senza dover mettere mano a codice complesso.

Per saperne di più sugli agenti AI, ti consiglio di leggere questi blog:

• OpenAI's Codex: una guida con 3 esempi pratici
• n8n: una guida con esempi pratici
• Tutorial Haystack AI: costruire workflow agentici
• Agent Development Kit (ADK) di Google: guida con progetto demo
• Agent2Agent (A2A): definizione, esempi, confronto con MCP