指南 05 · 变量读写与回传¶
本框架把「变量」分成两套，理解这一点是写好状态机（如分阶段办理）的关键：
- 内部控制变量（
ctx.variables）：工作流内部随便记，默认不回传前端。 - 对外回传变量（
ctx.return_variables）：只有你显式声明的键才作为updateVariables事件回传给前端。
| 节点 | 作用 | 是否回传 |
|---|---|---|
VariableUpdate |
写一个内部控制变量 | 否 |
VariableOutput |
显式挑选若干变量回传前端 | 是 |
Answer / 文本 |
把 {{key}} 占位符按 ctx.variables 渲染 |
— |
设计意图：内部算完，挑几个返回。流程内部可随意记录临时量，但只有明确声明的键会暴露给前端，避免泄露一堆内部状态。
1. VariableUpdate — 写内部变量¶
from agentframework.nodes import VariableUpdate
wf.add_node(VariableUpdate(name="set_count", key="turn_count", value=1))
wf.add_node(VariableUpdate(name="set_name", key="user_name", value=wf.ref("llm.reply")))
value 支持 wf.ref 引用节点输出。只写 ctx.variables，不产生对外事件。
2. VariableOutput — 显式回传¶
variables 的 value 有三种来源：
from agentframework.nodes import VariableOutput
# ① 显式传值
wf.add_node(VariableOutput(name="out", variables={"session_id": "s-123"}))
# ② value 为 None：从内部控制变量里取（内部算完挑几个返回）
wf.add_node(VariableOutput(name="out", variables={"currentStage": None, "nextStage": None}))
# ③ wf.ref 引用节点输出
wf.add_node(VariableOutput(name="out", variables={"name": wf.ref("llm.reply")}))
行为要点：
value is None时从ctx.variables[key]取，未设置会抛ValueError。- 多个键可一次性声明；
variables为空抛ValueError。 - 网关执行结束时对比请求基线（
merge_new_variables），只把这里声明的键的变更作为updateVariables事件回传。
3. {{key}} 占位符渲染¶
在 Answer 或 VariableUpdate 链路的文本里可用 {{key}}，由 render_variables 按 ctx.variables 渲染：
wf.add_node(VariableUpdate(name="set_name", key="user_name", value="张三"))
wf.add_node(
Answer(name="greet", text="你好{{user_name}}，很高兴为您服务")
) # → 你好张三，很高兴为您服务
未找到的 key 保留原占位符（不报错），由你的逻辑决定兜底。
4. 组合：分阶段办理状态机¶
完整案例的惯用组合是「VariableUpdate 写下一个阶段 + VariableOutput 回传」。
- 推进阶段：写内部变量，再回传。
wf.add_node(VariableUpdate(name="to_next", key="nextStage", value="userInput"))
wf.add_node(VariableOutput(name="out_next", variables={"nextStage": None})) # 取内部值回传
- 结束 / 退出：用单节点
VariableOutput显式清空并置nextStage: "end"——框架按基线merge_new_variables只回传变更键，无需维护一条「清空链」：
wf.add_node(
VariableOutput(
name="end_out",
variables={
"nextStage": "end",
"currentStage": "", # 显式传空即清空该前端变量
"flag": "",
},
)
)
前端靠
variables里带的currentStage驱动展示阶段；后端各IfElse读这些变量决定下一步。参考 withdrawal_customer_service 示例 的_route_flow（联合路由：分类结果 > 退出 > 阶段）。
5. 完整可运行示例¶
- withdrawal_customer_service 示例：阶段变量驱动 +
VariableUpdate写 +VariableOutput回传/清空 +{{key}}渲染，最完整的实战。