工作区 LLM 会话对象与调用规则

这些接口维护独立的会话、消息记录及其标签。它们不提交模型推理,也不创建智能体任务。

调用前准备

  1. 使用目标环境的产品 API 身份凭据和有效工作区角色。

  2. 将 BASE_URL 设为该环境的完整产品 API 前缀;工作区路径值与 X-Workspace-ID 一致。

  3. 从同环境的会话列表取得正整数 SESSION_ID,再从消息列表取得 MESSAGE_ID。这些数值 ID 与智能体会话字符串 ID、A2A 任务 ID 分开。

  4. 标签由非空 source 和 name 共同标识。将二者用于 URL 时分别编码,不能把含 /、空格或 ? 的原值直接拼接到路径。

示例中的 MOI_KEY 是当前环境的个人访问令牌,WORKSPACE_ID、SESSION_ID、MESSAGE_ID、TAG_SOURCE 和 TAG_NAME 均须使用该环境的实际值。新建对象后,使用响应的 ID 继续调用。

会话和消息正文操作按当前用户查询;读取详情和会话列表不是整个工作区全部成员的记录清单。标签定义是工作区级集合。标签关系读取、添加和移除是不同入口,不能从空列表或 HTTP 204 推断目标对象存在或属于当前用户。

会话记录

工作区会话响应的 data 或 data.sessions[] 使用以下对象。时间为 Unix 秒整数。

字段

类型

说明

id

integer

服务端生成的正整数会话 ID。

title

string

会话标题,可能为空。

source

string

应用来源,开放字符串。

user_id

string

会话所属的当前用户 ID。

config

string

配置文本。JSON 配置仍作为字符串返回。

created_at

integer

创建时间,Unix 秒;未记录时间时为 0。

updated_at

integer

更新时间,Unix 秒;未记录时间时为 0。

工作区会话对象没有内嵌 tags、page 或 page_size。标签通过独立关系接口读取。SDK 的共用对象可能具有这些属性,缺省属性不代表服务端返回了相应数据。

消息记录

消息详情的 data 和列表的 data.messages[] 使用以下对象。记录中的状态和模型名称属于存储数据,不表示一次模型调用实际发生。

字段

类型

说明

id

integer

消息 ID。

user_id

string

消息所属用户 ID。

session_id

integer

消息关联会话 ID。

source

string

消息的应用来源。

role

integer

0=user、1=system、2=assistant、3=agent_tool。

original_content

string

原始内容文本。

content

string

保存的内容文本。

model

string

保存的模型名称。

status

string

保存的消息状态,默认 pending。

response

string

保存的原响应文本。

modified_response

string

保存的修改后响应文本。

config

string

配置文本。

created_at

integer

创建时间,Unix 秒。

updated_at

integer

更新时间,Unix 秒。

消息对象没有内嵌标签;单独读取消息标签关系。创建时允许角色 3,当前列表服务对 role=3 会省略角色筛选;不能据此认为返回结果只含工具消息。

消息翻页使用 after,不是 offset。消息按 ID 升序,下一页取上页末条消息 ID。返回的 total 先按角色和状态统计,不按 after 减少;不能以该值作为剩余条数。会话列表和工作区标签列表则使用 page/page_size,两套分页方式分别处理。

LLM 标签定义

标签在 data 或 data.tags[] 中返回。

字段

类型

说明

source

string

标签来源,与 name 共同标识定义。

name

string

标签名称。

created_at

integer

创建时间,Unix 秒。

updated_at

integer

更新时间,Unix 秒。

创建定义使用 source/name;添加关系使用 tag_source/tag_name。添加关系可同时创建缺失的标签定义。移除关系保留定义;删除定义则清除该 source/name 在工作区内的所有会话、消息关系。

system/pinned、system/liked 和 system/disliked 是产品使用的系统标签。一般业务标签使用自己的来源名称,避免混同产品置顶、点赞和点踩状态。

错误格式与结果确认

工作区动作的业务错误使用数值 code 和 message:

{"code":2,"message":"invalid request"}

HTTP 状态码

业务 code

条件

400

2

工作区不一致、非正整数 ID、非法角色、无效标签或业务参数。

404

3

会话或消息读取动作找不到当前用户范围内的记录。

500

1

存储、转换或其他服务错误。

正文 JSON 解码复用另一层错误格式,可能返回 HTTP 400、字符串 code=ErrParamInvalid 和 msg。认证和准入还会返回各自错误;程序不能将所有失败固定解码成同一数值 code 类型。

条件更新标题不匹配可以返回 HTTP 200 和原值;这不是 409 冲突。重复删除一个已经不存在的会话可能为 404,而删除不存在的标签定义或标签关系可以为 204。标签关系读取返回空集合,也不能代替会话或消息详情的存在性检查。

保存消息和修改响应文本不调用模型;成功返回只说明对应存储动作的结果。会话/消息创建没有业务请求 ID 去重,追加文本也不是幂等操作。超时后先回读并确认,避免重复创建或重复追加。

删除会话后的消息、标签、文件清理要分别确认;会话删除的空响应不能作为其他资源已清理的证据。验证时登记实际生成的会话、消息及标签,保留尚不能确认清理的对象。

最后更新于