构建您的智能体

工作流

工作流让您在 LLM 参与之前编写智能体如何响应常见访客问题的脚本。适用于预设答案（退款常见问题、营业时间、商店政策）、潜在客户资格问卷、分支资格流程，以及在特定关键词上直接人工接管。

如何融入

每条访客消息都经过此管道：

精选答案匹配 — 管理员固定的精确问题答案。
工作流匹配 ← 本页。
RAG 检索 + LLM 生成。

当工作流匹配时，它会短路 LLM 调用：访客收到脚本化的气泡，不会产生 token 成本，并且对话会被标记工作流运行以供分析。

工作流如何连接到智能体

工作流仅在三个条件全部满足时才为访客轮次触发：

状态为 active。新工作流以 draft 开始，运行时完全忽略它们，直到您切换状态 — 这就是您在不破坏实时流量的情况下暂存编辑的方式。 disabled 是第三种状态，表示“暂停但未删除”。
智能体范围匹配。在工作流的编辑页面上， 限定到智能体 选择为您提供两种形状：
- 全工作区（每个智能体） — agent_id IS NULL。该工作区中的每个智能体都有资格使用该工作流。适用于跨领域流程，如“任何地方的 'human' 一词触发接管”。
- 固定到一个智能体 — 从下拉列表中选择一个特定的智能体。只有该智能体上的对话才有资格使用工作流。适用于商店特定的常见问题（“退货”只与 Shopify 商店智能体相关，而与文档智能体无关）。
触发器触发。访客的消息必须实际匹配工作流的关键字集（在配置的 any / all / exact 匹配模式下）。

具体来说，对于每个访客轮次，引擎运行一个查询：

SELECT * FROM workflows
 WHERE status = 'active'
   AND workspace_id = :current_workspace
   AND (agent_id IS NULL OR agent_id = :current_agent)

…并按顺序遍历匹配的行，返回第一个关键字与消息匹配的行。顺序是数据库中的插入顺序（即旧的工作流赢得平局）；使用状态 disabled 停用工作流而不丢失其关键字。今天没有优先级列 — 如果您需要更严格的优先级，请缩小关键字集，以便两个工作流不能同时匹配同一个轮次。

快速配方 — 将新工作流连接到智能体

转到 /app/workflows → 新建工作流。
给它一个名称。从 限定到智能体 中选择智能体（或保留在 全工作区 上）。
状态：如果您准备好立即发布，请选择激活，或者在您仍在编辑时选择草稿。
在触发器配置中添加至少一个关键字（例如 refund）并选择匹配模式。
添加至少一个步骤 — message 气泡即可。
保存。
在目标智能体的公共小部件上，键入包含关键字的消息。工作流代替 LLM 运行，您将看到脚本化的回复。

要在不删除工作流的情况下停止它，将其状态翻转为 disabled。要将其从一个智能体重新定位到另一个智能体，只需在同一工作流行上更改 限定到智能体 — 无需克隆步骤。

功能

一种触发器类型：关键字，具有三种匹配模式（any / all / exact）。
六种步骤类型：message, question, branch, tag_lead, webhook, escalate。
变量插值：任何消息文本中的 {{var_name}} 在运行时解析捕获的值。
基于捕获答案的条件分支（5 个匹配运算符 + 默认回退）。
用于标记潜在客户和 POST 到外部 webhook 的副作用步骤（排队、即发即弃）。

步骤类型

类型	作用
`message`	发送一个聊天气泡。支持 `{{var_name}}` 插值。直接走到下一步。
`question`	发送一个气泡 + 暂停运行。访客的下一条消息被捕获到 `var_name` 中，运行在下一轮从下一步恢复。
`branch`	针对有序的案例列表评估 `vars[var]`，并跳转到第一个匹配的 `go_to` 步骤索引。案例运算符为 `equals`, `contains`, `starts_with`, `is_empty`, `not_empty` 和 `default`（当没有其他案例命中时触发的回退）。每轮循环保护限制为 32 次跳转，因此格式错误的图不会挂起引擎。
`tag_lead`	将字符串标签附加到对话的 Lead 行（如果访客尚未提交内联表单，则创建存根 Lead）。标签累积并在 `fields.tags` 上去重。典型用法：在分支将他们引导到 Pro 通道后，将访客标记为 `pricing_intent`。
`webhook`	使用运行的 `vars`, `conversation_id`, `workflow_id` 和任何 `extra_payload` 向外部 URL 发送即发即弃的 POST（或 GET）。作为排队的 `DispatchWebhookJob` 调度，因此访客的聊天界面永远不会等待缓慢的集成。失败在 3 次重试后进入 `/admin/jobs/failed`。
`escalate`	发送再见气泡 + 将运行标记为升级。对话现在在收件箱中，供操作员从接管 UI 认领。

触发器匹配模式

模式	匹配条件
`any` （默认）	至少有一个关键字作为访客消息的不区分大小写的子字符串出现。`"pricing"` 匹配 "tell me about pricing please"。
`all`	每个关键字都必须作为子字符串出现。适用于复合限定符 — `["enterprise", "security"]` 不会在 "tell me about pricing" 上触发，但会在 "enterprise security review" 上触发。
`exact`	修剪后的小写消息与其中一个关键字完全相同。用于不需要在子字符串匹配上触发的单字命令（"cancel", "help", "support"）。

分支路由

branch 步骤的 cases 数组按顺序遍历。第一个 match 评估为 true 的案例获胜，执行跳转到 go_to（步骤索引）。 match: default 是一个始终匹配的特殊案例，应该放在最后 — 它是当前面的运算符都没有触发时的包罗万象。

{
  "type": "branch",
  "var": "plan_interest",
  "cases": [
    { "match": "equals",      "value": "free", "go_to": 5 },
    { "match": "contains",    "value": "pro",  "go_to": 8 },
    { "match": "not_empty",                    "go_to": 12 },
    { "match": "default",                      "go_to": 15 }
  ]
}

流程可以链接分支 — 循环保护将每轮执行限制为 32 次跳转，因此两个意外指向彼此的分支不能无限循环。当保护触发时，运行被标记为 failed，并且在循环之前发出的任何气泡仍然刷新到访客。

触发器语义

运行时遍历每个激活的工作流，其工作区与对话的智能体匹配，且 agent_id 为 NULL（全工作区）或与对话的智能体匹配。在这些行中，第一个关键字匹配的工作流（根据其 match_mode）获胜。索引页面上的顺序按 updated_at 降序排列 — 最近保存的工作流首先尝试。

编辑 — 可视化画布（默认）和线性表单（备选）

两种编辑工作流的方式，都由相同的 JSON 形状支持：

可视化画布 位于 /app/workflows/{id}/canvas — 默认编辑器。点击索引页面上的工作流或保存新创建的流程会将您带到这里。 React-Flow 编辑器，每个步骤一个节点，手柄之间可拖动的连接，以及右侧检查器面板。分支节点每个案例有一个手柄（加上可选的 default 手柄）；将每个手柄连接到下一步。
线性表单 位于 /app/workflows/{id}/edit — 备选方案。具有特定于类型的字段的步骤卡片堆栈。当流程足够简单以至于平面列表比图更清晰时，从画布页面的“线性编辑”按钮访问它。

画布将视觉布局（节点位置 + 边缘连接）保存在 definition.canvas 下，与运行时消耗的 definition.steps 数组一起 — 因此在画布中创作的流程下次重新打开时保持相同的排列。

从画布保存运行从触发器节点开始的图的拓扑遍历，并以 BFS 顺序序列化步骤数组。分支 cases[*].go_to 从边缘目标索引填充，因此仅打开以读取的流程重新保存不会更改步骤。

状态

草稿 — 从不匹配。在编辑时使用。
激活 — 在每个访客轮次上匹配。
禁用 — 保留用于历史但从不匹配。适用于您稍后将重新启用的季节性流程。

第 3 阶段展望

持久化形状保持向前兼容。第 3 阶段可能会添加：

A/B 测试 — 多个工作流变体共享一个触发器；运行时为每个访客选择一个并记录哪一个转化。
每流程分析 — 每步流失率、分支臂分布、接管时间。
访客细分触发器（除了关键字） — 页面 URL 模式、返回与新访客、GeoIP。

读取第 3 阶段定义的旧运行时会静默跳过它们不认识的步骤类型，因此未来的管理员可以保存一个在较旧部署上优雅降级的定义。