公共字段与 state
请求字段
| 字段 | 类型 | 提供方式 | 含义 |
|---|---|---|---|
session_id | string | 每轮传入 | 同一会话保持一致,后端据此保存、取回状态和历史对话。 |
content | string | 每轮传入 | 本轮用户发言。 |
history | string | 每轮传入 | 本轮之前的历史对话内容。 |
state | object 或 null | 每次请求传入 | 请求主路由时使用上轮保存的状态,无待续接业务时为 null;请求业务 Workflow 时使用本轮主路由返回的状态。 |
context | object | 按需传入 | 对话之外的业务背景,例如后端已查询到的服务资格、产品信息。 |
主路由返回后端
| 字段 | 类型 | 含义 |
|---|---|---|
target_workflow | string | 本轮需要调用的业务 Workflow 标识。需求不明确时为 other。 |
state | object 或 null | 继续当前业务或澄清时保留入参状态;明确切换业务时为 null。后端将此值传入本轮目标 Workflow。 |
首次没有业务状态时,主路由返回调用目标,并保留 state: null:
{
"target_workflow": "<业务workflow标识>",
"state": null
}
后端按 target_workflow 选择调用地址,保留原请求中的 session_id、content、history 和按需提供的 context,将 state 设为主路由返回值,再请求业务 Workflow。
业务 Workflow 返回后端
| 字段 | 类型 | 含义 |
|---|---|---|
script | string | 本轮对外话术,由后端用于回复用户。 |
state | object 或 null | 本轮业务处理后的续接状态;无待续接业务时为 null,否则包含完整的 routing 与 workflows。 |
后端以业务 Workflow 返回的整份 state 作为本轮最终状态,下一轮与新的 content、更新后的 history 一起传入主路由。会话状态统一由后端保存。
state:业务归属、续接入口与变量
state: null 表示没有待续接业务。有待续接业务时,state 分为两层:routing 记录业务归属,workflows 保存处理进度与跨轮变量。下面是等待用户反馈时的状态结构,尖括号中的值由具体业务定义;两处 <业务workflow标识> 使用相同取值。
{
"routing": {
"active_workflow": "<业务workflow标识>"
},
"workflows": {
"<业务workflow标识>": {
"status": "waiting_input",
"resume_from": "<续接入口>"
}
}
}
| 字段 | 类型 | 含义与更新方 |
|---|---|---|
routing.active_workflow | string | 当前待续接的业务 Workflow 标识,由业务根据处理结果设置。 |
workflows | object | 以业务 Workflow 标识为键保存当前业务的一份续接记录,由业务 Workflow 更新。切换业务后,以新业务返回的状态替换原状态。 |
workflows.<业务workflow标识>.status | string | 当前保留记录使用 waiting_input,表示等待用户反馈。 |
workflows.<业务workflow标识>.resume_from | string | 下一轮进入的业务处理分支,由业务 Workflow 定义取值并更新。 |
workflows.<业务workflow标识>.variables | object,可选 | 业务需要跨轮保存的值,内部字段由业务按需定义和更新。 |
后端维护业务 Workflow 标识到调用地址的映射。resume_from 是业务内部约定的分支键,与入口 Switch 的分支配置对应。每次业务新执行从入口开始:没有本业务记录时进入首次处理;已有记录时按 resume_from 选择续接分支。
公共约定固定字段结构;各业务分别定义业务 Workflow 标识、可续接入口和需要保留的变量。
调用目标与业务状态
| 字段 | 表达什么 |
|---|---|
target_workflow | 主路由选择的本轮调用目标。 |
state.routing.active_workflow | 已保存业务状态中的待续接归属,由业务 Workflow 返回。 |
主路由明确判定切换业务时,返回新调用目标和 state: null。后端携带空状态请求新业务,由新业务从首次处理开始,生成本轮话术与状态。
主路由负责决定旧续接状态是保留还是清空;业务 Workflow 负责生成和更新具体的业务状态。
需求不明确时,主路由返回 target_workflow: "other",同时保留原来的 state。本轮属于澄清,原业务仍待续接。other 结合本轮输入、历史对话和已有状态生成话术,返回原状态。
后端始终按 target_workflow 发起本轮业务请求。other 的本轮执行结束后,原业务仍可在后续路由判断中继续处理。
完成当前待续接业务时的返回
当前待续接的业务 Workflow 完成自身交互后,直接向后端返回话术和 state: null:
{
"script": "<本轮话术>",
"state": null
}
首次没有业务状态、明确切换业务以及业务完成交互,均使用 state: null。本轮执行结束后仍需用户反馈时,继续返回状态对象。这里的完成指本项对话交互完成,外部业务事项按各自流程继续处理。
四段调用
| 调用关系 | 传递内容 | 状态交接 |
|---|---|---|
| ① 后端 → 主路由 | session_id、content、history、state;按需附带 context | 传入上轮保存的完整状态,首轮为 null。 |
| ② 主路由 → 后端 | target_workflow、state | 选择调用目标;继续或澄清时保留原状态,明确切换时返回 null。 |
| ③ 后端 → 业务 Workflow | 沿用请求字段 | 对话与背景保持原值,state 使用本轮主路由返回值。 |
| ④ 业务 Workflow → 后端 | script、完整 state | 返回本轮话术和最终状态,后端保存结果并发送话术。 |
同一轮用户消息对应两次独立请求:先请求主路由,再请求目标业务 Workflow。主路由与业务 Workflow 各自通过 Webhook 接收后端请求,并将结果作为该次请求的响应返回后端。
主路由每轮结合 content、history 与已有状态判断消息归属。相关追问交给原业务;明确的新诉求选择对应业务;需求不明确时选择 other。
多轮之间如何衔接
| 本轮情况 | 主路由与业务如何处理 | 返回后保存的状态 |
|---|---|---|
| 首次请求,已识别业务 | 主路由返回业务标识,保留入参中的 state: null;后端请求对应 Workflow,从首次处理分支开始。 | 需要用户反馈时,由业务生成当前业务归属与续接记录。 |
| 继续当前业务 | 主路由返回当前业务标识与原状态;后端请求业务,按 resume_from 进入分支。 | 仍需反馈时更新业务状态;交互完成时返回 state: null。 |
| 明确切换业务 | 主路由返回新业务标识和 state: null;后端携带空状态请求新业务。 | 新业务从首次处理开始,返回自身状态,替换原业务状态。 |
| 需求尚不明确 | 主路由返回 other;后端请求 other Workflow,由其生成澄清话术。 | 保留已有业务状态。 |
业务示例
下面用“扣费投诉的服务安排确认”演示完整往返:业务给出核查安排后询问是否认可,用户可能认可、改问发票,或纠正当前理解。对话文本排版、业务名称、续接入口和话术均为示例设定。
“首次进入”展示第一轮;其余三个场景分别从首次返回的投诉状态继续,展示不同的第二轮回答。
本轮用户
下一轮
示例业务与续接入口
下表说明示例取值如何对应业务内部的处理分支。实际接入时,由各业务 Workflow 定义自己的入口,并配置相应的 Switch 分支。
| 示例业务 Workflow 标识 | 示例 resume_from | 示例中的处理分支 |
|---|---|---|
complaint(投诉) | handle_feedback | 处理对安排的认可、追问或异议。 |
complaint(投诉) | handle_adjustment | 已询问用户的调整诉求,处理其具体要求。 |
invoice(发票) | collect_invoice_title | 处理用户提供的发票抬头。 |
verification(验证码) | verify_code | 处理本轮验证码或相关问题。 |
other(澄清 / 兜底) | — | 结合对话与已有状态返回话术,保留原业务记录。 |
以调整诉求为例:用户只回答“不认可”时,业务询问具体要求,并保存 handle_adjustment;收到要求并给出新安排后,再保存 handle_feedback,等待用户确认。
context 示例:额外业务背景
假设后端已查询到服务资格和产品信息,可通过 context 提供;后端分别请求主路由与业务 Workflow 时均携带原值。此例中的 service_eligibility、product_name 是业务自定义字段。
{
"session_id": "S001",
"content": "这次扣费不对,我要投诉。",
"history": "",
"state": null,
"context": {
"service_eligibility": "eligible",
"product_name": "基础服务"
}
}
variables 示例:验证码尝试次数
假设验证码业务需要跨轮保留尝试次数,定义 variables.attempts_used。主路由已返回 target_workflow: "verification" 并保留原状态,后端请求验证码 Workflow:
{
"session_id": "S002",
"content": "222222",
"history": "[客服] 请输入 6 位验证码。\n[用户] 111111\n[客服] 验证码不正确,还可以尝试两次。",
"state": {
"routing": {
"active_workflow": "verification"
},
"workflows": {
"verification": {
"status": "waiting_input",
"resume_from": "verify_code",
"variables": {
"attempts_used": 1
}
}
}
}
}
假设验证服务确认本次为第二次失败,验证码 Workflow 直接向后端返回:
{
"script": "验证码不正确,还可以尝试一次。",
"state": {
"routing": {
"active_workflow": "verification"
},
"workflows": {
"verification": {
"status": "waiting_input",
"resume_from": "verify_code",
"variables": {
"attempts_used": 2
}
}
}
}
}
attempts_used 采用验证服务返回的次数;用户追问“没收到验证码”等未进行有效校验的情况,次数保持。是否保存变量及保存哪些值,由各业务的跨轮处理需要决定。