diff --git a/docs/ja/sessions/index.md b/docs/ja/sessions/index.md index 36b9960a7c..e5313b934c 100644 --- a/docs/ja/sessions/index.md +++ b/docs/ja/sessions/index.md @@ -4,11 +4,11 @@ search: --- # セッション -Agents SDK は、複数のエージェント実行にまたがって会話履歴を自動的に維持する組み込みのセッションメモリを提供しており、ターン間で `.to_input_list()` を手動で扱う必要をなくします。 +Agents SDK は、複数のエージェント実行にまたがって会話履歴を自動的に維持する組み込みのセッションメモリを提供し、ターン間で `.to_input_list()` を手動で扱う必要をなくします。 -Sessions は特定のセッションの会話履歴を保存し、明示的な手動メモリ管理を必要とせずにエージェントがコンテキストを維持できるようにします。これは、エージェントに過去のやり取りを記憶させたいチャットアプリケーションや複数ターンの会話を構築する際に特に有用です。 +セッションは特定のセッションの会話履歴を保存し、明示的な手動メモリ管理を必要とせずにエージェントがコンテキストを維持できるようにします。これは、チャットアプリケーションや、エージェントに以前のやり取りを記憶させたいマルチターン会話を構築する場合に特に有用です。 -SDK にクライアント側メモリ管理を任せたい場合は sessions を使用してください。Sessions は同一実行内で `conversation_id`、`previous_response_id`、`auto_previous_response_id` と組み合わせることはできません。代わりに OpenAI のサーバー管理による継続を使いたい場合は、session を重ねるのではなくそれらの仕組みのいずれかを選択してください。 +SDK にクライアント側メモリを管理させたい場合は、セッションを使用します。セッションは同じ実行内で `conversation_id`、`previous_response_id`、または `auto_previous_response_id` と組み合わせることはできません。代わりに OpenAI サーバー管理の継続を使いたい場合は、セッションを重ねるのではなく、それらの仕組みのいずれかを選択してください。 ## クイックスタート @@ -49,9 +49,9 @@ result = Runner.run_sync( print(result.final_output) # "Approximately 39 million" ``` -## 同一セッションで中断実行を再開 +## 同じセッションでの中断された実行の再開 -実行が承認待ちで一時停止した場合は、同じ session インスタンス(または同じバックエンドストアを指す別の session インスタンス)で再開してください。そうすることで、再開したターンは同じ保存済み会話履歴を継続します。 +実行が承認待ちで一時停止した場合は、再開後のターンが同じ保存済み会話履歴を引き継ぐように、同じセッションインスタンス(または同じバッキングストアを指す別のセッションインスタンス)で再開してください。 ```python result = await Runner.run(agent, "Delete temporary files that are no longer needed.", session=session) @@ -63,31 +63,31 @@ if result.interruptions: result = await Runner.run(agent, state, session=session) ``` -## セッションのコア動作 +## コアセッション動作 セッションメモリが有効な場合: -1. **各実行前**: runner はセッションの会話履歴を自動取得し、入力アイテムの先頭に追加します。 -2. **各実行後**: 実行中に生成されたすべての新規アイテム(ユーザー入力、assistant 応答、ツール呼び出しなど)が自動的にセッションへ保存されます。 -3. **コンテキスト保持**: 同じ session を使う後続の各実行には完全な会話履歴が含まれ、エージェントがコンテキストを維持できます。 +1. **各実行前**: runner はセッションの会話履歴を自動的に取得し、それを入力アイテムの先頭に追加します。 +2. **各実行後**: 実行中に生成されたすべての新しいアイテム(ユーザー入力、assistant 応答、ツール呼び出しなど)がセッションに自動的に保存されます。 +3. **コンテキスト保持**: 同じセッションでの後続の各実行には完全な会話履歴が含まれるため、エージェントはコンテキストを維持できます。 -これにより、`.to_input_list()` を手動で呼び出して実行間の会話状態を管理する必要がなくなります。 +これにより、`.to_input_list()` を手動で呼び出し、実行間の会話状態を管理する必要がなくなります。 -## 履歴と新規入力のマージ方法の制御 +## 履歴と新しい入力のマージ制御 -session を渡すと、runner は通常次のようにモデル入力を準備します: +セッションを渡すと、runner は通常、モデル入力を次のように準備します。 1. セッション履歴(`session.get_items(...)` から取得) 2. 新しいターンの入力 -モデル呼び出し前のこのマージ処理をカスタマイズするには [`RunConfig.session_input_callback`][agents.run.RunConfig.session_input_callback] を使用します。コールバックは 2 つのリストを受け取ります: +モデル呼び出しの前にそのマージ手順をカスタマイズするには、[`RunConfig.session_input_callback`][agents.run.RunConfig.session_input_callback] を使用します。コールバックは 2 つのリストを受け取ります。 - `history`: 取得されたセッション履歴(すでに入力アイテム形式に正規化済み) -- `new_input`: 現在ターンの新しい入力アイテム +- `new_input`: 現在のターンの新しい入力アイテム -モデルに送信する最終的な入力アイテムのリストを返してください。 +モデルに送信する最終的な入力アイテムのリストを返します。 -コールバックは両方のリストのコピーを受け取るため、安全に変更できます。返されたリストはそのターンのモデル入力を制御しますが、SDK が永続化するのは引き続き新しいターンに属するアイテムのみです。したがって、古い履歴を並べ替えたりフィルタしたりしても、古いセッションアイテムが新しい入力として再保存されることはありません。 +コールバックは両方のリストのコピーを受け取るため、安全に変更できます。返されたリストはそのターンのモデル入力を制御しますが、SDK が永続化するのは新しいターンに属するアイテムのみです。そのため、古い履歴を並べ替えたりフィルターしたりしても、古いセッションアイテムが新しい入力として再度保存されることはありません。 ```python from agents import Agent, RunConfig, Runner, SQLiteSession @@ -109,16 +109,16 @@ result = await Runner.run( ) ``` -これは、セッションの保存方法を変更せずに、履歴のカスタムな間引き、並べ替え、または選択的な取り込みが必要な場合に使用します。モデル呼び出し直前にさらに後段の最終処理が必要な場合は、[running agents guide](../running_agents.md) の [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter] を使用してください。 +セッションがアイテムを保存する方法を変えずに、カスタムの刈り込み、並べ替え、または履歴の選択的な取り込みが必要な場合に使用します。モデル呼び出しの直前にさらに最終パスが必要な場合は、[エージェント実行ガイド](../running_agents.md)の [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter] を使用してください。 ## 取得履歴の制限 -各実行前にどの程度の履歴を取得するかを制御するには [`SessionSettings`][agents.memory.SessionSettings] を使用します。 +各実行前に取得する履歴量を制御するには、[`SessionSettings`][agents.memory.SessionSettings] を使用します。 -- `SessionSettings(limit=None)`(デフォルト): 利用可能なセッションアイテムをすべて取得 -- `SessionSettings(limit=N)`: 直近 `N` 件のアイテムのみ取得 +- `SessionSettings(limit=None)`(デフォルト): 利用可能なすべてのセッションアイテムを取得します +- `SessionSettings(limit=N)`: 直近の `N` 個のアイテムのみを取得します -これは [`RunConfig.session_settings`][agents.run.RunConfig.session_settings] で実行ごとに適用できます: +これは [`RunConfig.session_settings`][agents.run.RunConfig.session_settings] を通じて実行ごとに適用できます。 ```python from agents import Agent, RunConfig, Runner, SessionSettings, SQLiteSession @@ -134,13 +134,13 @@ result = await Runner.run( ) ``` -セッション実装がデフォルトの session settings を公開している場合、`RunConfig.session_settings` はその実行において `None` 以外の値を上書きします。これは、セッションのデフォルト動作を変更せずに取得サイズの上限を設けたい長い会話で有用です。 +セッション実装がデフォルトのセッション設定を公開している場合、`RunConfig.session_settings` はその実行に対して `None` ではない値を上書きします。これは、セッションのデフォルト動作を変更せずに取得サイズに上限を設けたい長い会話で有用です。 ## メモリ操作 ### 基本操作 -Sessions は会話履歴を管理するための複数の操作をサポートしています: +セッションは会話履歴を管理するためのいくつかの操作をサポートしています。 ```python from agents import SQLiteSession @@ -165,9 +165,9 @@ print(last_item) # {"role": "assistant", "content": "Hi there!"} await session.clear_session() ``` -### 修正のための pop_item の使用 +### 修正での pop_item の使用 -`pop_item` メソッドは、会話の最後のアイテムを取り消したり変更したりしたい場合に特に有用です: +`pop_item` メソッドは、会話内の最後のアイテムを取り消したり変更したりしたい場合に特に有用です。 ```python from agents import Agent, Runner, SQLiteSession @@ -202,27 +202,28 @@ SDK は、さまざまなユースケース向けに複数のセッション実 ### 組み込みセッション実装の選択 -以下の詳細な例を読む前に、この表を使って開始点を選んでください。 +以下の詳細な例を読む前に、開始点を選ぶためにこの表を使用してください。 -| Session type | Best for | Notes | +| セッションタイプ | 最適な用途 | 備考 | | --- | --- | --- | -| `SQLiteSession` | ローカル開発とシンプルなアプリ | 組み込み、軽量、ファイル永続化またはインメモリ | -| `AsyncSQLiteSession` | `aiosqlite` を使った非同期 SQLite | 非同期ドライバー対応の拡張バックエンド | -| `RedisSession` | ワーカー / サービス間での共有メモリ | 低レイテンシな分散デプロイに適しています | -| `SQLAlchemySession` | 既存データベースを持つ本番アプリ | SQLAlchemy 対応データベースで動作 | -| `DaprSession` | Dapr sidecar を使うクラウドネイティブデプロイ | 複数の state store に加え TTL と整合性制御をサポート | -| `OpenAIConversationsSession` | OpenAI でのサーバー管理ストレージ | OpenAI Conversations API ベースの履歴 | -| `OpenAIResponsesCompactionSession` | 自動圧縮付きの長い会話 | 別のセッションバックエンドをラップ | -| `AdvancedSQLiteSession` | 分岐 / 分析機能付き SQLite | 機能セットが大きめ。専用ページを参照 | -| `EncryptedSession` | 別セッションの上に暗号化 + TTL | ラッパー。先に基盤バックエンドを選択 | +| `SQLiteSession` | ローカル開発とシンプルなアプリ | 組み込み、軽量、ファイルバックまたはインメモリ | +| `AsyncSQLiteSession` | `aiosqlite` を使う非同期 SQLite | 非同期ドライバーサポートを備えた拡張バックエンド | +| `RedisSession` | ワーカー/サービス間で共有されるメモリ | 低レイテンシの分散デプロイに適しています | +| `SQLAlchemySession` | 既存データベースを持つ本番アプリ | SQLAlchemy がサポートするデータベースで動作します | +| `MongoDBSession` | すでに MongoDB を使用している、またはマルチプロセスストレージが必要なアプリ | 非同期 pymongo。順序付け用のアトミックシーケンスカウンター | +| `DaprSession` | Dapr サイドカーを使用するクラウドネイティブデプロイ | 複数の状態ストアに加えて TTL と整合性制御をサポート | +| `OpenAIConversationsSession` | OpenAI 内のサーバー管理ストレージ | OpenAI Conversations API ベースの履歴 | +| `OpenAIResponsesCompactionSession` | 自動コンパクションを伴う長い会話 | 別のセッションバックエンドのラッパー | +| `AdvancedSQLiteSession` | SQLite と分岐/分析 | 機能セットはより重めです。専用ページを参照してください | +| `EncryptedSession` | 別のセッション上の暗号化 + TTL | ラッパーです。まず基盤となるバックエンドを選択してください | -一部の実装には追加の詳細を説明した専用ページがあり、それらは各サブセクション内でリンクされています。 +一部の実装には追加の詳細を含む専用ページがあり、それぞれの小節内でインラインにリンクされています。 -ChatKit 用の Python サーバーを実装する場合は、ChatKit のスレッドとアイテム永続化に `chatkit.store.Store` 実装を使用してください。`SQLAlchemySession` などの Agents SDK セッションは SDK 側の会話履歴を管理しますが、ChatKit の store のそのままの置き換えにはなりません。[ChatKit データストアの実装に関する `chatkit-python` ガイド](https://github.com/openai/chatkit-python/blob/main/docs/guides/respond-to-user-message.md#implement-your-chatkit-data-store) を参照してください。 +ChatKit 用の Python サーバーを実装している場合は、ChatKit のスレッドおよびアイテム永続化に `chatkit.store.Store` 実装を使用してください。`SQLAlchemySession` などの Agents SDK セッションは SDK 側の会話履歴を管理しますが、ChatKit のストアのドロップイン置換ではありません。[ChatKit データストアの実装に関する `chatkit-python` ガイド](https://github.com/openai/chatkit-python/blob/main/docs/guides/respond-to-user-message.md#implement-your-chatkit-data-store)を参照してください。 ### OpenAI Conversations API セッション -`OpenAIConversationsSession` を通じて [OpenAI's Conversations API](https://platform.openai.com/docs/api-reference/conversations) を使用します。 +`OpenAIConversationsSession` を通じて [OpenAI の Conversations API](https://platform.openai.com/docs/api-reference/conversations) を使用します。 ```python from agents import Agent, Runner, OpenAIConversationsSession @@ -256,11 +257,11 @@ result = await Runner.run( print(result.final_output) # "California" ``` -### OpenAI Responses 圧縮セッション +### OpenAI Responses コンパクションセッション -Responses API(`responses.compact`)で保存済み会話履歴を圧縮するには `OpenAIResponsesCompactionSession` を使用します。これは基盤となる session をラップし、`should_trigger_compaction` に基づいて各ターン後に自動圧縮できます。`OpenAIConversationsSession` をこれでラップしないでください。これら 2 つの機能は履歴を異なる方法で管理します。 +Responses API(`responses.compact`)で保存済み会話履歴をコンパクト化するには、`OpenAIResponsesCompactionSession` を使用します。これは基盤となるセッションをラップし、`should_trigger_compaction` に基づいて各ターン後に自動的にコンパクションできます。`OpenAIConversationsSession` をこれでラップしないでください。この 2 つの機能は異なる方法で履歴を管理します。 -#### 一般的な使用方法(自動圧縮) +#### 典型的な使用法(自動コンパクション) ```python from agents import Agent, Runner, SQLiteSession @@ -277,17 +278,17 @@ result = await Runner.run(agent, "Hello", session=session) print(result.final_output) ``` -デフォルトでは、候補しきい値に達すると各ターン後に圧縮が実行されます。 +デフォルトでは、候補しきい値に達すると、各ターン後にコンパクションが実行されます。 -`compaction_mode="previous_response_id"` は、すでに Responses API の response ID でターンを連結している場合に最適です。`compaction_mode="input"` は代わりに現在のセッションアイテムから圧縮リクエストを再構築します。これは response chain が利用できない場合や、セッション内容を信頼できる唯一の情報源にしたい場合に有用です。デフォルトの `"auto"` は、利用可能な中で最も安全な選択肢を選びます。 +`compaction_mode="previous_response_id"` は、Responses API の応答 ID を使ってすでにターンをチェーンしている場合に最適です。`compaction_mode="input"` は代わりに現在のセッションアイテムからコンパクションリクエストを再構築します。これは応答チェーンが利用できない場合や、セッション内容を信頼できる情報源にしたい場合に有用です。デフォルトの `"auto"` は、利用可能な中で最も安全なオプションを選択します。 -エージェント実行で `ModelSettings(store=False)` を使うと、Responses API は後で参照するための最新 response を保持しません。このステートレス構成では、デフォルトの `"auto"` モードは `previous_response_id` に依存せず、入力ベース圧縮にフォールバックします。完全な例は [`examples/memory/compaction_session_stateless_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/compaction_session_stateless_example.py) を参照してください。 +エージェントが `ModelSettings(store=False)` で実行されている場合、Responses API は後で参照するために最後の応答を保持しません。このステートレスな設定では、デフォルトの `"auto"` モードは `previous_response_id` に依存する代わりに、入力ベースのコンパクションにフォールバックします。完全な例については [`examples/memory/compaction_session_stateless_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/compaction_session_stateless_example.py) を参照してください。 -#### 自動圧縮はストリーミングをブロックする場合があります +#### 自動コンパクションがストリーミングをブロックする可能性 -圧縮はセッション履歴をクリアして再書き込みするため、SDK は圧縮完了前に実行完了と見なしません。ストリーミングモードでは、圧縮が重い場合、最後の出力トークンの後も `run.stream_events()` が数秒開いたままになることがあります。 +コンパクションはセッション履歴をクリアして書き直すため、SDK は実行が完了したとみなす前にコンパクションの終了を待ちます。ストリーミングモードでは、コンパクションが重い場合、最後の出力トークンの後も `run.stream_events()` が数秒間開いたままになる可能性があります。 -低レイテンシなストリーミングや高速なターン交代が必要な場合は、自動圧縮を無効化し、ターン間(またはアイドル時間)に `run_compaction()` を手動で呼び出してください。圧縮を強制するタイミングは独自の基準で決められます。 +低レイテンシのストリーミングや高速なターン処理が必要な場合は、自動コンパクションを無効にし、ターン間(またはアイドル時間中)に自分で `run_compaction()` を呼び出してください。独自の基準に基づいて、いつ強制的にコンパクションするかを決定できます。 ```python from agents import Agent, Runner, SQLiteSession @@ -310,7 +311,7 @@ await session.run_compaction({"force": True}) ### SQLite セッション -SQLite を使用したデフォルトの軽量セッション実装です: +SQLite を使用するデフォルトの軽量セッション実装です。 ```python from agents import SQLiteSession @@ -331,7 +332,7 @@ result = await Runner.run( ### 非同期 SQLite セッション -`aiosqlite` をバックエンドにした SQLite 永続化が必要な場合は `AsyncSQLiteSession` を使用します。 +`aiosqlite` による SQLite 永続化を使いたい場合は、`AsyncSQLiteSession` を使用します。 ```bash pip install aiosqlite @@ -348,7 +349,7 @@ result = await Runner.run(agent, "Hello", session=session) ### Redis セッション -複数のワーカーやサービス間でセッションメモリを共有するには `RedisSession` を使用します。 +複数のワーカーまたはサービス間で共有セッションメモリを使うには、`RedisSession` を使用します。 ```bash pip install openai-agents[redis] @@ -368,7 +369,7 @@ result = await Runner.run(agent, "Hello", session=session) ### SQLAlchemy セッション -SQLAlchemy 対応の任意のデータベースを使用した、本番対応の Agents SDK セッション永続化: +SQLAlchemy がサポートする任意のデータベースを使用した、本番対応の Agents SDK セッション永続化です。 ```python from agents.extensions.memory import SQLAlchemySession @@ -386,11 +387,11 @@ engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/db") session = SQLAlchemySession("user_123", engine=engine, create_tables=True) ``` -詳細は [SQLAlchemy Sessions](sqlalchemy_session.md) を参照してください。 +詳細なドキュメントについては [SQLAlchemy セッション](sqlalchemy_session.md)を参照してください。 ### Dapr セッション -すでに Dapr sidecar を運用している場合、またはエージェントコードを変更せずに異なる state-store バックエンド間で移行可能なセッションストレージが必要な場合は `DaprSession` を使用します。 +すでに Dapr サイドカーを実行している場合、またはエージェントコードを変更せずに異なる状態ストアバックエンド間を移動できるセッションストレージが必要な場合は、`DaprSession` を使用します。 ```bash pip install openai-agents[dapr] @@ -411,18 +412,50 @@ async with DaprSession.from_address( print(result.final_output) ``` -注意: +備考: -- `from_address(...)` は Dapr クライアントを作成して所有します。アプリですでに管理している場合は、`dapr_client=...` を指定して直接 `DaprSession(...)` を構築してください。 -- 基盤 state store が TTL をサポートしている場合、`ttl=...` を渡すと古いセッションデータを自動期限切れにできます。 -- より強い read-after-write 保証が必要な場合は `consistency=DAPR_CONSISTENCY_STRONG` を渡してください。 -- Dapr Python SDK は HTTP sidecar endpoint も確認します。ローカル開発では、`dapr_address` で使用する gRPC ポートに加えて、`--dapr-http-port 3500` でも Dapr を起動してください。 -- ローカルコンポーネントやトラブルシューティングを含む完全なセットアップ手順は [`examples/memory/dapr_session_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/dapr_session_example.py) を参照してください。 +- `from_address(...)` は Dapr クライアントを作成し、その所有権を持ちます。アプリがすでにクライアントを管理している場合は、`dapr_client=...` を指定して `DaprSession(...)` を直接構築してください。 +- バッキング状態ストアが TTL をサポートしている場合に、古いセッションデータを自動的に期限切れにするには、`ttl=...` を渡します。 +- より強い read-after-write 保証が必要な場合は、`consistency=DAPR_CONSISTENCY_STRONG` を渡します。 +- Dapr Python SDK は HTTP サイドカーエンドポイントも確認します。ローカル開発では、`dapr_address` で使用する gRPC ポートに加えて、`--dapr-http-port 3500` でも Dapr を起動してください。 +- ローカルコンポーネントやトラブルシューティングを含む完全なセットアップ手順については、[`examples/memory/dapr_session_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/dapr_session_example.py) を参照してください。 +### MongoDB セッション + +すでに MongoDB を使用しているアプリケーションや、水平スケーラブルなマルチプロセスセッションストレージが必要なアプリケーションでは、`MongoDBSession` を使用します。 + +```bash +pip install openai-agents[mongodb] +``` + +```python +from agents import Agent, Runner +from agents.extensions.memory import MongoDBSession + +agent = Agent(name="Assistant") + +# Create from URI — owns the client and closes it when session.close() is called +session = MongoDBSession.from_uri( + "user-123", + uri="mongodb://localhost:27017", + database="agents", +) +result = await Runner.run(agent, "Hello", session=session) +print(result.final_output) +await session.close() +``` + +備考: + +- `from_uri(...)` は `AsyncMongoClient` を作成して所有し、`session.close()` 時に閉じます。アプリケーションがすでにクライアントを管理している場合は、`client=...` を指定して `MongoDBSession(...)` を直接構築してください。その場合、`session.close()` は no-op になり、ライフサイクルは呼び出し元に残ります。 +- そのほかの変更なしに、`mongodb+srv://user:password@cluster.example.mongodb.net` URI を `from_uri(...)` に渡すことで、[MongoDB Atlas](https://www.mongodb.com/products/platform) に接続できます。 +- 2 つのコレクションが使用され、どちらの名前も `sessions_collection=`(デフォルト `agent_sessions`)および `messages_collection=`(デフォルト `agent_messages`)で構成できます。インデックスは初回使用時に自動的に作成されます。各メッセージドキュメントには、同時書き込み元やプロセス間で順序を保持する単調増加の `seq` カウンターが含まれます。 +- 最初の実行前に接続性を確認するには、`await session.ping()` を使用します。 + ### Advanced SQLite セッション -会話分岐、使用状況分析、構造化クエリを備えた拡張 SQLite セッション: +会話の分岐、利用状況分析、構造化クエリを備えた拡張 SQLite セッションです。 ```python from agents.extensions.memory import AdvancedSQLiteSession @@ -442,11 +475,11 @@ await session.store_run_usage(result) # Track token usage await session.create_branch_from_turn(2) # Branch from turn 2 ``` -詳細は [Advanced SQLite Sessions](advanced_sqlite_session.md) を参照してください。 +詳細なドキュメントについては [Advanced SQLite セッション](advanced_sqlite_session.md)を参照してください。 -### Encrypted セッション +### 暗号化セッション -任意のセッション実装向け透過的暗号化ラッパー: +任意のセッション実装向けの透過的な暗号化ラッパーです。 ```python from agents.extensions.memory import EncryptedSession, SQLAlchemySession @@ -469,17 +502,17 @@ session = EncryptedSession( result = await Runner.run(agent, "Hello", session=session) ``` -詳細は [Encrypted Sessions](encrypted_session.md) を参照してください。 +詳細なドキュメントについては [暗号化セッション](encrypted_session.md)を参照してください。 ### その他のセッションタイプ -このほかにもいくつかの組み込みオプションがあります。`examples/memory/` と `extensions/memory/` 配下のソースコードを参照してください。 +組み込みオプションはさらにいくつかあります。`examples/memory/` および `extensions/memory/` 配下のソースコードを参照してください。 ## 運用パターン -### セッション ID 命名 +### セッション ID の命名 -会話の整理に役立つ、意味のあるセッション ID を使用してください: +会話を整理しやすくする意味のあるセッション ID を使用してください。 - ユーザーベース: `"user_12345"` - スレッドベース: `"thread_abc123"` @@ -487,15 +520,16 @@ result = await Runner.run(agent, "Hello", session=session) ### メモリ永続化 -- 一時的な会話にはインメモリ SQLite(`SQLiteSession("session_id")`)を使用 -- 永続的な会話にはファイルベース SQLite(`SQLiteSession("session_id", "path/to/db.sqlite")`)を使用 -- `aiosqlite` ベース実装が必要な場合は非同期 SQLite(`AsyncSQLiteSession("session_id", db_path="...")`)を使用 -- 共有の低レイテンシなセッションメモリには Redis バックエンドセッション(`RedisSession.from_url("session_id", url="redis://...")`)を使用 -- SQLAlchemy が対応する既存データベースを持つ本番システムには SQLAlchemy ベースセッション(`SQLAlchemySession("session_id", engine=engine, create_tables=True)`)を使用 -- 組み込みテレメトリ、トレーシング、データ分離に加え 30 以上のデータベースバックエンドをサポートする本番クラウドネイティブデプロイには Dapr state store セッション(`DaprSession.from_address("session_id", state_store_name="statestore", dapr_address="localhost:50001")`)を使用 -- 履歴を OpenAI Conversations API に保存したい場合は OpenAI ホスト型ストレージ(`OpenAIConversationsSession()`)を使用 -- 任意のセッションを透過的暗号化と TTL ベース期限切れでラップするには暗号化セッション(`EncryptedSession(session_id, underlying_session, encryption_key)`)を使用 -- より高度なユースケース向けに、他の本番システム(例: Django)向けカスタムセッションバックエンドの実装も検討してください +- 一時的な会話にはインメモリ SQLite(`SQLiteSession("session_id")`)を使用します +- 永続的な会話にはファイルベース SQLite(`SQLiteSession("session_id", "path/to/db.sqlite")`)を使用します +- `aiosqlite` ベースの実装が必要な場合は非同期 SQLite(`AsyncSQLiteSession("session_id", db_path="...")`)を使用します +- 共有された低レイテンシのセッションメモリには Redis バックのセッション(`RedisSession.from_url("session_id", url="redis://...")`)を使用します +- SQLAlchemy がサポートする既存データベースを持つ本番システムには、SQLAlchemy によるセッション(`SQLAlchemySession("session_id", engine=engine, create_tables=True)`)を使用します +- すでに MongoDB を使用している、またはマルチプロセスで水平スケーラブルなセッションストレージが必要なアプリケーションには、MongoDB セッション(`MongoDBSession.from_uri("session_id", uri="mongodb://localhost:27017")`)を使用します +- 組み込みのテレメトリ、トレーシング、データ分離を備えた 30 以上のデータベースバックエンドに対応する本番クラウドネイティブデプロイには、Dapr 状態ストアセッション(`DaprSession.from_address("session_id", state_store_name="statestore", dapr_address="localhost:50001")`)を使用します +- 履歴を OpenAI Conversations API に保存したい場合は、OpenAI がホストするストレージ(`OpenAIConversationsSession()`)を使用します +- 任意のセッションを透過的な暗号化と TTL ベースの有効期限切れでラップするには、暗号化セッション(`EncryptedSession(session_id, underlying_session, encryption_key)`)を使用します +- より高度なユースケースでは、他の本番システム(たとえば Django)向けのカスタムセッションバックエンドの実装を検討してください ### 複数セッション @@ -543,7 +577,7 @@ result2 = await Runner.run( ## 完全な例 -セッションメモリの動作を示す完全な例です: +セッションメモリの動作を示す完全な例を以下に示します。 ```python import asyncio @@ -607,7 +641,7 @@ if __name__ == "__main__": ## カスタムセッション実装 -[`Session`][agents.memory.session.Session] プロトコルに従うクラスを作成することで、独自のセッションメモリを実装できます: +[`Session`][agents.memory.session.Session] プロトコルに従うクラスを作成することで、独自のセッションメモリを実装できます。 ```python from agents.memory.session import SessionABC @@ -652,25 +686,26 @@ result = await Runner.run( ## コミュニティセッション実装 -コミュニティでは追加のセッション実装が開発されています: +コミュニティは追加のセッション実装を開発しています。 -| Package | Description | +| パッケージ | 説明 | |---------|-------------| -| [openai-django-sessions](https://pypi.org/project/openai-django-sessions/) | 任意の Django 対応データベース( PostgreSQL、 MySQL、 SQLite など)向けの Django ORM ベースセッション | +| [openai-django-sessions](https://pypi.org/project/openai-django-sessions/) | Django がサポートする任意のデータベース(PostgreSQL、MySQL、SQLite など)向けの Django ORM ベースのセッション | -セッション実装を作成した場合は、ここに追加するためのドキュメント PR をぜひ送ってください。 +セッション実装を構築した場合は、ここに追加するためのドキュメント PR をぜひ提出してください。 ## API リファレンス -詳細な API ドキュメントは以下を参照してください: +詳細な API ドキュメントについては、以下を参照してください。 -- [`Session`][agents.memory.session.Session] - プロトコルインターフェース +- [`Session`][agents.memory.session.Session] - プロトコルインターフェイス - [`OpenAIConversationsSession`][agents.memory.OpenAIConversationsSession] - OpenAI Conversations API 実装 -- [`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession] - Responses API 圧縮ラッパー -- [`SQLiteSession`][agents.memory.sqlite_session.SQLiteSession] - 基本 SQLite 実装 -- [`AsyncSQLiteSession`][agents.extensions.memory.async_sqlite_session.AsyncSQLiteSession] - `aiosqlite` ベースの非同期 SQLite 実装 -- [`RedisSession`][agents.extensions.memory.redis_session.RedisSession] - Redis バックエンドセッション実装 -- [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - SQLAlchemy ベース実装 -- [`DaprSession`][agents.extensions.memory.dapr_session.DaprSession] - Dapr state store 実装 +- [`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession] - Responses API コンパクションラッパー +- [`SQLiteSession`][agents.memory.sqlite_session.SQLiteSession] - 基本的な SQLite 実装 +- [`AsyncSQLiteSession`][agents.extensions.memory.async_sqlite_session.AsyncSQLiteSession] - `aiosqlite` に基づく非同期 SQLite 実装 +- [`RedisSession`][agents.extensions.memory.redis_session.RedisSession] - Redis バックのセッション実装 +- [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - SQLAlchemy による実装 +- [`MongoDBSession`][agents.extensions.memory.mongodb_session.MongoDBSession] - MongoDB バックのセッション実装 +- [`DaprSession`][agents.extensions.memory.dapr_session.DaprSession] - Dapr 状態ストア実装 - [`AdvancedSQLiteSession`][agents.extensions.memory.advanced_sqlite_session.AdvancedSQLiteSession] - 分岐と分析を備えた拡張 SQLite -- [`EncryptedSession`][agents.extensions.memory.encrypt_session.EncryptedSession] - 任意のセッション向け暗号化ラッパー \ No newline at end of file +- [`EncryptedSession`][agents.extensions.memory.encrypt_session.EncryptedSession] - 任意のセッション向けの暗号化ラッパー \ No newline at end of file diff --git a/docs/ko/sessions/index.md b/docs/ko/sessions/index.md index 83005f3ae6..abadb1a240 100644 --- a/docs/ko/sessions/index.md +++ b/docs/ko/sessions/index.md @@ -4,11 +4,11 @@ search: --- # 세션 -Agents SDK 는 여러 에이전트 실행에 걸쳐 대화 기록을 자동으로 유지하는 내장 세션 메모리를 제공하여, 턴 사이에서 `.to_input_list()`를 수동으로 처리할 필요를 없앱니다 +Agents SDK는 여러 에이전트 실행에 걸쳐 대화 기록을 자동으로 유지하는 내장 세션 메모리를 제공하여, 턴 사이에 `.to_input_list()`를 수동으로 처리할 필요를 없애줍니다. -Sessions 는 특정 세션의 대화 기록을 저장하므로, 에이전트가 명시적인 수동 메모리 관리 없이 컨텍스트를 유지할 수 있습니다. 이는 특히 에이전트가 이전 상호작용을 기억해야 하는 채팅 애플리케이션이나 멀티턴 대화를 구축할 때 유용합니다 +세션은 특정 세션의 대화 기록을 저장하여, 명시적인 수동 메모리 관리 없이도 에이전트가 컨텍스트를 유지할 수 있게 합니다. 이는 특히 에이전트가 이전 상호작용을 기억하길 원하는 채팅 애플리케이션이나 멀티턴 대화를 구축할 때 유용합니다. -SDK 가 클라이언트 측 메모리를 관리하도록 하려면 세션을 사용하세요. 세션은 동일한 실행에서 `conversation_id`, `previous_response_id`, `auto_previous_response_id`와 함께 사용할 수 없습니다. 대신 OpenAI 서버 관리형 연속 처리를 원한다면, 세션을 덧씌우지 말고 해당 메커니즘 중 하나를 선택하세요 +SDK가 클라이언트 측 메모리를 관리하도록 하려면 세션을 사용하세요. 세션은 동일한 실행에서 `conversation_id`, `previous_response_id`, `auto_previous_response_id`와 함께 사용할 수 없습니다. 대신 OpenAI 서버 관리형 이어가기를 원한다면, 세션을 그 위에 겹쳐 쓰지 말고 이러한 메커니즘 중 하나를 선택하세요. ## 빠른 시작 @@ -49,9 +49,9 @@ result = Runner.run_sync( print(result.final_output) # "Approximately 39 million" ``` -## 동일한 세션으로 인터럽션(중단 처리)된 실행 재개 +## 동일한 세션으로 인터럽트된 실행 재개 -승인을 위해 실행이 일시 중지된 경우, 동일한 세션 인스턴스(또는 동일한 백킹 저장소를 가리키는 다른 세션 인스턴스)로 재개하면 재개된 턴이 같은 저장된 대화 기록을 계속 사용합니다 +승인을 위해 실행이 일시 중지되면, 재개된 턴이 동일한 저장된 대화 기록을 이어가도록 같은 세션 인스턴스(또는 동일한 백킹 스토어를 가리키는 다른 세션 인스턴스)로 재개하세요. ```python result = await Runner.run(agent, "Delete temporary files that are no longer needed.", session=session) @@ -65,29 +65,29 @@ if result.interruptions: ## 핵심 세션 동작 -세션 메모리가 활성화되면 다음과 같이 동작합니다 +세션 메모리가 활성화되면: -1. **각 실행 전**: 러너가 세션의 대화 기록을 자동으로 조회하여 입력 항목 앞에 추가합니다 -2. **각 실행 후**: 실행 중 생성된 모든 새 항목(사용자 입력, 어시스턴트 응답, 도구 호출 등)이 세션에 자동 저장됩니다 -3. **컨텍스트 보존**: 동일한 세션을 사용하는 이후 실행마다 전체 대화 기록이 포함되어 에이전트가 컨텍스트를 유지할 수 있습니다 +1. **각 실행 전**: 러너가 세션의 대화 기록을 자동으로 가져와 입력 항목 앞에 추가합니다. +2. **각 실행 후**: 실행 중 생성된 모든 새 항목(사용자 입력, 어시스턴트 응답, 도구 호출 등)이 세션에 자동으로 저장됩니다. +3. **컨텍스트 보존**: 동일한 세션으로 이어지는 각 실행에는 전체 대화 기록이 포함되어 에이전트가 컨텍스트를 유지할 수 있습니다. -이로써 실행 간 대화 상태를 관리하기 위해 `.to_input_list()`를 수동 호출할 필요가 없어집니다 +이를 통해 `.to_input_list()`를 수동으로 호출하고 실행 간 대화 상태를 관리할 필요가 없어집니다. ## 기록과 새 입력 병합 제어 -세션을 전달하면 러너는 일반적으로 모델 입력을 다음 순서로 준비합니다 +세션을 전달하면, 러너는 일반적으로 모델 입력을 다음과 같이 준비합니다. -1. 세션 기록(`session.get_items(...)`에서 조회) +1. 세션 기록(`session.get_items(...)`에서 가져옴) 2. 새 턴 입력 -모델 호출 전에 이 병합 단계를 사용자 지정하려면 [`RunConfig.session_input_callback`][agents.run.RunConfig.session_input_callback]을 사용하세요. 콜백은 두 리스트를 받습니다 +모델 호출 전에 이 병합 단계를 사용자 지정하려면 [`RunConfig.session_input_callback`][agents.run.RunConfig.session_input_callback]을 사용하세요. 콜백은 두 개의 목록을 받습니다. -- `history`: 조회된 세션 기록(이미 입력 항목 형식으로 정규화됨) +- `history`: 가져온 세션 기록(이미 입력 항목 형식으로 정규화됨) - `new_input`: 현재 턴의 새 입력 항목 -모델로 전송할 최종 입력 항목 리스트를 반환하세요 +모델에 전송할 최종 입력 항목 목록을 반환하세요. -콜백은 두 리스트의 복사본을 받으므로 안전하게 변경할 수 있습니다. 반환된 리스트는 해당 턴의 모델 입력을 제어하지만, SDK 는 여전히 새 턴에 속한 항목만 영속화합니다. 따라서 이전 기록을 재정렬하거나 필터링해도 기존 세션 항목이 새 입력으로 다시 저장되지는 않습니다 +콜백은 두 목록의 복사본을 받으므로 안전하게 변경할 수 있습니다. 반환된 목록은 해당 턴의 모델 입력을 제어하지만, SDK는 여전히 새 턴에 속한 항목만 저장합니다. 따라서 오래된 기록을 재정렬하거나 필터링해도 오래된 세션 항목이 새 입력으로 다시 저장되지는 않습니다. ```python from agents import Agent, RunConfig, Runner, SQLiteSession @@ -109,16 +109,16 @@ result = await Runner.run( ) ``` -세션 저장 방식은 바꾸지 않고 사용자 지정 가지치기, 재정렬, 선택적 기록 포함이 필요할 때 이를 사용하세요. 모델 호출 직전에 더 늦은 최종 패스가 필요하면 [에이전트 실행 가이드](../running_agents.md)의 [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter]를 사용하세요 +세션이 항목을 저장하는 방식을 바꾸지 않으면서 기록을 사용자 지정 가지치기, 재정렬 또는 선택적으로 포함해야 할 때 사용하세요. 모델 호출 직전에 한 번 더 최종 처리가 필요하다면 [running agents guide](../running_agents.md)의 [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter]를 사용하세요. -## 조회 기록 제한 +## 가져오는 기록 제한 -각 실행 전에 가져올 기록 양을 제어하려면 [`SessionSettings`][agents.memory.SessionSettings]를 사용하세요 +각 실행 전에 가져올 기록의 양을 제어하려면 [`SessionSettings`][agents.memory.SessionSettings]를 사용하세요. -- `SessionSettings(limit=None)`(기본값): 사용 가능한 모든 세션 항목 조회 -- `SessionSettings(limit=N)`: 가장 최근 `N`개 항목만 조회 +- `SessionSettings(limit=None)`(기본값): 사용 가능한 모든 세션 항목 가져오기 +- `SessionSettings(limit=N)`: 가장 최근 `N`개 항목만 가져오기 -[`RunConfig.session_settings`][agents.run.RunConfig.session_settings]를 통해 실행별로 적용할 수 있습니다 +[`RunConfig.session_settings`][agents.run.RunConfig.session_settings]를 통해 실행별로 이를 적용할 수 있습니다. ```python from agents import Agent, RunConfig, Runner, SessionSettings, SQLiteSession @@ -134,13 +134,13 @@ result = await Runner.run( ) ``` -세션 구현에서 기본 session settings 를 제공하는 경우, `RunConfig.session_settings`는 해당 실행에서 `None`이 아닌 값을 덮어씁니다. 이는 세션의 기본 동작을 변경하지 않고도 긴 대화에서 조회 크기를 제한하고 싶을 때 유용합니다 +세션 구현이 기본 세션 설정을 노출하는 경우, `RunConfig.session_settings`는 해당 실행에서 `None`이 아닌 값을 재정의합니다. 이는 긴 대화에서 세션의 기본 동작을 바꾸지 않고 가져오기 크기를 제한하고 싶을 때 유용합니다. ## 메모리 작업 ### 기본 작업 -Sessions 는 대화 기록 관리를 위한 여러 작업을 지원합니다 +세션은 대화 기록을 관리하기 위한 여러 작업을 지원합니다. ```python from agents import SQLiteSession @@ -165,9 +165,9 @@ print(last_item) # {"role": "assistant", "content": "Hi there!"} await session.clear_session() ``` -### 수정용 pop_item 사용 +### 수정을 위한 pop_item 사용 -`pop_item` 메서드는 대화의 마지막 항목을 되돌리거나 수정하려는 경우 특히 유용합니다 +`pop_item` 메서드는 대화의 마지막 항목을 되돌리거나 수정하려는 경우 특히 유용합니다. ```python from agents import Agent, Runner, SQLiteSession @@ -198,31 +198,32 @@ print(f"Agent: {result.final_output}") ## 내장 세션 구현 -SDK 는 다양한 사용 사례를 위한 여러 세션 구현을 제공합니다 +SDK는 다양한 사용 사례에 맞는 여러 세션 구현을 제공합니다. ### 내장 세션 구현 선택 -아래 상세 예제를 읽기 전에 시작점을 고르려면 이 표를 사용하세요 +아래의 상세 예제를 읽기 전에 이 표를 사용해 출발점을 선택하세요. -| Session type | Best for | Notes | +| 세션 유형 | 적합한 경우 | 참고 | | --- | --- | --- | -| `SQLiteSession` | 로컬 개발 및 단순 앱 | 내장, 경량, 파일 기반 또는 메모리 내 | -| `AsyncSQLiteSession` | `aiosqlite`를 사용한 비동기 SQLite | 비동기 드라이버 지원 확장 백엔드 | +| `SQLiteSession` | 로컬 개발 및 간단한 앱 | 내장형, 경량, 파일 기반 또는 인메모리 | +| `AsyncSQLiteSession` | `aiosqlite`를 사용하는 비동기 SQLite | 비동기 드라이버 지원이 있는 확장 백엔드 | | `RedisSession` | 워커/서비스 간 공유 메모리 | 저지연 분산 배포에 적합 | -| `SQLAlchemySession` | 기존 데이터베이스를 사용하는 프로덕션 앱 | SQLAlchemy 지원 데이터베이스에서 동작 | -| `DaprSession` | Dapr 사이드카를 사용하는 클라우드 네이티브 배포 | TTL 및 일관성 제어와 함께 여러 상태 저장소 지원 | -| `OpenAIConversationsSession` | OpenAI 의 서버 관리형 저장소 | OpenAI Conversations API 기반 기록 | +| `SQLAlchemySession` | 기존 데이터베이스를 사용하는 프로덕션 앱 | SQLAlchemy 지원 데이터베이스와 작동 | +| `MongoDBSession` | 이미 MongoDB를 사용하거나 멀티프로세스 스토리지가 필요한 앱 | 비동기 pymongo; 순서 보장을 위한 원자적 시퀀스 카운터 | +| `DaprSession` | Dapr 사이드카를 사용하는 클라우드 네이티브 배포 | 여러 상태 저장소와 TTL 및 일관성 제어 지원 | +| `OpenAIConversationsSession` | OpenAI의 서버 관리형 스토리지 | OpenAI Conversations API 기반 기록 | | `OpenAIResponsesCompactionSession` | 자동 압축이 필요한 긴 대화 | 다른 세션 백엔드를 감싸는 래퍼 | -| `AdvancedSQLiteSession` | SQLite + 브랜칭/분석 | 더 무거운 기능 세트, 전용 페이지 참조 | -| `EncryptedSession` | 다른 세션 위의 암호화 + TTL | 래퍼이며 먼저 기반 백엔드 선택 필요 | +| `AdvancedSQLiteSession` | SQLite와 브랜칭/분석 | 더 무거운 기능 세트; 전용 페이지 참조 | +| `EncryptedSession` | 다른 세션 위의 암호화 + TTL | 래퍼; 먼저 기반 백엔드 선택 | -일부 구현은 추가 세부 정보가 있는 전용 페이지를 제공합니다. 해당 링크는 각 하위 섹션에 포함되어 있습니다 +일부 구현에는 추가 세부 정보를 담은 전용 페이지가 있으며, 각 하위 섹션에 인라인으로 링크되어 있습니다. -ChatKit 용 Python 서버를 구현하는 경우 ChatKit 의 스레드 및 항목 영속성을 위해 `chatkit.store.Store` 구현을 사용하세요. `SQLAlchemySession` 같은 Agents SDK 세션은 SDK 측 대화 기록을 관리하지만 ChatKit store 를 대체하는 드롭인 솔루션은 아닙니다. [`chatkit-python` guide on implementing your ChatKit data store](https://github.com/openai/chatkit-python/blob/main/docs/guides/respond-to-user-message.md#implement-your-chatkit-data-store)를 참조하세요 +ChatKit용 파이썬 서버를 구현하는 경우 ChatKit의 스레드 및 항목 영속성을 위해 `chatkit.store.Store` 구현을 사용하세요. `SQLAlchemySession` 같은 Agents SDK 세션은 SDK 측 대화 기록을 관리하지만, ChatKit의 스토어를 대체하는 드롭인 대체품은 아닙니다. [`ChatKit 데이터 스토어 구현에 대한 chatkit-python 가이드`](https://github.com/openai/chatkit-python/blob/main/docs/guides/respond-to-user-message.md#implement-your-chatkit-data-store)를 참조하세요. ### OpenAI Conversations API 세션 -`OpenAIConversationsSession`을 통해 [OpenAI's Conversations API](https://platform.openai.com/docs/api-reference/conversations)를 사용하세요 +`OpenAIConversationsSession`을 통해 [OpenAI의 Conversations API](https://platform.openai.com/docs/api-reference/conversations)를 사용하세요. ```python from agents import Agent, Runner, OpenAIConversationsSession @@ -258,7 +259,7 @@ print(result.final_output) # "California" ### OpenAI Responses 압축 세션 -Responses API(`responses.compact`)로 저장된 대화 기록을 압축하려면 `OpenAIResponsesCompactionSession`을 사용하세요. 이는 기반 세션을 감싸며 `should_trigger_compaction`에 따라 각 턴 후 자동 압축할 수 있습니다. `OpenAIConversationsSession`을 이것으로 감싸지 마세요. 두 기능은 기록을 서로 다른 방식으로 관리합니다 +Responses API(`responses.compact`)로 저장된 대화 기록을 압축하려면 `OpenAIResponsesCompactionSession`을 사용하세요. 이는 기반 세션을 감싸며 `should_trigger_compaction`에 따라 각 턴 후 자동으로 압축할 수 있습니다. `OpenAIConversationsSession`을 이것으로 감싸지 마세요. 두 기능은 서로 다른 방식으로 기록을 관리합니다. #### 일반적인 사용법(자동 압축) @@ -277,17 +278,17 @@ result = await Runner.run(agent, "Hello", session=session) print(result.final_output) ``` -기본적으로 후보 임계값에 도달하면 각 턴 후 압축이 실행됩니다 +기본적으로, 후보 임계값에 도달하면 각 턴 후 압축이 실행됩니다. -`compaction_mode="previous_response_id"`는 Responses API response ID 로 이미 턴을 체이닝하고 있을 때 가장 잘 동작합니다. `compaction_mode="input"`은 현재 세션 항목에서 압축 요청을 재구성하며, response chain 을 사용할 수 없거나 세션 내용이 단일 진실 소스가 되길 원할 때 유용합니다. 기본값인 `"auto"`는 사용 가능한 가장 안전한 옵션을 선택합니다 +`compaction_mode="previous_response_id"`는 Responses API 응답 ID로 이미 턴을 체이닝하고 있을 때 가장 잘 작동합니다. `compaction_mode="input"`은 대신 현재 세션 항목에서 압축 요청을 다시 구성하므로, 응답 체인을 사용할 수 없거나 세션 내용이 진실의 원천이 되길 원할 때 유용합니다. 기본값 `"auto"`는 사용 가능한 가장 안전한 옵션을 선택합니다. -에이전트를 `ModelSettings(store=False)`로 실행하면 Responses API 는 나중 조회를 위해 마지막 응답을 유지하지 않습니다. 이 무상태 설정에서 기본 `"auto"` 모드는 `previous_response_id`에 의존하는 대신 입력 기반 압축으로 폴백합니다. 전체 예제는 [`examples/memory/compaction_session_stateless_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/compaction_session_stateless_example.py)를 참조하세요 +에이전트가 `ModelSettings(store=False)`로 실행되면 Responses API는 나중 조회를 위해 마지막 응답을 보관하지 않습니다. 이러한 무상태 설정에서는 기본 `"auto"` 모드가 `previous_response_id`에 의존하는 대신 입력 기반 압축으로 폴백합니다. 전체 예제는 [`examples/memory/compaction_session_stateless_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/compaction_session_stateless_example.py)를 참조하세요. -#### 자동 압축은 스트리밍을 차단할 수 있음 +#### 자동 압축과 스트리밍 차단 가능성 -압축은 세션 기록을 지우고 다시 쓰므로, SDK 는 압축이 완료될 때까지 실행 완료로 간주하지 않습니다. 스트리밍 모드에서는 압축이 무거울 경우 마지막 출력 토큰 이후에도 `run.stream_events()`가 몇 초간 열린 상태로 유지될 수 있습니다 +압축은 세션 기록을 지우고 다시 쓰므로, SDK는 실행을 완료로 간주하기 전에 압축이 끝날 때까지 기다립니다. 스트리밍 모드에서는 압축이 무거운 경우 마지막 출력 토큰 이후에도 `run.stream_events()`가 몇 초 동안 열려 있을 수 있음을 의미합니다. -저지연 스트리밍이나 빠른 턴 전환이 필요하면 자동 압축을 비활성화하고 턴 사이(또는 유휴 시간)에 `run_compaction()`을 직접 호출하세요. 자체 기준에 따라 압축 강제 시점을 결정할 수 있습니다 +저지연 스트리밍이나 빠른 턴 전환을 원한다면 자동 압축을 비활성화하고 턴 사이(또는 유휴 시간)에 직접 `run_compaction()`을 호출하세요. 자체 기준에 따라 언제 압축을 강제할지 결정할 수 있습니다. ```python from agents import Agent, Runner, SQLiteSession @@ -310,7 +311,7 @@ await session.run_compaction({"force": True}) ### SQLite 세션 -SQLite 를 사용하는 기본 경량 세션 구현입니다 +SQLite를 사용하는 기본 경량 세션 구현: ```python from agents import SQLiteSession @@ -331,7 +332,7 @@ result = await Runner.run( ### 비동기 SQLite 세션 -`aiosqlite` 기반 SQLite 영속성이 필요하면 `AsyncSQLiteSession`을 사용하세요 +`aiosqlite` 기반 SQLite 영속성이 필요할 때 `AsyncSQLiteSession`을 사용하세요. ```bash pip install aiosqlite @@ -348,7 +349,7 @@ result = await Runner.run(agent, "Hello", session=session) ### Redis 세션 -여러 워커 또는 서비스 간 공유 세션 메모리를 위해 `RedisSession`을 사용하세요 +여러 워커나 서비스 간 공유 세션 메모리에는 `RedisSession`을 사용하세요. ```bash pip install openai-agents[redis] @@ -368,7 +369,7 @@ result = await Runner.run(agent, "Hello", session=session) ### SQLAlchemy 세션 -SQLAlchemy 가 지원하는 모든 데이터베이스를 사용한 프로덕션 준비 완료 Agents SDK 세션 영속성입니다 +SQLAlchemy가 지원하는 모든 데이터베이스를 사용한 프로덕션 준비 Agents SDK 세션 영속성: ```python from agents.extensions.memory import SQLAlchemySession @@ -386,11 +387,11 @@ engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/db") session = SQLAlchemySession("user_123", engine=engine, create_tables=True) ``` -자세한 문서는 [SQLAlchemy Sessions](sqlalchemy_session.md)를 참조하세요 +자세한 문서는 [SQLAlchemy 세션](sqlalchemy_session.md)을 참조하세요. ### Dapr 세션 -이미 Dapr 사이드카를 실행 중이거나, 에이전트 코드를 변경하지 않고 서로 다른 상태 저장소 백엔드 간 이동 가능한 세션 저장소가 필요하면 `DaprSession`을 사용하세요 +이미 Dapr 사이드카를 실행 중이거나 에이전트 코드를 변경하지 않고 다양한 상태 저장소 백엔드 간 이동할 수 있는 세션 스토리지가 필요할 때 `DaprSession`을 사용하세요. ```bash pip install openai-agents[dapr] @@ -413,16 +414,48 @@ async with DaprSession.from_address( 참고: -- `from_address(...)`는 Dapr 클라이언트를 생성하고 소유합니다. 앱에서 이미 클라이언트를 관리 중이면 `dapr_client=...`와 함께 `DaprSession(...)`을 직접 구성하세요 -- 저장소가 TTL 을 지원할 때 오래된 세션 데이터를 자동 만료시키려면 `ttl=...`을 전달하세요 -- 더 강한 쓰기 후 읽기 보장이 필요하면 `consistency=DAPR_CONSISTENCY_STRONG`을 전달하세요 -- Dapr Python SDK 는 HTTP 사이드카 엔드포인트도 확인합니다. 로컬 개발에서는 `dapr_address`에 사용한 gRPC 포트와 함께 `--dapr-http-port 3500`으로 Dapr 를 시작하세요 -- 로컬 컴포넌트 및 문제 해결을 포함한 전체 설정 안내는 [`examples/memory/dapr_session_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/dapr_session_example.py)를 참조하세요 +- `from_address(...)`는 Dapr 클라이언트를 생성하고 소유합니다. 앱에서 이미 클라이언트를 관리한다면 `dapr_client=...`로 `DaprSession(...)`을 직접 생성하세요. +- 백킹 상태 저장소가 TTL을 지원하는 경우 오래된 세션 데이터가 자동으로 만료되도록 `ttl=...`을 전달하세요. +- 더 강한 쓰기 후 읽기 보장이 필요할 때는 `consistency=DAPR_CONSISTENCY_STRONG`을 전달하세요. +- Dapr Python SDK는 HTTP 사이드카 엔드포인트도 확인합니다. 로컬 개발에서는 `dapr_address`에서 사용하는 gRPC 포트와 함께 `--dapr-http-port 3500`으로 Dapr를 시작하세요. +- 로컬 컴포넌트와 문제 해결을 포함한 전체 설정 절차는 [`examples/memory/dapr_session_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/dapr_session_example.py)를 참조하세요. +### MongoDB 세션 + +이미 MongoDB를 사용하거나 수평 확장 가능한 멀티프로세스 세션 스토리지가 필요한 애플리케이션에는 `MongoDBSession`을 사용하세요. + +```bash +pip install openai-agents[mongodb] +``` + +```python +from agents import Agent, Runner +from agents.extensions.memory import MongoDBSession + +agent = Agent(name="Assistant") + +# Create from URI — owns the client and closes it when session.close() is called +session = MongoDBSession.from_uri( + "user-123", + uri="mongodb://localhost:27017", + database="agents", +) +result = await Runner.run(agent, "Hello", session=session) +print(result.final_output) +await session.close() +``` + +참고: + +- `from_uri(...)`는 `AsyncMongoClient`를 생성하고 소유하며 `session.close()`에서 이를 닫습니다. 애플리케이션에서 이미 클라이언트를 관리한다면 `client=...`로 `MongoDBSession(...)`을 직접 생성하세요. 이 경우 `session.close()`는 아무 작업도 하지 않으며 라이프사이클은 호출자에게 있습니다. +- 다른 변경 없이 `from_uri(...)`에 `mongodb+srv://user:password@cluster.example.mongodb.net` URI를 전달하여 [MongoDB Atlas](https://www.mongodb.com/products/platform)에 연결하세요. +- 두 컬렉션이 사용되며 두 이름 모두 `sessions_collection=`(기본값 `agent_sessions`)과 `messages_collection=`(기본값 `agent_messages`)를 통해 구성할 수 있습니다. 인덱스는 처음 사용할 때 자동으로 생성됩니다. 각 메시지 문서에는 동시 작성자와 프로세스 간 순서를 보존하는 단조 증가 `seq` 카운터가 포함됩니다. +- 첫 실행 전에 연결성을 확인하려면 `await session.ping()`을 사용하세요. + ### 고급 SQLite 세션 -대화 브랜칭, 사용량 분석, 구조화된 쿼리를 제공하는 향상된 SQLite 세션입니다 +대화 브랜칭, 사용량 분석, structured queries를 갖춘 향상된 SQLite 세션: ```python from agents.extensions.memory import AdvancedSQLiteSession @@ -442,11 +475,11 @@ await session.store_run_usage(result) # Track token usage await session.create_branch_from_turn(2) # Branch from turn 2 ``` -자세한 문서는 [Advanced SQLite Sessions](advanced_sqlite_session.md)를 참조하세요 +자세한 문서는 [고급 SQLite 세션](advanced_sqlite_session.md)을 참조하세요. -### 암호화 세션 +### 암호화된 세션 -모든 세션 구현을 위한 투명한 암호화 래퍼입니다 +모든 세션 구현을 위한 투명한 암호화 래퍼: ```python from agents.extensions.memory import EncryptedSession, SQLAlchemySession @@ -469,17 +502,17 @@ session = EncryptedSession( result = await Runner.run(agent, "Hello", session=session) ``` -자세한 문서는 [Encrypted Sessions](encrypted_session.md)를 참조하세요 +자세한 문서는 [암호화된 세션](encrypted_session.md)을 참조하세요. ### 기타 세션 유형 -추가 내장 옵션이 몇 가지 더 있습니다. `examples/memory/` 및 `extensions/memory/` 아래 소스 코드를 참조하세요 +몇 가지 내장 옵션이 더 있습니다. `examples/memory/` 및 `extensions/memory/` 아래의 소스 코드를 참조하세요. ## 운영 패턴 ### 세션 ID 명명 -대화를 정리하는 데 도움이 되는 의미 있는 세션 ID 를 사용하세요 +대화를 정리하는 데 도움이 되는 의미 있는 세션 ID를 사용하세요. - 사용자 기반: `"user_12345"` - 스레드 기반: `"thread_abc123"` @@ -487,17 +520,18 @@ result = await Runner.run(agent, "Hello", session=session) ### 메모리 영속성 -- 임시 대화에는 메모리 내 SQLite (`SQLiteSession("session_id")`) 사용 -- 영구 대화에는 파일 기반 SQLite (`SQLiteSession("session_id", "path/to/db.sqlite")`) 사용 -- `aiosqlite` 기반 구현이 필요하면 비동기 SQLite (`AsyncSQLiteSession("session_id", db_path="...")`) 사용 +- 임시 대화에는 인메모리 SQLite(`SQLiteSession("session_id")`) 사용 +- 영속 대화에는 파일 기반 SQLite(`SQLiteSession("session_id", "path/to/db.sqlite")`) 사용 +- `aiosqlite` 기반 구현이 필요할 때는 비동기 SQLite(`AsyncSQLiteSession("session_id", db_path="...")`) 사용 - 공유 저지연 세션 메모리에는 Redis 기반 세션(`RedisSession.from_url("session_id", url="redis://...")`) 사용 -- SQLAlchemy 가 지원하는 기존 데이터베이스가 있는 프로덕션 시스템에는 SQLAlchemy 기반 세션(`SQLAlchemySession("session_id", engine=engine, create_tables=True)`) 사용 -- 내장 텔레메트리, 트레이싱, 데이터 격리와 함께 30개 이상 데이터베이스 백엔드를 지원하는 클라우드 네이티브 프로덕션 배포에는 Dapr 상태 저장소 세션(`DaprSession.from_address("session_id", state_store_name="statestore", dapr_address="localhost:50001")`) 사용 -- 기록을 OpenAI Conversations API 에 저장하려면 OpenAI 호스트하는 도구 저장소(`OpenAIConversationsSession()`) 사용 -- 모든 세션을 투명 암호화 및 TTL 기반 만료로 감싸려면 암호화 세션(`EncryptedSession(session_id, underlying_session, encryption_key)`) 사용 -- 더 고급 사용 사례를 위해 다른 프로덕션 시스템(예: Django)용 사용자 지정 세션 백엔드 구현 고려 +- SQLAlchemy가 지원하는 기존 데이터베이스가 있는 프로덕션 시스템에는 SQLAlchemy 기반 세션(`SQLAlchemySession("session_id", engine=engine, create_tables=True)`) 사용 +- 이미 MongoDB를 사용하거나 멀티프로세스, 수평 확장 가능한 세션 스토리지가 필요한 애플리케이션에는 MongoDB 세션(`MongoDBSession.from_uri("session_id", uri="mongodb://localhost:27017")`) 사용 +- 내장 텔레메트리, 트레이싱 및 데이터 격리를 갖춘 30개 이상의 데이터베이스 백엔드를 지원하는 프로덕션 클라우드 네이티브 배포에는 Dapr 상태 저장소 세션(`DaprSession.from_address("session_id", state_store_name="statestore", dapr_address="localhost:50001")`) 사용 +- OpenAI Conversations API에 기록을 저장하는 것을 선호한다면 OpenAI 호스팅 스토리지(`OpenAIConversationsSession()`) 사용 +- 모든 세션을 투명한 암호화 및 TTL 기반 만료로 감싸려면 암호화된 세션(`EncryptedSession(session_id, underlying_session, encryption_key)`) 사용 +- 더 고급 사용 사례를 위해 다른 프로덕션 시스템(예: Django)에 대한 사용자 지정 세션 백엔드 구현 고려 -### 다중 세션 +### 여러 세션 ```python from agents import Agent, Runner, SQLiteSession @@ -543,7 +577,7 @@ result2 = await Runner.run( ## 전체 예제 -다음은 세션 메모리가 동작하는 모습을 보여주는 전체 예제입니다 +다음은 세션 메모리가 동작하는 모습을 보여주는 전체 예제입니다. ```python import asyncio @@ -607,7 +641,7 @@ if __name__ == "__main__": ## 사용자 지정 세션 구현 -[`Session`][agents.memory.session.Session] 프로토콜을 따르는 클래스를 만들어 자체 세션 메모리를 구현할 수 있습니다 +[`Session`][agents.memory.session.Session] 프로토콜을 따르는 클래스를 만들어 자체 세션 메모리를 구현할 수 있습니다. ```python from agents.memory.session import SessionABC @@ -652,17 +686,17 @@ result = await Runner.run( ## 커뮤니티 세션 구현 -커뮤니티에서 추가 세션 구현을 개발했습니다 +커뮤니티에서 추가 세션 구현을 개발했습니다. -| Package | Description | +| 패키지 | 설명 | |---------|-------------| -| [openai-django-sessions](https://pypi.org/project/openai-django-sessions/) | Django ORM 기반 세션(Django 지원 데이터베이스: PostgreSQL, MySQL, SQLite 등) | +| [openai-django-sessions](https://pypi.org/project/openai-django-sessions/) | Django가 지원하는 모든 데이터베이스(PostgreSQL, MySQL, SQLite 등)를 위한 Django ORM 기반 세션 | -세션 구현을 만들었다면, 여기에 추가할 수 있도록 문서 PR 제출을 환영합니다 +세션 구현을 구축했다면 여기에 추가할 수 있도록 문서 PR을 자유롭게 제출해 주세요! ## API 참조 -자세한 API 문서는 다음을 참조하세요 +자세한 API 문서는 다음을 참조하세요. - [`Session`][agents.memory.session.Session] - 프로토콜 인터페이스 - [`OpenAIConversationsSession`][agents.memory.OpenAIConversationsSession] - OpenAI Conversations API 구현 @@ -671,6 +705,7 @@ result = await Runner.run( - [`AsyncSQLiteSession`][agents.extensions.memory.async_sqlite_session.AsyncSQLiteSession] - `aiosqlite` 기반 비동기 SQLite 구현 - [`RedisSession`][agents.extensions.memory.redis_session.RedisSession] - Redis 기반 세션 구현 - [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - SQLAlchemy 기반 구현 +- [`MongoDBSession`][agents.extensions.memory.mongodb_session.MongoDBSession] - MongoDB 기반 세션 구현 - [`DaprSession`][agents.extensions.memory.dapr_session.DaprSession] - Dapr 상태 저장소 구현 -- [`AdvancedSQLiteSession`][agents.extensions.memory.advanced_sqlite_session.AdvancedSQLiteSession] - 브랜칭 및 분석을 갖춘 향상된 SQLite -- [`EncryptedSession`][agents.extensions.memory.encrypt_session.EncryptedSession] - 모든 세션용 암호화 래퍼 \ No newline at end of file +- [`AdvancedSQLiteSession`][agents.extensions.memory.advanced_sqlite_session.AdvancedSQLiteSession] - 브랜칭과 분석을 갖춘 향상된 SQLite +- [`EncryptedSession`][agents.extensions.memory.encrypt_session.EncryptedSession] - 모든 세션을 위한 암호화 래퍼 \ No newline at end of file diff --git a/docs/zh/sessions/index.md b/docs/zh/sessions/index.md index f6c267cee5..fb68240388 100644 --- a/docs/zh/sessions/index.md +++ b/docs/zh/sessions/index.md @@ -4,11 +4,11 @@ search: --- # 会话 -Agents SDK 提供内置的会话内存,可在多次智能体运行间自动维护对话历史,无需在轮次之间手动处理 `.to_input_list()`。 +Agents SDK 提供内置会话记忆,可在多次智能体运行之间自动维护对话历史,无需在轮次之间手动处理 `.to_input_list()`。 -Sessions 会为特定会话存储对话历史,使智能体无需显式手动管理内存即可保持上下文。这对于构建聊天应用或多轮对话特别有用,因为你希望智能体记住先前交互。 +会话会存储特定会话的对话历史,使智能体无需显式手动管理记忆即可保持上下文。这对于构建聊天应用或多轮对话尤其有用,在这些场景中你希望智能体记住之前的交互。 -当你希望 SDK 为你管理客户端内存时,请使用会话。会话不能与 `conversation_id`、`previous_response_id` 或 `auto_previous_response_id` 在同一次运行中组合使用。如果你希望改用 OpenAI 服务端管理续接,请选择这些机制之一,而不是在其上再叠加会话。 +当你希望 SDK 为你管理客户端侧记忆时,请使用会话。会话不能在同一次运行中与 `conversation_id`、`previous_response_id` 或 `auto_previous_response_id` 组合使用。如果你想使用 OpenAI 服务端托管的续接,请选择其中一种机制,而不是在其上叠加会话。 ## 快速开始 @@ -49,9 +49,9 @@ result = Runner.run_sync( print(result.final_output) # "Approximately 39 million" ``` -## 使用同一会话恢复中断运行 +## 使用相同会话恢复中断的运行 -如果某次运行因审批而暂停,请使用同一个会话实例(或另一个指向同一底层存储的会话实例)恢复,这样恢复后的轮次会延续同一份已存储的对话历史。 +如果某次运行因等待批准而暂停,请使用相同的会话实例(或指向同一底层存储的另一个会话实例)恢复它,以便恢复后的轮次继续使用同一份已存储的对话历史。 ```python result = await Runner.run(agent, "Delete temporary files that are no longer needed.", session=session) @@ -63,31 +63,31 @@ if result.interruptions: result = await Runner.run(agent, state, session=session) ``` -## 会话核心行为 +## 核心会话行为 -启用会话内存时: +启用会话记忆后: -1. **每次运行前**:运行器会自动检索该会话的对话历史,并将其预置到输入项前面。 -2. **每次运行后**:运行期间产生的所有新项(用户输入、助手回复、工具调用等)都会自动存入会话。 -3. **上下文保留**:后续每次使用同一会话的运行都会包含完整对话历史,使智能体能够保持上下文。 +1. **每次运行前**:运行器会自动检索该会话的对话历史,并将其前置到输入项中。 +2. **每次运行后**:运行期间生成的所有新项(用户输入、助手回复、工具调用等)都会自动存储到会话中。 +3. **上下文保留**:使用同一会话的每次后续运行都会包含完整的对话历史,使智能体能够保持上下文。 -这消除了手动调用 `.to_input_list()` 并在运行间管理对话状态的需求。 +这消除了在运行之间手动调用 `.to_input_list()` 和管理对话状态的需要。 -## 控制历史与新输入的合并方式 +## 历史记录与新输入的合并控制 -当你传入会话时,运行器通常按以下方式准备模型输入: +当你传入会话时,运行器通常会按如下方式准备模型输入: 1. 会话历史(从 `session.get_items(...)` 检索) -2. 当前轮次的新输入 +2. 新轮次输入 -使用 [`RunConfig.session_input_callback`][agents.run.RunConfig.session_input_callback] 可在调用模型前自定义该合并步骤。该回调接收两个列表: +使用 [`RunConfig.session_input_callback`][agents.run.RunConfig.session_input_callback] 在模型调用前自定义该合并步骤。回调会接收两个列表: - `history`:检索到的会话历史(已规范化为输入项格式) - `new_input`:当前轮次的新输入项 返回应发送给模型的最终输入项列表。 -回调接收到的是两个列表的副本,因此你可以安全地修改它们。返回的列表会控制该轮次的模型输入,但 SDK 仍只持久化属于当前新轮次的项。因此,对旧历史重排或过滤不会导致旧会话项再次作为新输入被保存。 +回调接收的是两个列表的副本,因此你可以安全地修改它们。返回的列表会控制该轮次的模型输入,但 SDK 仍然只持久化属于新轮次的项。因此,重新排序或过滤旧历史不会导致旧会话项被作为新的输入再次保存。 ```python from agents import Agent, RunConfig, Runner, SQLiteSession @@ -109,16 +109,16 @@ result = await Runner.run( ) ``` -当你需要自定义裁剪、重排或选择性纳入历史,同时又不改变会话存储项的方式时可使用此功能。如果你需要在模型调用前再做一次最终处理,请使用[运行智能体指南](../running_agents.md)中的 [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter]。 +当你需要自定义裁剪、重新排序或选择性纳入历史记录,同时不改变会话存储项的方式时,请使用此功能。如果你需要在模型调用前立即进行更靠后的最终处理,请使用[运行智能体指南](../running_agents.md)中的 [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter]。 -## 限制检索历史 +## 检索历史记录的限制 -使用 [`SessionSettings`][agents.memory.SessionSettings] 来控制每次运行前拉取多少历史。 +使用 [`SessionSettings`][agents.memory.SessionSettings] 控制每次运行前获取多少历史记录。 -- `SessionSettings(limit=None)`(默认):检索所有可用会话项 -- `SessionSettings(limit=N)`:仅检索最近的 `N` 项 +- `SessionSettings(limit=None)`(默认):检索所有可用的会话项 +- `SessionSettings(limit=N)`:仅检索最近的 `N` 个项 -你可以通过 [`RunConfig.session_settings`][agents.run.RunConfig.session_settings] 按次运行应用: +你可以通过 [`RunConfig.session_settings`][agents.run.RunConfig.session_settings] 按运行应用此设置: ```python from agents import Agent, RunConfig, Runner, SessionSettings, SQLiteSession @@ -134,13 +134,13 @@ result = await Runner.run( ) ``` -如果你的会话实现暴露了默认会话设置,`RunConfig.session_settings` 会覆盖该次运行中所有非 `None` 的值。这在长对话中很有用:你可以限制检索规模而不改变会话默认行为。 +如果你的会话实现暴露默认会话设置,`RunConfig.session_settings` 会覆盖该次运行中任何非 `None` 的值。这对于长对话很有用,你可以限制检索大小,而无需更改会话的默认行为。 -## 内存操作 +## 记忆操作 -### 基础操作 +### 基本操作 -Sessions 支持多种用于管理对话历史的操作: +会话支持多种用于管理对话历史的操作: ```python from agents import SQLiteSession @@ -167,7 +167,7 @@ await session.clear_session() ### 使用 pop_item 进行修正 -当你想撤销或修改对话中的最后一项时,`pop_item` 方法特别有用: +当你想撤销或修改对话中的最后一项时,`pop_item` 方法尤其有用: ```python from agents import Agent, Runner, SQLiteSession @@ -200,25 +200,26 @@ print(f"Agent: {result.final_output}") SDK 为不同用例提供了多种会话实现: -### 选择内置会话实现 +### 内置会话实现的选择 -在阅读下面详细示例前,可先用此表选择起点。 +在阅读下面的详细示例之前,请使用此表选择一个起点。 -| Session type | Best for | Notes | +| 会话类型 | 最适合 | 备注 | | --- | --- | --- | -| `SQLiteSession` | 本地开发和简单应用 | 内置、轻量、支持文件后端或内存后端 | -| `AsyncSQLiteSession` | 使用 `aiosqlite` 的异步 SQLite | 扩展后端,支持异步驱动 | -| `RedisSession` | 跨 worker/服务的共享内存 | 适合低延迟分布式部署 | +| `SQLiteSession` | 本地开发和简单应用 | 内置、轻量、基于文件或内存 | +| `AsyncSQLiteSession` | 使用 `aiosqlite` 的异步 SQLite | 具有异步驱动支持的扩展后端 | +| `RedisSession` | 跨 worker/服务的共享记忆 | 适用于低延迟分布式部署 | | `SQLAlchemySession` | 使用现有数据库的生产应用 | 适用于 SQLAlchemy 支持的数据库 | -| `DaprSession` | 使用 Dapr sidecar 的云原生部署 | 支持多个状态存储,并提供 TTL 与一致性控制 | -| `OpenAIConversationsSession` | OpenAI 中的服务端托管存储 | 基于 OpenAI Conversations API 的历史 | -| `OpenAIResponsesCompactionSession` | 需要自动压缩的长对话 | 对另一种会话后端的封装 | -| `AdvancedSQLiteSession` | SQLite + 分支/分析 | 功能更重;见专门页面 | -| `EncryptedSession` | 在其他会话之上提供加密 + TTL | 封装器;需先选择底层后端 | +| `MongoDBSession` | 已使用 MongoDB 或需要多进程存储的应用 | 异步 pymongo;用于排序的原子序列计数器 | +| `DaprSession` | 使用 Dapr sidecar 的云原生部署 | 支持多个状态存储以及 TTL 和一致性控制 | +| `OpenAIConversationsSession` | OpenAI 中的服务端托管存储 | 基于 OpenAI Conversations API 的历史记录 | +| `OpenAIResponsesCompactionSession` | 带自动压缩的长对话 | 围绕另一个会话后端的包装器 | +| `AdvancedSQLiteSession` | SQLite 加分支/分析 | 功能更丰富;请参阅专用页面 | +| `EncryptedSession` | 基于另一个会话的加密 + TTL | 包装器;请先选择底层后端 | -部分实现有包含更多细节的专门页面;其链接已在各小节中内联提供。 +某些实现有包含更多详细信息的专用页面;这些页面会在各自小节中以内联链接给出。 -如果你正在为 ChatKit 实现 Python 服务,请为 ChatKit 的线程与项持久化使用 `chatkit.store.Store` 实现。Agents SDK 会话(如 `SQLAlchemySession`)管理的是 SDK 侧对话历史,但它们不能直接替代 ChatKit 的存储。请参阅 [`chatkit-python` 中实现 ChatKit 数据存储的指南](https://github.com/openai/chatkit-python/blob/main/docs/guides/respond-to-user-message.md#implement-your-chatkit-data-store)。 +如果你正在为 ChatKit 实现 Python 服务,请使用 `chatkit.store.Store` 实现来持久化 ChatKit 的线程和项。诸如 `SQLAlchemySession` 的 Agents SDK 会话用于管理 SDK 侧的对话历史,但它们不能直接替代 ChatKit 的存储。请参阅 [`chatkit-python` 关于实现 ChatKit 数据存储的指南](https://github.com/openai/chatkit-python/blob/main/docs/guides/respond-to-user-message.md#implement-your-chatkit-data-store)。 ### OpenAI Conversations API 会话 @@ -258,7 +259,7 @@ print(result.final_output) # "California" ### OpenAI Responses 压缩会话 -使用 `OpenAIResponsesCompactionSession` 可通过 Responses API(`responses.compact`)压缩已存储的对话历史。它会封装一个底层会话,并可基于 `should_trigger_compaction` 在每轮后自动压缩。不要用它封装 `OpenAIConversationsSession`;两者以不同方式管理历史。 +使用 `OpenAIResponsesCompactionSession` 通过 Responses API(`responses.compact`)压缩已存储的对话历史。它包装底层会话,并可根据 `should_trigger_compaction` 在每个轮次后自动压缩。不要用它包装 `OpenAIConversationsSession`;这两个功能以不同方式管理历史记录。 #### 典型用法(自动压缩) @@ -277,17 +278,17 @@ result = await Runner.run(agent, "Hello", session=session) print(result.final_output) ``` -默认情况下,达到候选阈值后会在每轮结束后执行压缩。 +默认情况下,一旦达到候选阈值,压缩会在每个轮次后运行。 -当你已经使用 Responses API 的 response ID 串联轮次时,`compaction_mode="previous_response_id"` 效果最佳。`compaction_mode="input"` 则改为基于当前会话项重建压缩请求;当响应链不可用,或你希望以会话内容为单一事实来源时很有用。默认 `"auto"` 会选择当前可用且最安全的选项。 +当你已经使用 Responses API 响应 ID 串联轮次时,`compaction_mode="previous_response_id"` 效果最佳。`compaction_mode="input"` 则会基于当前会话项重新构建压缩请求,这在响应链不可用,或你希望会话内容作为事实来源时很有用。默认的 `"auto"` 会选择最安全的可用选项。 -如果你的智能体运行使用 `ModelSettings(store=False)`,Responses API 不会保留最后一次响应供后续查找。在这种无状态设置下,默认 `"auto"` 模式会回退为基于输入的压缩,而不是依赖 `previous_response_id`。完整示例见 [`examples/memory/compaction_session_stateless_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/compaction_session_stateless_example.py)。 +如果你的智能体使用 `ModelSettings(store=False)` 运行,Responses API 不会保留最后一次响应用于后续查找。在这种无状态设置中,默认的 `"auto"` 模式会回退为基于输入的压缩,而不是依赖 `previous_response_id`。完整示例请参阅 [`examples/memory/compaction_session_stateless_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/compaction_session_stateless_example.py)。 #### 自动压缩可能阻塞流式传输 -压缩会清空并重写会话历史,因此 SDK 会等待压缩完成后才将运行视为结束。在流式模式下,这意味着若压缩较重,`run.stream_events()` 可能在最后一个输出 token 后仍保持打开数秒。 +压缩会清除并重写会话历史,因此 SDK 会等待压缩完成后才认为运行结束。在流式传输模式下,这意味着如果压缩较重,`run.stream_events()` 可能会在最后一个输出 token 之后继续保持打开数秒。 -如果你希望低延迟流式传输或更快轮转,请禁用自动压缩,并在轮次之间(或空闲时)自行调用 `run_compaction()`。你可以按自己的标准决定何时强制压缩。 +如果你需要低延迟流式传输或快速轮次切换,请禁用自动压缩,并在轮次之间(或空闲时间)自行调用 `run_compaction()`。你可以根据自己的标准决定何时强制压缩。 ```python from agents import Agent, Runner, SQLiteSession @@ -310,7 +311,7 @@ await session.run_compaction({"force": True}) ### SQLite 会话 -默认的轻量级 SQLite 会话实现: +使用 SQLite 的默认轻量级会话实现: ```python from agents import SQLiteSession @@ -331,7 +332,7 @@ result = await Runner.run( ### 异步 SQLite 会话 -当你希望使用由 `aiosqlite` 支持持久化的 SQLite 时,请使用 `AsyncSQLiteSession`。 +当你希望使用由 `aiosqlite` 支持的 SQLite 持久化时,请使用 `AsyncSQLiteSession`。 ```bash pip install aiosqlite @@ -348,7 +349,7 @@ result = await Runner.run(agent, "Hello", session=session) ### Redis 会话 -使用 `RedisSession` 在多个 worker 或服务间共享会话内存。 +使用 `RedisSession` 在多个 worker 或服务之间共享会话记忆。 ```bash pip install openai-agents[redis] @@ -368,7 +369,7 @@ result = await Runner.run(agent, "Hello", session=session) ### SQLAlchemy 会话 -基于任意 SQLAlchemy 支持数据库的生产级 Agents SDK 会话持久化: +使用任何 SQLAlchemy 支持的数据库实现生产就绪的 Agents SDK 会话持久化: ```python from agents.extensions.memory import SQLAlchemySession @@ -386,11 +387,11 @@ engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/db") session = SQLAlchemySession("user_123", engine=engine, create_tables=True) ``` -详见 [SQLAlchemy Sessions](sqlalchemy_session.md) 文档。 +详细文档请参阅 [SQLAlchemy 会话](sqlalchemy_session.md)。 ### Dapr 会话 -当你已经运行 Dapr sidecar,或希望会话存储可在不同状态存储后端间迁移且无需改动智能体代码时,请使用 `DaprSession`。 +当你已经运行 Dapr sidecar,或希望会话存储能够在不同状态存储后端之间迁移且无需更改智能体代码时,请使用 `DaprSession`。 ```bash pip install openai-agents[dapr] @@ -411,18 +412,50 @@ async with DaprSession.from_address( print(result.final_output) ``` -说明: +备注: -- `from_address(...)` 会为你创建并持有 Dapr 客户端。如果你的应用已自行管理客户端,请直接用 `dapr_client=...` 构造 `DaprSession(...)`。 -- 传入 `ttl=...` 可在底层状态存储支持 TTL 时,让其自动过期旧会话数据。 -- 当你需要更强的写后读保证时,传入 `consistency=DAPR_CONSISTENCY_STRONG`。 -- Dapr Python SDK 还会检查 HTTP sidecar 端点。在本地开发中,除 `dapr_address` 使用的 gRPC 端口外,也请使用 `--dapr-http-port 3500` 启动 Dapr。 -- 完整配置流程(含本地组件与故障排查)请见 [`examples/memory/dapr_session_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/dapr_session_example.py)。 +- `from_address(...)` 会为你创建并拥有 Dapr 客户端。如果你的应用已经管理了一个客户端,请直接使用 `DaprSession(...)` 并传入 `dapr_client=...`。 +- 传入 `ttl=...`,可在底层状态存储支持 TTL 时让其自动过期旧会话数据。 +- 当你需要更强的写后读保证时,请传入 `consistency=DAPR_CONSISTENCY_STRONG`。 +- Dapr Python SDK 还会检查 HTTP sidecar 端点。在本地开发中,启动 Dapr 时除 `dapr_address` 使用的 gRPC 端口外,还应包含 `--dapr-http-port 3500`。 +- 完整设置演练(包括本地组件和故障排查)请参阅 [`examples/memory/dapr_session_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/dapr_session_example.py)。 +### MongoDB 会话 + +对于已经使用 MongoDB,或需要可水平扩展、多进程会话存储的应用,请使用 `MongoDBSession`。 + +```bash +pip install openai-agents[mongodb] +``` + +```python +from agents import Agent, Runner +from agents.extensions.memory import MongoDBSession + +agent = Agent(name="Assistant") + +# Create from URI — owns the client and closes it when session.close() is called +session = MongoDBSession.from_uri( + "user-123", + uri="mongodb://localhost:27017", + database="agents", +) +result = await Runner.run(agent, "Hello", session=session) +print(result.final_output) +await session.close() +``` + +备注: + +- `from_uri(...)` 会创建并拥有 `AsyncMongoClient`,并在 `session.close()` 时关闭它。如果你的应用已经管理客户端,请直接使用 `MongoDBSession(...)` 并传入 `client=...`;在这种情况下,`session.close()` 是空操作,生命周期由调用方管理。 +- 通过向 `from_uri(...)` 传入 `mongodb+srv://user:password@cluster.example.mongodb.net` URI(无需其他更改)连接到 [MongoDB Atlas](https://www.mongodb.com/products/platform)。 +- 使用两个集合,并且这两个名称都可以通过 `sessions_collection=`(默认 `agent_sessions`)和 `messages_collection=`(默认 `agent_messages`)配置。索引会在首次使用时自动创建。每条消息文档都带有一个单调递增的 `seq` 计数器,用于在并发写入者和进程之间保持顺序。 +- 在首次运行前,使用 `await session.ping()` 验证连接。 + ### 高级 SQLite 会话 -具备对话分支、用量分析和结构化查询的增强型 SQLite 会话: +增强型 SQLite 会话,支持对话分支、用量分析和结构化查询: ```python from agents.extensions.memory import AdvancedSQLiteSession @@ -442,11 +475,11 @@ await session.store_run_usage(result) # Track token usage await session.create_branch_from_turn(2) # Branch from turn 2 ``` -详见 [Advanced SQLite Sessions](advanced_sqlite_session.md) 文档。 +详细文档请参阅[高级 SQLite 会话](advanced_sqlite_session.md)。 ### 加密会话 -适用于任意会话实现的透明加密封装器: +适用于任何会话实现的透明加密包装器: ```python from agents.extensions.memory import EncryptedSession, SQLAlchemySession @@ -469,11 +502,11 @@ session = EncryptedSession( result = await Runner.run(agent, "Hello", session=session) ``` -详见 [Encrypted Sessions](encrypted_session.md) 文档。 +详细文档请参阅[加密会话](encrypted_session.md)。 ### 其他会话类型 -还有一些额外的内置选项。请参考 `examples/memory/` 以及 `extensions/memory/` 下的源码。 +还有一些其他内置选项。请参考 `examples/memory/` 以及 `extensions/memory/` 下的源代码。 ## 运维模式 @@ -485,19 +518,20 @@ result = await Runner.run(agent, "Hello", session=session) - 基于线程:`"thread_abc123"` - 基于上下文:`"support_ticket_456"` -### 内存持久化 +### 记忆持久化 -- 临时对话使用内存 SQLite(`SQLiteSession("session_id")`) -- 持久对话使用文件 SQLite(`SQLiteSession("session_id", "path/to/db.sqlite")`) +- 对临时对话使用内存 SQLite(`SQLiteSession("session_id")`) +- 对持久对话使用基于文件的 SQLite(`SQLiteSession("session_id", "path/to/db.sqlite")`) - 当你需要基于 `aiosqlite` 的实现时,使用异步 SQLite(`AsyncSQLiteSession("session_id", db_path="...")`) -- 共享、低延迟会话内存使用 Redis 后端会话(`RedisSession.from_url("session_id", url="redis://...")`) -- 对于使用 SQLAlchemy 支持的现有数据库的生产系统,使用 SQLAlchemy 驱动会话(`SQLAlchemySession("session_id", engine=engine, create_tables=True)`) -- 对于云原生生产部署,使用 Dapr 状态存储会话(`DaprSession.from_address("session_id", state_store_name="statestore", dapr_address="localhost:50001")`),可支持 30+ 数据库后端,并提供内置遥测、追踪和数据隔离 -- 若你希望将历史存储在 OpenAI Conversations API 中,使用 OpenAI 托管存储(`OpenAIConversationsSession()`) -- 使用加密会话(`EncryptedSession(session_id, underlying_session, encryption_key)`)可为任意会话添加透明加密和基于 TTL 的过期 -- 对于更高级用例,可考虑为其他生产系统(例如 Django)实现自定义会话后端 +- 使用 Redis 后端会话(`RedisSession.from_url("session_id", url="redis://...")`)实现共享、低延迟的会话记忆 +- 对于使用 SQLAlchemy 支持的现有数据库的生产系统,使用 SQLAlchemy 驱动的会话(`SQLAlchemySession("session_id", engine=engine, create_tables=True)`) +- 对于已经使用 MongoDB 或需要多进程、可水平扩展会话存储的应用,使用 MongoDB 会话(`MongoDBSession.from_uri("session_id", uri="mongodb://localhost:27017")`) +- 对于生产级云原生部署,使用 Dapr 状态存储会话(`DaprSession.from_address("session_id", state_store_name="statestore", dapr_address="localhost:50001")`),支持 30+ 数据库后端,并内置遥测、追踪和数据隔离 +- 当你倾向于将历史记录存储在 OpenAI Conversations API 中时,使用 OpenAI 托管存储(`OpenAIConversationsSession()`) +- 使用加密会话(`EncryptedSession(session_id, underlying_session, encryption_key)`)为任何会话包装透明加密和基于 TTL 的过期 +- 对于更高级的用例,可考虑为其他生产系统(例如 Django)实现自定义会话后端 -### 多会话 +### 多个会话 ```python from agents import Agent, Runner, SQLiteSession @@ -543,7 +577,7 @@ result2 = await Runner.run( ## 完整示例 -以下是一个展示会话内存实际效果的完整示例: +下面是一个展示会话记忆实际工作方式的完整示例: ```python import asyncio @@ -607,7 +641,7 @@ if __name__ == "__main__": ## 自定义会话实现 -你可以通过创建遵循 [`Session`][agents.memory.session.Session] 协议的类来实现自己的会话内存: +你可以创建一个遵循 [`Session`][agents.memory.session.Session] 协议的类,来实现自己的会话记忆: ```python from agents.memory.session import SessionABC @@ -652,9 +686,9 @@ result = await Runner.run( ## 社区会话实现 -社区已开发了额外的会话实现: +社区已经开发了额外的会话实现: -| Package | Description | +| 包 | 描述 | |---------|-------------| | [openai-django-sessions](https://pypi.org/project/openai-django-sessions/) | 基于 Django ORM 的会话,适用于任何 Django 支持的数据库(PostgreSQL、MySQL、SQLite 等) | @@ -662,15 +696,16 @@ result = await Runner.run( ## API 参考 -详细 API 文档见: +有关详细 API 文档,请参阅: - [`Session`][agents.memory.session.Session] - 协议接口 - [`OpenAIConversationsSession`][agents.memory.OpenAIConversationsSession] - OpenAI Conversations API 实现 -- [`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession] - Responses API 压缩封装器 +- [`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession] - Responses API 压缩包装器 - [`SQLiteSession`][agents.memory.sqlite_session.SQLiteSession] - 基础 SQLite 实现 - [`AsyncSQLiteSession`][agents.extensions.memory.async_sqlite_session.AsyncSQLiteSession] - 基于 `aiosqlite` 的异步 SQLite 实现 - [`RedisSession`][agents.extensions.memory.redis_session.RedisSession] - Redis 后端会话实现 -- [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - SQLAlchemy 驱动实现 +- [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - SQLAlchemy 驱动的实现 +- [`MongoDBSession`][agents.extensions.memory.mongodb_session.MongoDBSession] - MongoDB 后端会话实现 - [`DaprSession`][agents.extensions.memory.dapr_session.DaprSession] - Dapr 状态存储实现 -- [`AdvancedSQLiteSession`][agents.extensions.memory.advanced_sqlite_session.AdvancedSQLiteSession] - 带分支和分析功能的增强 SQLite -- [`EncryptedSession`][agents.extensions.memory.encrypt_session.EncryptedSession] - 适用于任意会话的加密封装器 \ No newline at end of file +- [`AdvancedSQLiteSession`][agents.extensions.memory.advanced_sqlite_session.AdvancedSQLiteSession] - 带分支和分析的增强型 SQLite +- [`EncryptedSession`][agents.extensions.memory.encrypt_session.EncryptedSession] - 适用于任何会话的加密包装器 \ No newline at end of file