マルチエージェントAgent SDK の会話を外に保存｜別の場所で再開
この記事の要点
- 既定では、会話の記録は動かしているパソコンの中のファイルに残る。SessionStore を使うと、自分のストレージやデータベースに写せる
- 必要な処理は「足す」と「読む」の2つだけ。一覧・削除・サブエージェントの記録などは、必要に応じて足す
- ストアは手元の記録の写し。ストアから再開した回だけは、手元の記録が消えてストアが唯一の記録になる
AI エージェントを会社の仕組みに組み込むと、「昨日の続きを別のサーバーで再開したい」「サーバーを入れ替えても会話の記録を失いたくない」 という要望が出てきます。サーバーレスや台数が自動で増減する環境では、パソコンの中のファイルが共有されないためです。
この記事では、公式ドキュメント「Persist sessions to external storage」（2026年11月11日確認）にもとづいて、Claude Agent SDK の会話の記録を外部に保存し、別の場所で再開する方法を整理します。同じ場所で会話を続ける・分ける基本は Agent SDK のセッション管理 で解説しています。
結論：SessionStore で、手元の記録を自分の保存先に写す
既定の SDK は、会話の記録を動かしているパソコンの中のファイルに書きます。 SessionStore という受け口を用意すると、その記録を 自分のストレージ（オブジェクトストレージ）・キーと値の保存先・データベース に写せます。別のサーバーでも、元と同じ作業フォルダから動かせば、写した記録から続きを再開できます。
公式ドキュメントで挙げられている使いどころは3つです。
| 使いどころ | 中身 |
|---|---|
| 複数のサーバー | サーバーレスや自動で増減する環境でも、互いの会話を引き継げる |
| 消えない | 使い捨ての環境を入れ替えても、記録が残る |
| 決まりに沿って保管 | 保管期間・暗号化・見られる人を、自社で管理している保存先で決められる |
必要な処理は「足す」と「読む」の2つ
SessionStore に 必ず用意する処理は2つだけ です。
| 処理 | 必須 | 呼ばれる時 |
|---|---|---|
| append（足す） | 必須 | 手元に記録が書かれるたびに、同じ内容が渡される |
| load（読む） | 必須 | 再開する時、作業を始める前に呼ばれる。無ければ「無い」と返す |
| listSessions | 任意 | 一番新しい会話から続ける時・会話の一覧を出す時 |
| listSessionSummaries | 任意 | 会話の一覧の情報を1回でまとめて読む時 |
| delete | 任意 | 会話を消す時。無ければ消す操作は何もしない |
| listSubkeys | 任意 | サブエージェントの記録も戻す時。無ければ本体の会話だけ戻る |
渡された記録は中身を解釈せず、順番どおりに保存して、同じ順番で返します。 返す内容は、渡されたものと中身が同じであれば、文字の並びまで同じである必要はありません。
まず試す時と、本番で作る時
- 試す：SDK に入っている InMemorySessionStore（メモリの中だけで持つもの）で、1回目の会話の番号を受け取り、2回目でその番号を指定して再開する
- 作る：公式の SDK の配布物に、オブジェクトストレージ・キーと値の保存先・データベース向けの作り例が入っている。保存先の接続は自分で用意したものを渡す形なので、認証や暗号化の設定は自社の決まりに合わせられる
- 確かめる：SDK には、作った受け口が決まりどおりに動くかを確かめるテスト一式が入っている。本番の前に通しておく
知っておきたい動き
ストアは「写し」。再開した回だけ逆になる
Claude Code は、まず手元のファイルに書き、同じ内容を SDK がストアに渡します。 ストアは手元の記録の写しで、置き換えではありません。どちらが残るかは、始め方で変わります。
| 始め方 | 残る記録 |
|---|---|
| 新しい会話（またはストアに記録が無い時） | 手元の記録が残り、ストアにも写しが入る |
| ストアから再開した会話 | 終わった時に手元の記録は消え、ストアが唯一の記録になる |
新しい会話でも手元に記録を残したくない時は、設定の置き場所（CLAUDE_CONFIG_DIR）を、その回だけの新しい一時フォルダにします。この時、ふだんのログインの情報が読めなくなる ため、長く使える認証の印かAPIキーを渡すなど、ログインの方法を別に用意します。
一緒に使えない設定が2つある
次の設定とストアを一緒に使うと、SDK は起動の時点で止まります。
- 手元に記録を書かない設定（TypeScript 版の persistSession を false にするもの）：写す元が無くなるため
- ファイルの巻き戻しの機能：ファイルの控えを手元に直接書き、ストアには写さないため
ファイルの巻き戻しは Agent SDK のファイルの巻き戻し で解説しています。
作業フォルダをそろえる
記録は、作業フォルダごとの区切りで管理されます。再開する時は、元と同じ作業フォルダから動かします。
よくある質問
Python 版と TypeScript 版で違いはありますか？
再開する時に手元から持ってくる設定の範囲が違います。 TypeScript 版はログインの情報と設定ファイルの一部を持ってきますが、Python 版はログインの情報と基本の設定だけです。そのため Python 版では、ユーザーの設定ファイルに書いた認証の方法（apiKeyHelper）に頼っていると、ストアからの再開でログインしていない扱いになります。
会話の記録には何が入りますか？取り扱いの注意は？
依頼の文や AI の返事、道具の結果などがそのまま入ります。 社内の情報が入る前提で、保存先の見られる人・保管期間・暗号化を決めておきます。AI エージェントを安全に動かす考え方は AI エージェントを安全に動かす で解説しています。
まとめ
- SessionStore で、会話の記録を自分の保存先に写し、別の場所で再開できる
- 必要な処理は 「足す」と「読む」の2つ。ほかは必要に応じて足す
- ストアは写し。ストアから再開した回だけ、ストアが唯一の記録になる
出典
この記事はAIを使って下書きし、著者が事実確認・加筆しています。ツールの機能や料金は変わることがあるため、最新の情報は各社の公式ページでご確認ください。
