<a id="openai-agents-conversation-sessions"></a>

# OpenAI Agents の会話セッション

<!-- i18n: source=docs/architecture/openai-agents-sessions.md blob=d96f44f5824749f9ff8d8d20e70fb23370c26d8b model=claude-sonnet-5-5 -->
> このページは[英語の原文](https://github.com/ClickHouse/loom/blob/main/docs/architecture/openai-agents-sessions.md)の機械翻訳です。内容は英語の原文が優先されます。
> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/architecture/openai-agents-sessions.md), which is authoritative.


`LoomSession` は、Loom のエピソードメモリ上にネイティブの Python および TypeScript セッションインターフェースを実装します。既存のツールは、会話の範囲を超えて事実を別途保持できます。フレームワークのパッケージは任意の依存関係のままです。

各アイテムは 1 回の `memory.set` 呼び出しに対応し、ネイティブの JSON、タイムスタンプとランダム値からなるキー、エンドユーザー、ユーザーとネイティブセッション ID から導出したセッションを持ちます。ポイント書き込みは SDK のコアレスをバイパスするため、同時に発生した同一内容のアイテムも別々に保持されます。エピソード行は、セマンティック抽出や重複のマージを行わずに、繰り返されたアイテムを保持します。ネイティブのアイテム形式が異なるため、Python と TypeScript は別々の導出セッションプレフィックスを使用します。

読み取りは `memory.list` でページを辿り、重複するキーを除外し、欠落または切り詰められた値を `memory.get` で補完します。アイテムはキー順に返され、limit を指定した場合は最新のアイテムが保持されます。サーバーの到着時刻では書き込み側が生成したキーの範囲を限定できないため、正の limit を指定した読み取りでも履歴全体をスキャンします。TypeScript アダプターは、構築時に検証済みのユーザーをスナップショットします。ネイティブの画像およびファイルのバイトペイロードは、保存時には JSON 配列として扱われ、読み取り時には `Uint8Array` として返されます。通常の JSON とメディア情報は変わりません。削除はユーザーと導出セッションを伴います。`pop_item` は最新のアイテムを削除し、`clear_session` は一覧取得した履歴を削除します。同時に行われる追加やクリアは個別のサーバー操作であり、会話全体にわたるトランザクションではありません。
補完の前にアイテムが消えた場合、読み取りは不完全なネイティブアイテムを返さずに失敗します。キーは書き込み側のクロックを使用するため、同時に書き込む複数のライターはサーバー側のシーケンスを共有しません。

どちらの実装も、構築時と各コールバックの時点で、アプリケーションが既に持つバインド済みの保護ファミリーを保持します。Python はさらに、コールバックのコンテキストでアクティブなコントリビューターも保持します。クライアントを再バインドしても、以前のコントリビューターを取り除くことはできません。ネイティブのユーザー ID とセッション ID は保存される履歴を選択するだけで、保護ファミリーを確立するものではありません。論理的な会話ファミリーごとに 1 つのセッションインスタンスを使用し、その会話を復元するときは、アプリケーションが所有する同じ保護カプセルを再度開いてください。

ネイティブの履歴の読み取りと追加は、保持されているすべてのコントリビューターのもとで自動処理として実行されます。マーク付きの応答は、値が返される前にすべてのコントリビューターを保護します。最初のマーク付き履歴応答が完全であれば、そのアイテムは返されることがありますが、以降のページ取得、補完、アイテム書き込みは抑制されます。マーク付きのアイテム書き込みが発生すると、バッチは次のアイテムの前で停止します。明示的な pop と clear の操作は、保護後も使用でき、保持されているコントリビューターのもとで引き続き応答を監視します。モデルが選択するツールは、明示的な操作のセマンティクスを維持します。

<a id="source-entry-points"></a>

## ソースのエントリポイント

- `sdk/python/loom/integrations/openai_agents.py`: `LoomSession`。
- `sdk/typescript/src/integrations/openai-agents.ts`: `LoomSession`。

<a id="invariants"></a>

## 不変条件

エージェントの組織、名前空間、名前が各履歴のスコープを決めます。ユーザーを省略すると共有の名前空間の行に書き込まれ、ユーザーを明示するとそのユーザーの履歴が選択されます。アクターとソースの来歴はサーバーが付与します。通常のメモリ削除、消去、ローリングアップグレードのルールが適用されます。ローカルの履歴データベースやスキーマは追加されません。
