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

# 会话控制

`QoderSDKClient` 默认每次连接启动一个全新的会话。通过 `QoderAgentOptions` 里几个字段可以指定会话 ID、恢复历史会话或从已有会话分叉。

<div id="概念" />

## 概念

一个 session 对应 CLI 端持久化的一条对话历史（含上下文、工具调用记录、压缩边界等），由 UUID 标识。系统消息 `init` 里包含本次的 `session_id`，也是后续 `resume` / `fork_session` 的锚点。

<div id="新建会话" />

## 新建会话

<div id="默认" />

### 默认

不传任何会话相关字段，每次新建：

```python theme={null}
from qoder_agent_sdk import QoderAgentOptions, QoderSDKClient, qodercli_auth

options = QoderAgentOptions(auth=qodercli_auth())

async with QoderSDKClient(options=options) as client:
    await client.query("Hello")
    async for msg in client.receive_response():
        ...
```

<div id="指定-session-id" />

<div id="指定sessionid" />

### 指定 session ID

让调用方决定 session 的 UUID（适合宿主自己管理 session 索引）：

```python theme={null}
import uuid

session_id = str(uuid.uuid4())

options = QoderAgentOptions(
    auth=qodercli_auth(),
    session_id=session_id,
)

async with QoderSDKClient(options=options) as client:
    await client.query("Hello")
    async for msg in client.receive_response():
        ...
```

<div id="恢复会话" />

## 恢复会话

<div id="按-id-恢复" />

<div id="按id恢复" />

### 按 ID 恢复

```python theme={null}
options = QoderAgentOptions(
    auth=qodercli_auth(),
    resume="previous-session-id",
)

async with QoderSDKClient(options=options) as client:
    await client.query("Continue the previous conversation")
    async for msg in client.receive_response():
        ...
```

<div id="恢复最近一次" />

### 恢复最近一次

不知道 session ID 时，用 `continue_conversation=True` 接上最近修改过的会话：

```python theme={null}
options = QoderAgentOptions(
    auth=qodercli_auth(),
    continue_conversation=True,
)

async with QoderSDKClient(options=options) as client:
    await client.query("Continue")
    async for msg in client.receive_response():
        ...
```

`resume` 和 `continue_conversation` 不要同时传。

<div id="分叉会话" />

## 分叉会话

从已有会话派生一条新会话，保留原上下文但获得新的 session ID。原会话不受影响：

```python theme={null}
options = QoderAgentOptions(
    auth=qodercli_auth(),
    resume="source-session-id",
    fork_session=True,
)

async with QoderSDKClient(options=options) as client:
    await client.query("Based on the prior context, explore a different direction")
    async for msg in client.receive_response():
        ...
```

要给分叉后的新会话指定 ID：

```python theme={null}
options = QoderAgentOptions(
    auth=qodercli_auth(),
    resume="source-session-id",
    fork_session=True,
    session_id="my-new-session-id",
)
```

<div id="字段速查" />

## 字段速查

| 字段                      | 类型     | 行为                                           |
| ----------------------- | ------ | -------------------------------------------- |
| `session_id`            | `str`  | 单独使用：用此 ID 新建；与 `fork_session` 同用：分叉后新会话的 ID |
| `resume`                | `str`  | 要恢复的 session ID                              |
| `continue_conversation` | `bool` | `True` 表示恢复最近一次会话                            |
| `fork_session`          | `bool` | 配合 `resume` 使用，分叉而非接续                        |

<div id="拿到当前-session-id" />

<div id="拿到当前sessionid" />

## 拿到当前 session ID

`init` 系统消息的 `data` 字典里带 `session_id`；`ResultMessage` 也带。两者都可以用来记账：

```python theme={null}
from qoder_agent_sdk import ResultMessage, SystemMessage

current_session_id = None

async with QoderSDKClient(options=options) as client:
    await client.query("Hello")
    async for msg in client.receive_response():
        if isinstance(msg, SystemMessage) and msg.subtype == "init":
            current_session_id = msg.data["session_id"]
            print(f"session: {current_session_id}")
        elif isinstance(msg, ResultMessage):
            current_session_id = msg.session_id
```