工作区 LLM 会话对象与调用规则¶
这些接口维护独立的会话、消息记录及其标签。它们不提交模型推理,也不创建智能体任务。
调用前准备¶
使用目标环境的产品 API 身份凭据和有效工作区角色。
将
BASE_URL设为该环境的完整产品 API 前缀;工作区路径值与X-Workspace-ID一致。从同环境的会话列表取得正整数
SESSION_ID,再从消息列表取得MESSAGE_ID。这些数值 ID 与智能体会话字符串 ID、A2A 任务 ID 分开。标签由非空
source和name共同标识。将二者用于 URL 时分别编码,不能把含/、空格或?的原值直接拼接到路径。
示例中的 MOI_KEY 是当前环境的个人访问令牌,WORKSPACE_ID、SESSION_ID、MESSAGE_ID、TAG_SOURCE 和 TAG_NAME 均须使用该环境的实际值。新建对象后,使用响应的 ID 继续调用。
会话和消息正文操作按当前用户查询;读取详情和会话列表不是整个工作区全部成员的记录清单。标签定义是工作区级集合。标签关系读取、添加和移除是不同入口,不能从空列表或 HTTP 204 推断目标对象存在或属于当前用户。
会话记录¶
工作区会话响应的 data 或 data.sessions[] 使用以下对象。时间为 Unix 秒整数。
字段 |
类型 |
说明 |
|---|---|---|
|
integer |
服务端生成的正整数会话 ID。 |
|
string |
会话标题,可能为空。 |
|
string |
应用来源,开放字符串。 |
|
string |
会话所属的当前用户 ID。 |
|
string |
配置文本。JSON 配置仍作为字符串返回。 |
|
integer |
创建时间,Unix 秒;未记录时间时为 0。 |
|
integer |
更新时间,Unix 秒;未记录时间时为 0。 |
工作区会话对象没有内嵌 tags、page 或 page_size。标签通过独立关系接口读取。SDK 的共用对象可能具有这些属性,缺省属性不代表服务端返回了相应数据。
消息记录¶
消息详情的 data 和列表的 data.messages[] 使用以下对象。记录中的状态和模型名称属于存储数据,不表示一次模型调用实际发生。
字段 |
类型 |
说明 |
|---|---|---|
|
integer |
消息 ID。 |
|
string |
消息所属用户 ID。 |
|
integer |
消息关联会话 ID。 |
|
string |
消息的应用来源。 |
|
integer |
0=user、1=system、2=assistant、3=agent_tool。 |
|
string |
原始内容文本。 |
|
string |
保存的内容文本。 |
|
string |
保存的模型名称。 |
|
string |
保存的消息状态,默认 pending。 |
|
string |
保存的原响应文本。 |
|
string |
保存的修改后响应文本。 |
|
string |
配置文本。 |
|
integer |
创建时间,Unix 秒。 |
|
integer |
更新时间,Unix 秒。 |
消息对象没有内嵌标签;单独读取消息标签关系。创建时允许角色 3,当前列表服务对 role=3 会省略角色筛选;不能据此认为返回结果只含工具消息。
消息翻页使用 after,不是 offset。消息按 ID 升序,下一页取上页末条消息 ID。返回的 total 先按角色和状态统计,不按 after 减少;不能以该值作为剩余条数。会话列表和工作区标签列表则使用 page/page_size,两套分页方式分别处理。
LLM 标签定义¶
标签在 data 或 data.tags[] 中返回。
字段 |
类型 |
说明 |
|---|---|---|
|
string |
标签来源,与 name 共同标识定义。 |
|
string |
标签名称。 |
|
integer |
创建时间,Unix 秒。 |
|
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 去重,追加文本也不是幂等操作。超时后先回读并确认,避免重复创建或重复追加。
删除会话后的消息、标签、文件清理要分别确认;会话删除的空响应不能作为其他资源已清理的证据。验证时登记实际生成的会话、消息及标签,保留尚不能确认清理的对象。