> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bigmodel.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 管理会话

本页涵盖会话的日常运维操作：查看状态、更新配置、检索、列表、归档与删除。发送事件与流式接收见[事件与流式输出](/cn/managed-agents/events)。

## 会话状态

| 状态               | 含义                                            |
| ---------------- | --------------------------------------------- |
| **idle**         | 等待输入。刚创建、或 Agent 完成本轮工作后处于此状态；发送新事件即可继续。      |
| **running**      | Agent 正在执行。可以追加消息引导它，或发送 user.interrupt 打断。   |
| **rescheduling** | 平台正在重新调度会话的沙箱（恢复或迁移），随后自动回到执行。                |
| **terminated**   | 会话已终止，不再接受交互（例如所引用的 Environment 被归档后触发的准入终止）。 |

归档是独立于状态的生命周期标记（**archived\_at**），见下文。

## 更新会话

**POST /v1/sessions/:sessionId** 支持更新四类内容，规则不同：

| 字段                     | 规则                                                                    |
| ---------------------- | --------------------------------------------------------------------- |
| **title**              | 任意状态可更新；null 清空。                                                      |
| **metadata**           | 任意状态可更新；键级合并，限制与创建相同（16 键、key ≤64、value ≤512）。                        |
| **agent.tools**        | 仅 **idle** 状态可更新（否则 409 session\_not\_idle，需先发送 user.interrupt）；整体替换。 |
| **agent.mcp\_servers** | 仅 idle 状态可更新；整体替换，与 agent.tools 的 mcp\_toolset 引用保持一致。                |

**model**、**system**、**skills**、**vault\_ids** 不支持会话中更新——它们在创建时冻结。已归档会话的任何更新返回 409 session\_archived；空请求体返回 400。

```bash theme={null}
curl -sS "$BASE_URL/v1/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $ZHIPUAI_API_KEY" \
  -H "zai-version: 2026-05-26" \
  -H "zai-beta: managed-agents-2026-05-26" \
  -H "content-type: application/json" \
  -d '{
    "agent": {
      "tools": [
        {
          "type": "agent_toolset_20260601",
          "configs": [{"name": "bash", "permission_policy": {"type": "always_ask"}}]
        }
      ]
    }
  }'
```

## 获取会话

```bash theme={null}
curl -sS "$BASE_URL/v1/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $ZHIPUAI_API_KEY" \
  -H "zai-version: 2026-05-26" \
  -H "zai-beta: managed-agents-2026-05-26"
```

响应中值得关注的运行时字段：**status**（当前真实状态）、**usage**（累计 input / output / cache\_read token）、**resources**（挂载的 Memory Store 与 File，含实际 mount\_path）、**agent**（解析后的配置快照）。

## 列出会话

**GET /v1/sessions** 支持丰富的过滤条件：

```bash theme={null}
curl -sS "$BASE_URL/v1/sessions?agent_id=$AGENT_ID&statuses[]=running&limit=20" \
  -H "Authorization: Bearer $ZHIPUAI_API_KEY" \
  -H "zai-version: 2026-05-26" \
  -H "zai-beta: managed-agents-2026-05-26"
```

| 参数                                                         | 说明                                                                     |
| ---------------------------------------------------------- | ---------------------------------------------------------------------- |
| **agent\_id** / **agent\_version**                         | 按 Agent 过滤；agent\_version 必须与 agent\_id 同用。                            |
| **memory\_store\_id**                                      | 按挂载的 Memory Store 过滤。                                                  |
| **statuses\[]**                                            | 可重复传入的状态过滤，如 statuses\[]=idle\&statuses\[]=running。                    |
| **created\_at\[gt]** / **\[gte]** / **\[lt]** / **\[lte]** | 按创建时间过滤，值为 RFC 3339。例如 `created_at[gte]=2026-01-01T00:00:00Z`。四个参数可组合。 |
| **include\_archived**                                      | 默认 false；true 时包含已归档会话。                                                |
| **limit** / **order** / **page**                           | 分页：limit 默认 20，order 默认 desc；用响应中的 page 游标向后翻页、prev\_page 游标向前翻页。      |

## 归档会话

归档把会话标记为已完成并使其只读。会话必须处于非 running 状态（否则 409，需先发送 **user.interrupt**）：

```bash theme={null}
curl -sS -X POST "$BASE_URL/v1/sessions/$SESSION_ID/archive" \
  -H "Authorization: Bearer $ZHIPUAI_API_KEY" \
  -H "zai-version: 2026-05-26" \
  -H "zai-beta: managed-agents-2026-05-26"
```

注意与其他资源不同：**对已归档会话重复归档返回 409 session\_archived**（不是幂等成功）。另外，非 API 创建的会话（例如 IM 渠道会话，可能出现在列表中）不可归档，返回 409 operation\_not\_supported。

## 删除会话

删除会永久移除会话及其事件历史，不可恢复：

```bash theme={null}
curl -sS -X DELETE "$BASE_URL/v1/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $ZHIPUAI_API_KEY" \
  -H "zai-version: 2026-05-26" \
  -H "zai-beta: managed-agents-2026-05-26"
```

```json theme={null}
{ "id": "sess_xxxxxxxxxxxx", "type": "session_deleted" }
```

规则：running 状态不可删除（409，先 interrupt）；已归档会话允许删除；非 API 创建的会话不可删除。会话挂载的 File 与 Memory Store 是独立资源，不随会话删除。

## 下一步

<CardGroup cols={2}>
  <Card title="事件与流式输出" href="/cn/managed-agents/events">
    发送事件、打断、恢复空闲会话
  </Card>

  <Card title="文件" href="/cn/managed-agents/files">
    列出并下载会话产出文件
  </Card>

  <Card title="本页对应 OpenAPI" href="/cn/managed-agents/api-reference#sessions">
    Session：获取、更新、归档、删除
  </Card>
</CardGroup>