# 分页查询会话列表

`GET` `/api/session/list`

按当前用户维度分页查询会话列表，支持按智能体、会话状态和触发来源类型过滤。智能体过滤可使用agentIdList（多值，适用于跨智能体聚合列表）或agentId（单值），两者同时传入时以agentIdList为准。triggerSourceTypeList可按触发来源类型收窄范围（精确匹配，命中任一类型即返回），适用于区分用户对话与定时任务产生的会话；注意早期会话可能未记录触发来源，传入该过滤条件时这类会话不会返回。返回结果包含sessionStatus字段，可选值：IDLE(空闲就绪)、PROCESSING(执行中)、WAITING_PERMISSION(等待权限确认)、ERROR(执行出错)。默认（includeProjectSessions=false）仅返回未绑定项目的临时会话；传true时返回当前身份主体符合其余过滤条件的全部会话（含项目会话），可用于单列表同时展示临时会话与项目会话。身份说明：当您通过API访问本系统时，请求头中必须传递 X-Principal-Id 以标识操作主体；当您通过页面访问本系统时，无需传递。

## 请求参数

### 请求头参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| X-Principal-Id | integer | 否 | 身份主体ID（Long类型）。通过API访问时必须传递以标识操作主体；通过页面访问时无需传递。可通过「身份主体」模块的创建接口获取。 |

### Query 参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| agentId | integer | 否 | 智能体ID过滤条件 |
| agentIdList | array | 否 | 智能体ID列表过滤条件（重复query参或逗号分隔，如 123,456），最多50个；与 agentId 同时传入时以本参数为准 |
| sessionStatus | string | 否 | 会话状态过滤条件，可选值：IDLE、PROCESSING、WAITING_PERMISSION、ERROR |
| triggerSourceTypeList | array | 否 | 触发来源类型过滤条件（重复query参或逗号分隔，如 human_message,api_call），可传多个，命中列表中任一类型即返回。精确匹配，可选值：human_message(人类消息，用户通过通道发送的消息触发)、scheduled_task(定时任务，由定时调度系统触发)、api_call(API调用，通过API直接调用触发，如Web端调试)、internal(内部调用，系统内部触发)、imported(外部导入，历史轨迹迁入系统)；不传则不过滤 |
| includeProjectSessions | boolean | 否 | 是否包含项目会话，默认false仅返回未绑定项目的临时会话；true返回当前身份主体符合其余过滤条件的全部会话（含项目会话） |
| page | integer | 否 | 页码，从1开始 |
| pageSize | integer | 否 | 每页记录数 |

## 响应

### 200

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | PageResultSessionItemVO | 响应数据 |
|     items | array | 数据列表 |
|         sessionId | integer | 会话ID |
|         principalId | integer | 主体ID |
|         agentId | integer | 智能体ID |
|         projectId | integer | 项目会话归属的项目ID，临时会话为 null |
|         modelName | string | 使用的模型名称 |
|         title | string | 会话标题 |
|         gmtCreate | string | 创建时间 |
|         gmtModified | string | 最后修改时间 |
|         lastActiveTime | string | 最后活跃时间 |
|         sessionStatus | string | 会话当前状态，可选值：IDLE-空闲就绪可发送新消息、PROCESSING-智能体正在执行、WAITING_PERMISSION-等待用户权限确认、ERROR-上次执行出错（会话仍可继续使用） |
|         triggerSourceType | string | 触发来源类型（取自会话首次运行时的触发来源，早期会话可能为空），可选值：human_message-人类消息、scheduled_task-定时任务、api_call-API调用、internal-内部调用、imported-外部导入 |
|     total | integer | 总记录数 |
|     page | integer | 当前页码，从1开始 |
|     pageSize | integer | 每页大小 |
|     totalPages | integer | - |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |

### 400

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |

### 500

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |