Guide · 使用教程
Langflow Agent 教程：可视化 Flow、工具审批、API 接入与人工验收
从 Simple Agent 模板开始，先做有出处的只读答复，再用测试工具验证人工审批，最后通过 API 调用已验收的 Flow。
这篇教程会完成什么
用 Langflow 搭一个可调试的 Agent：先让它读取公开或已授权的资料，只输出带来源的答复草稿；再给一个测试环境中的写入工具加人工审批；最后让只读 Flow 通过 API 供现有应用调用。产物包括 Flow 版本、20 题验收表、一次批准和一次拒绝的记录，以及按通过验收的答复统计的费用。以下是操作方案，不声称已经在读者的账户或服务器运行。
开始前准备
按官方安装指南选桌面版或 Docker。演示可在本机启动，但若计划放到共享网络，先配置 LANGFLOW_AUTO_LOGIN=False、强密码、独立的 LANGFLOW_SECRET_KEY、反向代理和 TLS；不要把 7860 编辑器端口直接暴露公网。锁定官方稳定版本并查安全公告，升级前备份 Flow 与数据库。准备一个模型提供商的有效密钥，并记下其独立计费。密钥放在受控环境或 Langflow 全局变量，不写进 Flow 导出文件和代码库。
准备 20 个已授权问题：10 个能从公开资料回答，5 个资料没有答案，5 个涉及旧版本或相互矛盾的描述。人工写好预期答案和出处。另准备一个可丢弃的测试系统，用来验证“写入前审批”；不要一开始连接真实邮件、CRM 或生产数据库。
第一步：从 Simple Agent 模板开始
新建 Flow，选择官方 Simple Agent 模板。它已经连接 Chat Input、Agent、Chat Output 和示例工具。先选有额度的模型，在 Playground 运行两个低风险问题，观察 Agent 是否调用了正确工具、输入输出是什么。把不需要的工具操作关掉，修改工具说明，使动作边界清楚。读网页或文档时只给已授权来源；网页摘要和模型生成语句都不能自动当作可信证据。
第二步：把资料和答案分开验收
按官方组件文档接入 Read File、模型与检索组件，或先用允许访问的公开网页做试点。每次答复都留存使用的文档版本、URL、检索片段和运行时间。要求模型在找不到支持材料时说“不知道”，并在最终输出中列出对应来源。由人逐条检查：引用是否确实支持该句、旧版资料是否被误用、越权请求是否被拒绝。若答案错，先区分是文件读取、检索召回、工具返回还是模型生成问题。
第三步：为有副作用的工具设置审批
在测试系统准备一个仅能写测试数据的工具组件，开启 Tool Mode，将其连接到 Agent 的 Tools 输入；只暴露所需动作，并在 Agent 的工具菜单为这个写入动作启用 Requires approval。用 Playground 发起一次会触发写入的请求，分别测试 Approve 和 Reject：批准后只允许测试数据变化；拒绝后确认没有写入，并保存运行记录。批准界面不能替代权限控制，工具凭据仍需限制到最小范围。
官方 1.12 文档说明，包含 Human-in-the-Loop 的目标 Flow 不能作为 Run Flow 组件中的嵌套 Flow 等待审批；审批应放在父 Flow。把该 Flow 接入外部 API 前，还应按当前版本文档实测暂停、恢复和调用方处理方式。若你的运行路径不能可靠完成审批，就让 API 仅产生待审草稿，由现有业务系统负责批准后写入。
第四步：通过 API 调用只读 Flow
先复制一份只有读取和生成草稿能力的 Flow。按官方快速入门在 Langflow 中创建 API key，把 Flow ID 和地址替换为自己的值，用以下请求调用；密钥应来自受控环境变量，不放在前端浏览器：
curl --request POST \
--url "https://YOUR_LANGFLOW_HOST/api/v1/run/YOUR_FLOW_ID" \
--header "Content-Type: application/json" \
--header "x-api-key: $LANGFLOW_API_KEY" \
--data '{"output_type":"chat","input_type":"chat","input_value":"请根据已授权资料说明退货条件"}'
在后端设置超时、并发、重试上限和审计 ID。不要把同一个用户请求无限重放；对写入工具要另设幂等键。记录模型 token、检索调用、主机与人工审核时间，按“有正确出处且通过人工验收的答复”核算单件成本。
第五步：发布前验收与回退
把 20 题跑两轮：先测只读答复，再测异常与审批。至少满足：无答案时不编造；引用指向正确版本；未授权资料不进入上下文；拒绝审批时零写入；重复请求不会重复发消息；API key 失效时明确报错。把 Flow 导出并存版本，去掉导出文件中的密钥。升级或更换模型前重跑同一组题；若错误率上升，回退到上一个已验收版本。
常见错误
- API 返回 401：检查 Langflow key 的权限与请求头，别用模型提供商 key 代替。
- Flow 有输出却缺少出处：检查检索结果是否保留 URL、文档版本与片段。
- Agent 调错工具：缩小可用动作并写清工具说明，不靠提示词单独限制权限。
- 审批在 Playground 能用、嵌套调用失败：对照当前 Human-in-the-Loop 和 Run Flow 限制，把审批放父 Flow 或业务系统。
- 成本突然上升：查看模型重试、检索次数、循环调用与未设上限的 Agent 步数。
什么时候换工具
若团队需要完整知识库、应用发布和内容运营工作台，试 Dify；若主任务是连接邮件、CRM 和审批系统，试 n8n。Langflow 擅长把 AI 逻辑做成可观察的 Flow，但业务级权限、运行保障和审计仍要由整体系统承担。
官方资料
常见问题
- Langflow 必须用 Docker 吗？
- 不必。官方还提供桌面版和 Python 包；团队共享与生产部署应选择有持久化、鉴权和升级方案的路径。
- Langflow API key 和模型 API key 是同一个吗？
- 不是。前者用于调用 Langflow 服务，后者用于模型提供商；要分开保管和授权。
- Requires approval 能自动保护所有运行方式吗？
- 不能这样假定。先在所用版本和具体运行路径实测暂停、批准、拒绝与恢复；嵌套 Run Flow 对 HITL 有限制。
- 怎样证明资料问答可靠？
- 用带人工答案和出处的题集核对检索片段、文档版本、最终引用，并加入无答案和冲突资料测试。
- 自部署后资料就不会外发吗？
- 不一定。外部模型、向量库和工具仍可能接收数据，需逐项核对网络与日志路径。
- 软件免费后还要计算什么成本？
- 主机、数据库、模型 token、向量库、失败重试、备份和人工复核；按通过验收的任务数核算。