Create session¶

Creates a visible session for the specified active agent. This interface only creates sessions and displays information, does not send messages, and does not start agent tasks.

HTTP
POST $CLOUDSIGMA_API_BASE/workspaces/{workspace_id}/conversations

Before you call this API¶

Configure the regional API endpoint and authentication, and select the target workspace.

First confirm that the target agent is active.

Set the operation-specific values used in the request:

$WORKSPACE_ID: Target workspace ID, passed through the X-Workspace-ID header and as workspace_id in the path.
$AGENT_ID: target agent ID.

Request¶

Input examples

Shell
curl -X POST "$CLOUDSIGMA_API_BASE/workspaces/$WORKSPACE_ID/conversations" \
  -H "X-API-Key: $CLOUDSIGMA_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "agent_id": "'"$AGENT_ID"'",
    "title": "销售分析",
    "purpose": "chat",
    "pinned": false
  }'

Parameter reference

Path parameters

Parameters	Type	Is it required	Description
`workspace_id`	string	Yes	Current workspace ID, must be consistent with `X-Workspace-ID`.

Request body

Parameters	Type	Is it required	Description
`agent_id`	string	Yes	Target agent ID; target agent must be active.
`agent_workspace_id`	string	No	ID of the workspace to which the target agent belongs. If not provided, the current workspace is used; only the current workspace or the system workspace can be specified.
`id`	string	No	Session ID. Generated by the server if not provided.
`title`	string	No	Session title, length cannot exceed 256.
`status`	string	No	Session state, can be `active` or `archived`; if not provided, `active`.
`purpose`	string	No	Session usage, can be `chat` or `workflow`; if not provided, `chat`. `workflow` Applies only to system workflow agents.
`visibility`	string	No	Session visibility. This interface only accepts `visible`; when not provided, `visible`.
`pinned`	boolean	No	Whether to pin the conversation to the top.

The workspace_id, user_id, agent display name and avatar in the request are determined by the server based on the current identity, path and agent data, and do not need to be passed in. This interface does not accept hidden sessions, nor does it accept parent_conversation_id.

Successful response¶

Returns 201 on success. data is a newly created session; save data.id, which is used to read, update sessions and query saved messages.

Response example

JSON
{
  "code": 0,
  "data": {
    "id": "conv_01",
    "workspace_id": "ws_01",
    "agent_workspace_id": "ws_01",
    "agent_id": "agent_01",
    "agent_summary": {
      "id": "agent_01",
      "display_name": "销售分析助手",
      "available": true
    },
    "title": "销售分析",
    "status": "active",
    "purpose": "chat",
    "visibility": "visible",
    "pinned": false,
    "created_at": "2026-01-02T15:04:05Z",
    "updated_at": "2026-01-02T15:04:05Z"
  }
}

Field reference

The response fields are as follows.

Field	Type	Description
`code`	integer	`0` on success.
`data.id`	string	Session ID.
`data.workspace_id`	string	ID of the workspace to which the session belongs.
`data.agent_workspace_id`	string	ID of the workspace to which the target agent belongs.
`data.agent_id`	string	Target agent ID.
`data.agent_summary`	object	Agent display summary; can contain `id`, `display_name`, `avatar_ref`, `status`, `available`, and `unavailable_reason`.
`data.title`	string	Session title; not returned if not set.
`data.status`	string	Current session status.
`data.purpose`	string	Current session usage.
`data.visibility`	string	Session visibility.
`data.pinned`	boolean	Whether to pin it to the top.
`data.head_message_id`	string	Recent message ID; does not return if there is no message yet.
`data.active_task_id`	string	Active task ID; not returned if there is no active task.
`data.last_message_at`	string	Last message time; does not return if there is no message yet.
`data.created_at`	string	Creation and last update times, in RFC 3339 format.
`data.updated_at`	string	Creation and last update times, in RFC 3339 format.

Error response¶

Response example

JSON
{
  "code": 2,
  "message": "请求参数无效",
  "details": {
    "cause": "invalid runtime conversation"
  }
}

Field reference

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`400`	`2`（`INVALID_ARGUMENT`）	The request body cannot be parsed, the agent workspace is not within the allowed range, or the session title, status, purpose, and visibility do not meet the requirements.	Check the request fields; do not pass in a hidden session or parent session ID.
`404`	`3`（`NOT_FOUND`）	The specified agent does not exist.	Check `agent_id` and the workspace to which the agent belongs.
`500`	`1`（`INTERNAL`）	The server cannot create a session or generate session display information.	Record the request time and error message and try again.
`503`	`15`（`UNAVAILABLE`）	Session service is temporarily unavailable.	Try again later.

Follow-up operations¶

Use Query session messages to read messages that have been written during runtime. To send messages, use the agent call interface.

Last updated on Sep 15, 2026