ChatKitの会話履歴の構造

ChatKitでは，会話履歴をThreadという単位で管理しています。（ややこしいですが，以前のエントリで少し触れたAgents SDKのSessionとは別物です。）

ChatKitを使いこなすには，このThreadのデータ構造と，またThreadの管理を担うStoreを理解することが一番大事といってもよいと思います。

ドキュメントはこちら： Threads and items

主要なデータ構造

会話履歴に登場する主要なデータタイプは，ThreadMetadata, ThreadItem, Attachmentの３つだけです。

ThreadMetadataが一つの会話を表し，ThreadItemが会話の中の一つ一つの発話やアクションを表します。ThreadItemはユーザーの発話，アシスタントの応答の他，内部で行われるツール実行など，会話の中で発生するありとあらゆるアクションを表します（そのため実態はUnion typeになっている）。また，Attachmentが添付ファイルを表します。

ものすごく雑なクラス図を書くとこう。

また，これらを保存・管理するリポジトリに相当するクラスがStoreです。

Attachment が ThreadMetadata とが関連づけられていないように見えますが，実際直接は関連づけられていなくて，ThreadMetadataの中のひとつのThreadItemを介して関連づける形になっています。認識が間違っていなければ，昨日のエントリで触れたThreadItemConverterが，Attachmentから新しいThreadItemを作るという処理をしている，はず。

Threadの永続化について

RDBMSかドキュメントデータベースのいずれもストレージに使えそうです。

ChatKitのexampleリポジトリには，MemoryStore（インメモリストア）しか実装例がないのですが，Microsoft謹製のagent-frameworkというリポジトリに，SQLiteをバックエンドにした簡易なStoreの実装があります。RDBのテーブル設計はこちらを起点にすると良さそう。

python/samples/demos/chatkit-integration/store.py

これは Agents SDK+αのTipsを一人で書いていくアドカレ Advent Calendar 2025の8日目の記事です。