Langflow: Um guia com projeto de demonstração

Como instalar o Langflow?

Você pode usar o Langflow gratuitamente, seja no seu site oficial por meio da interface de usuário da Web ou instalando-o localmente.

Neste tutorial, usaremos uma configuração local com o Docker. Você não precisa conhecer o Docker para seguir este tutorial. Mas se você quiser saber mais, confira este guia do Docker para iniciantes e este curso do Docker.

O Docker é uma ferramenta que nos permite executar aplicativos em ambientes isolados chamados contêineres, facilitando o desenvolvimento, o teste e a implantação de software de forma consistente. No nosso caso, usamos o Docker porque ele oferece mais flexibilidade para a criação de componentes personalizados com Python, pois poderemos usar um banco de dados local e não precisaremos nos conectar a um serviço externo.

O Langflow fornece um exemplo pré-construído pronto para ser executado, portanto, você não precisará configurá-lo sozinho.

Executando o Langflow localmente com o Docker

Para executar o Langflow localmente com o Docker, siga estas etapas:

1. Instale o Docker seguindo as etapas aqui.
2. Clone ou baixe o repositório repositório oficial do Langflow.
3. Abra um terminal na pasta docker_example.
4. Execute o comando docker compose up.

Agora, o Langflow deve estar em execução em nosso computador local. Você deverá ver esta mensagem no terminal:

Você pode abrir o aplicativo visitando o URL mostrado no terminal, http://0.0.0.0:7860 no exemplo acima.

Explorando o agente simples com o Langflow

Nesta seção, exploramos como o Langflow funciona examinando o modelo simples de agente de IA do Langflow. Para isso, selecionamos "Simple Agent" na primeira tela.

Isso criará um fluxo de trabalho de agente como este:

O principal componente desse fluxo de trabalho é o componente "Agente" no meio:

Esse componente de agente está usando o modelo gpt-4.1 da OpenAI. Para usá-lo, você precisa colar uma chave de API da OpenAI. Se você ainda não tem um, pode criar um aqui.

À esquerda do componente do agente, vemos as entradas e as ferramentas disponíveis para ele (veja a imagem abaixo). Nesse caso, ele tem duas ferramentas e uma entrada:

• Uma entrada de bate-papo que usa uma mensagem do usuário na interface de bate-papo como entrada.
• Uma ferramenta Calculadora usada para realizar cálculos.
• Uma ferramenta de URL usada para buscar informações de um URL específico.

A entrada de bate-papo significa que, quando executamos o fluxo de trabalho, podemos usar a interface de bate-papo integrada do Langflow para enviar mensagens ao modelo. Na parte superior de cada ferramenta, você verá uma descrição. O modelo usa essas informações para decidir se você deve ou não chamar cada ferramenta.

À direita, vemos os resultados. Nesse caso, há um único componente de saída, que é um componente de saída de chat, indicando que a resposta do agente deve ser enviada para o chat.

Compreensão dos componentes

Antes de executarmos o agente simples, vamos usar o componente URL para entender como os componentes funcionam em geral. Vamos criar uma cópia dele para você experimentar.

1. Selecione o componente URL.
2. Copie e cole.
3. Não o conecte a nada.

Na parte superior do novo componente, há um botão "Tool Mode" (Modo de ferramenta); desative-o.

No campo URLs, coloque, por exemplo, https://en.wikipedia.org/wiki/Data_science, a página da Wikipedia sobre ciência de dados. Execute o componente clicando na seta de execução no canto superior direito.

O componente será executado e carregará o conteúdo do URL que fornecemos. Você pode ver isso clicando no inspetor ao lado dos links de saída. Cada um representa um formato de saída diferente.

Nos bastidores, cada nó é um script Python. Saberemos mais sobre isso quando criarmos nós personalizados mais adiante. Você pode inspecionar o código clicando no botão "Code" (Código) na parte superior:

No fluxo de trabalho original do Simple Agent, o nó de URL é configurado para ser uma ferramenta. Isso significa que ele deve ser usado por um agente. Nesse caso, os URLs não são fornecidos explicitamente. Em vez disso, o agente fornecerá os próprios URLs.

Executando o agente simples

De volta ao agente simples, podemos executá-lo clicando no botão "Playground" no canto superior direito. Isso abre a interface de bate-papo, permitindo que você converse com o agente.

Vamos pedir a ele que resuma a página da Wikipedia sobre ciência de dados:

Se expandirmos a caixa na parte superior da resposta, veremos as etapas que foram executadas no fluxo de trabalho.

Aqui vemos, por exemplo, que ele usa a função fetch_content_text(), que é definida na ferramenta de URL que fornecemos ao agente.

Podemos testar o uso da ferramenta Cálculo pedindo que você faça um cálculo. A expressão será analisada e enviada à ferramenta para avaliação. Isso fornece uma resposta mais confiável do que confiar estritamente no LLM.

Criando um componente personalizado no Langflow com Python

Nesta seção, aprenderemos a criar componentes personalizados. Para começar, clique no botão "New Custom Component" (Novo componente personalizado) no canto inferior esquerdo:

Por padrão, isso cria um componente que recebe um valor de texto como entrada e gera esse mesmo texto. A entrada padrão é "Hello, World!" e, se a executarmos e inspecionarmos a saída, veremos que é exatamente isso que obtemos.

Ao inspecionar o código, você verá o seguinte:

1. Esses campos são valores de configuração para o componente. A descrição é importante, pois é usada pelos agentes de IA para saber quando usar esse componente quando fornecido como uma ferramenta. O campo documentation é um URL opcional para a documentação do componente, portanto, não precisamos nos preocupar com ele aqui.
2. A lista inputs especifica os tipos de entradas disponíveis para o componente. Nesse caso, ele inclui uma única entrada da classe MessageTextInput chamada input_value, que corresponde ao campo de texto. O nome deve ser um nome de variável Python válido, pois ele se torna um atributo da classe. Quando um componente é definido como uma ferramenta, essas entradas são preenchidas automaticamente pelo agente de IA. Ele usa o campo info para determinar qual deve ser a entrada. O Langflow oferece suporte a vários tipos de entradas. Aqui está uma lista completa das entradas compatíveis.
3. Essa parte define as saídas. O campo method especifica a função que é executada para gerar a saída. A função tem acesso à entrada por meio de self. Por exemplo, a entrada nesta instância é denominada input_value, portanto, podemos acessá-la usando self.input_value. O valor de retorno deve ser uma classe das classes de saída suportadas.

Para obter mais informações sobre como criar um componente personalizado, consulte a a documentação oficial do componente Langflow.

Aqui está um exemplo de como podemos criar um componente que adiciona dois números:

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 data

Criando um tutor de idiomas com o Langflow

Vamos criar um agente de IA para nos ajudar a praticar nossas habilidades de leitura ao aprender um novo idioma.

De acordo com minha experiência, ao aprender um novo idioma, uma das maneiras de aprimorar suas habilidades é ler. É claro que, no início, você conhece apenas algumas palavras, portanto, ler um livro é impossível. Portanto, queremos ter materiais de leitura que se concentrem no vocabulário que já conhecemos.

Usaremos um LLM para gerar pequenas histórias para lermos. No entanto, para ter uma experiência de aprendizado personalizada, queremos que as histórias geradas por ele se concentrem no vocabulário que já conhecemos.

Aqui está um detalhamento do que você precisa:

1. Um banco de dados de vocabulário conhecido.
2. O agente de IA precisa acessar o banco de dados para recuperar o vocabulário conhecido e gerar uma história.
3. O agente de IA precisa acessar o banco de dados para adicionar novas palavras.

Componente de configuração do banco de dados

Quando usamos o Docker para executar o Langflow, ele inicia um banco de dados Postgres. Você pode acessá-lo usando o pacote psycopg2. Para saber mais sobre o Postgres, confira este tutorial do PostgreSQL.

Vamos criar um nó no qual podemos carregar um arquivo CSV com palavras conhecidas para inicializar o banco de dados. Meu arquivo CSV tem a seguinte aparência:

Criei um componente com duas entradas.

1. Um nome de coluna para especificar a coluna que contém as palavras que você deseja incluir.
2. Uma entrada de arquivo para fornecer o arquivo CSV com as palavras.

Aqui está o código do 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)}"

O componente tem a seguinte aparência:

Ele foi projetado para ser usado sozinho e não conectado a nenhum outro componente. Você pode usá-lo para carregar palavras manualmente no banco de dados.

Ferramenta de adição de palavras

Aqui criamos uma ferramenta que o agente de IA pode usar para adicionar novas palavras ao banco de dados. Dessa forma, o usuário pode adicionar facilmente novas palavras enviando uma mensagem ao agente.

Esse código reutiliza as funções connect_to_database() e add_word() do nó anterior. Com uma configuração melhor do Docker, podemos evitar a repetição do código, mas, para este tutorial, vamos mantê-lo simples.

Aqui está o código para essa ferramenta:

# 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}"

Observe que essa ferramenta pressupõe que o banco de dados foi criado anteriormente. Ele não funcionará sem que você execute o componente anterior pelo menos uma vez.

Lembre-se de colocá-lo no modo de ferramenta:

Ferramenta de criação de histórias

Para criar uma história, usamos um componente de agente de IA. Aqui está a estrutura:

Nas instruções do agente, em vez de adicionar o prompt diretamente no componente, usamos um componentePrompt porque isso nos permite adicionar parâmetros ao prompt. Este é o prompt que usamos:

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

{words}

O prompt tem dois parâmetros, {language} e {words}. Ao adicionar parâmetros como esse, você adiciona um campo para cada um deles ao componente.

Para o valor do idioma, basta defini-lo na caixa de texto. As palavras precisam ser carregadas do banco de dados, portanto, criamos um componente personalizado que carrega todas as palavras do banco de dados e conectamos a saída desse nó ao campo de palavras.

Aqui está o código do componente do carregador de palavras:

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()))

Em seguida, definimos o agente como uma ferramenta. Dessa forma, o agente principal (que criaremos a seguir) poderá usar esse agente para gerar uma história quando necessário.

Por fim, renomeamos o agente e alteramos a descrição da ferramenta para que a IA saiba quando usar essa ferramenta:

Agente de idiomas

Para o agente principal, usamos um componente de nó de agente de IA comum vinculado às duas ferramentas que criamos. Esse agente usa um componente de entrada e saída de bate-papo para que possamos interagir com ele usando a interface de bate-papo.

Aqui está a arquitetura final:

O prompt que usamos foi:

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.

Você pode executar o fluxo de trabalho completo clicando no botão "Playground". Aqui está um exemplo de interação:

Conclusão

Exploramos os aspectos fundamentais do Langflow e como ele pode ser usado para criar um fluxo de trabalho de agente de IA que ajuda os usuários a praticar suas habilidades de leitura. Ao usar o Python para criar componentes personalizados, você abre mais possibilidades. 

Essa abordagem híbrida mescla o melhor dos dois mundos: a flexibilidade dos scripts Python, que permitem a execução de qualquer tarefa desejada, e a interface gráfica intuitiva do Langflow, que simplifica a construção do fluxo de trabalho sem a necessidade de você mergulhar em códigos complexos.

Para saber mais sobre agentes de IA, recomendo que você leia estes blogs:

• Codex da OpenAI: Um guia com três exemplos práticos
• n8n: Um guia com exemplos práticos
• Tutorial de IA do Haystack: Criando fluxos de trabalho agênticos
• Kit de desenvolvimento de agentes (ADK) do Google: Um guia com projeto de demonstração
• Agent2Agent (A2A): Definição, exemplos, comparação de MCP