【免费下载链接】PocketFlow
Pocket Flow: 100-line LLM framework. Let Agents build Agents!
本教程以 PocketFlow 官方 cookbook 中的 pocketflow-gradio-hitl 示例为蓝本,讲解如何用 PocketFlow(100 行级 LLM 框架)编排带有人类反馈闭环的 Agent 工作流,并通过 Gradio 提供可交互的 Web 界面。读完本文,你将掌握如何设计决策式多节点 Flow、如何用共享上下文(shared)在节点间传递会话状态、如何把 LLM 的结构化 YAML 决策解析为流程跳转,以及如何借助消息队列把 Agent 的思考过程实时流式渲染到聊天界面。
示例概览:一个会订酒店、查天气的生活助手
cookbook/pocketflow-gradio-hitl 是一个"生活助理"演示应用:用户通过 Gradio 聊天界面与 AI 对话,AI 能完成两类任务——查询指定城市与日期的天气、预订酒店(含入住/退房日期);当信息不足或问题超出范围时,AI 会主动向用户追问;任务完成后则向用户播报结果并询问是否还有其他需求。
它的核心价值在于演示了 Human-in-the-Loop(HITL):整个工作流不是"一把梭"式地调 LLM,而是把"决策"与"执行"拆开——LLM 每轮只决定下一步动作,需要用户补充信息(如酒店名称、入住日期)时就暂停流程向用户提问,拿到反馈后再继续。这既避免了 LLM 一次生成错误参数,也让每个动作都在人类监督下逐步推进。
示例入口为 main.py,流程编排在 flow.py,节点实现集中在 nodes.py。
快速上手:安装、配置与启动
1. 安装依赖
先确认已克隆 PocketFlow 仓库并进入示例目录,然后安装依赖(见 requirements.txt):
pip install -r requirements.txt
依赖项及版本下限如下(与 README 中的 Requirements 一致):
| 依赖 | 版本要求 | 用途 |
|---|---|---|
| pocketflow | >= 0.0.2 | 工作流编排框架 |
| gradio | >= 5.29.1 | Web 聊天界面(5.x 起采用 type="messages" 消息格式) |
| openai | >= 1.78.1 | 调用 OpenAI 模型 |
2. 配置 OpenAI API Key
应用使用 OpenAI 模型(默认 gpt-4o,见 utils/call_llm.py)做动作决策。设置环境变量:
export OPENAI_API_KEY="your-openai-api-key-here"
如果你用的是兼容 OpenAI 协议的代理或国内模型网关,也可以直接修改 utils/call_llm.py 中的 base_url 与 model 两个常量,示例默认值为 https://api.openai.com/v1 与 gpt-4o。
3. 启动应用
python main.py
启动后 Gradio 界面默认运行在 http://localhost:7860。打开浏览器即可与 AI 对话,示例会自动为每个会话生成一个 UUID 作为 conversation_id,用于隔离不同会话的状态(见 main.py 中 gr.State 与 clear_fn 的实现)。
工作流架构:五个节点与条件跳转
整体流程图
README 给出了完整的工作流拓扑:
- Decide Action Node:中枢决策节点。根据"上一动作 + 动作执行结果 + 聊天历史 + 当前用户问题"决定下一步动作。
- Check Weather Node:查询指定城市与日期的天气。
- Book Hotel Node:处理酒店预订请求(含入住、退房日期)。
- Follow Up Node:向用户追问澄清信息,或引导超出范围的请求。
- Result Notification Node:向用户播报任务结果并提供进一步帮助。
用 PocketFlow 的语法连接节点
flow.py 中通过 PocketFlow 的 - "action" >> 与 >> 运算符完成带动作标签的条件连接与默认连接:
from pocketflow import Flow
from nodes import (
DecideAction, CheckWeather, BookHotel, FollowUp, ResultNotification,
)
def create_flow():
decide_action = DecideAction()
check_weather = CheckWeather()
book_hotel = BookHotel()
follow_up = FollowUp()
result_notification = ResultNotification()
decide_action - "check-weather" >> check_weather
check_weather >> decide_action
decide_action - "book-hotel" >> book_hotel
book_hotel >> decide_action
decide_action - "follow-up" >> follow_up
decide_action - "result-notification" >> result_notification
return Flow(start=decide_action)
关键点:
node - "action" >> next_node表示条件边:当节点post方法返回字符串"action"时,流程跳转到next_node。node >> next_node表示默认边:当post返回"default"时走这条路径。Flow(start=decide_action)以决策节点为起始。PocketFlow 的节点继承自BaseNode,其__sub__返回携带动作标签的_ConditionalTransition对象,__rshift__负责注册后继节点(见 pocketflow/init.pyi 的类型声明)。
从源码结构看,CheckWeather 与 BookHotel 的 post 返回 "default"(nodes.py 与 nodes.py),因此执行完天气查询或酒店预订后会沿默认边回到决策节点,让 LLM 基于执行结果决定"继续追问、再次调用工具还是播报结果"——这正是循环型 Agent 工作流的典型形态。
决策节点:让 LLM 输出结构化 YAML 来驱动流程
DecideAction 是整条工作流的"大脑",它把"下一步做什么"完全交给 LLM 决策,并通过强约束的 YAML 输出格式把决策结果结构化。
prep:组装上下文
def prep(self, shared):
conversation_id = shared["conversation_id"]
session = load_conversation(conversation_id)
return session, shared["history"], shared["query"]
prep 从 shared 字典中读取会话 ID、聊天历史与当前用户问题,并从会话缓存中加载 last_action(上一次动作)与 action_result(上一次动作结果)。
exec:构造提示词并解析决策
exec 中构造的提示词包含四部分:
- 角色指令:你是能订酒店、查天气的生活助理,需要基于"上一动作、动作结果、聊天历史、当前问题"决策下一步。
- 聊天历史:由
format_chat_history格式化。 - 上下文:
Last Action、Last Action Result、Current Date(当前日期由datetime.now().date()动态注入)。 - 动作空间(ACTION SPACE):四个候选动作及其参数 schema:
| 动作 | 适用场景 | 关键参数 |
|---|---|---|
check-weather | 用户询问天气 | city(必填)、date(选填,缺省用当天) |
book-hotel | 用户要订酒店 | hotel、checkin_date、checkout_date(均必填) |
follow-up | 问题超出范围,或当前信息不足以调用工具 | question(追问内容) |
result-notification | 酒店预订或天气查询已完成 | result(结果播报) |
提示词强制 LLM 输出固定格式的 YAML:
thinking: |
<你的逐步推理过程>
action: check-weather OR book-hotel OR follow-up OR result-notification
reason: <选择该动作的原因>
question: <当动作是 follow-up 时>
city: <当动作是 check-weather 时>
hotel: <当动作是 book-hotel 时>
checkin_date: <当动作是 book-hotel 时>
checkout_date: <当动作是 book-hotel 时>
result: <当动作是 result-notification 时>
并在提示词末尾强调三条格式纪律:多行字段用 4 空格缩进、多行文本用 | 块引用、单行字段不用 |。随后调用 call_llm 获取响应,通过 response.split("```yaml")[1].split("```")[0].strip() 剥离代码围栏,再用 yaml.safe_load 解析为字典。
post:写回会话并决定下一跳
post 是 HITL 闭环的关键:
def post(self, shared, prep_res, exec_res):
conversation_id = shared["conversation_id"]
session = load_conversation(conversation_id)
session["last_action"] = exec_res["action"]
flow_log = shared["flow_queue"]
for line in exec_res["thinking"].split("\n"):
line = line.replace("-", "").strip()
if line:
flow_log.put(f"🤔 {line}")
if exec_res["action"] == "check-weather":
session["check_weather_params"] = {
"city": exec_res["city"], "date": exec_res.get("date", None),
}
flow_log.put(f"➡️ Agent decided to check weather for: {exec_res['city']}")
elif exec_res["action"] == "book-hotel":
session["book_hotel_params"] = {
"hotel": exec_res["hotel"],
"checkin_date": exec_res["checkin_date"],
"checkout_date": exec_res["checkout_date"],
}
flow_log.put(f"➡️ Agent decided to book hotel: {exec_res['hotel']}")
elif exec_res["action"] == "follow-up":
session["follow_up_params"] = {"question": exec_res["question"]}
flow_log.put(f"➡️ Agent decided to follow up: {exec_res['question']}")
elif exec_res["action"] == "result-notification":
session["result_notification_params"] = {"result": exec_res["result"]}
flow_log.put(f"➡️ Agent decided to notify the result: {exec_res['result']}")
save_conversation(conversation_id, session)
return exec_res["action"]
这里发生了三件事:
- 持久化动作参数:把决策中的
city/date、hotel/checkin_date/checkout_date、question、result分别写入会话 session,供后续执行节点取用。 - 推送流程日志:把 LLM 的
thinking逐行、以及动作摘要(➡️ ...)推入flow_queue,供前端实时展示"思考过程"。 - 返回动作名作为跳转条件:
return exec_res["action"]的值会与flow.py中注册的动作标签匹配,从而驱动条件边跳转——"check-weather"去CheckWeather,"book-hotel"去BookHotel,"follow-up"去FollowUp,"result-notification"去ResultNotification。
执行节点:天气查询与酒店预订
CheckWeather / BookHotel
两个执行节点的结构完全对称,都遵循 PocketFlow 的 prep → exec → post 三段式:
- prep:从 session 中取出上一步决策写入的参数(城市/日期,或酒店/入住/退房日期)。
- exec:调用 mock API(utils/call_mock_api.py)返回模拟结果,避免真实调用外部服务。
- post:把结果推入
flow_queue(⬅️ ...),写入session["action_result"],然后返回"default"让流程回到决策节点。
Mock API 内置了贴近真实业务的校验规则,是很好的参数边界参考:
- 天气查询:日期与当前日期相差超过 7 天返回失败(
abs(date_diff) > 7)。 - 酒店预订:入住日期必须晚于当前日期;入住日期不得晚于(等于)退房日期;入住天数不得超过 7 天。
- 模拟返回值:天气为
sunny/cloudy/rainy/snowy随机选择、温度10~30°C随机;酒店预订成功返回包含日期范围的确认信息。
这些规则保证了 LLM 即使"脑补"了参数,也会在执行层被校验拦截并反馈回决策节点,触发 follow-up 追问,这正是 HITL 的意义所在。
FollowUp / ResultNotification:通过消息队列与前端通信
这两个节点不再直接操作 LLM,而是通过 shared["queue"](一个 Python queue.Queue)把要展示给用户的最终文本发送给 Gradio 前端:
class FollowUp(Node):
def prep(self, shared):
flow_log = shared["flow_queue"]
flow_log.put(None) # 标记思考日志结束
conversation_id = shared["conversation_id"]
session = load_conversation(conversation_id)
question = session["follow_up_params"]["question"]
return question, shared["queue"]
def exec(self, prep_res):
question, queue = prep_res
queue.put(question)
queue.put(None) # 标记聊天消息结束
return question
def post(self, shared, prep_res, exec_res):
conversation_id = shared["conversation_id"]
session = load_conversation(conversation_id)
session["action_result"] = exec_res
return "done"
注意 post 返回 "done",而 flow.py 中没有注册 "done" 边,因此流程在 FollowUp / ResultNotification 节点处自然终止——用户的每条消息触发一轮完整的"决策→执行→(可能)追问/播报"循环,而追问的答案由用户在下一条消息中给出。ResultNotification 在播报后还会清空 action_result 与 last_action(nodes.py),为下一轮对话重置上下文。
会话管理:shared 与内存级会话缓存
PocketFlow 的节点之间通过 shared 字典共享数据。在本示例中,main.py 为每轮对话构造了:
shared = {
"conversation_id": str(uuid),
"query": message,
"history": history,
"queue": chat_queue, # 用户可见的聊天消息
"flow_queue": flow_queue, # 思考过程/流程日志
}
而跨节点、跨轮次的状态(last_action、action_result、各动作参数)则由 utils/conversation.py 提供的内存缓存管理:
conversation_cache = {}
def load_conversation(conversation_id: str):
return conversation_cache.get(conversation_id, {})
def save_conversation(conversation_id: str, session: dict):
conversation_cache[conversation_id] = session
以 conversation_id(UUID)为键隔离不同会话,避免多人同时使用时状态串扰。需要说明的是,这是单进程内存缓存,重启进程后状态即丢失;如需持久化,可以替换为文件存储或 Redis 等方案。此外,utils/format_chat_history.py 在把历史喂给 LLM 前会过滤掉以 - 🤔、- ➡️、- ⬅️ 开头的思考/流程日志行,防止 Agent 把自己的"思维链"当成对话内容重复输入。
前端集成:Gradio 多线程流式渲染
main.py 展示了如何把 PocketFlow 同步流程嵌入 Web 应用:
- 全局线程池:
ThreadPoolExecutor(max_workers=5)让多个会话的 Flow 并发运行,避免阻塞 Gradio 事件循环。 - 异步提交:
chatflow_thread_pool.submit(chat_flow.run, shared)把 Flow 丢到后台线程执行。 - 双队列流式输出:主线程先消费
flow_queue累积"思考日志",逐条yield更新ChatMessage(其metadata含title="Flow Log"、status与duration字段);待流程结束(队列收到None哨兵)后,再消费chat_queue,把追问或结果作为普通消息yield出去。 - 界面搭建:
gr.Blocks(fill_height=True, theme="ocean")中放置gr.Chatbot(type="messages")与gr.ChatInterface,通过gr.State保存 UUID;点击清除按钮时clear_fn生成新 UUID 开启全新会话。
这样,用户能在界面上实时看到 Agent 的思考步骤与节点执行顺序,而不仅仅是最终答案。
运行效果与流程可视化
应用提供实时流程可视化:节点激活顺序按时间先后展示,用户可以看到哪些决策路径被触发,从而理解 AI 的决策过程。
下图是用户发送 hello 时的完整界面:上方是带耗时统计的 Flow Log,逐条展示 Agent 的分析与决策("用户用 hello 问候,无天气或酒店预订的上下文,需友好跟进以明确需求"),下方是 AI 的友好追问:
预订酒店的示例输出——用户提出"明天订酒店",AI 追问酒店与入住时长,发现"最长只能订 7 天"后与用户协商,最终确认纽约希尔顿 2025-05-31 至 2025-06-07 的预订:
对话中途改变意图的示例——用户从"订酒店"临时转向"查纽约明天天气",AI 先给出天气结果,再确认继续预订希尔顿 3 天,展示了 HITL 工作流对用户意图变化的灵活响应:
文件结构与扩展建议
示例目录结构如下:
| 文件 | 作用 |
|---|---|
| main.py | 入口:Gradio 界面搭建、线程池、双队列流式输出 |
| flow.py | 定义 PocketFlow 图与节点连接关系 |
| nodes.py | 五个节点的实现 |
| utils/call_llm.py | OpenAI 调用封装(模型、base_url 可改) |
| utils/call_mock_api.py | 天气/酒店的模拟 API 与业务校验 |
| utils/conversation.py | 内存级会话缓存 |
| utils/format_chat_history.py | 聊天历史格式化(过滤思考日志) |
| requirements.txt | 依赖清单 |
想扩展这个示例时,推荐按以下顺序动手:
- 新增工具节点:在
ACTION SPACE中追加新动作描述与参数 schema,在flow.py中注册条件边,在nodes.py中实现新节点,并在post中保存参数。 - 替换 mock API:把
call_book_hotel_api/call_check_weather_api换成真实后端 HTTP 调用,业务校验可保留在服务端。 - 持久化会话:将
conversation_cache换成数据库或 Redis,即可支持多实例部署。 - 升级异步:如需更高并发,可参考仓库内 docs/core_abstraction/async.md 与 tests/test_async_flow.py,将节点改为
AsyncNode。
小结
pocketflow-gradio-hitl 用约 300 行代码完整演示了"决策循环 + 人工介入 + 可视化"的 HITL 应用范式:LLM 只做结构化决策,工具执行与参数校验交给普通节点,用户追问通过消息队列回到前端,整个流程由 PocketFlow 的 shared 上下文与动作标签无缝串联。这套模式稍加改造即可复用于预订、下单、审批等任何"AI 出主意、人来拍板"的真实业务场景。
【免费下载链接】PocketFlow
Pocket Flow: 100-line LLM framework. Let Agents build Agents!
创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考






