docs: update config and guardrails pages
This commit is contained in:
Kazuhiro Sera
+23
-2
@@ -12,6 +12,25 @@ If you need to configure a specific agent or run instead, start with:
|
||||
- [Models](models/index.md) for model selection and provider configuration.
|
||||
- [Tracing](tracing.md) for per-run tracing metadata and custom trace processors.
|
||||
|
||||
## Configuration objects and dictionaries
|
||||
|
||||
SDK-owned configuration parameters generally accept either their typed settings object or a dictionary containing the same fields. This applies across agent, run, model, session, sandbox, and voice configuration boundaries whose type annotations include a dictionary. Nested SDK-owned settings can also use dictionaries.
|
||||
|
||||
```python
|
||||
from agents import Agent
|
||||
|
||||
agent = Agent(
|
||||
name="Assistant",
|
||||
model="gpt-5.6-sol",
|
||||
model_settings={
|
||||
"reasoning": {"effort": "high"},
|
||||
"verbosity": "low",
|
||||
},
|
||||
)
|
||||
```
|
||||
|
||||
The SDK normalizes these dictionaries into the corresponding settings objects. Unknown fields in SDK-owned dataclass configurations raise `TypeError`, which helps catch misspelled option names early. Check the parameter's type annotation or API reference to confirm whether a specific boundary accepts a dictionary.
|
||||
|
||||
## API keys and clients
|
||||
|
||||
By default, the SDK uses the `OPENAI_API_KEY` environment variable for LLM requests and tracing. The key is resolved when the SDK first creates an OpenAI client (lazy initialization), so set the environment variable before your first model call. If you are unable to set that environment variable before your app starts, you can use the [set_default_openai_key()][agents.set_default_openai_key] function to set the key.
|
||||
@@ -182,9 +201,9 @@ logger.setLevel(logging.WARNING)
|
||||
logger.addHandler(logging.StreamHandler())
|
||||
```
|
||||
|
||||
### Sensitive data in logs
|
||||
### Sensitive data in logs and diagnostics
|
||||
|
||||
Certain logs may contain sensitive data (for example, user data).
|
||||
Certain logs and diagnostic exceptions may contain sensitive data (for example, model or tool inputs and outputs).
|
||||
|
||||
By default, the SDK does **not** log LLM inputs/outputs or tool inputs/outputs. These protections are controlled by:
|
||||
|
||||
@@ -199,3 +218,5 @@ If you need to include this data temporarily for debugging, set either variable
|
||||
export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=0
|
||||
export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=0
|
||||
```
|
||||
|
||||
These flags also control whether affected failures retain payload-bearing diagnostic details. For example, with tool-data redaction enabled, invalid function-tool arguments raise a generic `ModelBehaviorError` without chaining the underlying validation error. Setting either variable to `0` can expose raw model or tool data in logs, exception messages, exception chains, and other diagnostic context, so enable it only in a controlled development environment.
|
||||
|
||||
+4
-2
@@ -64,9 +64,11 @@ See the code snippet below for details.
|
||||
|
||||
## Tripwires
|
||||
|
||||
If the input or output fails the guardrail, the Guardrail can signal this with a tripwire. As soon as we see a guardrail that has triggered the tripwires, we immediately raise a `{Input,Output}GuardrailTripwireTriggered` exception and halt the Agent execution.
|
||||
If an agent input or output fails a guardrail, the guardrail can signal this with a tripwire. The runner immediately raises an `InputGuardrailTripwireTriggered` or `OutputGuardrailTripwireTriggered` exception and halts agent execution. Tool guardrails use the corresponding `ToolInputGuardrailTripwireTriggered` and `ToolOutputGuardrailTripwireTriggered` exceptions.
|
||||
|
||||
The exception's `guardrail_result` identifies the guardrail that triggered the tripwire. For an input tripwire raised by the runner, `exception.run_data.input_guardrail_results` contains every input guardrail result completed before the run stopped, including the result that triggered the tripwire. Output tripwires provide the equivalent accumulated results through `exception.run_data.output_guardrail_results`. After `stream_events()` raises, the streamed result exposes the same completed results through `input_guardrail_results` or `output_guardrail_results`. `run_data` can be `None` when an exception is raised outside a runner-managed execution path.
|
||||
For agent-level tripwires, the exception's `guardrail_result` identifies the guardrail that triggered the tripwire. For an input tripwire raised by the runner, `exception.run_data.input_guardrail_results` contains every input guardrail result completed before the run stopped, including the result that triggered the tripwire. Output tripwires provide the equivalent accumulated results through `exception.run_data.output_guardrail_results`.
|
||||
|
||||
Tool tripwire exceptions instead expose the triggering `guardrail` and `output` directly. Their `run_data.tool_input_guardrail_results` and `run_data.tool_output_guardrail_results` lists preserve results accumulated from completed turns before the failure; the triggering result is available through the exception's `output`. Other runner-managed failures, such as `MaxTurnsExceeded`, also preserve completed tool guardrail results in these lists. After `stream_events()` raises, the streamed result exposes the same accumulated agent and tool guardrail result lists. `run_data` can be `None` when an exception is raised outside a runner-managed execution path.
|
||||
|
||||
## Implementing a guardrail
|
||||
|
||||
|
||||
@@ -4,15 +4,15 @@ search:
|
||||
---
|
||||
# 高度な SQLite セッション
|
||||
|
||||
`AdvancedSQLiteSession` は基本的な `SQLiteSession` の拡張版であり、会話の分岐、詳細な使用状況分析、構造化された会話クエリなど、高度な会話管理機能を提供します。
|
||||
`AdvancedSQLiteSession` は、基本的な `SQLiteSession` の拡張版であり、会話の分岐、詳細な使用状況分析、構造化された会話クエリなど、高度な会話管理機能を提供します。
|
||||
|
||||
## 機能
|
||||
|
||||
- **会話の分岐**: 任意のユーザーメッセージから別の会話パスを作成します
|
||||
- **使用状況の追跡**: ターンごとの詳細なトークン使用状況分析を、完全な JSON 内訳付きで提供します
|
||||
- **構造化クエリ**: ターン別の会話、ツール使用状況の統計などを取得します
|
||||
- **ブランチ管理**: 独立したブランチ切り替えと管理を行います
|
||||
- **メッセージ構造メタデータ**: メッセージタイプ、ツール使用、会話フローを追跡します
|
||||
- **会話の分岐**: 任意のユーザーメッセージから別の会話経路を作成
|
||||
- **使用状況の追跡**: ターンごとの詳細なトークン使用状況分析と完全な JSON 内訳
|
||||
- **構造化クエリ**: ターン単位の会話、ツール使用状況の統計などを取得
|
||||
- **ブランチ管理**: 独立したブランチの切り替えと管理
|
||||
- **メッセージ構造のメタデータ**: メッセージタイプ、ツールの使用状況、会話フローを追跡
|
||||
|
||||
## クイックスタート
|
||||
|
||||
@@ -84,14 +84,14 @@ session = AdvancedSQLiteSession(
|
||||
|
||||
### パラメーター
|
||||
|
||||
- `session_id` (str): 会話セッションの一意の識別子
|
||||
- `db_path` (str | Path): SQLite データベースファイルへのパス。デフォルトはインメモリストレージ用の `:memory:` です
|
||||
- `session_id` (str): 会話セッションの一意な識別子
|
||||
- `db_path` (str | Path): SQLite データベースファイルへのパス。インメモリストレージの場合、デフォルトは `:memory:` です
|
||||
- `create_tables` (bool): 高度なテーブルを自動的に作成するかどうか。デフォルトは `False` です
|
||||
- `logger` (logging.Logger | None): セッション用のカスタムロガー。デフォルトはモジュールロガーです
|
||||
|
||||
## 使用状況の追跡
|
||||
|
||||
AdvancedSQLiteSession は、会話ターンごとにトークン使用状況データを保存することで、詳細な使用状況分析を提供します。 **これは、各エージェント実行後に `store_run_usage` メソッドが呼び出されることに完全に依存します。**
|
||||
AdvancedSQLiteSession は、会話の各ターンのトークン使用状況データを保存することで、詳細な使用状況分析を提供します。**これは、エージェントの実行後に毎回 `store_run_usage` メソッドが呼び出されることに全面的に依存します。**
|
||||
|
||||
### 使用状況データの保存
|
||||
|
||||
@@ -137,7 +137,7 @@ turn_2_usage = await session.get_turn_usage(user_turn_number=2)
|
||||
|
||||
## 会話の分岐
|
||||
|
||||
AdvancedSQLiteSession の主要機能の 1 つは、任意のユーザーメッセージから会話ブランチを作成し、別の会話パスを探索できることです。
|
||||
AdvancedSQLiteSession の主な機能の 1 つは、任意のユーザーメッセージから会話のブランチを作成し、別の会話経路を探索できることです。
|
||||
|
||||
### ブランチの作成
|
||||
|
||||
@@ -165,6 +165,8 @@ branch_id = await session.create_branch_from_content(
|
||||
)
|
||||
```
|
||||
|
||||
ブランチ ID は、セッション ID の存続期間を通じて一意です。ブランチを削除したりセッションをクリアしたりすると、その会話データは削除されますが、以前使用したブランチ ID が再び使用可能になるわけではありません。別のブランチを作成する際は、新しい名前を使用してください。
|
||||
|
||||
### ブランチ管理
|
||||
|
||||
```python
|
||||
@@ -182,7 +184,7 @@ await session.switch_to_branch(branch_id)
|
||||
await session.delete_branch(branch_id, force=True) # force=True allows deleting current branch
|
||||
```
|
||||
|
||||
### ブランチワークフロー例
|
||||
### ブランチワークフローの例
|
||||
|
||||
```python
|
||||
# Original conversation
|
||||
@@ -245,9 +247,9 @@ for turn in matching_turns:
|
||||
|
||||
### メッセージ構造
|
||||
|
||||
セッションは、次を含むメッセージ構造を自動的に追跡します。
|
||||
セッションは、以下を含むメッセージ構造を自動的に追跡します。
|
||||
|
||||
- メッセージタイプ（ユーザー、assistant、tool_call など）
|
||||
- メッセージタイプ（user、assistant、tool_call など）
|
||||
- ツール呼び出しのツール名
|
||||
- ターン番号とシーケンス番号
|
||||
- ブランチとの関連付け
|
||||
@@ -255,9 +257,9 @@ for turn in matching_turns:
|
||||
|
||||
## データベーススキーマ
|
||||
|
||||
AdvancedSQLiteSession は、基本的な SQLite スキーマを 2 つの追加テーブルで拡張します。
|
||||
AdvancedSQLiteSession は、基本的な SQLite スキーマを 3 つの追加テーブルで拡張します。
|
||||
|
||||
### message_structure テーブル
|
||||
### `message_structure` テーブル
|
||||
|
||||
```sql
|
||||
CREATE TABLE message_structure (
|
||||
@@ -276,7 +278,19 @@ CREATE TABLE message_structure (
|
||||
);
|
||||
```
|
||||
|
||||
### turn_usage テーブル
|
||||
### `branch_reservations` テーブル
|
||||
|
||||
```sql
|
||||
CREATE TABLE branch_reservations (
|
||||
session_id TEXT NOT NULL,
|
||||
branch_id TEXT NOT NULL,
|
||||
PRIMARY KEY (session_id, branch_id)
|
||||
);
|
||||
```
|
||||
|
||||
このテーブルは、コピーされた接頭部分が空のブランチを含め、ブランチ ID をアトミックに予約します。予約行はブランチの削除後やセッションのクリア後も保持されるため、古いセッションインスタンスが、同じ ID を再利用した後続のブランチに履歴をマージすることはありません。
|
||||
|
||||
### `turn_usage` テーブル
|
||||
|
||||
```sql
|
||||
CREATE TABLE turn_usage (
|
||||
@@ -298,10 +312,10 @@ CREATE TABLE turn_usage (
|
||||
|
||||
## 完全な例
|
||||
|
||||
すべての機能を包括的に示す [完全な例](https://github.com/openai/openai-agents-python/tree/main/examples/memory/advanced_sqlite_session_example.py) を確認してください。
|
||||
すべての機能を包括的に紹介する[完全な例](https://github.com/openai/openai-agents-python/tree/main/examples/memory/advanced_sqlite_session_example.py)をご確認ください。
|
||||
|
||||
|
||||
## API リファレンス
|
||||
|
||||
- [`AdvancedSQLiteSession`][agents.extensions.memory.advanced_sqlite_session.AdvancedSQLiteSession] - メインクラス
|
||||
- [`Session`][agents.memory.session.Session] - ベースセッションプロトコル
|
||||
- [`Session`][agents.memory.session.Session] - 基本セッションプロトコル
|
||||
+62
-62
@@ -6,9 +6,9 @@ search:
|
||||
|
||||
Agents SDK には、複数回のエージェント実行にわたって会話履歴を自動的に維持する組み込みのセッションメモリが用意されているため、ターン間で `.to_input_list()` を手動で処理する必要がありません。
|
||||
|
||||
セッションは特定のセッションの会話履歴を保存し、明示的な手動メモリ管理を必要とせずに、エージェントがコンテキストを維持できるようにします。これは、エージェントに以前のやり取りを記憶させたいチャットアプリケーションや複数ターンの会話を構築する場合に特に便利です。
|
||||
セッションは特定のセッションの会話履歴を保存し、明示的な手動のメモリ管理を必要とせずに、エージェントがコンテキストを維持できるようにします。これは、エージェントに以前のやり取りを記憶させたいチャットアプリケーションや、複数ターンの会話を構築する場合に特に便利です。
|
||||
|
||||
SDK にクライアント側のメモリを管理させたい場合は、セッションを使用してください。同じ実行内で、セッションを `conversation_id`、`previous_response_id`、または `auto_previous_response_id` と組み合わせることはできません。代わりに OpenAI サーバーが管理する継続機能を使用する場合は、セッションと重ねて使用せず、これらのメカニズムのいずれかを選択してください。
|
||||
SDK にクライアント側のメモリを管理させたい場合は、セッションを使用します。同じ実行内でセッションを `conversation_id`、`previous_response_id`、または `auto_previous_response_id` と組み合わせることはできません。代わりに OpenAI のサーバーで管理される継続機能を使用したい場合は、セッションと重ねて使用せず、これらの仕組みのいずれかを選択してください。
|
||||
|
||||
## クイックスタート
|
||||
|
||||
@@ -51,7 +51,7 @@ print(result.final_output) # "Approximately 39 million"
|
||||
|
||||
## 同じセッションによる中断された実行の再開
|
||||
|
||||
承認待ちで実行が一時停止した場合は、再開されたターンが同じ保存済み会話履歴を継続できるように、同じセッションインスタンス、または同じバッキングストアを指す別のセッションインスタンスを使用して再開してください。
|
||||
実行が承認待ちで一時停止した場合は、同じセッションインスタンス（または同じバックエンドストアを参照する別のセッションインスタンス）を使用して再開し、再開後のターンが保存済みの同じ会話履歴を引き継ぐようにしてください。
|
||||
|
||||
```python
|
||||
result = await Runner.run(agent, "Delete temporary files that are no longer needed.", session=session)
|
||||
@@ -67,27 +67,27 @@ if result.interruptions:
|
||||
|
||||
セッションメモリが有効な場合、次のように動作します。
|
||||
|
||||
1. **各実行の前**: Runner はセッションの会話履歴を自動的に取得し、入力項目の先頭に追加します。
|
||||
2. **各実行の後**: 実行中に生成されたすべての新しい項目（ユーザー入力、アシスタントの応答、ツール呼び出しなど）が、セッションに自動的に保存されます。
|
||||
1. **各実行前**: ランナーはセッションの会話履歴を自動的に取得し、入力項目の先頭に追加します。
|
||||
2. **各実行後**: 実行中に生成されたすべての新しい項目（ユーザー入力、アシスタントの応答、ツール呼び出しなど）がセッションに自動的に保存されます。
|
||||
3. **コンテキストの保持**: 同じセッションを使用する後続の各実行には完全な会話履歴が含まれるため、エージェントはコンテキストを維持できます。
|
||||
|
||||
これにより、`.to_input_list()` を手動で呼び出し、実行間の会話状態を管理する必要がなくなります。
|
||||
|
||||
## 履歴と新規入力のマージ制御
|
||||
## 履歴と新しい入力のマージ制御
|
||||
|
||||
セッションを渡すと、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`: 現在のターンの新しい入力項目
|
||||
|
||||
モデルに送信する最終的な入力項目のリストを返してください。
|
||||
モデルに送信する入力項目の最終的なリストを返してください。
|
||||
|
||||
コールバックは両方のリストのコピーを受け取るため、安全に変更できます。返されたリストはそのターンのモデル入力を制御しますが、SDK が永続化するのは新しいターンに属する項目のみです。そのため、古い履歴を並べ替えたりフィルタリングしたりしても、古いセッション項目が新しい入力として再度保存されることはありません。
|
||||
コールバックは両方のリストのコピーを受け取るため、安全に変更できます。返されたリストによってそのターンのモデル入力が決まりますが、SDK が永続化するのは新しいターンに属する項目だけです。したがって、古い履歴を並べ替えたりフィルタリングしたりしても、古いセッション項目が新しい入力として再び保存されることはありません。
|
||||
|
||||
```python
|
||||
from agents import Agent, RunConfig, Runner, SQLiteSession
|
||||
@@ -109,7 +109,7 @@ 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] を使用してください。
|
||||
|
||||
## 取得する履歴の制限
|
||||
|
||||
@@ -134,13 +134,13 @@ result = await Runner.run(
|
||||
)
|
||||
```
|
||||
|
||||
セッション実装がデフォルトのセッション設定を公開している場合、`RunConfig.session_settings` はその実行について、`None` 以外の値を上書きします。これは、セッションのデフォルト動作を変更せずに取得件数を制限したい長い会話で役立ちます。
|
||||
セッション実装がデフォルトのセッション設定を公開している場合、`RunConfig.session_settings` はその実行について、`None` ではない値を上書きします。これは、セッションのデフォルト動作を変更せずに取得サイズを制限したい長い会話で便利です。
|
||||
|
||||
## メモリ操作
|
||||
|
||||
### 基本操作
|
||||
|
||||
セッションでは、会話履歴を管理するための複数の操作を使用できます。
|
||||
セッションでは、会話履歴を管理するために複数の操作を使用できます。
|
||||
|
||||
```python
|
||||
from agents import SQLiteSession
|
||||
@@ -165,7 +165,7 @@ print(last_item) # {"role": "assistant", "content": "Hi there!"}
|
||||
await session.clear_session()
|
||||
```
|
||||
|
||||
### 修正での pop_item の使用
|
||||
### `pop_item` を使用した修正
|
||||
|
||||
`pop_item` メソッドは、会話の最後の項目を取り消したり変更したりする場合に特に便利です。
|
||||
|
||||
@@ -206,20 +206,20 @@ SDK には、さまざまなユースケースに対応する複数のセッシ
|
||||
|
||||
| セッションタイプ | 最適な用途 | 備考 |
|
||||
| --- | --- | --- |
|
||||
| `SQLiteSession` | ローカル開発とシンプルなアプリ | 組み込みで軽量、ファイルベースまたはインメモリ |
|
||||
| `SQLiteSession` | ローカル開発とシンプルなアプリ | 組み込みで軽量。ファイルベースまたはインメモリ |
|
||||
| `AsyncSQLiteSession` | `aiosqlite` を使用する非同期 SQLite | 非同期ドライバーをサポートする拡張バックエンド |
|
||||
| `RedisSession` | ワーカーやサービス間での共有メモリ | 低レイテンシーの分散デプロイに適しています |
|
||||
| `SQLAlchemySession` | 既存のデータベースを使用する本番アプリ | SQLAlchemy がサポートするデータベースで動作します |
|
||||
| `RedisSession` | ワーカーやサービス間の共有メモリ | 低レイテンシーの分散デプロイに最適 |
|
||||
| `SQLAlchemySession` | 既存のデータベースを使用する本番アプリ | SQLAlchemy がサポートするデータベースに対応 |
|
||||
| `MongoDBSession` | MongoDB をすでに使用しているアプリ、またはマルチプロセスストレージが必要なアプリ | 非同期 pymongo。順序付け用のアトミックなシーケンスカウンター |
|
||||
| `DaprSession` | Dapr サイドカーを使用するクラウドネイティブなデプロイ | 複数のステートストアに加え、TTL と整合性制御をサポートします |
|
||||
| `OpenAIConversationsSession` | OpenAI でのサーバー管理ストレージ | OpenAI Conversations API を利用した履歴 |
|
||||
| `OpenAIResponsesCompactionSession` | 自動コンパクションを使用する長い会話 | 別のセッションバックエンドをラップします |
|
||||
| `AdvancedSQLiteSession` | SQLite に加えて分岐や分析が必要な場合 | より多機能です。専用ページを参照してください |
|
||||
| `EncryptedSession` | 別のセッションに暗号化と TTL を追加する場合 | ラッパーです。まず基盤となるバックエンドを選択してください |
|
||||
| `DaprSession` | Dapr サイドカーを使用するクラウドネイティブなデプロイ | 複数の状態ストアに加え、TTL と整合性の制御をサポート |
|
||||
| `OpenAIConversationsSession` | OpenAI でのサーバー管理ストレージ | OpenAI Conversations API をバックエンドとする履歴 |
|
||||
| `OpenAIResponsesCompactionSession` | 自動圧縮を伴う長い会話 | 別のセッションバックエンドをラップ |
|
||||
| `AdvancedSQLiteSession` | SQLite に加えて分岐や分析が必要な場合 | より高度な機能セット。専用ページを参照 |
|
||||
| `EncryptedSession` | 別のセッションに追加する暗号化と TTL | ラッパー。最初に基盤となるバックエンドを選択 |
|
||||
|
||||
一部の実装には追加の詳細を説明する専用ページがあり、それぞれのサブセクション内にリンクがあります。
|
||||
一部の実装には、追加の詳細を記載した専用ページがあります。それぞれのサブセクション内にリンクがあります。
|
||||
|
||||
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)を参照してください。
|
||||
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 セッション
|
||||
|
||||
@@ -257,11 +257,11 @@ result = await Runner.run(
|
||||
print(result.final_output) # "California"
|
||||
```
|
||||
|
||||
### OpenAI Responses コンパクションセッション
|
||||
### OpenAI Responses 圧縮セッション
|
||||
|
||||
Responses API（`responses.compact`）を使用して保存済みの会話履歴を圧縮するには、`OpenAIResponsesCompactionSession` を使用します。これは基盤となるセッションをラップし、`should_trigger_compaction` に基づいて各ターンの後に自動的にコンパクションを実行できます。`OpenAIConversationsSession` をこれでラップしないでください。この 2 つの機能は異なる方法で履歴を管理します。
|
||||
Responses API（`responses.compact`）を使用して保存済みの会話履歴を圧縮するには、`OpenAIResponsesCompactionSession` を使用します。これは基盤となるセッションをラップし、`should_trigger_compaction` に基づいて各ターン後に自動圧縮できます。`OpenAIConversationsSession` をラップしないでください。この 2 つの機能は異なる方法で履歴を管理します。
|
||||
|
||||
#### 一般的な使用方法（自動コンパクション）
|
||||
#### 典型的な使用方法（自動圧縮）
|
||||
|
||||
```python
|
||||
from agents import Agent, Runner, SQLiteSession
|
||||
@@ -278,17 +278,17 @@ result = await Runner.run(agent, "Hello", session=session)
|
||||
print(result.final_output)
|
||||
```
|
||||
|
||||
デフォルトでは、候補のしきい値に達すると、各ターンの後にコンパクションが実行されます。
|
||||
デフォルトでは、候補のしきい値に達すると、各ターン後に圧縮が実行されます。
|
||||
|
||||
Responses API のレスポンス 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()` が数秒間開いたままになることがあります。
|
||||
圧縮はセッション履歴を消去して書き換えるため、SDK は圧縮が完了するまで実行を完了と見なしません。ストリーミングモードでは、圧縮処理が重い場合、最後の出力トークンの後も `run.stream_events()` が数秒間開いたままになることがあります。
|
||||
|
||||
低レイテンシーのストリーミングやターンの迅速な切り替えが必要な場合は、自動コンパクションを無効にし、ターン間またはアイドル時間中に `run_compaction()` を自分で呼び出してください。独自の基準に基づいて、コンパクションを強制するタイミングを決定できます。
|
||||
低レイテンシーのストリーミングや素早いターン移行が必要な場合は、自動圧縮を無効にし、ターン間またはアイドル時に `run_compaction()` を自分で呼び出してください。独自の基準に基づいて、圧縮を強制するタイミングを決定できます。
|
||||
|
||||
```python
|
||||
from agents import Agent, Runner, SQLiteSession
|
||||
@@ -311,7 +311,7 @@ await session.run_compaction({"force": True})
|
||||
|
||||
### SQLite セッション
|
||||
|
||||
SQLite を使用するデフォルトの軽量セッション実装です。
|
||||
SQLite を使用する、デフォルトの軽量なセッション実装です。
|
||||
|
||||
```python
|
||||
from agents import SQLiteSession
|
||||
@@ -332,7 +332,7 @@ result = await Runner.run(
|
||||
|
||||
### 非同期 SQLite セッション
|
||||
|
||||
`aiosqlite` を基盤とする SQLite 永続化が必要な場合は、`AsyncSQLiteSession` を使用します。
|
||||
`aiosqlite` をバックエンドとする SQLite 永続化が必要な場合は、`AsyncSQLiteSession` を使用します。
|
||||
|
||||
```bash
|
||||
pip install aiosqlite
|
||||
@@ -349,7 +349,7 @@ result = await Runner.run(agent, "Hello", session=session)
|
||||
|
||||
### Redis セッション
|
||||
|
||||
複数のワーカーまたはサービス間でセッションメモリを共有するには、`RedisSession` を使用します。
|
||||
複数のワーカーやサービス間でセッションメモリを共有するには、`RedisSession` を使用します。
|
||||
|
||||
```bash
|
||||
pip install openai-agents[redis]
|
||||
@@ -368,11 +368,11 @@ result = await Runner.run(agent, "Hello", session=session)
|
||||
await session.close()
|
||||
```
|
||||
|
||||
`from_url(...)` は Redis クライアントを作成して所有します。`close()` の後、セッションは終了状態になり、それ以降のセッション操作では `RuntimeError` が発生します。`close()` を繰り返し、または同時に呼び出しても安全です。アプリケーションがすでに Redis クライアントを管理している場合は、`redis_client=...` を指定して `RedisSession(...)` を直接構築してください。その場合、`close()` は何も行わず、呼び出し元がクライアントの所有権とセッションの利用可能性の両方を維持します。
|
||||
`from_url(...)` は Redis クライアントを作成して所有します。`close()` の後、セッションは終了状態となり、後続のセッション操作では `RuntimeError` が発生します。`close()` を繰り返し呼び出したり、同時に呼び出したりしても安全です。アプリケーションがすでに Redis クライアントを管理している場合は、`redis_client=...` を指定して `RedisSession(...)` を直接構築してください。その場合、`close()` は何も行わず、呼び出し元がクライアントの所有権を保持し、セッションも引き続き利用できます。
|
||||
|
||||
### SQLAlchemy セッション
|
||||
|
||||
SQLAlchemy がサポートする任意のデータベースを使用した、本番環境向けの Agents SDK セッション永続化です。
|
||||
SQLAlchemy がサポートする任意のデータベースを使用する、本番環境対応の Agents SDK セッション永続化です。
|
||||
|
||||
```python
|
||||
from agents.extensions.memory import SQLAlchemySession
|
||||
@@ -394,7 +394,7 @@ session = SQLAlchemySession("user_123", engine=engine, create_tables=True)
|
||||
|
||||
### Dapr セッション
|
||||
|
||||
Dapr サイドカーをすでに実行している場合、またはエージェントコードを変更せずに異なるステートストアバックエンド間で移行できるセッションストレージが必要な場合は、`DaprSession` を使用します。
|
||||
すでに Dapr サイドカーを実行している場合や、エージェントコードを変更せずに異なる状態ストアのバックエンド間で移行できるセッションストレージが必要な場合は、`DaprSession` を使用します。
|
||||
|
||||
```bash
|
||||
pip install openai-agents[dapr]
|
||||
@@ -415,19 +415,19 @@ async with DaprSession.from_address(
|
||||
print(result.final_output)
|
||||
```
|
||||
|
||||
注意事項:
|
||||
注記:
|
||||
|
||||
- `from_address(...)` は Dapr クライアントを作成して所有します。アプリがすでにクライアントを管理している場合は、`dapr_client=...` を指定して `DaprSession(...)` を直接構築してください。
|
||||
- コンテキストを終了するか `close()` を呼び出すと、所有クライアントを使用するセッションは終了状態になります。それ以降のセッション操作では `RuntimeError` が発生しますが、`close()` を繰り返し、または同時に呼び出しても安全です。注入されたクライアントを使用する場合、`close()` は何も行わず、セッションは引き続き使用できます。
|
||||
- バッキングステートストアが TTL をサポートしている場合、古いセッションデータを自動的に期限切れにするには `ttl=...` を渡します。
|
||||
- 書き込み後の読み取りについて、より強い保証が必要な場合は `consistency=DAPR_CONSISTENCY_STRONG` を渡します。
|
||||
- コンテキストを終了するか `close()` を呼び出すと、所有クライアントを使用するセッションは終了状態になります。後続のセッション操作では `RuntimeError` が発生しますが、`close()` を繰り返し呼び出したり、同時に呼び出したりしても安全です。注入されたクライアントを使用する場合、`close()` は何も行わず、セッションは引き続き利用できます。
|
||||
- バックエンドの状態ストアが 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` を使用します。
|
||||
MongoDB をすでに使用しているアプリケーションや、水平スケーリング可能なマルチプロセスのセッションストレージが必要な場合は、`MongoDBSession` を使用します。
|
||||
|
||||
```bash
|
||||
pip install openai-agents[mongodb]
|
||||
@@ -450,16 +450,16 @@ print(result.final_output)
|
||||
await session.close()
|
||||
```
|
||||
|
||||
注意事項:
|
||||
注記:
|
||||
|
||||
- `from_uri(...)` は `AsyncMongoClient` を作成して所有し、`session.close()` で閉じます。アプリケーションがすでにクライアントを管理している場合は、`client=...` を指定して `MongoDBSession(...)` を直接構築してください。その場合、`session.close()` は何も行わず、ライフサイクルの管理は呼び出し元が引き続き行います。
|
||||
- `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` カウンターが含まれ、同時に書き込む複数のライターやプロセス間でも順序が保持されます。
|
||||
- `from_uri(...)` は `AsyncMongoClient` を作成して所有し、`session.close()` で閉じます。所有クライアントを使用するセッションは `close()` 後に終了状態となり、後続のセッション操作では `RuntimeError` が発生します。アプリケーションがすでにクライアントを管理している場合は、`client=...` を指定して `MongoDBSession(...)` を直接構築してください。その場合、`session.close()` は何も行わず、ライフサイクルとセッションの利用可否は呼び出し元が管理します。
|
||||
- ほかに変更を加えることなく、`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()` を使用します。
|
||||
|
||||
### 高度な SQLite セッション
|
||||
|
||||
会話の分岐、使用状況分析、構造化クエリを備えた拡張 SQLite セッションです。
|
||||
会話の分岐、使用状況分析、構造化クエリに対応した拡張 SQLite セッションです。
|
||||
|
||||
```python
|
||||
from agents.extensions.memory import AdvancedSQLiteSession
|
||||
@@ -483,7 +483,7 @@ await session.create_branch_from_turn(2) # Branch from turn 2
|
||||
|
||||
### 暗号化セッション
|
||||
|
||||
任意のセッション実装に対する透過的な暗号化ラッパーです。
|
||||
任意のセッション実装に対応する透過的な暗号化ラッパーです。
|
||||
|
||||
```python
|
||||
from agents.extensions.memory import EncryptedSession, SQLAlchemySession
|
||||
@@ -527,12 +527,12 @@ 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://...")`）を使用します
|
||||
- 共有可能で低レイテンシーのセッションメモリには、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")`）を使用します
|
||||
- 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)`）を使用します
|
||||
- 任意のセッションを透過的な暗号化と TTL ベースの期限切れ機能でラップするには、暗号化セッション（`EncryptedSession(session_id, underlying_session, encryption_key)`）を使用します
|
||||
- より高度なユースケースでは、ほかの本番システム（Django など）向けのカスタムセッションバックエンドの実装を検討してください
|
||||
|
||||
### 複数のセッション
|
||||
@@ -581,7 +581,7 @@ result2 = await Runner.run(
|
||||
|
||||
## 完全な例
|
||||
|
||||
セッションメモリの動作を示す完全な例を以下に示します。
|
||||
セッションメモリの実際の動作を示す完全な例を次に示します。
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
@@ -645,7 +645,7 @@ if __name__ == "__main__":
|
||||
|
||||
## カスタムセッション実装
|
||||
|
||||
[`Session`][agents.memory.session.Session] プロトコルに準拠するクラスを作成することで、独自のセッションメモリを実装できます。
|
||||
[`Session`][agents.memory.session.Session] プロトコルに従うクラスを作成することで、独自のセッションメモリを実装できます。
|
||||
|
||||
```python
|
||||
from agents.memory.session import SessionABC
|
||||
@@ -704,12 +704,12 @@ result = await Runner.run(
|
||||
|
||||
- [`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 ベースのセッション実装
|
||||
- [`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] - 任意のセッション向けの暗号化ラッパー
|
||||
- [`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] - 任意のセッションに対応する暗号化ラッパー
|
||||
@@ -4,14 +4,14 @@ search:
|
||||
---
|
||||
# 고급 SQLite 세션
|
||||
|
||||
`AdvancedSQLiteSession`은 기본 `SQLiteSession`의 향상된 버전으로, 대화 분기, 상세 사용량 분석, 구조화된 대화 쿼리 등 고급 대화 관리 기능을 제공합니다.
|
||||
`AdvancedSQLiteSession`은 기본 `SQLiteSession`을 개선한 버전으로, 대화 브랜칭, 상세한 사용량 분석, 구조화된 대화 쿼리 등 고급 대화 관리 기능을 제공합니다.
|
||||
|
||||
## 기능
|
||||
|
||||
- **대화 분기**: 모든 사용자 메시지에서 대체 대화 경로를 생성
|
||||
- **사용량 추적**: 전체 JSON 세부 내역과 함께 턴별 상세 토큰 사용량 분석
|
||||
- **구조화된 쿼리**: 턴별 대화, 도구 사용 통계 등을 조회
|
||||
- **분기 관리**: 독립적인 분기 전환 및 관리
|
||||
- **대화 브랜칭**: 모든 사용자 메시지에서 대체 대화 경로 생성
|
||||
- **사용량 추적**: 전체 JSON 세부 내역을 포함한 턴별 상세 토큰 사용량 분석
|
||||
- **구조화된 쿼리**: 턴별 대화, 도구 사용 통계 등 조회
|
||||
- **브랜치 관리**: 독립적인 브랜치 전환 및 관리
|
||||
- **메시지 구조 메타데이터**: 메시지 유형, 도구 사용, 대화 흐름 추적
|
||||
|
||||
## 빠른 시작
|
||||
@@ -87,11 +87,11 @@ session = AdvancedSQLiteSession(
|
||||
- `session_id` (str): 대화 세션의 고유 식별자
|
||||
- `db_path` (str | Path): SQLite 데이터베이스 파일 경로. 인메모리 저장소의 경우 기본값은 `:memory:`
|
||||
- `create_tables` (bool): 고급 테이블을 자동으로 생성할지 여부. 기본값은 `False`
|
||||
- `logger` (logging.Logger | None): 세션용 사용자 지정 로거. 기본값은 모듈 로거
|
||||
- `logger` (logging.Logger | None): 세션의 사용자 지정 로거. 기본값은 모듈 로거
|
||||
|
||||
## 사용량 추적
|
||||
|
||||
AdvancedSQLiteSession은 대화 턴별 토큰 사용량 데이터를 저장하여 상세한 사용량 분석을 제공합니다. **이는 각 에이전트 실행 후 `store_run_usage` 메서드가 호출되는지에 전적으로 의존합니다.**
|
||||
AdvancedSQLiteSession은 대화 턴별 토큰 사용량 데이터를 저장하여 상세한 사용량 분석을 제공합니다. **이 기능은 각 에이전트 실행 후 `store_run_usage` 메서드를 호출하는지 여부에 전적으로 달려 있습니다.**
|
||||
|
||||
### 사용량 데이터 저장
|
||||
|
||||
@@ -135,11 +135,11 @@ for turn_data in turn_usage:
|
||||
turn_2_usage = await session.get_turn_usage(user_turn_number=2)
|
||||
```
|
||||
|
||||
## 대화 분기
|
||||
## 대화 브랜칭
|
||||
|
||||
AdvancedSQLiteSession의 핵심 기능 중 하나는 모든 사용자 메시지에서 대화 분기를 생성하여 대체 대화 경로를 탐색할 수 있는 기능입니다.
|
||||
AdvancedSQLiteSession의 주요 기능 중 하나는 모든 사용자 메시지에서 대화 브랜치를 생성하여 대체 대화 경로를 탐색할 수 있다는 점입니다.
|
||||
|
||||
### 분기 생성
|
||||
### 브랜치 생성
|
||||
|
||||
```python
|
||||
# Get available turns for branching
|
||||
@@ -165,7 +165,9 @@ branch_id = await session.create_branch_from_content(
|
||||
)
|
||||
```
|
||||
|
||||
### 분기 관리
|
||||
브랜치 ID는 세션 ID의 수명 동안 고유합니다. 브랜치를 삭제하거나 세션을 지우면 해당 대화 데이터는 제거되지만, 이전에 사용한 브랜치 ID를 다시 사용할 수 있는 것은 아닙니다. 다른 브랜치를 생성할 때는 새로운 이름을 사용하세요.
|
||||
|
||||
### 브랜치 관리
|
||||
|
||||
```python
|
||||
# List all branches
|
||||
@@ -182,7 +184,7 @@ await session.switch_to_branch(branch_id)
|
||||
await session.delete_branch(branch_id, force=True) # force=True allows deleting current branch
|
||||
```
|
||||
|
||||
### 분기 워크플로 예제
|
||||
### 브랜치 워크플로 예제
|
||||
|
||||
```python
|
||||
# Original conversation
|
||||
@@ -217,7 +219,7 @@ await session.store_run_usage(result)
|
||||
|
||||
## 구조화된 쿼리
|
||||
|
||||
AdvancedSQLiteSession은 대화 구조와 내용을 분석하기 위한 여러 메서드를 제공합니다.
|
||||
AdvancedSQLiteSession은 대화 구조와 콘텐츠를 분석하기 위한 여러 메서드를 제공합니다.
|
||||
|
||||
### 대화 분석
|
||||
|
||||
@@ -247,17 +249,17 @@ for turn in matching_turns:
|
||||
|
||||
세션은 다음을 포함한 메시지 구조를 자동으로 추적합니다.
|
||||
|
||||
- 메시지 유형(사용자, 어시스턴트, tool_call 등)
|
||||
- 도구 호출의 도구 이름
|
||||
- 메시지 유형(사용자, 어시스턴트, `tool_call` 등)
|
||||
- 도구 호출에 사용된 도구 이름
|
||||
- 턴 번호 및 시퀀스 번호
|
||||
- 분기 연결
|
||||
- 브랜치 연결 관계
|
||||
- 타임스탬프
|
||||
|
||||
## 데이터베이스 스키마
|
||||
|
||||
AdvancedSQLiteSession은 두 개의 추가 테이블로 기본 SQLite 스키마를 확장합니다.
|
||||
AdvancedSQLiteSession은 세 개의 테이블을 추가하여 기본 SQLite 스키마를 확장합니다.
|
||||
|
||||
### message_structure 테이블
|
||||
### `message_structure` 테이블
|
||||
|
||||
```sql
|
||||
CREATE TABLE message_structure (
|
||||
@@ -276,7 +278,19 @@ CREATE TABLE message_structure (
|
||||
);
|
||||
```
|
||||
|
||||
### turn_usage 테이블
|
||||
### `branch_reservations` 테이블
|
||||
|
||||
```sql
|
||||
CREATE TABLE branch_reservations (
|
||||
session_id TEXT NOT NULL,
|
||||
branch_id TEXT NOT NULL,
|
||||
PRIMARY KEY (session_id, branch_id)
|
||||
);
|
||||
```
|
||||
|
||||
이 테이블은 복사된 접두사가 비어 있는 브랜치를 포함하여 브랜치 ID를 원자적으로 예약합니다. 브랜치를 삭제하거나 세션을 지운 후에도 예약 행이 유지되므로, 오래된 세션 인스턴스가 동일한 ID를 재사용한 이후의 브랜치에 기록을 병합할 수 없습니다.
|
||||
|
||||
### `turn_usage` 테이블
|
||||
|
||||
```sql
|
||||
CREATE TABLE turn_usage (
|
||||
@@ -298,10 +312,10 @@ CREATE TABLE turn_usage (
|
||||
|
||||
## 전체 예제
|
||||
|
||||
모든 기능을 종합적으로 보여 주는 [전체 예제](https://github.com/openai/openai-agents-python/tree/main/examples/memory/advanced_sqlite_session_example.py)를 확인하세요.
|
||||
모든 기능을 종합적으로 살펴보려면 [전체 예제](https://github.com/openai/openai-agents-python/tree/main/examples/memory/advanced_sqlite_session_example.py)를 확인하세요.
|
||||
|
||||
|
||||
## API 참조
|
||||
## API 레퍼런스
|
||||
|
||||
- [`AdvancedSQLiteSession`][agents.extensions.memory.advanced_sqlite_session.AdvancedSQLiteSession] - 메인 클래스
|
||||
- [`AdvancedSQLiteSession`][agents.extensions.memory.advanced_sqlite_session.AdvancedSQLiteSession] - 기본 클래스
|
||||
- [`Session`][agents.memory.session.Session] - 기본 세션 프로토콜
|
||||
+74
-74
@@ -4,11 +4,11 @@ search:
|
||||
---
|
||||
# 세션
|
||||
|
||||
Agents SDK는 여러 에이전트 실행에 걸쳐 대화 기록을 자동으로 유지하는 내장 세션 메모리를 제공하므로, 턴 사이에 `.to_input_list()`를 수동으로 처리할 필요가 없습니다.
|
||||
Agents SDK는 여러 에이전트 실행에 걸쳐 대화 기록을 자동으로 유지하는 기본 제공 세션 메모리를 지원하므로, 턴 사이에 `.to_input_list()`를 수동으로 처리할 필요가 없습니다.
|
||||
|
||||
세션은 특정 세션의 대화 기록을 저장하여, 명시적으로 메모리를 직접 관리하지 않아도 에이전트가 컨텍스트를 유지할 수 있게 합니다. 이는 에이전트가 이전 상호작용을 기억해야 하는 채팅 애플리케이션이나 멀티턴 대화를 구축할 때 특히 유용합니다.
|
||||
세션은 특정 세션의 대화 기록을 저장하므로, 명시적인 수동 메모리 관리 없이도 에이전트가 컨텍스트를 유지할 수 있습니다. 이는 에이전트가 이전 상호작용을 기억해야 하는 채팅 애플리케이션이나 멀티턴 대화를 구축할 때 특히 유용합니다.
|
||||
|
||||
SDK가 클라이언트 측 메모리를 관리하도록 하려면 세션을 사용하세요. 동일한 실행에서 세션을 `conversation_id`, `previous_response_id` 또는 `auto_previous_response_id`와 함께 사용할 수 없습니다. OpenAI 서버에서 관리하는 대화 연속성을 사용하려면 세션을 추가로 적용하지 말고 이러한 메커니즘 중 하나를 선택하세요.
|
||||
SDK가 클라이언트 측 메모리를 관리하도록 하려면 세션을 사용하세요. 동일한 실행에서 세션을 `conversation_id`, `previous_response_id` 또는 `auto_previous_response_id`와 함께 사용할 수 없습니다. 대신 OpenAI 서버가 관리하는 연속 실행을 원한다면 세션을 추가로 계층화하지 말고 이러한 메커니즘 중 하나를 선택하세요.
|
||||
|
||||
## 빠른 시작
|
||||
|
||||
@@ -51,7 +51,7 @@ 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. **컨텍스트 보존**: 동일한 세션을 사용하는 이후의 각 실행에는 전체 대화 기록이 포함되므로 에이전트가 컨텍스트를 유지할 수 있습니다.
|
||||
3. **컨텍스트 유지**: 동일한 세션을 사용하는 이후의 각 실행에는 전체 대화 기록이 포함되므로 에이전트가 컨텍스트를 유지할 수 있습니다.
|
||||
|
||||
따라서 `.to_input_list()`를 수동으로 호출하고 실행 사이의 대화 상태를 관리할 필요가 없습니다.
|
||||
따라서 `.to_input_list()`를 수동으로 호출하거나 실행 사이의 대화 상태를 직접 관리할 필요가 없습니다.
|
||||
|
||||
## 기록과 새 입력의 병합 방식 제어
|
||||
|
||||
세션을 전달하면 일반적으로 러너는 다음 순서로 모델 입력을 준비합니다.
|
||||
세션을 전달하면 러너는 일반적으로 다음 순서로 모델 입력을 준비합니다.
|
||||
|
||||
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`: 가져온 세션 기록(이미 입력 항목 형식으로 정규화됨)
|
||||
- `new_input`: 현재 턴의 새 입력 항목
|
||||
|
||||
모델로 전송할 최종 입력 항목 목록을 반환하세요.
|
||||
|
||||
콜백은 두 목록의 복사본을 받으므로 안전하게 변경할 수 있습니다. 반환된 목록은 해당 턴의 모델 입력을 제어하지만, SDK는 여전히 새 턴에 속하는 항목만 저장합니다. 따라서 이전 기록을 재정렬하거나 필터링해도 기존 세션 항목이 새로운 입력으로 다시 저장되지 않습니다.
|
||||
콜백은 두 목록의 복사본을 받으므로 안전하게 변경할 수 있습니다. 반환된 목록은 해당 턴의 모델 입력을 제어하지만, SDK는 여전히 새 턴에 속한 항목만 저장합니다. 따라서 이전 기록의 순서를 바꾸거나 필터링해도 이전 세션 항목이 새로운 입력으로 다시 저장되지 않습니다.
|
||||
|
||||
```python
|
||||
from agents import Agent, RunConfig, Runner, SQLiteSession
|
||||
@@ -109,14 +109,14 @@ 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(limit=None)`(기본값): 사용 가능한 모든 세션 항목을 가져옵니다
|
||||
- `SessionSettings(limit=N)`: 가장 최근의 `N`개 항목만 가져옵니다
|
||||
- `SessionSettings(limit=None)`(기본값): 사용 가능한 모든 세션 항목 가져오기
|
||||
- `SessionSettings(limit=N)`: 가장 최근의 `N`개 항목만 가져오기
|
||||
|
||||
[`RunConfig.session_settings`][agents.run.RunConfig.session_settings]를 통해 실행별로 적용할 수 있습니다.
|
||||
|
||||
@@ -134,13 +134,13 @@ result = await Runner.run(
|
||||
)
|
||||
```
|
||||
|
||||
세션 구현에서 기본 세션 설정을 제공하는 경우, `RunConfig.session_settings`는 해당 실행에서 `None`이 아닌 값을 재정의합니다. 이는 세션의 기본 동작을 변경하지 않고 가져올 기록의 크기를 제한하려는 긴 대화에 유용합니다.
|
||||
세션 구현이 기본 세션 설정을 제공하는 경우, `RunConfig.session_settings`는 해당 실행에서 `None`이 아닌 모든 값을 재정의합니다. 이는 세션의 기본 동작을 변경하지 않으면서 긴 대화에서 가져올 기록의 크기를 제한하려는 경우 유용합니다.
|
||||
|
||||
## 메모리 작업
|
||||
|
||||
### 기본 작업
|
||||
|
||||
세션은 대화 기록을 관리하기 위한 여러 작업을 지원합니다.
|
||||
세션은 대화 기록 관리를 위한 여러 작업을 지원합니다.
|
||||
|
||||
```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
|
||||
@@ -196,30 +196,30 @@ result = await Runner.run(
|
||||
print(f"Agent: {result.final_output}")
|
||||
```
|
||||
|
||||
## 내장 세션 구현
|
||||
## 기본 제공 세션 구현
|
||||
|
||||
SDK는 다양한 사용 사례를 위한 여러 세션 구현을 제공합니다.
|
||||
|
||||
### 내장 세션 구현 선택
|
||||
### 기본 제공 세션 구현 선택
|
||||
|
||||
아래의 상세한 예제를 읽기 전에 이 표를 참고하여 시작점을 선택하세요.
|
||||
아래의 상세한 예제를 읽기 전에 이 표를 사용하여 시작할 구현을 선택하세요.
|
||||
|
||||
| 세션 유형 | 적합한 용도 | 참고 |
|
||||
| 세션 유형 | 적합한 용도 | 참고 사항 |
|
||||
| --- | --- | --- |
|
||||
| `SQLiteSession` | 로컬 개발 및 간단한 앱 | 내장형 경량 구현, 파일 기반 또는 인메모리 |
|
||||
| `SQLiteSession` | 로컬 개발 및 간단한 앱 | 기본 제공, 경량, 파일 기반 또는 인메모리 |
|
||||
| `AsyncSQLiteSession` | `aiosqlite`를 사용하는 비동기 SQLite | 비동기 드라이버를 지원하는 확장 백엔드 |
|
||||
| `RedisSession` | 여러 워커/서비스 간 공유 메모리 | 지연 시간이 짧은 분산 배포에 적합 |
|
||||
| `SQLAlchemySession` | 기존 데이터베이스를 사용하는 프로덕션 앱 | SQLAlchemy가 지원하는 데이터베이스에서 작동 |
|
||||
| `MongoDBSession` | 이미 MongoDB를 사용하거나 다중 프로세스 스토리지가 필요한 앱 | 비동기 pymongo 사용, 순서 보존을 위한 원자적 시퀀스 카운터 |
|
||||
| `DaprSession` | Dapr 사이드카를 사용하는 클라우드 네이티브 배포 | 여러 상태 스토어와 TTL 및 일관성 제어 지원 |
|
||||
| `OpenAIConversationsSession` | OpenAI에서 서버가 관리하는 스토리지 | OpenAI Conversations API 기반 기록 |
|
||||
| `OpenAIResponsesCompactionSession` | 자동 압축을 사용하는 긴 대화 | 다른 세션 백엔드를 감싸는 래퍼 |
|
||||
| `AdvancedSQLiteSession` | SQLite와 분기/분석 기능 | 더 많은 기능을 제공하며 전용 페이지 참고 |
|
||||
| `EncryptedSession` | 다른 세션에 암호화와 TTL 추가 | 래퍼이므로 먼저 기반 백엔드 선택 필요 |
|
||||
| `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 스토어를 그대로 대체할 수는 없습니다. [`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-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 세션
|
||||
|
||||
@@ -259,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`을 이 세션으로 감싸지 마세요. 두 기능은 기록을 서로 다른 방식으로 관리합니다.
|
||||
|
||||
#### 일반적인 사용법(자동 압축)
|
||||
|
||||
@@ -278,17 +278,17 @@ result = await Runner.run(agent, "Hello", session=session)
|
||||
print(result.final_output)
|
||||
```
|
||||
|
||||
기본적으로 압축 후보 임계값에 도달하면 각 턴 이후 압축이 실행됩니다.
|
||||
기본적으로 후보 항목 수가 임계값에 도달하면 각 턴 후에 압축이 실행됩니다.
|
||||
|
||||
Responses API 응답 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()`가 몇 초 동안 열린 상태로 유지될 수 있습니다.
|
||||
압축은 세션 기록을 지우고 다시 작성하므로, SDK는 압축이 완료될 때까지 실행이 완료된 것으로 간주하지 않습니다. 스트리밍 모드에서는 압축 작업이 많은 경우 마지막 출력 토큰 후에도 `run.stream_events()`가 몇 초 동안 열린 상태로 유지될 수 있습니다.
|
||||
|
||||
지연 시간이 짧은 스트리밍이나 빠른 턴 전환이 필요하면 자동 압축을 비활성화하고 턴 사이 또는 유휴 시간에 `run_compaction()`을 직접 호출하세요. 자체 기준에 따라 압축을 강제로 실행할 시점을 결정할 수 있습니다.
|
||||
지연 시간이 짧은 스트리밍이나 빠른 턴 전환이 필요한 경우 자동 압축을 비활성화하고 턴 사이(또는 유휴 시간)에 직접 `run_compaction()`을 호출하세요. 자체 기준에 따라 압축을 강제로 실행할 시점을 결정할 수 있습니다.
|
||||
|
||||
```python
|
||||
from agents import Agent, Runner, SQLiteSession
|
||||
@@ -332,7 +332,7 @@ result = await Runner.run(
|
||||
|
||||
### 비동기 SQLite 세션
|
||||
|
||||
`aiosqlite` 기반의 SQLite 영속성이 필요하면 `AsyncSQLiteSession`을 사용하세요.
|
||||
`aiosqlite` 기반 SQLite 영속성이 필요한 경우 `AsyncSQLiteSession`을 사용하세요.
|
||||
|
||||
```bash
|
||||
pip install aiosqlite
|
||||
@@ -349,7 +349,7 @@ result = await Runner.run(agent, "Hello", session=session)
|
||||
|
||||
### Redis 세션
|
||||
|
||||
여러 워커 또는 서비스에서 세션 메모리를 공유하려면 `RedisSession`을 사용하세요.
|
||||
여러 워커 또는 서비스 간에 세션 메모리를 공유하려면 `RedisSession`을 사용하세요.
|
||||
|
||||
```bash
|
||||
pip install openai-agents[redis]
|
||||
@@ -368,11 +368,11 @@ result = await Runner.run(agent, "Hello", session=session)
|
||||
await session.close()
|
||||
```
|
||||
|
||||
`from_url(...)`은 Redis 클라이언트를 생성하고 소유합니다. `close()` 이후에는 세션이 종료 상태가 되며, 이후 세션 작업은 `RuntimeError`를 발생시킵니다. 반복적으로 또는 동시에 `close()`를 호출해도 안전합니다. 애플리케이션에서 이미 Redis 클라이언트를 관리하고 있다면 `redis_client=...`를 사용하여 `RedisSession(...)`을 직접 생성하세요. 이 경우 `close()`는 아무 작업도 하지 않으며 호출자가 클라이언트 소유권을 유지하고 세션도 계속 사용할 수 있습니다.
|
||||
`from_url(...)`은 Redis 클라이언트를 생성하고 소유합니다. `close()` 후에는 세션이 종료 상태가 되며 이후 세션 작업에서 `RuntimeError`가 발생합니다. `close()`를 반복해서 또는 동시에 호출해도 안전합니다. 애플리케이션에서 이미 Redis 클라이언트를 관리하고 있다면 `redis_client=...`를 사용하여 `RedisSession(...)`을 직접 생성하세요. 이 경우 `close()`는 아무 작업도 수행하지 않으며 호출자가 클라이언트의 소유권과 세션의 사용 가능 상태를 모두 유지합니다.
|
||||
|
||||
### SQLAlchemy 세션
|
||||
|
||||
SQLAlchemy가 지원하는 모든 데이터베이스를 사용하는 프로덕션 수준의 Agents SDK 세션 영속성 구현입니다.
|
||||
SQLAlchemy가 지원하는 모든 데이터베이스를 사용하는 프로덕션용 Agents SDK 세션 영속성 구현입니다.
|
||||
|
||||
```python
|
||||
from agents.extensions.memory import SQLAlchemySession
|
||||
@@ -390,11 +390,11 @@ engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/db")
|
||||
session = SQLAlchemySession("user_123", engine=engine, create_tables=True)
|
||||
```
|
||||
|
||||
자세한 문서는 [SQLAlchemy 세션](sqlalchemy_session.md)을 참고하세요.
|
||||
자세한 내용은 [SQLAlchemy 세션](sqlalchemy_session.md)을 참조하세요.
|
||||
|
||||
### Dapr 세션
|
||||
|
||||
이미 Dapr 사이드카를 실행 중이거나 에이전트 코드를 변경하지 않고 다양한 상태 스토어 백엔드 간에 이동할 수 있는 세션 스토리지가 필요하면 `DaprSession`을 사용하세요.
|
||||
이미 Dapr 사이드카를 실행하고 있거나 에이전트 코드를 변경하지 않고 여러 상태 저장소 백엔드 간에 이동할 수 있는 세션 저장소가 필요한 경우 `DaprSession`을 사용하세요.
|
||||
|
||||
```bash
|
||||
pip install openai-agents[dapr]
|
||||
@@ -415,19 +415,19 @@ async with DaprSession.from_address(
|
||||
print(result.final_output)
|
||||
```
|
||||
|
||||
참고:
|
||||
참고 사항:
|
||||
|
||||
- `from_address(...)`는 Dapr 클라이언트를 생성하고 소유합니다. 앱에서 이미 클라이언트를 관리하고 있다면 `dapr_client=...`를 사용하여 `DaprSession(...)`을 직접 생성하세요.
|
||||
- 컨텍스트에서 나가거나 `close()`를 호출하면 클라이언트를 소유한 세션은 종료 상태가 됩니다. 이후 세션 작업은 `RuntimeError`를 발생시키지만, 반복적으로 또는 동시에 `close()`를 호출해도 안전합니다. 주입된 클라이언트를 사용하면 `close()`는 아무 작업도 하지 않으며 세션을 계속 사용할 수 있습니다.
|
||||
- 상태 스토어에서 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)를 참고하세요.
|
||||
- 컨텍스트에서 나가거나 `close()`를 호출하면 소유 클라이언트 세션이 종료 상태가 되며 이후 세션 작업에서 `RuntimeError`가 발생합니다. 단, `close()`를 반복해서 또는 동시에 호출해도 안전합니다. 주입된 클라이언트를 사용하는 경우 `close()`는 아무 작업도 수행하지 않으며 세션은 계속 사용할 수 있습니다.
|
||||
- 기반 상태 저장소에서 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`을 사용하세요.
|
||||
이미 MongoDB를 사용하는 애플리케이션이나 수평 확장이 가능한 다중 프로세스 세션 저장소가 필요한 경우 `MongoDBSession`을 사용하세요.
|
||||
|
||||
```bash
|
||||
pip install openai-agents[mongodb]
|
||||
@@ -450,12 +450,12 @@ print(result.final_output)
|
||||
await session.close()
|
||||
```
|
||||
|
||||
참고:
|
||||
참고 사항:
|
||||
|
||||
- `from_uri(...)`는 `AsyncMongoClient`를 생성하고 소유하며 `session.close()` 호출 시 이를 닫습니다. 애플리케이션에서 이미 클라이언트를 관리하고 있다면 `client=...`를 사용하여 `MongoDBSession(...)`을 직접 생성하세요. 이 경우 `session.close()`는 아무 작업도 하지 않으며 수명 주기는 호출자가 관리합니다.
|
||||
- `from_uri(...)`는 `AsyncMongoClient`를 생성하고 소유하며 `session.close()` 호출 시 이를 닫습니다. 소유 클라이언트 세션은 `close()` 후 종료 상태가 되며 이후 세션 작업에서 `RuntimeError`가 발생합니다. 애플리케이션에서 이미 클라이언트를 관리하고 있다면 `client=...`를 사용하여 `MongoDBSession(...)`을 직접 생성하세요. 이 경우 `session.close()`는 아무 작업도 수행하지 않으며 수명 주기 및 세션 사용 가능 여부는 호출자가 관리합니다.
|
||||
- 다른 변경 없이 `mongodb+srv://user:password@cluster.example.mongodb.net` URI를 `from_uri(...)`에 전달하여 [MongoDB Atlas](https://www.mongodb.com/products/platform)에 연결할 수 있습니다.
|
||||
- 두 개의 컬렉션이 사용되며, 두 이름 모두 `sessions_collection=`(기본값 `agent_sessions`)과 `messages_collection=`(기본값 `agent_messages`)을 통해 설정할 수 있습니다. 인덱스는 처음 사용할 때 자동으로 생성됩니다. 각 메시지 문서에는 단조 증가하는 `seq` 카운터가 포함되어 동시 작성자와 여러 프로세스 간에도 순서를 보존합니다.
|
||||
- 첫 실행 전에 연결을 확인하려면 `await session.ping()`을 사용하세요.
|
||||
- 두 개의 컬렉션이 사용되며, 두 이름 모두 `sessions_collection=`(기본값 `agent_sessions`) 및 `messages_collection=`(기본값 `agent_messages`)을 통해 구성할 수 있습니다. 인덱스는 처음 사용할 때 자동으로 생성됩니다. 각 메시지 문서에는 단조 증가하는 `seq` 카운터가 포함되어 동시 작성자와 프로세스 전반에서 순서를 유지합니다.
|
||||
- 첫 번째 실행 전에 `await session.ping()`을 사용하여 연결 상태를 확인하세요.
|
||||
|
||||
### 고급 SQLite 세션
|
||||
|
||||
@@ -479,11 +479,11 @@ await session.store_run_usage(result) # Track token usage
|
||||
await session.create_branch_from_turn(2) # Branch from turn 2
|
||||
```
|
||||
|
||||
자세한 문서는 [고급 SQLite 세션](advanced_sqlite_session.md)을 참고하세요.
|
||||
자세한 내용은 [고급 SQLite 세션](advanced_sqlite_session.md)을 참조하세요.
|
||||
|
||||
### 암호화된 세션
|
||||
|
||||
모든 세션 구현에 적용할 수 있는 투명한 암호화 래퍼입니다.
|
||||
모든 세션 구현을 위한 투명한 암호화 래퍼입니다.
|
||||
|
||||
```python
|
||||
from agents.extensions.memory import EncryptedSession, SQLAlchemySession
|
||||
@@ -506,17 +506,17 @@ session = EncryptedSession(
|
||||
result = await Runner.run(agent, "Hello", session=session)
|
||||
```
|
||||
|
||||
자세한 문서는 [암호화된 세션](encrypted_session.md)을 참고하세요.
|
||||
자세한 내용은 [암호화된 세션](encrypted_session.md)을 참조하세요.
|
||||
|
||||
### 기타 세션 유형
|
||||
|
||||
그 밖에도 몇 가지 내장 옵션이 있습니다. `examples/memory/`와 `extensions/memory/`의 소스 코드를 참고하세요.
|
||||
이 밖에도 몇 가지 기본 제공 옵션이 있습니다. `examples/memory/` 및 `extensions/memory/` 아래의 소스 코드를 참조하세요.
|
||||
|
||||
## 운영 패턴
|
||||
|
||||
### 세션 ID 명명법
|
||||
### 세션 ID 명명
|
||||
|
||||
대화를 정리하는 데 도움이 되는 의미 있는 세션 ID를 사용하세요.
|
||||
대화를 체계적으로 정리하는 데 도움이 되는 의미 있는 세션 ID를 사용하세요.
|
||||
|
||||
- 사용자 기반: `"user_12345"`
|
||||
- 스레드 기반: `"thread_abc123"`
|
||||
@@ -524,16 +524,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)`)을 사용합니다
|
||||
- 이미 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)을 위한 맞춤형 세션 백엔드 구현을 고려합니다
|
||||
- 임시 대화에는 인메모리 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)을 위한 사용자 지정 세션 백엔드 구현 고려
|
||||
|
||||
### 여러 세션
|
||||
|
||||
@@ -581,7 +581,7 @@ result2 = await Runner.run(
|
||||
|
||||
## 전체 예제
|
||||
|
||||
다음은 세션 메모리의 실제 동작을 보여 주는 전체 예제입니다.
|
||||
다음은 세션 메모리의 실제 동작을 보여주는 전체 예제입니다.
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
@@ -643,7 +643,7 @@ if __name__ == "__main__":
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
## 맞춤형 세션 구현
|
||||
## 사용자 지정 세션 구현
|
||||
|
||||
[`Session`][agents.memory.session.Session] 프로토콜을 따르는 클래스를 생성하여 자체 세션 메모리를 구현할 수 있습니다.
|
||||
|
||||
@@ -696,11 +696,11 @@ result = await Runner.run(
|
||||
|---------|-------------|
|
||||
| [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 구현
|
||||
@@ -710,6 +710,6 @@ result = await Runner.run(
|
||||
- [`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 상태 스토어 구현
|
||||
- [`DaprSession`][agents.extensions.memory.dapr_session.DaprSession] - Dapr 상태 저장소 구현
|
||||
- [`AdvancedSQLiteSession`][agents.extensions.memory.advanced_sqlite_session.AdvancedSQLiteSession] - 분기 및 분석 기능을 갖춘 향상된 SQLite
|
||||
- [`EncryptedSession`][agents.extensions.memory.encrypt_session.EncryptedSession] - 모든 세션을 위한 암호화 래퍼
|
||||
@@ -4,15 +4,15 @@ search:
|
||||
---
|
||||
# 高级 SQLite 会话
|
||||
|
||||
`AdvancedSQLiteSession` 是基础 `SQLiteSession` 的增强版本，提供高级对话管理能力，包括对话分支、详细的使用情况分析以及结构化对话查询。
|
||||
`AdvancedSQLiteSession` 是基础 `SQLiteSession` 的增强版本，提供高级会话管理功能，包括会话分支、详细的使用情况分析和结构化会话查询。
|
||||
|
||||
## 功能
|
||||
|
||||
- **对话分支**：从任意用户消息创建替代对话路径
|
||||
- **使用情况追踪**：按轮次提供详细的 token 使用情况分析，并包含完整的 JSON 明细
|
||||
- **结构化查询**：按轮次获取对话、工具使用统计等
|
||||
- **分支管理**：独立的分支切换与管理
|
||||
- **消息结构元数据**：跟踪消息类型、工具使用情况和对话流程
|
||||
- **会话分支**：从任意用户消息创建不同的会话路径
|
||||
- **使用情况追踪**：提供每轮详细的 token 使用情况分析及完整的 JSON 明细
|
||||
- **结构化查询**：按轮次获取会话、工具使用情况统计等信息
|
||||
- **分支管理**：独立切换和管理分支
|
||||
- **消息结构元数据**：追踪消息类型、工具使用情况和会话流程
|
||||
|
||||
## 快速开始
|
||||
|
||||
@@ -84,14 +84,14 @@ session = AdvancedSQLiteSession(
|
||||
|
||||
### 参数
|
||||
|
||||
- `session_id` (str)：对话会话的唯一标识符
|
||||
- `db_path` (str | Path)：SQLite 数据库文件路径。默认为 `:memory:`，用于内存存储
|
||||
- `create_tables` (bool)：是否自动创建高级表。默认为 `False`
|
||||
- `logger` (logging.Logger | None)：用于会话的自定义日志记录器。默认为模块日志记录器
|
||||
- `session_id` (str)：会话 session 的唯一标识符
|
||||
- `db_path` (str | Path)：SQLite 数据库文件的路径。默认值为 `:memory:`，用于内存存储
|
||||
- `create_tables` (bool)：是否自动创建高级数据表。默认值为 `False`
|
||||
- `logger` (logging.Logger | None)：会话的自定义日志记录器。默认使用模块日志记录器
|
||||
|
||||
## 使用情况追踪
|
||||
|
||||
AdvancedSQLiteSession 通过按对话轮次存储 token 使用情况数据，提供详细的使用情况分析。**这完全依赖于在每次智能体运行后调用 `store_run_usage` 方法。**
|
||||
AdvancedSQLiteSession 通过存储每轮会话的 token 使用情况数据，提供详细的使用情况分析。**这完全取决于是否在每次智能体运行后调用 `store_run_usage` 方法。**
|
||||
|
||||
### 使用情况数据存储
|
||||
|
||||
@@ -135,9 +135,9 @@ for turn_data in turn_usage:
|
||||
turn_2_usage = await session.get_turn_usage(user_turn_number=2)
|
||||
```
|
||||
|
||||
## 对话分支
|
||||
## 会话分支
|
||||
|
||||
AdvancedSQLiteSession 的关键功能之一是能够从任意用户消息创建对话分支，从而让你探索替代的对话路径。
|
||||
AdvancedSQLiteSession 的一项关键功能是能够从任意用户消息创建会话分支，以便探索不同的会话路径。
|
||||
|
||||
### 分支创建
|
||||
|
||||
@@ -165,6 +165,8 @@ branch_id = await session.create_branch_from_content(
|
||||
)
|
||||
```
|
||||
|
||||
在一个会话 ID 的整个生命周期内，分支 ID 都是唯一的。删除分支或清除会话会移除其会话数据，但不会使之前使用过的分支 ID 再次可用；创建其他分支时，请使用新名称。
|
||||
|
||||
### 分支管理
|
||||
|
||||
```python
|
||||
@@ -217,9 +219,9 @@ await session.store_run_usage(result)
|
||||
|
||||
## 结构化查询
|
||||
|
||||
AdvancedSQLiteSession 提供了多种方法，用于分析对话结构和内容。
|
||||
AdvancedSQLiteSession 提供多种方法，用于分析会话的结构和内容。
|
||||
|
||||
### 对话分析
|
||||
### 会话分析
|
||||
|
||||
```python
|
||||
# Get conversation organized by turns
|
||||
@@ -245,17 +247,17 @@ for turn in matching_turns:
|
||||
|
||||
### 消息结构
|
||||
|
||||
会话会自动跟踪消息结构，包括：
|
||||
会话会自动追踪消息结构，包括：
|
||||
|
||||
- 消息类型（用户、assistant、tool_call 等）
|
||||
- 工具调用的工具名称
|
||||
- 轮次编号和序列号
|
||||
- 分支关联
|
||||
- 消息类型（用户、助手、工具调用等）
|
||||
- 工具调用对应的工具名称
|
||||
- 轮次编号和序列编号
|
||||
- 分支关联关系
|
||||
- 时间戳
|
||||
|
||||
## 数据库架构
|
||||
|
||||
AdvancedSQLiteSession 在基础 SQLite 架构之上扩展了两个额外的表：
|
||||
AdvancedSQLiteSession 在基础 SQLite 架构之上新增了三个表：
|
||||
|
||||
### message_structure 表
|
||||
|
||||
@@ -276,6 +278,18 @@ CREATE TABLE message_structure (
|
||||
);
|
||||
```
|
||||
|
||||
### branch_reservations 表
|
||||
|
||||
```sql
|
||||
CREATE TABLE branch_reservations (
|
||||
session_id TEXT NOT NULL,
|
||||
branch_id TEXT NOT NULL,
|
||||
PRIMARY KEY (session_id, branch_id)
|
||||
);
|
||||
```
|
||||
|
||||
此表以原子方式预留分支 ID，也包括所复制前缀为空的分支。删除分支和清除会话后，预留记录仍会保留，从而防止过期的会话实例将历史记录合并到之后复用同一 ID 的分支中。
|
||||
|
||||
### turn_usage 表
|
||||
|
||||
```sql
|
||||
@@ -298,7 +312,7 @@ CREATE TABLE turn_usage (
|
||||
|
||||
## 完整示例
|
||||
|
||||
查看[完整示例](https://github.com/openai/openai-agents-python/tree/main/examples/memory/advanced_sqlite_session_example.py)，全面了解所有功能。
|
||||
请查看[完整示例](https://github.com/openai/openai-agents-python/tree/main/examples/memory/advanced_sqlite_session_example.py)，全面了解所有功能。
|
||||
|
||||
|
||||
## API 参考
|
||||
|
||||
+94
-94
@@ -4,11 +4,11 @@ search:
|
||||
---
|
||||
# 会话
|
||||
|
||||
Agents SDK提供内置会话记忆，可在多次智能体运行之间自动维护对话历史，无需在轮次之间手动处理 `.to_input_list()`。
|
||||
Agents SDK提供内置会话内存，可在多次智能体运行之间自动维护对话历史记录，无需在不同轮次之间手动处理`.to_input_list()`。
|
||||
|
||||
会话会存储特定会话的对话历史，使智能体无需显式的手动记忆管理即可维护上下文。这对于构建聊天应用或多轮对话尤其有用，因为你希望智能体记住之前的交互。
|
||||
会话存储特定会话的对话历史记录，使智能体无需显式手动管理内存即可保持上下文。这对于构建聊天应用或多轮对话尤其有用，因为在这些场景中，你希望智能体能够记住先前的交互。
|
||||
|
||||
当你希望 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(...)` 检索）
|
||||
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`：检索到的会话历史（已规范化为输入条目格式）
|
||||
- `new_input`：当前轮次的新输入条目
|
||||
- `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`值。这适用于较长的对话，可在不更改会话默认行为的情况下限制检索量。
|
||||
|
||||
## 记忆操作
|
||||
## 内存操作
|
||||
|
||||
### 基本操作
|
||||
|
||||
会话支持多种对话历史管理操作：
|
||||
会话支持多种对话历史记录管理操作：
|
||||
|
||||
```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
|
||||
@@ -202,28 +202,28 @@ SDK 针对不同使用场景提供了多种会话实现：
|
||||
|
||||
### 内置会话实现的选择
|
||||
|
||||
阅读下方详细示例之前，可使用此表选择起点。
|
||||
阅读下方详细示例之前，可使用此表选择一个起点。
|
||||
|
||||
| 会话类型 | 最适用场景 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `SQLiteSession` | 本地开发和简单应用 | 内置、轻量，可由文件支持或在内存中运行 |
|
||||
| `AsyncSQLiteSession` | 使用 `aiosqlite` 的异步 SQLite | 支持异步驱动程序的扩展后端 |
|
||||
| `RedisSession` | 跨工作进程或服务共享记忆 | 适合低延迟分布式部署 |
|
||||
| `SQLAlchemySession` | 使用现有数据库的生产应用 | 适用于 SQLAlchemy 支持的数据库 |
|
||||
| `MongoDBSession` | 已使用 MongoDB 或需要多进程存储的应用 | 异步 pymongo；使用原子序列计数器保持顺序 |
|
||||
| `DaprSession` | 使用 Dapr sidecar 的云原生部署 | 支持多种状态存储，以及 TTL 和一致性控制 |
|
||||
| `OpenAIConversationsSession` | 由OpenAI服务管理的存储 | 由OpenAI Conversations API 支持的历史记录 |
|
||||
| `SQLiteSession` | 本地开发和简单应用 | 内置、轻量，可使用文件或内存作为后端 |
|
||||
| `AsyncSQLiteSession` | 通过`aiosqlite`使用异步 SQLite | 支持异步驱动程序的扩展后端 |
|
||||
| `RedisSession` | 跨工作进程或服务共享内存 | 适合低延迟分布式部署 |
|
||||
| `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.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)。
|
||||
如果你正在为 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 会话
|
||||
|
||||
通过 `OpenAIConversationsSession` 使用 [OpenAI的 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
|
||||
@@ -259,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`；这两项功能采用不同的方式管理历史记录。
|
||||
|
||||
#### 典型用法（自动压缩）
|
||||
|
||||
@@ -278,17 +278,17 @@ result = await Runner.run(agent, "Hello", session=session)
|
||||
print(result.final_output)
|
||||
```
|
||||
|
||||
默认情况下，一旦达到候选阈值，每个轮次后都会执行压缩。
|
||||
默认情况下，达到候选阈值后，每个轮次结束时都会运行压缩。
|
||||
|
||||
当你已经使用 Responses API 响应 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 会等待压缩完成后，才将运行视为已完成。在流式传输模式下，如果压缩负载较重，这意味着最后一个输出 token 生成后，`run.stream_events()` 可能还会保持打开数秒。
|
||||
压缩会清除并重写会话历史记录，因此 SDK 会等待压缩完成后，才将运行视为完成。在流式传输模式下，如果压缩任务较重，这意味着`run.stream_events()`可能会在输出最后一个 token 后继续保持打开数秒。
|
||||
|
||||
如果你需要低延迟流式传输或快速轮次切换，请禁用自动压缩，并在轮次之间（或空闲时）自行调用 `run_compaction()`。你可以根据自己的条件决定何时强制执行压缩。
|
||||
如果希望实现低延迟流式传输或快速轮次切换，请禁用自动压缩，并在轮次之间（或空闲期间）自行调用`run_compaction()`。你可以根据自己的标准决定何时强制压缩。
|
||||
|
||||
```python
|
||||
from agents import Agent, Runner, SQLiteSession
|
||||
@@ -332,7 +332,7 @@ result = await Runner.run(
|
||||
|
||||
### 异步 SQLite 会话
|
||||
|
||||
如果希望使用由 `aiosqlite` 支持的 SQLite 持久化，请使用 `AsyncSQLiteSession`。
|
||||
如果希望使用由`aiosqlite`支持的 SQLite 持久化，请使用`AsyncSQLiteSession`。
|
||||
|
||||
```bash
|
||||
pip install aiosqlite
|
||||
@@ -349,7 +349,7 @@ result = await Runner.run(agent, "Hello", session=session)
|
||||
|
||||
### Redis 会话
|
||||
|
||||
使用 `RedisSession` 可在多个工作进程或服务之间共享会话记忆。
|
||||
使用`RedisSession`可在多个工作进程或服务之间共享会话内存。
|
||||
|
||||
```bash
|
||||
pip install openai-agents[redis]
|
||||
@@ -368,11 +368,11 @@ result = await Runner.run(agent, "Hello", session=session)
|
||||
await session.close()
|
||||
```
|
||||
|
||||
`from_url(...)` 会创建并拥有 Redis 客户端。调用 `close()` 后，会话将进入终止状态，后续会话操作会引发 `RuntimeError`；重复或并发调用 `close()` 是安全的。如果应用已管理 Redis 客户端，请直接构造 `RedisSession(...)` 并传入 `redis_client=...`。在这种情况下，`close()` 不执行任何操作，调用方仍拥有客户端所有权，会话也仍可使用。
|
||||
`from_url(...)`会创建并拥有 Redis 客户端。调用`close()`后，会话将进入终止状态，后续会话操作会引发`RuntimeError`；重复或并发调用`close()`是安全的。如果应用已经管理 Redis 客户端，请通过`redis_client=...`直接构造`RedisSession(...)`。在这种情况下，`close()`不会执行任何操作，调用方仍拥有客户端，并且会话仍然可用。
|
||||
|
||||
### SQLAlchemy 会话
|
||||
|
||||
使用任何 SQLAlchemy 支持的数据库，为 Agents SDK提供可用于生产环境的会话持久化：
|
||||
使用 SQLAlchemy 所支持的任意数据库，为Agents SDK提供可用于生产环境的会话持久化：
|
||||
|
||||
```python
|
||||
from agents.extensions.memory import SQLAlchemySession
|
||||
@@ -390,11 +390,11 @@ engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/db")
|
||||
session = SQLAlchemySession("user_123", engine=engine, create_tables=True)
|
||||
```
|
||||
|
||||
详细文档请参阅 [SQLAlchemy 会话](sqlalchemy_session.md)。
|
||||
有关详细文档，请参阅[SQLAlchemy 会话](sqlalchemy_session.md)。
|
||||
|
||||
### Dapr 会话
|
||||
|
||||
如果你已运行 Dapr sidecar，或希望在不更改智能体代码的情况下，让会话存储可在不同状态存储后端之间迁移，请使用 `DaprSession`。
|
||||
如果你已经运行 Dapr 边车，或希望会话存储能在不同状态存储后端之间迁移而无需更改智能体代码，请使用`DaprSession`。
|
||||
|
||||
```bash
|
||||
pip install openai-agents[dapr]
|
||||
@@ -417,17 +417,17 @@ async with DaprSession.from_address(
|
||||
|
||||
注意：
|
||||
|
||||
- `from_address(...)` 会为你创建并拥有 Dapr 客户端。如果应用已管理客户端，请直接构造 `DaprSession(...)` 并传入 `dapr_client=...`。
|
||||
- 退出上下文或调用 `close()` 会使拥有客户端的会话进入终止状态；后续会话操作会引发 `RuntimeError`，但重复或并发调用 `close()` 是安全的。使用注入的客户端时，`close()` 不执行任何操作，会话仍可使用。
|
||||
- 当底层状态存储支持 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 客户端。如果应用已经管理 Dapr 客户端，请通过`dapr_client=...`直接构造`DaprSession(...)`。
|
||||
- 退出上下文或调用`close()`会使拥有客户端的会话进入终止状态；后续会话操作会引发`RuntimeError`，但重复或并发调用`close()`是安全的。使用注入客户端时，`close()`不会执行任何操作，会话仍然可用。
|
||||
- 传入`ttl=...`可在底层状态存储支持 TTL 时，使其自动让旧会话数据过期。
|
||||
- 当需要更强的写后读保证时，传入`consistency=DAPR_CONSISTENCY_STRONG`。
|
||||
- Dapr Python SDK 还会检查 HTTP 边车端点。在本地开发中，启动 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`。
|
||||
对于已经使用 MongoDB 或需要可横向扩展的多进程会话存储的应用，请使用`MongoDBSession`。
|
||||
|
||||
```bash
|
||||
pip install openai-agents[mongodb]
|
||||
@@ -452,14 +452,14 @@ await session.close()
|
||||
|
||||
注意：
|
||||
|
||||
- `from_uri(...)` 会创建并拥有 `AsyncMongoClient`，并在调用 `session.close()` 时将其关闭。如果应用已管理客户端，请直接构造 `MongoDBSession(...)` 并传入 `client=...`；在这种情况下，`session.close()` 不执行任何操作，生命周期仍由调用方管理。
|
||||
- 若要连接到 [MongoDB Atlas](https://www.mongodb.com/products/platform)，只需向 `from_uri(...)` 传入 `mongodb+srv://user:password@cluster.example.mongodb.net` URI，无需进行其他更改。
|
||||
- 系统会使用两个集合，二者的名称均可配置：通过 `sessions_collection=` 配置会话集合（默认值为 `agent_sessions`），通过 `messages_collection=` 配置消息集合（默认值为 `agent_messages`）。首次使用时会自动创建索引。每个消息文档都包含一个单调递增的 `seq` 计数器，可在并发写入方和进程之间保持顺序。
|
||||
- 在首次运行前，使用 `await session.ping()` 验证连接。
|
||||
- `from_uri(...)`会创建并拥有`AsyncMongoClient`，并在调用`session.close()`时将其关闭。调用`close()`后，拥有客户端的会话将进入终止状态，后续会话操作会引发`RuntimeError`。如果应用已经管理客户端，请通过`client=...`直接构造`MongoDBSession(...)`；在这种情况下，`session.close()`不会执行任何操作，生命周期管理和会话可用性由调用方负责。
|
||||
- 要连接到[MongoDB Atlas](https://www.mongodb.com/products/platform)，只需向`from_uri(...)`传入`mongodb+srv://user:password@cluster.example.mongodb.net`URI，无需进行其他更改。
|
||||
- 系统会使用两个集合，其名称都可分别通过`sessions_collection=`（默认为`agent_sessions`）和`messages_collection=`（默认为`agent_messages`）进行配置。首次使用时会自动创建索引。每个消息文档都带有单调递增的`seq`计数器，可在并发写入进程和多个进程之间保持顺序。
|
||||
- 首次运行之前，使用`await session.ping()`验证连接。
|
||||
|
||||
### 高级 SQLite 会话
|
||||
|
||||
增强型 SQLite 会话，支持对话分支、用量分析和结构化查询：
|
||||
支持对话分支、用量分析和结构化查询的增强型 SQLite 会话：
|
||||
|
||||
```python
|
||||
from agents.extensions.memory import AdvancedSQLiteSession
|
||||
@@ -479,7 +479,7 @@ await session.store_run_usage(result) # Track token usage
|
||||
await session.create_branch_from_turn(2) # Branch from turn 2
|
||||
```
|
||||
|
||||
详细文档请参阅[高级 SQLite 会话](advanced_sqlite_session.md)。
|
||||
有关详细文档，请参阅[高级 SQLite 会话](advanced_sqlite_session.md)。
|
||||
|
||||
### 加密会话
|
||||
|
||||
@@ -506,34 +506,34 @@ session = EncryptedSession(
|
||||
result = await Runner.run(agent, "Hello", session=session)
|
||||
```
|
||||
|
||||
详细文档请参阅[加密会话](encrypted_session.md)。
|
||||
有关详细文档，请参阅[加密会话](encrypted_session.md)。
|
||||
|
||||
### 其他会话类型
|
||||
|
||||
此外还有一些内置选项。请参阅 `examples/memory/` 以及 `extensions/memory/` 下的源代码。
|
||||
还有少量其他内置选项。请参阅`examples/memory/`和`extensions/memory/`下的源代码。
|
||||
|
||||
## 运维模式
|
||||
## 操作模式
|
||||
|
||||
### 会话 ID 命名
|
||||
|
||||
使用有意义的会话 ID 以便组织对话：
|
||||
使用有意义的会话 ID 来帮助组织对话：
|
||||
|
||||
- 基于用户：`"user_12345"`
|
||||
- 基于线程：`"thread_abc123"`
|
||||
- 基于上下文：`"support_ticket_456"`
|
||||
|
||||
### 记忆持久化
|
||||
### 内存持久化
|
||||
|
||||
- 对于临时对话，使用内存 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")`）
|
||||
- 对于生产环境中的云原生部署，使用 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）实现自定义会话后端
|
||||
- 对临时对话使用内存 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")`）
|
||||
- 对生产环境中的云原生部署，使用 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）实现自定义会话后端
|
||||
|
||||
### 多会话
|
||||
|
||||
@@ -581,7 +581,7 @@ result2 = await Runner.run(
|
||||
|
||||
## 完整示例
|
||||
|
||||
以下完整示例展示了会话记忆的实际运作方式：
|
||||
以下完整示例展示了会话内存的实际工作方式：
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
@@ -645,7 +645,7 @@ if __name__ == "__main__":
|
||||
|
||||
## 自定义会话实现
|
||||
|
||||
你可以创建遵循 [`Session`][agents.memory.session.Session] 协议的类，实现自己的会话记忆：
|
||||
你可以创建遵循[`Session`][agents.memory.session.Session]协议的类，以实现自己的会话内存：
|
||||
|
||||
```python
|
||||
from agents.memory.session import SessionABC
|
||||
@@ -690,26 +690,26 @@ result = await Runner.run(
|
||||
|
||||
## 社区会话实现
|
||||
|
||||
社区开发了其他会话实现：
|
||||
社区开发了更多会话实现：
|
||||
|
||||
| 软件包 | 描述 |
|
||||
| 软件包 | 说明 |
|
||||
|---------|-------------|
|
||||
| [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，将其添加到此处！
|
||||
|
||||
## API 参考
|
||||
|
||||
详细 API 文档请参阅：
|
||||
有关详细的 API 文档，请参阅：
|
||||
|
||||
- [`Session`][agents.memory.session.Session] - 协议接口
|
||||
- [`OpenAIConversationsSession`][agents.memory.OpenAIConversationsSession] - OpenAI Conversations API 实现
|
||||
- [`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 的实现
|
||||
- [`MongoDBSession`][agents.extensions.memory.mongodb_session.MongoDBSession] - MongoDB 支持的会话实现
|
||||
- [`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] - 适用于任意会话的加密封装器
|
||||
- [`AdvancedSQLiteSession`][agents.extensions.memory.advanced_sqlite_session.AdvancedSQLiteSession] - 支持分支和分析功能的增强型 SQLite
|
||||
- [`EncryptedSession`][agents.extensions.memory.encrypt_session.EncryptedSession] - 适用于任何会话的加密封装器
|
||||
Reference in New Issue
Block a user