# Agent SDKのセッションをマルチホストで共有する設計

> Claude Agent SDKはセッション履歴をローカルのJSONLファイルに保存するため、サーバーレスや複数インスタンス構成ではSessionStoreアダプタでS3やRedis等の外部ストレージにミラーする必要があります。

- Canonical: https://kuucorp.com/blog/agent-sdk-session-store-multi-host-persistence/
- Date: 2026-09-25
- Last modified: 2026-09-25
- Publisher: Kuu株式会社 (https://kuucorp.com)

---
> 本記事はClaude Agent SDKの公式ドキュメント（sessions / session-storage）を根拠に、SessionStoreアダプタによるマルチホスト永続化の設計を解説します。

[Claude Agent SDK](/glossary/agent-harness/)は会話履歴を「セッション」としてローカルディスクに自動保存し、`resume`で続きから復帰できます。ただし保存先は既定で単一ホストに閉じており、サーバーレス関数やオートスケールワーカーのようにリクエストごとにホストが変わる構成では前提が崩れます。

## Agent SDKのセッションはなぜ複数ホスト間で共有できないのか

> Agent SDKはセッション履歴を`~/.claude/projects/`配下のJSONLファイルにホスト単位で保存するため、別ホストからは直接resumeできません。

セッションは作業ディレクトリ名を変換したパスの下、`<session-id>.jsonl`に1行1エントリで追記されます。`continue`（最新セッションへの継続）や`resume`（指定IDへの復帰）はこのローカルファイルが前提のため、ホストAで作成したセッションをホストBから`resume`しても復帰できません。オートスケールやLambda・Cloud RunのようなFaaS環境では、この制約がそのまま可用性の問題になります。

## SessionStoreアダプタとは何か

> SessionStoreはセッション転記をS3・Redis・Postgres等の外部ストレージへミラーし、他ホストからのresumeを可能にするアダプタ抽象です。

Agent SDKは`SessionStore`という抽象インターフェースを公開しています。必須メソッドは`append`（書き込み）と`load`（読み出し）の2つで、`listSessions`等は任意です。公式リポジトリにはS3・Redis・Postgresの3種類の参照実装が提供され、コピーして自社バックエンドに合わせる使い方が想定されています。

要点は「ミラーであってローカル保存の代替ではない」ことです。サブプロセスは常にローカルディスクへ先に書き込み、同じバッチをストアの`append()`へ転送します。ストアから復元実行したセッションのみ終了時にローカルコピーが削除され、ストアが唯一の永続コピーになります。

## SessionStoreの実装で注意すべき設計ポイント

> append()の再送によるエントリ重複はentry.uuidで排除し、フォークはID書き換えを伴うためストレージ層の単純コピーでは代替できません。

デフォルト挙動を把握せずに実装すると事故につながる点が3つあります。

- **ベストエフォート**: `append()`が失敗すると最大3回再試行され、それでも失敗すれば`mirror_error`を発行してクエリは継続します。再送で既着バッチが重複しうるため`entry.uuid`による排除が必須です。
- **フォークはバイトコピーではない**: `forkSession`は元セッションのエントリを読み出し、`sessionId`とメッセージUUIDを書き換えて新キーに追記します。ストレージ層の単純コピーで代替すると壊れた転記になります。
- **保持期間はアダプタの責務**: SDK側は自発的にストアからデータを削除しません。TTLは自社で設計します。

## 規模別の留意点（SMB / エンタープライズ）

> SMBはRedis等の軽量ストアで冗長化不要な範囲に留め、エンタープライズは保持ポリシーとアダプタの適合性検証まで含めて設計します。

SMBでサーバーレスの多重実行を採用する場合、公式のRedisまたはPostgres参照実装をそのまま流用し、`InMemorySessionStore`で開発時の挙動を確認してから本番用に切り替える順序が着手しやすいでしょう。単一インスタンスで十分な規模なら導入せずローカルファイルのままにする選択も合理的です。

エンタープライズでは複数チームが異なるバックエンド（監査ログ用のオブジェクトストアと高速応答用のRedisなど）を使い分けるケースが増えます。SDKが提供する適合性検証スイート（`run_session_store_conformance`等）を自社アダプタに必ず実行し、契約を満たすことを確認してください。マルチチームでのAI基盤統制を横断的に設計する場合は、[エージェントガバナンス](/services/rde/)の観点からアダプタ選定基準の標準化も検討に値します。

## 参考

- [Work with sessions - Claude Code Docs](https://code.claude.com/docs/en/agent-sdk/sessions)
- [Persist sessions to external storage - Claude Code Docs](https://code.claude.com/docs/en/agent-sdk/session-storage)
- [Agent SDK overview - Claude Code Docs](https://code.claude.com/docs/en/agent-sdk/overview)

## まとめ

Agent SDKのセッションは既定でホスト単位のローカルファイルに閉じているため、複数ホストをまたいで会話を継続するにはSessionStoreアダプタの実装が前提になります。`append`/`load`の契約、ベストエフォートなミラー書き込み、フォーク時のID書き換えといった挙動を踏まえずに設計すると、復元漏れやデータ不整合につながります。KuuのAIエージェントガバナンスサービス（[/services/ai-ops/](https://kuucorp.com/services/ai-ops/)）では、エージェント基盤のアーキテクチャ設計から運用体制の構築までを支援しています。導入を検討中の方はお気軽にお問い合わせください。