Compare UI and workspace LLM protocols

Both sets of entry points share the same persistence owner and numeric record ID types. They are not interchangeable HTTP aliases. Do not copy parameters, success statuses, or error formats between them.

Item

UI protocol

Workspace LLM protocol

Path

/sessions、/messages

/workspaces/{workspace_id}/llm/…

Workspace

Header still required

Path and header must match

Identity wrapper

Ordinary product identity; additional runtime authorization headers rejected

Product entry point supporting runtime identity, subject to the corresponding admission checks

Success code

String OK, msg=OK

Numeric 0

Creation status

200

201

Delete session

200,data.message=deleted

204, no response body

Empty source on creation

Defaults to moi

Saved as an empty string

Original-title condition on update

Does not read expected_title

Optional expected_title; a mismatch still returns the current session

Session object tags

Field exists; current storage reads return an empty array

Object does not contain this field

Session list

POST with body page/page_size/source/keyword/tags

GET with query page/page_size/source/keyword/tag

Returned page number

Ordinary/unpinned lists return the original requested value, not necessarily normalized

Does not return page number or page size

Pinned list

Pinned subset of the ordinary requested page

No dedicated workspace entry point with the same name

Message role filter

String user/system/assistant; other strings ignored

One integer 0–3; 3 is ignored after entering the owner

Message list data

data is directly an array, without total

data.messages array and data.total

Output message roles

user/system/assistant; agent_tool maps to user

Integer 0/1/2/3

session_id

May be null

Workspace DTO uses an integer

Latest message

Does not read completed_only; returns session_id/message_id

Supports completed_only; returns message_id

Rating actions

PUT like/dislike toggles the rating

Workspace message reads and text maintenance do not replace rating toggles

Errors

String code/msg/data:null; details have a separate 404

Business errors use numeric code/message; body decoding uses another shared format

The SDK exposes both sets through the same ConversationService. UI in method names and the request types matter: defaults, inputs, and responses for CreateUISession/ConversationUISessionRequest and CreateSession/ConversationWorkspaceSessionRequest follow their actual entry points.

Python restores UI message list session_id/after to JSON numbers. Go and CLI must also use numbers. UI message session_id=null may appear as unset in an SDK optional field; this does not mean the server returned 0. CLI protobuf JSON may omit default fields. Check raw HTTP fields separately from client output.

Writing session tags does not create tag relationships, and reading empty session tags does not establish pin status. LLM source/name tags, UI system/pinned relationships, and generic resource tag ID/value/resource relationships have different contracts.

Last updated on