1. 项目概述：用 Langflow 搭建一个真正能“教语言”的 AI 阅读教练

Langflow 是我过去一年在实际项目中反复验证过、最接近“开箱即用”理想的低代码 AI 工作流平台。它不是另一个需要你从零写 prompt、调接口、搭服务的玩具框架，而是一个能把“想法快速变成可交互原型”的真实生产力工具。关键词是 低代码 、 可视化编排 、 Python 可扩展性 ——这三者叠加，意味着你不需要成为全栈工程师，也能做出一个能真正帮人学语言的 AI 教练。我带过的几个教育科技初创团队，都是靠 Langflow 在两周内跑通 MVP，把原本要两个月才能交付的阅读训练功能，压缩到五天就上线测试。它解决的核心问题很朴素：当你要让一个 AI 不只是“回答问题”，而是“执行一连串有逻辑的动作”（比如查词库→生成故事→返回文本→记录学习行为），传统写代码的方式太重，而纯拖拽的 no-code 工具又太死板。Langflow 的价值，恰恰卡在这个中间地带：图形界面负责流程组织和状态可视化，Python 负责所有需要真实计算、数据库操作或复杂逻辑的部分。这篇文章不讲虚的，我会带你从零开始，完整复现一个“语言阅读教练”项目——它能根据你当前掌握的词汇表，实时生成只用这些词写成的短故事；你能随时往词库里加新词；所有操作都在一个聊天窗口里完成。这不是概念演示，而是我在真实教学场景中打磨出来的方案。如果你是教育产品负责人、语言类 App 开发者，或者只是想用 AI 辅助自己学外语的自学者，这个项目就是为你准备的。它不依赖任何外部云服务，全部跑在你本地 Docker 环境里，数据完全可控，配置一次，长期可用。

2. 核心设计思路与架构拆解：为什么选 Langflow 而不是其他方案？

2.1 为什么不是直接写 Python 脚本？

我试过。最开始，我用 Flask + LangChain 写了一个类似的阅读教练后端，逻辑是清晰的：接收用户请求 → 查询本地 SQLite 词库 → 拼接 prompt → 调用 OpenAI API → 返回故事。但很快遇到三个硬伤：第一，调试成本高。每次改一句 prompt，都要重启服务、清缓存、重新发请求，光是等待响应就打断了思考流；第二，状态不可见。用户问“刚才生成的故事用了哪些词？”，脚本里没有保存上下文，我得临时加日志、查数据库，再手动拼回复；第三，协作困难。当我把代码交给设计师看 UI 效果时，他得先配 Python 环境、装依赖、改 config 文件，一个环境问题就能卡住半天。Langflow 的核心优势，就是把“流程”本身变成了可编辑、可观察、可分享的一等公民。你在界面上拖一个“Chat Input”，它就天然带输入框；连一条线到“LLM”，这条线就代表数据流向；点一下“Playground”，整个流程就在浏览器里跑起来，每一步的输入输出都实时显示。这种所见即所得，对快速验证想法的价值，远超任何代码简洁性。

2.2 为什么不是纯 no-code 工具（如 n8n 或 Zapier）？

n8n 我也深度用过，它在自动化邮件、处理 PDF、同步 CRM 这类任务上非常稳。但它不是为“AI Agent”设计的。关键区别在于 工具调用的决策权 。在 n8n 里，你必须用 if-else 判断用户消息里有没有“add word”这个词，然后走分支 A；有没有“story”就走分支 B。这叫“规则驱动”，僵硬且易出错——用户说“帮我造个用这些词写的小故事”，n8n 就可能漏判。而 Langflow 的 Agent 组件，是让 LLM 自己读消息、理解意图、决定要不要调用工具。它看到“add word ‘serendipity’”，会自动提取出动词“add”和名词“serendipity”，再匹配到你注册的“AddWordTool”。这种基于语义的动态路由，是 no-code 工具无法原生支持的。Langflow 的 Agent 不是黑盒，它的提示词（system prompt）你完全可控，你可以明确告诉它：“只有当用户明确要求添加单词时，才调用 AddWordTool；否则一律忽略”。这种细粒度的控制力，是构建可靠 AI 助手的基础。

2.3 为什么数据库必须用 PostgreSQL 而不是 SQLite 或内存？

原文提到用 Docker 启动 Langflow 会自带一个 Postgres 实例，这绝非偶然。我踩过坑：最初为了省事，我把词库存在内存字典里，结果每次重启 Langflow 容器，所有用户添加的单词就全丢了。换成 SQLite 后，问题更隐蔽——Docker 容器的文件系统是临时的，SQLite 文件写在容器内部，容器一删，数据就蒸发。PostgreSQL 的妙处在于，Langflow 的官方 Docker Compose 配置里，已经为 postgres 服务定义了 持久化卷（volume） 。这意味着，只要你没手动删掉那个卷，数据库文件就永远躺在你电脑的硬盘上，重启、重装、甚至换台机器（只要挂载同一个卷），数据都在。更重要的是，并发安全。当多个用户同时向你的语言教练提问时，内存字典或 SQLite 可能因锁机制导致响应延迟甚至报错；PostgreSQL 是专业级关系型数据库，天生支持高并发读写。我实测过，在 5 个并发请求下，PostgreSQL 的词库查询平均耗时 12ms，而内存字典是 0.3ms，但稳定性差了两个数量级。所以，这个选择不是“为了用而用”，而是用最小的运维成本，换取生产级的可靠性。你不需要懂 SQL 优化，Langflow 已经帮你把底层数据库的“脏活”包圆了。

2.4 自定义组件的设计哲学：何时该写 Python，何时该用内置节点？

Langflow 内置了上百个节点：HTTP 请求、JSON 解析、文本分割……但它们都有边界。比如，内置的“Database”节点只能做简单 CRUD，不能执行 INSERT ... ON CONFLICT DO NOTHING 这种防重复插入的高级语法；内置的“File Input”节点能上传 CSV，但没法指定“按哪一列读单词”。这就是自定义组件的用武之地。我的经验是： 凡是涉及“业务规则”的地方，必须用 Python；凡是“数据搬运”的地方，优先用内置节点 。例如，“UploadWordFile”组件里，解析 CSV、找列名、去重插入，这是业务规则（我们只认这一列的词，且不允许重复）；而“WordLoader”组件里，只是把数据库里所有词取出来、用逗号拼成字符串，这本质是数据搬运，但因为内置节点不支持 PostgreSQL 查询，所以必须写 Python。再比如，“AddWordTool”里，检查单词是否已存在、只插入新词，这也是业务规则。总结一句话：内置节点是乐高积木，自定义组件是你亲手捏的陶土——前者搭房子快，后者能做出独一无二的雕塑。

3. 环境搭建与本地部署：绕过所有网络和权限陷阱的实操指南

3.1 Docker 安装：为什么必须用官方安装包，而不是 Homebrew 或 Snap？

很多开发者习惯用 brew install docker 或 sudo snap install docker ，这在 Mac 或 Linux 上看似方便，但会埋下大坑。我遇到的真实案例：一位同事用 Homebrew 装的 Docker Desktop，启动 Langflow 后，PostgreSQL 容器一直报错 connection refused 。排查三天才发现，Homebrew 版 Docker 默认不启用 Kubernetes，而 Langflow 的 Compose 文件里， postgres 服务的 host 设为 "postgres" ，这依赖 Docker 内部 DNS 解析，而精简版 Docker Desktop 关闭了这项服务。解决方案极其简单：卸载所有第三方 Docker，去 Docker 官网 下载 Docker Desktop for Mac/Windows/Linux 的官方安装包。安装时勾选 “Install required Windows subsystems”（Win）或 “Enable Docker Dashboard”（Mac），确保 Kubernetes 选项是灰色不可选状态（说明已启用）。安装完成后，在终端运行 docker --version 和 docker-compose --version ，确认两者都输出版本号（如 Docker version 24.0.7 ），再运行 docker info | grep "Default Runtime" ，看到 runc 即表示运行时正常。这一步看似琐碎，但能避免 80% 的后续连接失败问题。

3.2 Langflow 仓库克隆与目录切换：一个被严重低估的关键细节

原文说“克隆官方 Langflow 仓库，进入 docker_example 文件夹”，但没强调路径。Langflow 仓库结构是这样的：

langflow/
├── docker_example/          ← 这才是我们要的！
│   ├── docker-compose.yml
│   └── ...
├── examples/
├── langflow/
└── ...

很多人克隆后，直接在根目录 langflow/ 下运行 docker compose up ，结果报错 no such file or directory: docker-compose.yml 。正确操作是：

1. 打开终端，执行 git clone https://github.com/logspace-ai/langflow.git
2. 进入 cd langflow/docker_example （注意，是 docker_example ，不是 docker-examples 或 examples/docker ）
3. 此时，用 ls -la 确认当前目录下有 docker-compose.yml 和 .env 文件

.env 文件里预设了默认密码和端口，你无需修改。但有一个隐藏风险：如果之前运行过其他 Docker 项目占用了 7860 端口， docker compose up 会卡在 Starting langflow-langflow-1 ... done 却打不开网页。解决方法：编辑 .env 文件，把 LANGFLOW_PORT=7860 改成 LANGFLOW_PORT=7861 ，保存后重新运行命令。端口修改后，访问地址就变成 http://0.0.0.0:7861 。这个细节，我见过至少 5 个团队在 Slack 里反复问，其实就改一行配置。

3.3 首次启动的完整终端日志与成功标志识别

运行 docker compose up 后，终端会滚动大量日志。新手常因看到 ERROR 字样就 panic，其实大部分是初始化日志。你需要盯住的 唯一成功标志 是这行：

langflow-langflow-1  | INFO:     Application startup complete.
langflow-langflow-1  | INFO:     Uvicorn running on http://0.0.0.0:7860 (Press CTRL+C to quit)

注意，是 Uvicorn running on... 这行，不是前面的 Starting postgres... 或 Waiting for postgres... 。如果等了超过 2 分钟还没出现这行，大概率是 PostgreSQL 启动失败。此时，按 Ctrl+C 停止，然后执行 docker logs langflow-postgres-1 查看数据库日志。最常见的错误是 password authentication failed for user "langflow" ，这说明 .env 文件里的 POSTGRES_PASSWORD 和 LANGFLOW_POSTGRES_PASSWORD 不一致。打开 .env ，确保这两行值完全相同：

POSTGRES_PASSWORD=langflow
LANGFLOW_POSTGRES_PASSWORD=langflow

改完后，先清理旧容器： docker compose down -v （ -v 参数会删除关联的 volume，清除坏数据），再重新 docker compose up 。这个 -v 是救命参数，记住它。

3.4 Web UI 访问与基础设置：避开浏览器缓存和跨域的隐形墙

浏览器访问 http://0.0.0.0:7860 失败？别急着重装。90% 的情况是浏览器缓存或跨域策略作祟。正确做法：

1. 强制刷新 ：在 Chrome 或 Edge 中，按 Ctrl+Shift+R （Windows）或 Cmd+Shift+R （Mac），不是普通的 F5 。
2. 无痕模式 ：直接打开无痕窗口，粘贴网址。因为 Langflow 第一次加载会存大量前端资源，普通窗口的缓存可能损坏。
3. 检查控制台 ：按 F12 打开开发者工具，切换到 Console 标签页。如果看到红色错误 Failed to load resource: net::ERR_CONNECTION_REFUSED ，说明后端没起来；如果是 Access to fetch at 'http://0.0.0.0:7860/api/v1/version' from origin 'null' has been blocked by CORS policy ，说明前端页面是从本地文件打开的（比如双击 index.html ），必须通过 http:// 协议访问。

首次进入 UI 后，你会看到一个空白画布和左侧组件栏。此时， 不要急着拖组件 。先点击右上角头像 → Settings → API Keys ，在这里粘贴你的 OpenAI API Key。Key 必须以 sk- 开头，长度 51 位。粘贴后，点 Save 。这一步至关重要，因为所有 LLM 节点都依赖它。如果你跳过此步，后面拖入任何 LLM 组件，都会在运行时报 Authentication failed 。Key 保存后，可以关闭 Settings 页面，正式开始构建。

4. 核心组件实现与数据库集成：从零编写可落地的 Python 自定义节点

4.1 数据库初始化组件（UploadWordFile）：CSV 解析的健壮性设计

这个组件的目标是：让用户上传一个 CSV 文件，指定哪一列是单词，然后把所有单词存进 PostgreSQL 的 words 表。原文代码有个致命缺陷——它用 open(self.csv_file, "rt") 直接读文件，但 Langflow 的 FileInput 传进来的是一个 临时文件路径 ，而 Docker 容器内的 Python 进程，根本无法访问宿主机的文件系统。这是 Docker 环境下最经典的路径错误。正确解法是：Langflow 会把上传的文件自动复制到容器内的 /tmp 目录下，路径是 self.csv_file ，但这个路径是容器内的绝对路径，可以直接 open 。不过，为了万无一失，我增加了三重防护：

from langflow.custom import Component
from langflow.io import StrInput, FileInput, Output
from langflow.schema import Message
import psycopg2
import csv
import os
import logging

# 配置日志，方便调试
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

def connect_to_database():
    try:
        conn = psycopg2.connect(
            dbname="langflow",
            user="langflow",
            password="langflow",
            host="postgres",  # 注意：这是 Docker 内部服务名，不是 localhost
            port="5432"
        )
        conn.autocommit = True
        return conn.cursor()
    except Exception as e:
        logger.error(f"Database connection failed: {e}")
        raise

def initialize_database(cursor):
    create_table_query = """
        CREATE TABLE IF NOT EXISTS words (
            id SERIAL PRIMARY KEY,
            word TEXT UNIQUE NOT NULL,
            created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
        );
    """
    cursor.execute(create_table_query)

def add_word(cursor, word):
    # 使用更安全的 INSERT，避免 SQL 注入
    cursor.execute(
        "INSERT INTO words (word) VALUES (%s) ON CONFLICT (word) DO NOTHING;",
        (word.strip().lower(),)  # 强制小写并去空格，统一格式
    )

class UploadWordFile(Component):
    display_name = "Upload Word File"
    description = "Upload a CSV file of words to the database. Handles headers and empty rows."
    icon = "database"
    name = "UploadWordFile"
    inputs = [
        StrInput(
            name="column_name",
            display_name="Column Name",
            info="The exact name of the column containing words (case-sensitive)",
            required=True
        ),
        FileInput(
            name="csv_file",
            display_name="CSV file",
            info="CSV input file with header row",
            file_types=["csv"],
            required=True
        ),
    ]
    outputs = [
        Output(
            display_name="Output",
            name="output",
            method="load_words_into_database"
        ),
    ]

    def load_words_into_database(self) -> Message:
        try:
            # 1. 验证文件是否存在且可读
            if not os.path.exists(self.csv_file):
                return Message(text=f"Error: File not found at {self.csv_file}")
            
            cursor = connect_to_database()
            initialize_database(cursor)
            
            # 2. 安全读取 CSV
            words_added = 0
            with open(self.csv_file, "r", encoding="utf-8") as f:
                # 使用 csv.Sniffer 自动检测分隔符，兼容 , ; \t
                sample = f.read(1024)
                f.seek(0)
                sniffer = csv.Sniffer()
                dialect = sniffer.sniff(sample)
                
                reader = csv.reader(f, dialect)
                headers = next(reader, None)  # 读取第一行作为 header
                
                if not headers:
                    return Message(text="Error: CSV file is empty or has no header")
                
                # 3. 查找目标列索引
                try:
                    column_index = headers.index(self.column_name)
                except ValueError:
                    return Message(text=f"Error: Column '{self.column_name}' not found in CSV headers: {headers}")
                
                # 4. 逐行处理，跳过空行和无效行
                for i, row in enumerate(reader, start=2):  # start=2 因为 header 是第1行
                    if len(row) <= column_index or not row[column_index].strip():
                        continue  # 跳过空值或列数不足的行
                    word = row[column_index].strip()
                    if word:  # 确保非空
                        add_word(cursor, word)
                        words_added += 1
            
            return Message(text=f"Success: Added {words_added} unique words to database.")
            
        except UnicodeDecodeError as e:
            return Message(text=f"Error: File encoding issue. Please save CSV as UTF-8. {e}")
        except Exception as e:
            logger.error(f"Upload failed: {e}")
            return Message(text=f"Error: {str(e)}")

关键改进点解析 ：

• 编码处理 ：显式指定 encoding="utf-8" ，避免中文 CSV 乱码。
• 分隔符自适应 ：用 csv.Sniffer() 自动识别 , 、 ; 或制表符，用户不用纠结导出格式。
• 空行/空值过滤 ： if not row[column_index].strip(): continue ，防止把空字符串当单词插入。
• 大小写归一化 ： word.strip().lower() ，确保 “Apple” 和 “apple” 不会重复入库。
• 错误反馈具体化 ：返回的消息明确告诉用户是“列名找不到”还是“文件编码错误”，而不是笼统的 “Error”。

使用时，在 Langflow UI 中拖入此组件，填入 column_name （如 english_word ），上传 CSV，点击右上角 ▶️ 运行。成功后，右侧 Inspector 会显示绿色 “Success” 消息。这是整个系统的基石，务必先运行它，否则后续所有数据库操作都会失败。

4.2 词库查询组件（WordLoader）：高效加载与缓存策略

“Story Creator”需要把所有已知单词传给 LLM，如果每次生成故事都查一遍数据库，效率极低。原文的 WordLoader 每次都新建连接、执行查询、拼字符串，没有考虑性能。我做了两层优化：连接池复用和结果缓存。

from langflow.custom import Component
from langflow.io import Output
from langflow.schema import Message
import psycopg2
from psycopg2 import pool
import threading

# 创建全局连接池，避免频繁创建连接
# 连接池参数：最小连接数=1，最大连接数=5，超时30秒
connection_pool = None
pool_lock = threading.Lock()

def get_connection_pool():
    global connection_pool
    if connection_pool is None:
        with pool_lock:
            if connection_pool is None:
                try:
                    connection_pool = psycopg2.pool.ThreadedConnectionPool(
                        1, 5,
                        dbname="langflow",
                        user="langflow",
                        password="langflow",
                        host="postgres",
                        port="5432"
                    )
                except Exception as e:
                    raise RuntimeError(f"Failed to create connection pool: {e}")
    return connection_pool

def load_words_cached():
    # 使用模块级变量缓存结果，有效期5分钟
    import time
    now = time.time()
    if not hasattr(load_words_cached, 'cache') or \
       not hasattr(load_words_cached, 'cache_time') or \
       now - load_words_cached.cache_time > 300:  # 300秒=5分钟
        
        pool = get_connection_pool()
        conn = pool.getconn()
        try:
            cursor = conn.cursor()
            cursor.execute("SELECT word FROM words ORDER BY word;")
            rows = cursor.fetchall()
            words = [row[0] for row in rows]
            load_words_cached.cache = words
            load_words_cached.cache_time = now
        finally:
            pool.putconn(conn)
    
    return load_words_cached.cache

class WordLoader(Component):
    display_name = "Word Loader (Cached)"
    description = "Load all words from database with caching (5 min). Reduces DB load."
    icon = "search"
    name = "WordLoaderCached"
    outputs = [
        Output(
            display_name="Words List",
            name="output",
            method="build_output"
        ),
    ]

    def build_output(self) -> Message:
        try:
            words = load_words_cached()
            if not words:
                return Message(text="No words found in database. Please upload a CSV first.")
            # 用换行符分隔，更利于 LLM 理解列表结构
            return Message(text="\n".join(words))
        except Exception as e:
            return Message(text=f"DB Load Error: {str(e)}")

为什么用连接池？
每个数据库连接（connection）都是昂贵的资源。Langflow 在高并发时，可能同时有 10 个 WordLoader 实例在运行，如果每个都新建连接，PostgreSQL 会因连接数超限而拒绝新请求。 ThreadedConnectionPool 在后台维护一个连接池，实例需要时“借”一个，用完“还”回去，复用连接。

为什么缓存 5 分钟？
用户添加新词的频率很低（可能几分钟才加一个），而故事生成请求可能每秒多次。缓存让 95% 的查询走内存，数据库压力直降。缓存键是 time.time() ，简单有效。

在 UI 中使用时，拖入此组件，它没有输入，只有一个输出。连接到 Prompt 组件的 {words} 参数即可。你会发现，第一次运行稍慢（要建连接池），之后几乎瞬时返回。

4.3 单词添加工具（AddWordTool）：Agent 调用的契约设计

这个组件是 Agent 的“手”，必须严格遵守 Langflow 的工具调用规范。原文代码有个严重问题：它在 add_new_word 方法里直接 return f"Added word: {self.word}" ，但 Langflow 的 Agent 期望的返回值是一个 Message 对象，且内容必须是纯文本，不能带额外格式。否则 Agent 会解析失败，整个流程中断。

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

def connect_to_database():
    return psycopg2.connect(
        dbname="langflow",
        user="langflow",
        password="langflow",
        host="postgres",
        port="5432"
    ).cursor()

class AddWordTool(Component):
    display_name = "Add Word Tool"
    description = "Add a new word to the vocabulary database. Use this when user requests to add a word."
    icon = "plus"
    name = "AddWordTool"
    inputs = [
        MessageTextInput(
            name="word",
            display_name="Word to Add",
            info="The exact word string to be inserted into the database.",
            # tool_mode=True 是必须的！告诉 Langflow 这是个 Agent 工具
            tool_mode=True,
            required=True
        ),
    ]
    outputs = [
        Output(
            display_name="Result",
            name="output",
            method="add_new_word"
        ),
    ]

    def add_new_word(self) -> Message:
        try:
            # 输入清洗：去空格，转小写，确保一致性
            clean_word = self.word.strip().lower()
            if not clean_word:
                return Message(text="Error: Word cannot be empty.")
            
            cursor = connect_to_database()
            # 使用更安全的参数化查询
            cursor.execute(
                "INSERT INTO words (word) VALUES (%s) ON CONFLICT (word) DO NOTHING RETURNING id;",
                (clean_word,)
            )
            result = cursor.fetchone()
            
            if result:
                return Message(text=f"Successfully added word: '{clean_word}'.")
            else:
                return Message(text=f"Word '{clean_word}' already exists in database.")
                
        except Exception as e:
            return Message(text=f"Database error: {str(e)}")

核心契约要点 ：

• tool_mode=True ：这是开关，不加它，Agent 根本看不到这个工具。
• required=True ：强制用户（其实是 Agent）必须提供 word 参数，避免空值。
• 返回 Message(text=...) ：必须是 langflow.schema.Message 类型，且 text 属性是字符串。Agent 会把这段文字原样塞回对话流。
• RETURNING id ：检查插入是否真的发生了，给出精准反馈（“已存在” vs “已添加”）。

在 UI 中，把这个组件拖入画布，右键 → Toggle Tool Mode ，确保右上角显示 “Tool Mode: ON”。然后，在 Agent 的 Tools 面板里，它就会出现，Agent 才能调用。

5. AI Agent 工作流编排：从 Prompt 工程到多层 Agent 协同

5.1 主 Agent 的 Prompt 设计：用“角色-规则-约束”三段式结构

Langflow 的 Agent 组件，Prompt 决定一切。原文的 prompt 是：“You will help the user practice their language skills...”，这太泛了。我用的是经过 12 轮 A/B 测试优化的三段式结构：

# ROLE
You are LinguaTutor, a patient and encouraging language learning assistant. Your sole purpose is to help users improve reading fluency through personalized, level-appropriate stories.

# RULES
- You MUST use the Story Generation Tool to create stories. Never generate stories yourself.
- You MUST use the Add Word Tool to add new words. Never add words manually.
- If the user asks for a story, you MUST ask for the target language first (e.g., "Which language would you like the story in?"). Then call the Story Generation Tool.
- If the user asks to add a word, you MUST extract the exact word string and call the Add Word Tool with it.
- Your responses must be concise, friendly, and in plain text. No markdown, no code blocks, no explanations of your process.

# CONSTRAINTS
- NEVER mention that you are an AI or that you are using tools.
- NEVER generate text outside the scope of reading practice.
- If a request is ambiguous, ask ONE clarifying question before proceeding.

为什么这样写？

• ROLE 定义人格，让 LLM 有代入感，减少“机械感”。
• RULES 是硬性指令，用 “MUST” 和 “NEVER” 强制行为，比 “please” 有效 10 倍。
• CONSTRAINTS 是护栏，防止 LLM “发挥创意”跑题。

在 Langflow UI 中，把这个 prompt 粘贴到主 Agent 组件的 System Message 字段。注意，不要粘在 User Message 里！ System Message 是给 LLM 的“大脑指令”， User Message 是每次用户输入的内容。

5.2 Story Generation 子 Agent：Prompt 参数化的实战技巧

子 Agent 的 Prompt 是： Create a story in {language} using only words from the following list:\n\n{words} 。这里 {language} 和 {words} 是两个参数，Langflow 会自动为它们生成输入框。但 {words} 的来源是 WordLoader 组件的输出，而 WordLoader 输出的是一个换行分隔的字符串。为了让 LLM 更好地理解这是一个“词汇表”，我在 WordLoader 的 build_output 方法里，特意用 \n 分隔，而不是原文的 ", " 。因为 LLM 对列表的感知， \n 比逗号强得多。实测对比：用逗号分隔时，LLM 有时会把 “apple, banana” 当成一个词；用换行分隔，它 100% 识别为两个独立词。

此外，子 Agent 的 System Message 需要更强的约束，因为它直接面对 LLM：

You are a creative story writer. Your task is to generate a very short, engaging story (3-5 sentences) in the specified language, using ONLY the words provided in the list. Do not invent any new words. Do not explain the story. Just output the story text.

这个 prompt 里，“very short”、“3-5 sentences”、“ONLY”、“Do not invent” 都是针对 LLM 常见幻觉的精准打击。我在测试中发现，不加 “Do not explain the story”，LLM 有 30% 概率在故事前加一句 “Here is a story about...”，这会污染输出，导致前端显示异常。

5.3 多层 Agent 协同架构：主 Agent 如何调度子 Agent

Langflow 允许 Agent 调用另一个 Agent，形成“Agent of Agents”。这是构建复杂工作流的核心能力。架构图如下：

[Chat Input] 
    ↓
[Main Agent] ——(calls)——→ [AddWordTool] 
    ↓
    (calls)——→ [Story Generator Agent] ——(uses)——→ [WordLoader] → [Prompt] → [LLM]
    ↓
[Chat Output]

关键配置点：

• 在 Main Agent 的 Tools 面板里，勾选 AddWordTool 和 Story Generator Agent （注意，是 Agent 组件本身，不是它的子节点）。
• Story Generator Agent 必须设置为 Tool Mode: ON ，并且它的 Tool Description 要写清楚：“Generates a short story in the target language using only words from the user's vocabulary list.”。这个描述会被 Main Agent 读取，用于判断何时调用它。
• Story Generator Agent 的 Output 必须连接到 Chat Output ，否则故事不会显示给用户。

实测中，一个常见错误是：用户说 “Make me a story in Spanish”，Main Agent 调用 Story Generator，但 Story Generator 的 {language} 参数没被填入。这是因为 Main Agent 的 prompt 没有明确指令它“提取语言”。所以我在 Main Agent 的 prompt 里加了那句：“If the user asks for a story, you MUST ask for the target language first...”，强制它先问，再调用，确保参数完备。

6. 实操全流程演示与避坑指南：从零到可交互产品的每一步

6.1 完整构建流程：按顺序执行的 7 个不可跳过步骤

我整理了一个严格顺序的 checklist，确保你一次成功：

1. 启动环境 ： cd langflow/docker_example && docker compose up -d （ -d 后台运行，不占终端）
2. 配置 API Key ：打开 http://0.0.0.0:7860 → Settings → API Keys → 粘贴 OpenAI Key → Save
3. 上传词库 ：拖入 UploadWordFile 组件 → 填 column_name （如 word ）→ 上传 CSV → 点 ▶️ → 等待绿色 Success
4. 构建子 Agent ：拖入 Agent 组件 → 命名为 StoryGenerator → 粘贴 Story Prompt → 设置 Tool Mode: ON → 在 Tool Description 填写精准描述 → 连接 WordLoader 到 {words} → 连接 Chat Input 到 User Message → 连接 Chat Output 到 Output
5. 构建主 Agent ：拖入另一个 Agent 组件 → 命名为 LinguaTutor → 粘贴 Main Prompt → 在 Tools 面板勾选 AddWordTool 和 StoryGenerator → 连接 Chat Input 和 Chat Output
6. 连接画布 ：确保 Chat Input → LinguaTutor → Chat Output 形成闭环； LinguaTutor 的 Tools 已关联两个工具
7. 测试 Playground ：点击右上角 Playground → 在聊天框输入 “Add word ‘gato’” → 应看到 “Successfully added word: 'gato'.”；再输入 “Make a story in Spanish” → 应先问 “Which language would you like the story in?” → 你答 “Spanish” → 它生成故事

为什么顺序不能乱？
步骤 3 是基石，没词库，后续所有数据库操作都返回空；步骤 4 和 5 的命名（ StoryGenerator ）必须和步骤 6 的 Tools 勾选名完全一致，Langflow 区分大小写；步骤 7 的 Playground 是最终验证，必须在所有组件配置完后才点。

6.2 典型问题速查表：90% 的报错都在这里

问题现象	根本原因	一键修复方案
Playground 打不开，白屏	浏览器缓存损坏	Ctrl+Shift+R 强制刷新，或换无痕窗口
Agent 报错 “Tool not found”	Tools 面板没勾选对应组件，或组件名不匹配	检查主 Agent 的 Tools 列表，确认勾选的名称和画布上组件的 name 属性（右键组件 → Edit → name）完全一致
Story 生成为空，或返回 “No words found”	WordLoader 没连接到 {words} ，或 UploadWordFile 没运行	在 WordLoader 组件上右键 → Inspect ，看输出是否为单词列表；