# 按智能体汇总当前会话

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

读取当前账户在当前工作区中按智能体分组的普通聊天会话。分组只统计 active、chat、visible 且未置顶的持久化会话，不是全部智能体或全部会话清单。

```text
GET https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/conversations/agent-groups
```

## 调用前准备

`PRODUCT_API_BASE_URL` 使用产品 API 前缀 `https://api.moi.matrixorigin.cn/v5`；专有部署填写对应的产品 API 地址。

PRODUCT_API_BASE_URL 包含目标环境的产品前缀。准备本人的凭据与有权限的 WORKSPACE_ID，路径 ID 和 X-Workspace-ID 必须一致。示例 ID 需替换为该环境的实际返回值。

## 请求

:::::::{div} mo-api-tabs mo-api-request-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

```bash
curl --get "$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/conversations/agent-groups" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

:::::
:::::{tab-item} 参数说明

无业务查询参数或请求体；当前动作不解析 limit、offset、keyword、surface 等筛选。不要复制会话列表参数并据此认为分组范围已改变。

按 agent_workspace_id 与 agent_id 共同分组。当前动作没有分页字段，total 表示分组数量，不是各组 conversation_count 的和。

:::::
::::::
:::::::

## 成功响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{"code":0,"data":{"items":[{"agent_workspace_id":"workspace-example","agent_id":"agent-example","agent_summary":{"id":"agent-example","workspace_id":"workspace-example","display_name":"示例智能体","available":true},"conversation_count":3,"last_activity_at":"2026-11-12T01:02:03Z"}],"total":1}}
```

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| data.items | array | 本次全部分组；无结果为空数组。 |
| data.items[].agent_workspace_id | string | 智能体来源工作区。 |
| data.items[].agent_id | string | 智能体 ID。 |
| data.items[].agent_summary | object | 智能体展示摘要；优先当前定义，找不到时保留历史展示信息。 |
| data.items[].agent_summary.available | boolean | 当前摘要是否标记可用；不代替真实调用成功。 |
| data.items[].agent_summary.unavailable_reason | string | 可选的不可用原因。 |
| data.items[].conversation_count | integer | 满足本动作固定范围的会话数量。 |
| data.items[].last_activity_at | string | 组内最近消息时间，无消息时使用会话创建时间。 |
| data.total | integer | 分组数。 |

按 last_activity_at 降序；同时间按智能体来源工作区、智能体 ID 排序。智能体被归档或删除后，历史分组仍可能存在；不能据此认定还可调用。

:::::
::::::
:::::::

## 继续读取

选定一组后，调用智能体会话列表，并保持同一 agent_workspace_id、agent_id，明确传 status=active、purpose=chat、visibility=visible、pinned=false，以匹配本分组统计范围。置顶、归档和其他用途需单独查询，不能从当前分组不存在推定没有相关会话。

## 错误

工作区不匹配可返回 400，身份或权限失败可返回 401/403；读取或展示依赖失败可返回 500/503。分组读取失败不改变已有会话；恢复条件后重新读取。
