从回答创建会话分支

从源会话中的一条已完成回答创建子会话。子会话保留通向该回答的对话内容,并使用独立的 Provider 会话继续对话。

POST https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/conversations/{conversation_id}/forks

调用前准备

BASE_URL 使用产品 API 前缀 https://api.moi.matrixorigin.cn/v5;专有部署填写对应的产品 API 地址。

  1. 使用目标环境的普通产品身份凭据和工作区。将 BASE_URL 设为该环境的完整产品 API 前缀。此入口会拒绝附加的任务运行期授权头。

  2. 读取当前用户创建的源会话及其消息。源会话须为 purpose=chat、status=active、visibility=visible。

  3. 从源会话选择一条原生的 assistant 或 agent 消息,填写它的 id。该消息须关联同一会话、同一智能体的已完成 Astra 任务,并具有当前用户和工作区匹配的 Provider 会话记录。

  4. 为这次分叉生成并保存 REQUEST_ID。请求结果未知时,保留原请求 ID、源会话、源消息、标题以及发起时的有效角色。

从已有分支继承的消息带有 source_message_id,不能直接作为新的分叉点;可选择该分支后来生成的原生回答。源会话中更晚的其他任务仍在运行,不代表选中的已完成回答不能分叉。

请求

准备 WORKSPACE_ID、CONVERSATION_ID、SOURCE_MESSAGE_ID 和已保存的 REQUEST_ID。此请求创建子会话,但不会提交新的对话任务。

jq -n \
  --arg request_id "$REQUEST_ID" \
  --arg source_message_id "$SOURCE_MESSAGE_ID" \
  '{request_id: $request_id, source_message_id: $source_message_id}' > fork-request.json

curl --request POST \
  "$BASE_URL/workspaces/$WORKSPACE_ID/conversations/$CONVERSATION_ID/forks" \
  --header "X-API-Key: $MOI_KEY" \
  --header "X-Workspace-ID: $WORKSPACE_ID" \
  --header "Content-Type: application/json" \
  --data-binary @fork-request.json

保存成功响应中的子会话 data.id。通过会话详情和消息列表核对父会话、源消息和继承内容,再使用子会话 ID 继续对话。

参数

位置

类型

必填

说明

workspace_id

路径

string

是

当前用户所属的工作区 ID。

conversation_id

路径

string

是

源会话 ID。

agent_id

查询

string

否

限定源会话所属的智能体。

agent_workspace_id

查询

string

否

限定智能体所属的工作区,只接受当前工作区或 system;只能出现一次,空值按当前工作区处理。

request_id

请求体

string

是

此次分叉的稳定请求 ID,最多 128 字节。

source_message_id

请求体

string

是

选中回答的消息 ID,最多 128 字节。

title

请求体

string

否

子会话标题;合法 UTF-8,最多 256 个 Unicode 码点。

request_id 和 source_message_id 不能是空字符串、. 或 ..,不能含 /、\ 或控制字符,前后不能有空白。

省略 agent_workspace_id 且指定 agent_id 时,智能体工作区默认为路径工作区。title 会去掉前后空白;省略、空字符串或全部为空白时,系统根据源会话标题生成带序号的标题。省略或传入 null 的 title 都由当前字符串绑定处理为空标题。

分叉复制所选回答的祖先分支,包含所选回答。重新生成的其他回答版本及其后续消息不会因时间较早就被一起复制。子会话消息使用新的 ID,通过 source_message_id 标识来源;继承消息没有源任务或执行清单身份。显示内容中的文件引用保留为引用,不表示复制全部物理文件或授予新的文件权限。

同一工作区和用户下,请求 ID 标识同一次分叉。确认结果时保持源会话、源消息、标题和原有效角色一致。同一请求 ID 改换内容会发生冲突;只改变有效角色时,返回角色变化错误。请求 ID 不是客户端指定的子会话 ID。

成功响应

{
  "code": 0,
  "data": {
    "id": "7d694ce0-e9e6-5e16-b7aa-ef0ecbe261d5",
    "workspace_id": "workspace-example",
    "agent_workspace_id": "workspace-example",
    "agent_id": "agent-example",
    "agent_summary": {
      "id": "agent-example",
      "workspace_id": "workspace-example",
      "display_name": "知识问答",
      "status": "active",
      "available": true
    },
    "title": "数据分析(2)",
    "title_user_edited": true,
    "status": "active",
    "purpose": "chat",
    "visibility": "visible",
    "parent_conversation_id": "conversation-example",
    "source_message_id": "assistant-example",
    "pinned": false,
    "head_message_id": "child-message-example",
    "last_message_at": "2026-11-12T01:00:00Z",
    "created_at": "2026-11-12T02:00:00Z",
    "updated_at": "2026-11-12T02:00:00Z"
  }
}

字段

类型

说明

code

integer

成功时为 0;HTTP 状态码为 201。

data.id

string

服务端生成的子会话 ID;成功表示分叉会话已发布。

data.workspace_id

string

会话所属工作区 ID。

data.agent_workspace_id

string

智能体所属工作区 ID。

data.agent_id

string

智能体 ID,与源会话相同。

data.agent_summary

object

智能体的当前展示信息和可用状态。

data.agent_summary.id

string

智能体 ID。

data.agent_summary.workspace_id

string

智能体工作区 ID;有值时返回。

data.agent_summary.display_name

string

智能体名称;有值时返回。

data.agent_summary.avatar_ref

string

头像引用;有值时返回。

data.agent_summary.status

string

智能体状态;有值时返回。

data.agent_summary.available

boolean

智能体当前是否可用。

data.agent_summary.unavailable_reason

string

不可用原因;有值时返回。

data.title

string

子会话标题;有值时返回。

data.title_user_edited

boolean

分叉标题标记为已编辑,异步标题生成不会覆盖它。

data.status

string

会话状态。新分支为 active。

data.purpose

string

会话用途。分叉为 chat。

data.visibility

string

会话可见性。成功发布后为 visible。

data.parent_conversation_id

string

源会话 ID。

data.source_message_id

string

选中的源回答消息 ID。

data.pinned

boolean

是否置顶。新分支为 false。

data.head_message_id

string

子会话中复制后的末条消息 ID。

data.active_task_id

string

当前任务 ID;有值时返回。分叉本身不创建任务。

data.latest_task_id

string

最近任务 ID;有值时返回。新分支未继承源任务 ID。

data.latest_task_state

string

最近任务状态;有值时返回。

data.last_message_at

string

末条继承消息的时间;有值时返回。

data.created_at

string

子会话创建时间,RFC 3339 格式。

data.updated_at

string

子会话更新时间,RFC 3339 格式。

错误响应

{"code":"conversation_fork_role_changed","msg":"此分支操作由另一个角色发起。请切回发起时使用的角色,再重试以确认结果。"}

HTTP 状态码

code

条件及处理

400

conversation_fork_invalid

分叉参数或分叉记录无效。检查请求字段。

403

conversation_fork_forbidden

当前主体或 Provider 会话身份不满足分叉条件。

404

conversation_fork_not_found

源会话、选中消息或相关 Provider 对象不存在或不符合读取范围。

409

conversation_fork_not_ready

选中任务尚未完成,或 Provider 的对应位置尚未就绪。保留原请求身份确认结果。

422

conversation_fork_unsupported

会话用途、消息类型、Provider 位置或历史文件引用不支持分叉。

409

conversation_fork_conflict

相同请求 ID 对应不同请求内容,或 Provider 返回分叉冲突。

409

conversation_fork_role_changed

重试使用了不同有效角色。切回原角色确认结果。

409

conversation_fork_pending

同一次操作仍在执行、竞争执行权或等待继续。保留原请求内容重试。

410

conversation_fork_aborted

Provider 已确认该分叉终止。需要重新创建时使用新的请求 ID。

429

conversation_fork_quota_exceeded

Provider 的用户会话数、并发会话数或每日 token 配额不足。处理配额后再发起新的操作。

503

conversation_fork_unavailable

依赖、存储或响应确认失败;操作可能已经产生效果。保留原请求内容确认结果。

身份认证、路径与查询参数校验、工作区准入可能先于分叉业务校验返回通用错误。错误 msg 会按请求语言本地化,程序应读取 code。

超时、断开连接或 503 都不能证明没有创建分支。系统会保留无法确认结果的操作并尝试恢复;恢复仍使用发起时的用户和有效角色重新校验准入。确认结果前,不要更换请求 ID 重复创建同一分支,也不要将关闭页面视为取消。

最后更新于