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.