> ## 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="コンセプト" />

## コンセプト

1 つのセッションは CLI 側で永続化された 1 つの対話履歴（コンテキスト、ツール呼び出し記録、圧縮境界などを含む）に対応し、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="セッション-id-の指定" />

<div id="セッションidの指定" />

### セッション ID の指定

呼び出し側がセッションの UUID を決定します（ホストが独自にセッションインデックスを管理する場合に適します）：

```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="最後のセッションの復元" />

### 最後のセッションの復元

セッション 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="セッションのフォーク" />

## セッションのフォーク

既存のセッションから新しいセッションを派生させ、元のコンテキストを保持しつつ新しいセッション 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`  | 復元するセッション ID                                         |
| `continue_conversation` | `bool` | `True` で最後のセッションを復元                                  |
| `fork_session`          | `bool` | `resume` と併用し、接続ではなくフォーク                             |

<div id="現在のセッション-id-の取得" />

<div id="現在のセッションidの取得" />

## 現在のセッション 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
```