Python 转场函数：用代码驱动 Flow 的复杂逻辑

什么时候需要转场函数

无代码 Flow（Default Steps + 实体提取）适合绝大多数业务场景——预订、身份验证、FAQ 引导这些都不需要写代码。但以下情况会遇到天花板：

• 路由逻辑依赖外部数据：比如"如果客户的账户余额 > 0 走充值 Flow，= 0 走新注册 Flow"——余额需要实时从 CRM 查
• 需要调用 API：比如检查某个时间是否可预订、验证一个确认码是否有效
• 需要做数值比较或复杂判断：比如"如果用户提供的订单号超过 30 天、且状态是'已发货未签收'、且用户地址在华东地区，走特殊处理路径"

遇到这些场景时，用 Python 转场函数。

转场函数在 Flow 里的位置

转场函数是 Flow 的高级步骤（Advanced Step）。它和普通 Collect / Confirm Step 的区别是：

• 普通 Step 的逻辑由 PolyAI 内置实现，你只需要配置参数
• 转场函数的逻辑由你用 Python 写，可以包含任意复杂的判断、API 调用、数据处理

转场函数通常出现在 Flow 的路由节点——比如收集完所有预订信息后，需要调用预订系统检查时间是否可用，然后根据 API 返回值决定走"确认预订"还是"推荐其他时间"。

基本结构

一个转场函数的 Python 结构大致是：

函数接收：当前对话上下文、已收集的实体值、会话 ID 等
函数执行：你写的业务逻辑（查 API、比较值、做判断）
函数返回：下一步该走哪个 Edge / Step，可选带附加数据

PolyAI 为转场函数提供了 conv 对象，你可以在函数里直接访问：

• conv.variables.xxx：之前 Collect Step 收集的实体值
• conv.goto_flow("X")：跳转到另一个 Flow
• （如果集成了 CRM）conv.crm.query(...)：查询客户数据

和 ADK 的关系

转场函数的 Python 代码在两个地方可以编辑：

• Agent Studio 界面里直接写（适合简单函数，代码量小）
• ADK 本地项目里编辑 functions/ 目录下的 .py 文件（适合复杂函数，用完整 IDE 开发 + Git 版本管理）

两种方式指向同一份底层配置——你在 Studio 里写的函数，pull 下来后就是一个 .py 文件；你在本地 IDE 里改完 push 回去，Studio 界面会实时显示更新。

安全和性能

转场函数在 PolyAI 的服务器端沙箱里执行，有以下限制：

• 网络访问受限于你配置的集成端点（不能随便联网调 API）
• 执行时间有上限（避免阻塞对话管道）
• 不允许执行 subprocess、文件系统访问等系统级操作

这些限制是为了保证对话管道的稳定性——你的转场函数不会因为一个慢 API 调用就把用户卡在 Flow 里。如果需要执行耗时操作，建议通过异步方式（让函数返回占位结果，后续通过 Webhook 更新）。