Langflow Agent 教程：可视化 Flow、工具审批、API 接入与人工验收

这篇教程会完成什么

用 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 代替。