github-featured/openai--openai-agents-python
2
0
Fork 0
Code Issues Pull Requests Deployments Models Agent Notes Packages Projects Releases Wiki Activity

docs: update translated document pages (#2589)

Browse Source
This commit is contained in:
github-actions[bot]
2026-03-04 07:12:39 +09:00
committed by GitHub
parent 072410349b
commit cf441bbafd
9 changed files with 625 additions and 436 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ja/examples.md
+43 -41
View File
@@ -4,96 +4,98 @@ search:
---
# コード例
[repo](https://github.com/openai/openai-agents-python/tree/main/examples) の examples セクションで、 SDK のさまざまなサンプル実装をご覧ください。 examples は、異なるパターンと機能を示すいくつかのカテゴリーに整理されています。
[repo](https://github.com/openai/openai-agents-python/tree/main/examples) の examples セクションで、 SDK のさまざまなサンプル実装をご覧ください。examples は、異なるパターンや機能を示す複数のカテゴリーに整理されています。
## カテゴリー
- **[agent_patterns](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns):**
このカテゴリーの例は、次のような一般的な エージェント 設計パターンを示します。
このカテゴリーのコード例では、次のような一般的なエージェント設計パターンを紹介します。
- 決定的なワークフロー
- 決定論的ワークフロー
- Agents as tools
- 並列 エージェント 実行
- エージェントの並列実行
- 条件付きツール使用
- 入出力 ガードレール
- 入出力ガードレール
- 判定者としての LLM
- ルーティング
- ストリーミング ガードレール
- ストリーミングガードレール
- **[basic](https://github.com/openai/openai-agents-python/tree/main/examples/basic):**
これらの例は、次のような SDK の基礎的な機能を紹介します。
これらのコード例では、次のような SDK の基本機能を紹介します。
- Hello World の例 (Default model、 GPT-5、 open-weight model)
- エージェント のライフサイクル管理
- 動的な システムプロンプト
- ストリーミング 出力 (text、 items、 function call args)
- ターンをまたいで共有セッションヘルパーを使う Responses websocket transport (`examples/basic/stream_ws.py`)
- Hello world のコード例（デフォルトモデル、 GPT-5、 open-weight モデル）
- エージェントのライフサイクル管理
- 動的システムプロンプト
- ストリーミング出力（テキスト、項目、関数呼び出し引数）
- ターンをまたいで共有セッションヘルパーを使用する Responses websocket transport（`examples/basic/stream_ws.py`）
- プロンプトテンプレート
- ファイル処理 (ローカルとリモート、画像と PDF)
- 使用状況トラッキング
- ファイル処理（ローカルおよびリモート、画像および PDF）
- 使用状況のトラッキング
- 非 strict な出力型
- 以前の response ID の使用
- 以前の response ID の利用
- **[customer_service](https://github.com/openai/openai-agents-python/tree/main/examples/customer_service):**
航空会社向けのカスタマーサービスシステム例です。
航空会社向けのカスタマーサービスシステムのコード例です。
- **[financial_research_agent](https://github.com/openai/openai-agents-python/tree/main/examples/financial_research_agent):**
金融データ分析のための エージェント とツールを用いた、構造化されたリサーチワークフローを示す金融リサーチ エージェント です。
金融データ分析のためのエージェントとツールを用いた、構造化された調査ワークフローを示す金融調査エージェントです。
- **[handoffs](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs):**
メッセージフィルタリングを伴う エージェント の ハンドオフ の実践例をご覧ください。
メッセージフィルタリングを使ったエージェントのハンドオフの実践的なコード例をご覧ください。
- **[hosted_mcp](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp):**
hosted MCP (Model context protocol) コネクターと承認の使い方を示す例です。
ホスト型 MCP（Model Context Protocol）コネクタと承認の使い方を示すコード例です。
- **[mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp):**
次を含め、 MCP (Model context protocol) を用いた エージェント の構築方法を学びます。
MCP（Model Context Protocol）を使ってエージェントを構築する方法を学べます。内容は以下を含みます。
- ファイルシステムの例
- Git の例
- MCP プロンプトサーバーの例
- SSE (Server-Sent Events) の例
- ストリーム可能な HTTP の例
- Filesystem のコード例
- Git のコード例
- MCP prompt server のコード例
- SSE（Server-Sent Events）のコード例
- Streamable HTTP のコード例
- **[memory](https://github.com/openai/openai-agents-python/tree/main/examples/memory):**
次を含む、 エージェント 向けのさまざまなメモリ実装の例です。
エージェント向けのさまざまなメモリ実装のコード例です。以下を含みます。
- SQLite セッションストレージ
- 高度な SQLite セッションストレージ
- Redis セッションストレージ
- SQLAlchemy セッションストレージ
- 暗号化されたセッションストレージ
- OpenAI セッションストレージ
- Dapr state store セッションストレージ
- 暗号化セッションストレージ
- OpenAI Conversations セッションストレージ
- Responses compaction セッションストレージ
- **[model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):**
カスタムプロバイダーや LiteLLM 連携を含め、 SDK で非 OpenAI モデルを使用する方法を確認します。
カスタムプロバイダーや LiteLLM 統合を含め、 SDK で OpenAI 以外のモデルを使う方法を確認できます。
- **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):**
次を含め、 SDK を使ってリアルタイム体験を構築する方法を示す例です。
SDK を使ってリアルタイム体験を構築する方法を示すコード例です。以下を含みます。
- Web アプリケーション
- コマンドラインインターフェース
- Twilio 連携
- Twilio SIP 連携
- Twilio 統合
- Twilio SIP 統合
- **[reasoning_content](https://github.com/openai/openai-agents-python/tree/main/examples/reasoning_content):**
reasoning content と structured outputs の扱い方を示す例です。
reasoning content と structured outputs を扱う方法を示すコード例です。
- **[research_bot](https://github.com/openai/openai-agents-python/tree/main/examples/research_bot):**
複雑なマルチ エージェント のリサーチワークフローを示す、シンプルな ディープリサーチ クローンです。
複雑なマルチエージェント調査ワークフローを示す、シンプルなディープリサーチクローンです。
- **[tools](https://github.com/openai/openai-agents-python/tree/main/examples/tools):**
次を含む OpenAI がホストするツール と、実験的な Codex ツール機能の実装方法を学びます。
OpenAI がホストするツールや、次のような実験的な Codex ツール機能を実装する方法を学べます。
- Web 検索 とフィルター付き Web 検索
- Web 検索 およびフィルター付き Web 検索
- ファイル検索
- Code Interpreter
- インラインスキル付き hosted container shell (`examples/tools/container_shell_inline_skill.py`)
- スキル参照付き hosted container shell (`examples/tools/container_shell_skill_reference.py`)
- インラインスキル付きホスト型コンテナシェル（`examples/tools/container_shell_inline_skill.py`）
- スキル参照付きホスト型コンテナシェル（`examples/tools/container_shell_skill_reference.py`）
- コンピュータ操作
- 画像生成
- 実験的な Codex ツールのワークフロー (`examples/tools/codex.py`)
- 実験的な Codex の同一スレッドワークフロー (`examples/tools/codex_same_thread.py`)
- 実験的な Codex ツールワークフロー（`examples/tools/codex.py`）
- 実験的な Codex 同一スレッドワークフロー（`examples/tools/codex_same_thread.py`）
- **[voice](https://github.com/openai/openai-agents-python/tree/main/examples/voice):**
ストリーミング音声の例を含め、当社の TTS および STT モデルを使用する音声 エージェント の例をご覧ください。
ストリーミング音声のコード例を含む、 TTS および STT モデルを使った音声エージェントのコード例をご覧ください。
docs/ja/models/index.md
+78 -48
View File
@@ -4,39 +4,39 @@ search:
---
# モデル
Agents SDK には、OpenAI モデル向けの即時利用可能なサポートが 2 種類あります。
Agents SDK には、OpenAI モデルをすぐに使える形で 2 つの方式でサポートしています。
- **推奨**: 新しい [Responses API](https://platform.openai.com/docs/api-reference/responses) を使って OpenAI API を呼び出す [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]。
- [Chat Completions API](https://platform.openai.com/docs/api-reference/chat) を使って OpenAI API を呼び出す [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]。
## モデル設定の選択
設定に応じて、このページを次の順序で利用してください。
設定に応じて、次の順序でこのページをご利用ください。
| 目標 | 開始箇所 |
| 目的 | 開始場所 |
| --- | --- |
| SDK のデフォルトで OpenAI ホストモデルを使う | [OpenAI モデル](#openai-models) |
| WebSocket 転送で OpenAI Responses API を使う | [Responses WebSocket 転送](#responses-websocket-transport) |
| OpenAI 以外のプロバイダーを使う | [OpenAI 以外のモデル](#non-openai-models) |
| websocket トランスポートで OpenAI Responses API を使う | [Responses WebSocket トランスポート](#responses-websocket-transport) |
| OpenAI 以外のプロバイダーを使う | [非 OpenAI モデル](#non-openai-models) |
| 1 つのワークフローでモデル / プロバイダーを混在させる | [高度なモデル選択と混在](#advanced-model-selection-and-mixing) と [プロバイダー間でのモデル混在](#mixing-models-across-providers) |
| プロバイダー互換性の問題をデバッグする | [OpenAI 以外のプロバイダーのトラブルシューティング](#troubleshooting-non-openai-providers) |
| プロバイダー互換性の問題をデバッグする | [非 OpenAI プロバイダーのトラブルシューティング](#troubleshooting-non-openai-providers) |
## OpenAI モデル
`Agent` 初期化時にモデルを指定しない場合、デフォルトモデルが使われます。現在のデフォルトは、互換性と低レイテンシのため [`gpt-4.1`](https://platform.openai.com/docs/models/gpt-4.1) です。利用可能であれば、明示的な `model_settings` を維持したまま、より高品質な [`gpt-5.2`](https://platform.openai.com/docs/models/gpt-5.2) をエージェントに設定することを推奨します。
`Agent` の初期化時にモデルを指定しない場合、デフォルトモデルが使われます。現在のデフォルトは、互換性と低レイテンシのため [`gpt-4.1`](https://platform.openai.com/docs/models/gpt-4.1) です。アクセス可能であれば、明示的な `model_settings` を維持しつつ、より高品質な [`gpt-5.2`](https://platform.openai.com/docs/models/gpt-5.2) にエージェントを設定することを推奨します。
[`gpt-5.2`](https://platform.openai.com/docs/models/gpt-5.2) のような他モデルに切り替えたい場合、エージェントを設定する方法は 2 つあります。
[`gpt-5.2`](https://platform.openai.com/docs/models/gpt-5.2) のような他モデルに切り替えるには、エージェントを設定する方法が 2 つあります。
### デフォルトモデル
まず、カスタムモデルを設定していないすべてのエージェントで一貫して特定モデルを使いたい場合は、エージェント実行前に環境変数 `OPENAI_DEFAULT_MODEL` を設定します。
まず、カスタムモデルを設定していないすべてのエージェントで一貫して特定モデルを使いたい場合は、エージェント実行前に `OPENAI_DEFAULT_MODEL` 環境変数を設定します。
```bash
export OPENAI_DEFAULT_MODEL=gpt-5.2
python3 my_awesome_agent.py
```
次に、`RunConfig` を介して実行単位のデフォルトモデルを設定できます。エージェントにモデルを設定しない場合、この実行のモデルが使われます。
次に、`RunConfig` 経由で実行ごとのデフォルトモデルを設定できます。エージェントにモデルを設定しない場合は、この実行のモデルが使われます。
```python
from agents import Agent, RunConfig, Runner
@@ -55,7 +55,7 @@ result = await Runner.run(
#### GPT-5.x モデル
この方法で [`gpt-5.2`](https://platform.openai.com/docs/models/gpt-5.2) などの GPT-5.x モデルを使うと、SDK はデフォルトの `ModelSettings` を適用します。ほとんどのユースケースで最適に動作する設定が使われます。デフォルトモデルの reasoning effort を調整するには、独自の `ModelSettings` を渡してください。
この方法で [`gpt-5.2`](https://platform.openai.com/docs/models/gpt-5.2) などの GPT-5.x モデルを使う場合、SDK はデフォルトの `ModelSettings` を適用します。これはほとんどのユースケースで最適に動作する設定です。デフォルトモデルの推論負荷を調整するには、独自の `ModelSettings` を渡してください。
```python
from openai.types.shared import Reasoning
@@ -71,15 +71,15 @@ my_agent = Agent(
)
```
より低レイテンシにするには、`gpt-5.2` で `reasoning.effort="none"` を使うことを推奨します。gpt-4.1 ファミリー（ mini / nano を含む）も、インタラクティブなエージェントアプリ構築において引き続き有力な選択肢です。
低レイテンシのためには、`gpt-5.2` で `reasoning.effort="none"` を使うことを推奨します。gpt-4.1 ファミリー（ mini および nano バリアントを含む）も、対話型エージェントアプリ構築における有力な選択肢です。
#### 非 GPT-5 モデル
カスタム `model_settings` なしで非 GPT-5 のモデル名を渡すと、SDK は任意のモデルと互換性のある汎用 `ModelSettings` に戻します。
カスタム `model_settings` なしで非 GPT-5 モデル名を渡すと、SDK は任意モデルと互換性のある汎用 `ModelSettings` に戻します。
### Responses WebSocket 転送
### Responses WebSocket トランスポート
デフォルトでは、OpenAI Responses API リクエストは HTTP 転送を使います。OpenAI バックエンドのモデルを使う場合は、WebSocket 転送を有効化できます。
デフォルトでは、OpenAI Responses API リクエストは HTTP トランスポートを使います。OpenAI バックエンドのモデルを使う場合、websocket トランスポートを有効化できます。
```python
from agents import set_default_openai_responses_transport
@@ -87,11 +87,11 @@ from agents import set_default_openai_responses_transport
set_default_openai_responses_transport("websocket")
```
これは、デフォルトの OpenAI provider によって解決される OpenAI Responses モデル（ `"gpt-5.2"` のような文字列モデル名を含む）に影響します。
これは、デフォルトの OpenAI プロバイダーで解決される OpenAI Responses モデル（`"gpt-5.2"` のような文字列モデル名を含む）に影響します。
転送方式の選択は、SDK がモデル名をモデルインスタンスへ解決する際に行われます。具体的な [`Model`][agents.models.interface.Model] オブジェクトを渡した場合、その転送方式はすでに固定されています。[`OpenAIResponsesWSModel`][agents.models.openai_responses.OpenAIResponsesWSModel] は WebSocket、[`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] は HTTP、[`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] は Chat Completions のままです。`RunConfig(model_provider=...)` を渡すと、グローバルデフォルトではなく、その provider が転送方式の選択を制御します。
トランスポート選択は、SDK がモデル名をモデルインスタンスに解決する際に行われます。具体的な [`Model`][agents.models.interface.Model] オブジェクトを渡した場合、そのトランスポートはすでに固定されています。[`OpenAIResponsesWSModel`][agents.models.openai_responses.OpenAIResponsesWSModel] は websocket、[`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] は HTTP、[`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] は Chat Completions のままです。`RunConfig(model_provider=...)` を渡した場合は、グローバルデフォルトではなくそのプロバイダーがトランスポート選択を制御します。
WebSocket 転送は、provider 単位または実行単位でも設定できます。
websocket トランスポートは、プロバイダー単位または実行単位でも設定できます。
```python
from agents import Agent, OpenAIProvider, RunConfig, Runner
@@ -110,48 +110,48 @@ result = await Runner.run(
)
```
プレフィックスベースのモデルルーティング（たとえば 1 回の実行で `openai/...` と `litellm/...` のモデル名を混在）を使う必要がある場合は、[`MultiProvider`][agents.MultiProvider] を使い、代わりに `openai_use_responses_websocket=True` をそこで設定してください。
プレフィックスベースのモデルルーティング（例: 1 回の実行で `openai/...` と `litellm/...` のモデル名を混在）を使う必要がある場合は、代わりに [`MultiProvider`][agents.MultiProvider] を使い、そこで `openai_use_responses_websocket=True` を設定してください。
カスタムの OpenAI 互換 endpoint や proxy を使う場合、WebSocket 転送には互換性のある WebSocket `/responses` endpoint も必要です。これらの構成では `websocket_base_url` を明示的に設定する必要がある場合があります。
カスタムの OpenAI 互換エンドポイントまたはプロキシを使う場合、websocket トランスポートには互換性のある websocket `/responses` エンドポイントも必要です。そのような構成では、`websocket_base_url` を明示的に設定する必要がある場合があります。
注意:
- これは WebSocket 転送上の Responses API であり、[Realtime API](../realtime/guide.md) ではありません。Chat Completions や、Responses WebSocket `/responses` endpoint をサポートしない OpenAI 以外のプロバイダーには適用されません。
- これは websocket トランスポート上の Responses API であり、[Realtime API](../realtime/guide.md) ではありません。Chat Completions や非 OpenAI プロバイダーには、Responses websocket `/responses` エンドポイントをサポートしていない限り適用されません。
- 環境で未導入の場合は、`websockets` パッケージをインストールしてください。
- WebSocket 転送を有効化した後に、[`Runner.run_streamed()`][agents.run.Runner.run_streamed] を直接使用できます。複数ターンのワークフローで、同じ WebSocket 接続をターン間（およびネストされた agent-as-tool 呼び出し間）で再利用したい場合は、[`responses_websocket_session()`][agents.responses_websocket_session] ヘルパーを推奨します。[エージェントの実行](../running_agents.md) ガイドと [`examples/basic/stream_ws.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/stream_ws.py) を参照してください。
- websocket トランスポート有効化後は、[`Runner.run_streamed()`][agents.run.Runner.run_streamed] を直接使えます。複数ターンのワークフローで同じ websocket 接続をターン間（およびネストした Agents-as-tools 呼び出し間）で再利用したい場合は、[`responses_websocket_session()`][agents.responses_websocket_session] ヘルパーの利用を推奨します。[エージェント実行](../running_agents.md) ガイドと [`examples/basic/stream_ws.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/stream_ws.py) を参照してください。
## OpenAI 以外のモデル
## 非 OpenAI モデル
ほとんどの OpenAI 以外のモデルは、[ LiteLLM 統合](./litellm.md) を通じて利用できます。まず、litellm dependency group をインストールします。
ほとんどの非 OpenAI モデルは、[LiteLLM 統合](./litellm.md) 経由で利用できます。まず、litellm 依存関係グループをインストールしてください。
```bash
pip install "openai-agents[litellm]"
```
次に、`litellm/` プレフィックス付きで [サポートされているモデル](https://docs.litellm.ai/docs/providers) を使用します。
次に、`litellm/` プレフィックス付きで任意の[対応モデル](https://docs.litellm.ai/docs/providers)を使います。
```python
claude_agent = Agent(model="litellm/anthropic/claude-3-5-sonnet-20240620", ...)
gemini_agent = Agent(model="litellm/gemini/gemini-2.5-flash-preview-04-17", ...)
```
### OpenAI 以外のモデルを使う他の方法
### 非 OpenAI モデルを使うその他の方法
他の LLM provider は、さらに 3 つの方法で統合できます（コード例は [こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)）。
他の LLM プロバイダーは、さらに 3 つの方法で統合できます（コード例は[こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)）。
1. [`set_default_openai_client`][agents.set_default_openai_client] は、`AsyncOpenAI` のインスタンスを LLM クライアントとしてグローバルに使いたい場合に有用です。これは、LLM provider が OpenAI 互換 API endpoint を持ち、`base_url` と `api_key` を設定できる場合向けです。設定可能な例は [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py) を参照してください。
2. [`ModelProvider`][agents.models.interface.ModelProvider] は `Runner.run` レベルです。これにより「この実行のすべてのエージェントにカスタムモデル provider を使う」と指定できます。設定可能な例は [examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py) を参照してください。
3. [`Agent.model`][agents.agent.Agent.model] では、特定の Agent インスタンスにモデルを指定できます。これにより、エージェントごとに異なる provider を組み合わせられます。設定可能な例は [examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py) を参照してください。利用可能なモデルの多くを簡単に使う方法としては、[ LiteLLM 統合](./litellm.md) があります。
1. [`set_default_openai_client`][agents.set_default_openai_client] は、`AsyncOpenAI` のインスタンスを LLM クライアントとしてグローバルに使いたい場合に有用です。これは、LLM プロバイダーが OpenAI 互換 API エンドポイントを持ち、`base_url` と `api_key` を設定できるケース向けです。設定可能なコード例は [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py) を参照してください。
2. [`ModelProvider`][agents.models.interface.ModelProvider] は `Runner.run` レベルです。これにより、「この実行のすべてのエージェントにカスタムモデルプロバイダーを使う」と指定できます。設定可能なコード例は [examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py) を参照してください。
3. [`Agent.model`][agents.agent.Agent.model] では、特定の Agent インスタンスに対してモデルを指定できます。これにより、エージェントごとに異なるプロバイダーを組み合わせられます。設定可能なコード例は [examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py) を参照してください。利用可能な多くのモデルを簡単に使う方法として、[LiteLLM 統合](./litellm.md) があります。
`platform.openai.com` の API キーを持っていない場合は、`set_tracing_disabled()` によってトレーシングを無効化するか、[別のトレーシングプロセッサー](../tracing.md) を設定することを推奨します。
`platform.openai.com` の API キーを持っていない場合は、`set_tracing_disabled()` でトレーシングを無効化するか、[別のトレーシングプロセッサー](../tracing.md) を設定することを推奨します。
!!! note
これらの例では、ほとんどの LLM provider がまだ Responses API をサポートしていないため、Chat Completions API / model を使っています。LLM provider が対応している場合は、Responses の利用を推奨します。
これらのコード例では、ほとんどの LLM プロバイダーがまだ Responses API をサポートしていないため、Chat Completions API / モデルを使っています。LLM プロバイダーが対応している場合は、Responses の利用を推奨します。
## 高度なモデル選択と混在
単一のワークフロー内で、エージェントごとに異なるモデルを使いたい場合があります。たとえば、トリアージには小型で高速なモデルを使い、複雑なタスクにはより大型で高性能なモデルを使う、といった構成です。[`Agent`][agents.Agent] を設定する際は、次のいずれかで特定モデルを選択できます。
単一ワークフロー内で、エージェントごとに異なるモデルを使いたい場合があります。たとえば、トリアージには小型で高速なモデルを使い、複雑なタスクにはより大型で高性能なモデルを使えます。[`Agent`][agents.Agent] を設定する際は、次のいずれかで特定モデルを選択できます。
1. モデル名を渡す。
2. 任意のモデル名 + その名前を Model インスタンスにマッピングできる [`ModelProvider`][agents.models.interface.ModelProvider] を渡す。
@@ -159,7 +159,7 @@ gemini_agent = Agent(model="litellm/gemini/gemini-2.5-flash-preview-04-17", ...)
!!!note
SDK は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] と [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] の両方の形状をサポートしていますが、2 つの形状はサポートする機能とツールのセットが異なるため、各ワークフローでは単一のモデル形状を使うことを推奨します。ワークフローでモデル形状の混在が必要な場合は、使用するすべての機能が両方で利用可能であることを確認してください。
SDK は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] と [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] の両方の形式をサポートしますが、2 つはサポートする機能とツールのセットが異なるため、ワークフローごとに単一のモデル形式を使うことを推奨します。ワークフローでモデル形式を混在させる必要がある場合は、使用するすべての機能が両方で利用可能であることを確認してください。
```python
from agents import Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel
@@ -195,7 +195,7 @@ async def main():
1. OpenAI モデル名を直接設定します。
2. [`Model`][agents.models.interface.Model] 実装を提供します。
エージェントで使うモデルをさらに設定したい場合は、温度などの任意のモデル設定パラメーターを提供する [`ModelSettings`][agents.models.interface.ModelSettings] を渡せます。
エージェントで使うモデルをさらに設定したい場合は、temperature などの任意のモデル設定パラメーターを提供する [`ModelSettings`][agents.models.interface.ModelSettings] を渡せます。
```python
from agents import Agent, ModelSettings
@@ -208,7 +208,37 @@ english_agent = Agent(
)
```
また、OpenAI の Responses API を使う場合、[他にもいくつかの任意パラメーター](https://platform.openai.com/docs/api-reference/responses/create)（例: `user`、`service_tier` など）があります。これらがトップレベルで利用できない場合でも、`extra_args` を使って渡せます。
#### 一般的な高度な `ModelSettings` オプション
OpenAI Responses API を使っている場合、いくつかのリクエストフィールドにはすでに直接対応する `ModelSettings` フィールドがあるため、`extra_args` は不要です。
| フィールド | 用途 |
| --- | --- |
| `parallel_tool_calls` | 同一ターン内で複数のツール呼び出しを許可または禁止します。 |
| `truncation` | コンテキスト超過時に失敗する代わりに、Responses API が最も古い会話項目を破棄できるよう `"auto"` を設定します。 |
| `prompt_cache_retention` | たとえば `"24h"` のように、キャッシュされたプロンプトプレフィックスをより長く保持します。 |
| `response_include` | `web_search_call.action.sources`、`file_search_call.results`、`reasoning.encrypted_content` など、より豊富なレスポンスペイロードを要求します。 |
| `top_logprobs` | 出力テキストの上位トークン logprobs を要求します。SDK は `message.output_text.logprobs` も自動で追加します。 |
```python
from agents import Agent, ModelSettings
research_agent = Agent(
name="Research agent",
model="gpt-5.2",
model_settings=ModelSettings(
parallel_tool_calls=False,
truncation="auto",
prompt_cache_retention="24h",
response_include=["web_search_call.action.sources"],
top_logprobs=5,
),
)
```
SDK がまだトップレベルで直接公開していない、プロバイダー固有または新しいリクエストフィールドが必要な場合に `extra_args` を使います。
また、OpenAI の Responses API を使う場合、[他にもいくつかの任意パラメーター](https://platform.openai.com/docs/api-reference/responses/create)（例: `user`、`service_tier` など）があります。これらがトップレベルで利用できない場合も、`extra_args` で渡せます。
```python
from agents import Agent, ModelSettings
@@ -224,26 +254,26 @@ english_agent = Agent(
)
```
## OpenAI 以外のプロバイダーのトラブルシューティング
## 非 OpenAI プロバイダーのトラブルシューティング
### トレーシングクライアントエラー 401
トレーシング関連のエラーが出る場合、トレースは OpenAI サーバーにアップロードされる一方で、OpenAI API キーがないことが原因です。解決方法は 3 つあります。
トレーシング関連のエラーが出る場合、これはトレースが OpenAI サーバーにアップロードされる一方で OpenAI API キーを持っていないためです。解決方法は 3 つあります。
1. トレーシングを完全に無効化する: [`set_tracing_disabled(True)`][agents.set_tracing_disabled]。
2. トレーシング用の OpenAI キーを設定する: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]。この API キーはトレースのアップロードにのみ使用され、[platform.openai.com](https://platform.openai.com/) のものが必要です。
3. OpenAI 以外のトレースプロセッサーを使う。[トレーシングドキュメント](../tracing.md#custom-tracing-processors)を参照してください。
2. トレーシング用の OpenAI キーを設定する: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]。この API キーはトレースのアップロードのみに使われ、[platform.openai.com](https://platform.openai.com/) 発行のものが必要です。
3. 非 OpenAI のトレースプロセッサーを使う。[トレーシングドキュメント](../tracing.md#custom-tracing-processors)を参照してください。
### Responses API サポート
SDK はデフォルトで Responses API を使いますが、ほとんどの他の LLM provider はまだ対応していません。その結果、404 や類似の問題が発生する場合があります。解決するには次の 2 つの方法があります。
SDK はデフォルトで Responses API を使いますが、ほとんどの他 LLM プロバイダーはまだこれをサポートしていません。その結果、404 や類似の問題が発生することがあります。解決方法は 2 つあります。
1. [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api] を呼び出す。これは環境変数で `OPENAI_API_KEY` と `OPENAI_BASE_URL` を設定している場合に機能します。
2. [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] を使う。コード例は [こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/) にあります。
2. [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] を使う。コード例は [こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/) です。
### structured outputs サポート
一部のモデル provider は [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) をサポートしていません。これにより、次のようなエラーが発生することがあります。
一部のモデルプロバイダーは [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) をサポートしていません。これにより、次のようなエラーが発生する場合があります。
```
@@ -251,12 +281,12 @@ BadRequestError: Error code: 400 - {'error': {'message': "'response_format.type'
```
これは一部のモデル provider の制約です。JSON 出力はサポートしていても、出力で使う `json_schema` を指定できません。この問題の修正を進めていますが、JSON schema 出力をサポートする provider に依存することを推奨します。そうでない場合、JSON の形式不正によりアプリが頻繁に壊れるためです。
これは一部モデルプロバイダーの制約です。JSON 出力はサポートしていても、出力に使用する `json_schema` を指定できません。現在修正に取り組んでいますが、JSON schema 出力をサポートするプロバイダーへの依存を推奨します。そうでない場合、不正な JSON によりアプリが頻繁に壊れる可能性があります。
## プロバイダー間でのモデル混在
モデル provider 間の機能差を認識しておく必要があります。そうしないとエラーに遭遇する可能性があります。たとえば OpenAI は structured outputs、マルチモーダル入力、ホスト型のファイル検索と Web 検索をサポートしますが、多くの他プロバイダーはこれらをサポートしません。次の制約に注意してください。
モデルプロバイダー間の機能差を把握する必要があります。把握していないとエラーになる可能性があります。たとえば OpenAI は structured outputs、マルチモーダル入力、ホストされたファイル検索と Web 検索をサポートしますが、他の多くのプロバイダーはこれらをサポートしません。次の制約に注意してください。
- 非対応の provider には、理解できない `tools` を送信しない
- テキスト専用モデルを呼び出す前に、マルチモーダル入力を除外する
- structured JSON 出力をサポートしない provider は、無効な JSON をときどき生成する点に注意する
- 対応していないプロバイダーに未対応の `tools` を送らない
- テキスト専用モデルを呼び出す前にマルチモーダル入力を除外する
- structured JSON 出力をサポートしないプロバイダーは、ときどき無効な JSON を生成することを認識する
docs/ja/sessions/index.md
+108 -77
View File
@@ -4,11 +4,11 @@ search:
---
# セッション
Agents SDK は、複数回のエージェント実行にまたがって会話履歴を自動的に維持する組み込みのセッションメモリを提供し、ターン間で `.to_input_list()` を手動処理する必要をなくします。
Agents SDK は組み込みのセッションメモリを提供し、複数のエージェント実行にまたがる会話履歴を自動で維持するため、ターン間で `.to_input_list()` を手動で扱う必要がありません。
Sessions は特定のセッションの会話履歴を保存し、明示的な手動メモリ管理を必要とせずにエージェントがコンテキストを維持できるようにします。これは、エージェントに過去のやり取りを記憶させたいチャットアプリケーションや複数ターンの会話を構築する際に特に有用です。
Sessions は特定のセッションの会話履歴を保存し、明示的な手動メモリ管理なしでエージェントがコンテキストを維持できるようにします。これは、エージェントに過去のやり取りを記憶させたいチャットアプリケーションや複数ターンの会話を構築する際に特に有用です。
SDK にクライアント側メモリ管理を任せたい場合は sessions を使用します。すでに `conversation_id` または `previous_response_id` を使って OpenAI のサーバー管理 state を利用している場合、通常は同じ会話に対して session も併用する必要はありません。
SDK にクライアント側メモリを管理させたい場合は、セッションを使用します。すでに `conversation_id` または `previous_response_id` を使って OpenAI のサーバー管理状態を使用している場合、通常は同じ会話に対してセッションを併用する必要はありません。
## クイックスタート
@@ -49,9 +49,9 @@ result = Runner.run_sync(
print(result.final_output) # "Approximately 39 million"
```
## 同一 session を使った中断実行の再開
## 同一セッションによる中断実行の再開
実行が承認待ちで一時停止した場合は、同じ session インスタンス（または同じ backing store を指す別の session インスタンス）で再開してください。これにより、再開したターンは同じ保存済み会話履歴を継続します。
実行が承認待ちで一時停止した場合は、同じセッションインスタンス（または同じバックエンドストアを指す別のセッションインスタンス）で再開し、再開ターンが同じ保存済み会話履歴を継続するようにします。
```python
result = await Runner.run(agent, "Delete temporary files that are no longer needed.", session=session)
@@ -65,27 +65,27 @@ if result.interruptions:
## セッションのコア動作
session メモリが有効な場合:
セッションメモリが有効な場合:
1. **各実行前**: runner は session の会話履歴を自動取得し、入力アイテムの先頭に追加します。
2. **各実行後**: 実行中に生成されたすべての新規アイテム（ユーザー入力、assistant 応答、ツール呼び出しなど）が自動的に session に保存されます。
3. **コンテキスト保持**: 同じ session を使う後続の各実行には会話履歴全体が含まれ、エージェントがコンテキストを維持できます。
1. **各実行前**: ランナーはセッションの会話履歴を自動で取得し、入力アイテムの先頭に追加します。
2. **各実行後**: 実行中に生成されたすべての新規アイテム（ユーザー入力、アシスタント応答、ツール呼び出しなど）が自動的にセッションへ保存されます。
3. **コンテキスト維持**: 同じセッションでの後続実行には会話履歴全体が含まれ、エージェントがコンテキストを維持できます。
これにより、`.to_input_list()` を手動で呼び出して実行間の会話 state を管理する必要がなくなります。
これにより、 `.to_input_list()` の手動呼び出しや、実行間の会話状態管理が不要になります。
## 履歴と新規入力のマージ方法の制御
## 履歴と新規入力のマージ制御
session を渡すと、runner は通常次のように model 入力を準備します:
セッションを渡すと、ランナーは通常次のようにモデル入力を準備します:
1. Session 履歴（`session.get_items(...)` から取得）
2. 新規ターン入力
1. セッション履歴（ `session.get_items(...)` から取得）
2. 新しいターン入力
model 呼び出し前のこのマージ処理をカスタマイズするには [`RunConfig.session_input_callback`][agents.run.RunConfig.session_input_callback] を使用します。callback は次の 2 つのリストを受け取ります:
モデル呼び出し前のこのマージ手順をカスタマイズするには、 [`RunConfig.session_input_callback`][agents.run.RunConfig.session_input_callback] を使用します。コールバックは次の 2 つのリストを受け取ります:
- `history`: 取得した session 履歴（すでに入力アイテム形式へ正規化済み）
- `new_input`: 現在のターンの新規入力アイテム
- `history`: 取得されたセッション履歴（すでに入力アイテム形式に正規化済み）
- `new_input`: 現在ターンの新規入力アイテム
model に送信する最終的な入力アイテムのリストを返してください。
モデルに送信すべき最終的な入力アイテムのリストを返してください。
```python
from agents import Agent, RunConfig, Runner, SQLiteSession
@@ -107,16 +107,16 @@ result = await Runner.run(
)
```
これは、session のアイテム保存方法を変更せずに、履歴のカスタム削減、並べ替え、または選択的な取り込みを行いたい場合に使用します。
セッションでのアイテム保存方法を変更せずに、履歴のカスタムな間引き、並べ替え、または選択的な含有が必要な場合に使用します。
## 取得履歴の制限
各実行前にどの程度の履歴を取得するかを制御するには [`SessionSettings`][agents.memory.SessionSettings] を使用します。
各実行前に取得する履歴量を制御するには、 [`SessionSettings`][agents.memory.SessionSettings] を使用します。
- `SessionSettings(limit=None)`（デフォルト）: 利用可能なすべての session アイテムを取得
- `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
@@ -132,13 +132,13 @@ result = await Runner.run(
)
```
session 実装がデフォルトの session settings を公開している場合、`RunConfig.session_settings` はその実行において `None` 以外の値を上書きします。これは、session のデフォルト動作を変えずに取得サイズを制限したい長い会話で有用です。
セッション実装がデフォルトのセッション設定を公開している場合、 `RunConfig.session_settings` はその実行において `None` でない値を上書きします。これは、セッションのデフォルト動作を変えずに取得サイズを制限したい長い会話で有用です。
## メモリ操作
### 基本操作
Sessions は会話履歴管理のために複数の操作をサポートします:
Sessions は会話履歴を管理するための複数の操作をサポートします:
```python
from agents import SQLiteSession
@@ -165,7 +165,7 @@ await session.clear_session()
### 修正のための pop_item の使用
`pop_item` メソッドは、会話内の最後のアイテムを取り消したい、または変更したい場合に特に有用です:
`pop_item` メソッドは、会話の最後のアイテムを取り消したり変更したい場合に特に有用です:
```python
from agents import Agent, Runner, SQLiteSession
@@ -194,30 +194,31 @@ result = await Runner.run(
print(f"Agent: {result.final_output}")
```
## 組み込み session 実装
## 組み込みセッション実装
SDK は異なるユースケース向けに複数の session 実装を提供します:
SDK は異なるユースケース向けに複数のセッション実装を提供します:
### 組み込み session 実装の選択
### 組み込みセッション実装の選択
以下の詳細な例を読む前に、この表を使って開始点を選んでください。
| Session type | Best for | Notes |
| --- | --- | --- |
| `SQLiteSession` | ローカル開発とシンプルなアプリ | 組み込み、軽量、ファイルまたはメモリベース |
| `SQLiteSession` | ローカル開発とシンプルなアプリ | 組み込み、軽量、ファイルベースまたはインメモリ |
| `AsyncSQLiteSession` | `aiosqlite` を使う非同期 SQLite | 非同期ドライバー対応の拡張バックエンド |
| `RedisSession` | ワーカー/サービス間で共有するメモリ | 低レイテンシな分散デプロイに適しています |
| `RedisSession` | ワーカー/サービス間で共有するメモリ | 低レイテンシーな分散デプロイに適しています |
| `SQLAlchemySession` | 既存データベースを使う本番アプリ | SQLAlchemy 対応データベースで動作 |
| `DaprSession` | Dapr サイドカーを使うクラウドネイティブデプロイ | 複数のステートストアに加え TTL と整合性制御をサポート |
| `OpenAIConversationsSession` | OpenAI でのサーバー管理ストレージ | OpenAI Conversations API ベースの履歴 |
| `OpenAIResponsesCompactionSession` | 自動 compact を伴う長い会話 | 別の session バックエンドを包むラッパー |
| `AdvancedSQLiteSession` | 分岐/分析付き SQLite | 機能は重厚です。専用ページを参照してください |
| `EncryptedSession` | 別 session の上に暗号化 + TTL | ラッパーです。先に基盤バックエンドを選択してください |
| `OpenAIResponsesCompactionSession` | 自動圧縮を伴う長い会話 | 別のセッションバックエンドをラップ |
| `AdvancedSQLiteSession` | 分岐/分析機能付き SQLite | 機能が多い実装です。専用ページを参照してください |
| `EncryptedSession` | 別セッション上での暗号化 + TTL | ラッパーです。先に基盤バックエンドを選択してください |
一部の実装には追加詳細を記載した専用ページがあり、各サブセクション内でリンクされています。
一部の実装には追加詳細を記載した専用ページがあります。各サブセクション内でリンクしています。
### 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
@@ -251,11 +252,11 @@ result = await Runner.run(
print(result.final_output) # "California"
```
### OpenAI Responses compact セッション
### OpenAI Responses 圧縮セッション
Responses API (`responses.compact`) を使って保存済み会話履歴を compact するには `OpenAIResponsesCompactionSession` を使用します。これは基盤となる session をラップし、`should_trigger_compaction` に基づいて各ターン後に自動で compact できます。`OpenAIConversationsSession` をこれでラップしないでください。この 2 つの機能は履歴を異なる方法で管理します。
Responses API （ `responses.compact` ）で保存済み会話履歴を圧縮するには `OpenAIResponsesCompactionSession` を使用します。これは基盤セッションをラップし、 `should_trigger_compaction` に基づいて各ターン後に自動圧縮できます。 `OpenAIConversationsSession` をこれでラップしないでください。両者は異なる方法で履歴を管理します。
#### 一般的な使用方法（自動 compact）
#### 典型的な使用法（自動圧縮）
```python
from agents import Agent, Runner, SQLiteSession
@@ -272,15 +273,15 @@ result = await Runner.run(agent, "Hello", session=session)
print(result.final_output)
```
デフォルトでは、候補しきい値に達すると各ターン後に compact が実行されます。
デフォルトでは、候補しきい値に達すると各ターン後に圧縮が実行されます。
`compaction_mode="previous_response_id"` は、Responses API の response ID でターンをすでに連結している場合に最適です。`compaction_mode="input"` は代わりに現在の session アイテムから compact リクエストを再構築します。これは response chain が利用できない場合や、session 内容を信頼できる唯一の情報源にしたい場合に有用です。デフォルトの `"auto"` は利用可能な中で最も安全な方法を選びます。
`compaction_mode="previous_response_id"` は、Responses API の response ID ですでにターン連結している場合に最適です。 `compaction_mode="input"` は代わりに現在のセッションアイテムから圧縮リクエストを再構築するため、応答チェーンが利用できない場合やセッション内容を信頼できる情報源にしたい場合に有用です。デフォルトの `"auto"` は利用可能な中で最も安全なオプションを選択します。
#### 自動 compact はストリーミングをブロックする可能性
#### 自動圧縮はストリーミングをブロックする可能性
compact は session 履歴を消去して再書き込みするため、SDK は compact 完了まで実行完了と見なしません。ストリーミングモードでは、compact が重い場合、最後の出力トークン後も `run.stream_events()` が数秒間開いたままになることがあります。
圧縮はセッション履歴をクリアして書き直すため、SDK は圧縮完了まで実行完了とみなしません。ストリーミングモードでは、圧縮が重い場合、最後の出力トークンの後も `run.stream_events()` が数秒開いたままになることがあります。
低レイテンシのストリーミングや高速なターン交代が必要な場合は、自動 compact を無効にし、ターン間（またはアイドル時間）で `run_compaction()` を自分で呼び出してください。独自の基準に基づいて compact を強制するタイミングを決められます。
低レイテンシーなストリーミングや高速なターン切り替えが必要な場合は、自動圧縮を無効にし、ターン間（またはアイドル時間）に `run_compaction()` を手動で呼び出してください。独自の基準に基づいて圧縮を強制するタイミングを決められます。
```python
from agents import Agent, Runner, SQLiteSession
@@ -303,7 +304,7 @@ await session.run_compaction({"force": True})
### SQLite セッション
SQLite を使用するデフォルトの軽量 session 実装です:
SQLite を使用したデフォルトの軽量セッション実装です:
```python
from agents import SQLiteSession
@@ -341,7 +342,7 @@ result = await Runner.run(agent, "Hello", session=session)
### Redis セッション
複数ワーカーまたはサービス間で共有する session メモリには `RedisSession` を使用します。
複数ワーカーまたはサービス間で共有するセッションメモリには `RedisSession` を使用します。
```bash
pip install openai-agents[redis]
@@ -361,7 +362,7 @@ result = await Runner.run(agent, "Hello", session=session)
### SQLAlchemy セッション
SQLAlchemy 対応の任意のデータベースを使う、本番対応の session です:
SQLAlchemy 対応の任意のデータベースを使う本番対応セッションです:
```python
from agents.extensions.memory import SQLAlchemySession
@@ -381,11 +382,41 @@ session = SQLAlchemySession("user_123", engine=engine, create_tables=True)
詳細は [SQLAlchemy Sessions](sqlalchemy_session.md) を参照してください。
### Dapr セッション
すでに Dapr サイドカーを運用している場合、またはエージェントコードを変更せずに異なるステートストアバックエンド間で移行可能なセッションストレージが必要な場合は `DaprSession` を使用します。
```bash
pip install openai-agents[dapr]
```
```python
from agents import Agent, Runner
from agents.extensions.memory import DaprSession
agent = Agent(name="Assistant")
async with DaprSession.from_address(
"user_123",
state_store_name="statestore",
dapr_address="localhost:50001",
) as session:
result = await Runner.run(agent, "Hello", session=session)
print(result.final_output)
```
注意:
- `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) を参照してください。
### Advanced SQLite セッション
会話分岐、使用分析、構造化クエリを備えた拡張 SQLite セッションです:
会話分岐、利用分析、structured outputs クエリを備えた強化 SQLite セッションです:
```python
from agents.extensions.memory import AdvancedSQLiteSession
@@ -409,7 +440,7 @@ await session.create_branch_from_turn(2) # Branch from turn 2
### 暗号化セッション
任意の session 実装向けの透過的暗号化ラッパーです:
任意のセッション実装向けの透過的な暗号化ラッパーです:
```python
from agents.extensions.memory import EncryptedSession, SQLAlchemySession
@@ -434,15 +465,15 @@ result = await Runner.run(agent, "Hello", session=session)
詳細は [Encrypted Sessions](encrypted_session.md) を参照してください。
### その他の session タイプ
### その他のセッションタイプ
そのほかにもいくつかの組み込みオプションがあります。`examples/memory/` と `extensions/memory/` 配下のソースコードを参照してください。
この他にもいくつかの組み込みオプションがあります。 `examples/memory/` と `extensions/memory/` 配下のソースコードを参照してください。
## 運用パターン
### Session ID 命名
### セッション ID 命名
会話整理に役立つ意味のある session ID を使用してください:
会話を整理しやすい意味のあるセッション ID を使用してください:
- ユーザーベース: `"user_12345"`
- スレッドベース: `"thread_abc123"`
@@ -450,17 +481,17 @@ 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="...")`）を使用
- 共有かつ低レイテンシな session メモリには Redis バックエンド session（`RedisSession.from_url("session_id", url="redis://...")`）を使用
- SQLAlchemy がサポートする既存データベースを持つ本番システムには SQLAlchemy 駆動 session（`SQLAlchemySession("session_id", engine=engine, create_tables=True)`）を使用
- 組み込み telemetry、トレーシング、データ分離を備え、30 を超えるデータベースバックエンドをサポートする本番クラウドネイティブデプロイには Dapr state store session（`DaprSession.from_address("session_id", state_store_name="statestore", dapr_address="localhost:50001")`）を使用
- OpenAI Conversations API に履歴を保存したい場合は OpenAI ホスト型ストレージ（`OpenAIConversationsSession()`）を使用
- 任意の session を透過的暗号化と TTL ベース有効期限でラップするには暗号化 session（`EncryptedSession(session_id, underlying_session, encryption_key)`）を使用
- より高度なユースケースでは、他の本番システム（例: Django）向けのカスタム 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 ステートストアセッション（ `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）向けのカスタムセッションバックエンド実装を検討
### 複数 session
### 複数セッション
```python
from agents import Agent, Runner, SQLiteSession
@@ -483,7 +514,7 @@ result2 = await Runner.run(
)
```
### session 共有
### セッション共有
```python
# Different agents can share the same session
@@ -506,7 +537,7 @@ result2 = await Runner.run(
## 完全な例
session メモリの動作を示す完全な例です:
以下はセッションメモリが動作する完全な例です:
```python
import asyncio
@@ -568,9 +599,9 @@ if __name__ == "__main__":
asyncio.run(main())
```
## カスタム session 実装
## カスタムセッション実装
[`Session`][agents.memory.session.Session] プロトコルに従うクラスを作成することで、独自の session メモリを実装できます:
[`Session`][agents.memory.session.Session] プロトコルに従うクラスを作成することで、独自のセッションメモリを実装できます:
```python
from agents.memory.session import SessionABC
@@ -613,15 +644,15 @@ result = await Runner.run(
)
```
## コミュニティ session 実装
## コミュニティセッション実装
コミュニティにより追加の session 実装が開発されています:
コミュニティにより追加のセッション実装が開発されています:
| Package | Description |
|---------|-------------|
| [openai-django-sessions](https://pypi.org/project/openai-django-sessions/) | 任意の Django 対応データベース（PostgreSQL、MySQL、SQLite など）向けの Django ORM ベース session |
| [openai-django-sessions](https://pypi.org/project/openai-django-sessions/) | Django がサポートする任意のデータベース（ PostgreSQL 、 MySQL 、 SQLite など）向けの Django ORM ベースセッション |
session 実装を構築した場合は、ぜひここに追加するための documentation PR を提出してください。
セッション実装を作成した場合は、ここに追加するためのドキュメント PR をぜひ提出してください。
## API リファレンス
@@ -629,11 +660,11 @@ session 実装を構築した場合は、ぜひここに追加するための do
- [`Session`][agents.memory.session.Session] - プロトコルインターフェース
- [`OpenAIConversationsSession`][agents.memory.OpenAIConversationsSession] - OpenAI Conversations API 実装
- [`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession] - Responses API compact ラッパー
- [`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 バックエンド session 実装
- [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - SQLAlchemy 駆動実装
- [`DaprSession`][agents.extensions.memory.dapr_session.DaprSession] - Dapr state store 実装
- [`AdvancedSQLiteSession`][agents.extensions.memory.advanced_sqlite_session.AdvancedSQLiteSession] - 分岐と分析を備えた拡張 SQLite
- [`EncryptedSession`][agents.extensions.memory.encrypt_session.EncryptedSession] - 任意の session 向け暗号化ラッパー
- [`RedisSession`][agents.extensions.memory.redis_session.RedisSession] - Redis ベースのセッション実装
- [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - SQLAlchemy ベース実装
- [`DaprSession`][agents.extensions.memory.dapr_session.DaprSession] - Dapr ステートストア実装
- [`AdvancedSQLiteSession`][agents.extensions.memory.advanced_sqlite_session.AdvancedSQLiteSession] - 分岐と分析機能を備えた強化 SQLite
- [`EncryptedSession`][agents.extensions.memory.encrypt_session.EncryptedSession] - 任意セッション向け暗号化ラッパー
docs/ko/examples.md
+33 -31
View File
@@ -2,9 +2,9 @@
search:
exclude: true
---
# 예제
# 코드 예제
[repo](https://github.com/openai/openai-agents-python/tree/main/examples)의 examples 섹션에서 SDK의 다양한 sample 구현을 확인하세요. examples는 여러 카테고리로 구성되어 있으며, 서로 다른 패턴과 기능을 보여줍니다.
[repo](https://github.com/openai/openai-agents-python/tree/main/examples)의 예제 섹션에서 SDK의 다양한 샘플 구현을 확인해 보세요. 예제는 서로 다른 패턴과 기능을 보여주는 여러 카테고리로 구성되어 있습니다
## 카테고리
@@ -15,85 +15,87 @@ search:
- Agents as tools
- 병렬 에이전트 실행
- 조건부 도구 사용
- 입력/출력 가드레일
- 판정자로서의 LLM
- 입출력 가드레일
- 심판으로서의 LLM
- 라우팅
- 스트리밍 가드레일
- **[basic](https://github.com/openai/openai-agents-python/tree/main/examples/basic):**
이 예제들은 다음과 같은 SDK의 기초 기능을 보여줍니다
이 예제들은 다음과 같은 SDK의 기본 기능을 보여줍니다
- Hello World 예제(기본 모델, GPT-5, open-weight 모델)
- 에이전트 라이프사이클 관리
- Hello World 예제(Default model, GPT-5, open-weight model)
- 에이전트 수명 주기 관리
- 동적 시스템 프롬프트
- 스트리밍 출력(텍스트, 항목, 함수 호출 인자)
- turns 전반에 걸쳐 공유 세션 헬퍼를 사용하는 Responses websocket 전송(`examples/basic/stream_ws.py`)
- 스트리밍 출력(text, items, function call args)
- 턴 전반에 걸쳐 공유 세션 헬퍼를 사용하는 Responses websocket 전송(`examples/basic/stream_ws.py`)
- 프롬프트 템플릿
- 파일 처리(로컬 및 원격, 이미지 및 PDF)
- 사용량 추적
- 엄격하지 않은 출력 타입
- 이전 response ID 사용
- 비엄격 출력 유형
- 이전 응답 ID 사용
- **[customer_service](https://github.com/openai/openai-agents-python/tree/main/examples/customer_service):**
항공사를 위한 고객 서비스 시스템 예제입니다.
항공사를 위한 고객 서비스 시스템 예제
- **[financial_research_agent](https://github.com/openai/openai-agents-python/tree/main/examples/financial_research_agent):**
금융 데이터 분석을 위한 에이전트와 도구로 구성된 structured 리서치 워크플로를 보여주는 금융 리서치 에이전트입니다.
금융 데이터 분석을 위한 에이전트와 도구를 활용한 구조화된 리서치 워크플로를 보여주는 금융 리서치 에이전트
- **[handoffs](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs):**
메시지 필터링을 사용한 에이전트 핸드오프의 실용적인 예제를 확인하세요.
메시지 필터링을 사용한 에이전트 핸드오프의 실용적인 예제를 확인해 보세요
- **[hosted_mcp](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp):**
hosted MCP(Model context protocol) 커넥터와 승인(approval)을 사용하는 방법을 보여주는 예제입니다.
호스티드 MCP(Model context protocol) 커넥터와 승인 사용 방법을 보여주는 예제
- **[mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp):**
다음을 포함하여 MCP(Model context protocol)로 에이전트를 만드는 방법을 알아보세요
다음을 포함하여 MCP(Model context protocol)로 에이전트를 구축하는 방법을 알아보세요
- 파일시스템 예제
- 파일 시스템 예제
- Git 예제
- MCP 프롬프트 서버 예제
- SSE(Server-Sent Events) 예제
- 스트리밍 가능한 HTTP 예제
- **[memory](https://github.com/openai/openai-agents-python/tree/main/examples/memory):**
다음을 포함해 에이전트의 다양한 메모리 구현 예제입니다
다음을 포함한 에이전트를 위한 다양한 메모리 구현 예제
- SQLite 세션 스토리지
- 고급 SQLite 세션 스토리지
- Redis 세션 스토리지
- SQLAlchemy 세션 스토리지
- Dapr 상태 저장소 세션 스토리지
- 암호화된 세션 스토리지
- OpenAI 세션 스토리지
- OpenAI Conversations 세션 스토리지
- Responses 압축 세션 스토리지
- **[model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):**
커스텀 프로바이더와 LiteLLM 통합을 포함해, SDK에서 OpenAI가 아닌 모델을 사용하는 방법을 살펴보세요.
사용자 지정 provider와 LiteLLM 통합을 포함하여 SDK에서 OpenAI 이외의 모델을 사용하는 방법을 살펴보세요
- **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):**
다음을 포함해 SDK로 실시간 경험을 만드는 방법을 보여주는 예제입니다
다음을 포함하여 SDK를 사용해 실시간 경험을 구축하는 방법을 보여주는 예제
- 웹 애플리케이션
- 커맨드라인 인터페이스
- 명령줄 인터페이스
- Twilio 통합
- Twilio SIP 통합
- **[reasoning_content](https://github.com/openai/openai-agents-python/tree/main/examples/reasoning_content):**
reasoning content와 structured outputs를 다루는 방법을 보여주는 예제입니다.
reasoning content 및 structured outputs를 다루는 방법을 보여주는 예제
- **[research_bot](https://github.com/openai/openai-agents-python/tree/main/examples/research_bot):**
복잡한 멀티 에이전트 리서치 워크플로를 보여주는 간단한 딥 리서치 클론입니다.
복잡한 멀티 에이전트 리서치 워크플로를 보여주는 간단한 딥 리서치 클론
- **[tools](https://github.com/openai/openai-agents-python/tree/main/examples/tools):**
다음과 같은 OpenAI 호스트하는 도구와 실험적 Codex 도구를 구현하는 방법을 알아보세요
다음과 같은 OAI hosted tools 및 실험적 Codex 도구화를 구현하는 방법을 알아보세요
- 웹 검색 및 필터가 있는 웹 검색
- 웹 검색 및 필터를 사용하는 웹 검색
- 파일 검색
- Code Interpreter
- 인라인 스킬을 사용하는 호스티드 컨테이너 셸(`examples/tools/container_shell_inline_skill.py`)
- 스킬 레퍼런스를 사용하는 호스티드 컨테이너 셸(`examples/tools/container_shell_skill_reference.py`)
- 코드 인터프리터
- 인라인 스킬이 포함된 호스티드 컨테이너 셸(`examples/tools/container_shell_inline_skill.py`)
- 스킬 참조가 포함된 호스티드 컨테이너 셸(`examples/tools/container_shell_skill_reference.py`)
- 컴퓨터 사용
- 이미지 생성
- 실험적 Codex 도구 워크플로(`examples/tools/codex.py`)
- 실험적 Codex same-thread 워크플로(`examples/tools/codex_same_thread.py`)
- 실험적 Codex 동일 스레드 워크플로(`examples/tools/codex_same_thread.py`)
- **[voice](https://github.com/openai/openai-agents-python/tree/main/examples/voice):**
스트리밍 음성 예제를 포함해, TTS 및 STT 모델을 사용하는 음성 에이전트 예제를 확인하세요.
스트리밍 음성 예제를 포함해 TTS 및 STT 모델을 사용하는 음성 에이전트 예제를 확인해 보세요
docs/ko/models/index.md
+75 -45
View File
@@ -6,37 +6,37 @@ search:
Agents SDK 는 OpenAI 모델을 두 가지 방식으로 즉시 사용할 수 있도록 지원합니다:
- **권장**: [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] — 새로운 [Responses API](https://platform.openai.com/docs/api-reference/responses)를 사용해 OpenAI API 를 호출합니다
- [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] — [Chat Completions API](https://platform.openai.com/docs/api-reference/chat)를 사용해 OpenAI API 를 호출합니다
- **권장**: 새로운 [Responses API](https://platform.openai.com/docs/api-reference/responses)를 사용해 OpenAI API 를 호출하는 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]
- [Chat Completions API](https://platform.openai.com/docs/api-reference/chat)를 사용해 OpenAI API 를 호출하는 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]
## 모델 설정 선택
설정에 따라 다음 순서로 이 페이지를 활용하세요:
| 목표 | 시작 위치 |
| 목표 | 시작 지점 |
| --- | --- |
| SDK 기본값으로 OpenAI 호스팅 모델 사용 | [OpenAI 모델](#openai-models) |
| websocket 전송으로 OpenAI Responses API 사용 | [Responses WebSocket 전송](#responses-websocket-transport) |
| OpenAI 이외 제공자 사용 | [비 OpenAI 모델](#non-openai-models) |
| OpenAI 이외 제공자 사용 | [OpenAI 이외 모델](#non-openai-models) |
| 하나의 워크플로에서 모델/제공자 혼합 | [고급 모델 선택 및 혼합](#advanced-model-selection-and-mixing) 및 [제공자 간 모델 혼합](#mixing-models-across-providers) |
| 제공자 호환성 문제 디버깅 | [비 OpenAI 제공자 문제 해결](#troubleshooting-non-openai-providers) |
| 제공자 호환성 문제 디버깅 | [OpenAI 이외 제공자 문제 해결](#troubleshooting-non-openai-providers) |
## OpenAI 모델
`Agent` 를 초기화할 때 모델을 지정하지 않으면 기본 모델이 사용됩니다. 현재 기본값은 호환성과 낮은 지연 시간을 위해 [`gpt-4.1`](https://platform.openai.com/docs/models/gpt-4.1)입니다. 접근 권한이 있다면, 명시적인 `model_settings` 를 유지하면서 더 높은 품질을 위해 에이전트를 [`gpt-5.2`](https://platform.openai.com/docs/models/gpt-5.2)로 설정하는 것을 권장합니다.
`Agent` 를 초기화할 때 모델을 지정하지 않으면 기본 모델이 사용됩니다. 현재 기본값은 호환성과 낮은 지연 시간을 위해 [`gpt-4.1`](https://platform.openai.com/docs/models/gpt-4.1)입니다. 접근 권한이 있다면, 명시적인 `model_settings` 를 유지하면서 더 높은 품질을 위해 에이전트를 [`gpt-5.2`](https://platform.openai.com/docs/models/gpt-5.2)로 설정할 것을 권장합니다.
[`gpt-5.2`](https://platform.openai.com/docs/models/gpt-5.2) 같은 다른 모델로 전환하려면 에이전트를 구성하는 두 가지 방법이 있습니다.
[`gpt-5.2`](https://platform.openai.com/docs/models/gpt-5.2) 같은 다른 모델로 전환하려면, 에이전트를 설정하는 방법이 두 가지 있습니다.
### 기본 모델
첫째, 사용자 지정 모델을 설정하지 않은 모든 에이전트에서 특정 모델을 일관되게 사용하려면, 에이전트를 실행하기 전에 `OPENAI_DEFAULT_MODEL` 환경 변수를 설정하세요.
첫째, 커스텀 모델을 설정하지 않은 모든 에이전트에서 특정 모델을 일관되게 사용하려면, 에이전트를 실행하기 전에 `OPENAI_DEFAULT_MODEL` 환경 변수를 설정하세요.
```bash
export OPENAI_DEFAULT_MODEL=gpt-5.2
python3 my_awesome_agent.py
```
둘째, `RunConfig` 를 통해 실행(run) 단위 기본 모델을 설정할 수 있습니다. 에이전트에 모델을 설정하지 않으면 이 실행의 모델이 사용됩니다.
둘째, `RunConfig` 를 통해 실행 단위 기본 모델을 설정할 수 있습니다. 에이전트에 모델을 설정하지 않으면 이 실행의 모델이 사용됩니다.
```python
from agents import Agent, RunConfig, Runner
@@ -55,7 +55,7 @@ result = await Runner.run(
#### GPT-5.x 모델
이 방식으로 [`gpt-5.2`](https://platform.openai.com/docs/models/gpt-5.2) 같은 GPT-5.x 모델을 사용하면 SDK 가 기본 `ModelSettings` 를 적용합니다. 대부분의 사용 사례에서 가장 잘 작동하는 값으로 설정됩니다. 기본 모델의 reasoning effort 를 조정하려면 사용자 지정 `ModelSettings` 를 전달하세요:
이 방식으로 [`gpt-5.2`](https://platform.openai.com/docs/models/gpt-5.2) 같은 GPT-5.x 모델을 사용하면 SDK 가 기본 `ModelSettings` 를 적용합니다. 대부분의 사용 사례에 가장 잘 맞는 설정이 적용됩니다. 기본 모델의 추론 강도를 조정하려면 사용자 정의 `ModelSettings` 를 전달하세요:
```python
from openai.types.shared import Reasoning
@@ -71,15 +71,15 @@ my_agent = Agent(
)
```
더 낮은 지연 시간을 위해 `gpt-5.2` 에서 `reasoning.effort="none"` 사용을 권장합니다. gpt-4.1 계열( mini 및 nano 변형 포함)도 인터랙티브 에이전트 앱 구축에 여전히 좋은 선택입니다.
더 낮은 지연 시간을 위해 `gpt-5.2` 에서 `reasoning.effort="none"` 사용을 권장합니다. gpt-4.1 계열( mini 및 nano 변형 포함)도 대화형 에이전트 앱 구축에 여전히 훌륭한 선택지입니다.
#### 비 GPT-5 모델
#### GPT-5 이외 모델
사용자 지정 `model_settings` 없이 비 GPT-5 모델 이름을 전달하면 SDK 는 모든 모델과 호환되는 일반 `ModelSettings` 로 되돌아갑니다.
사용자 정의 `model_settings` 없이 GPT-5 이외 모델 이름을 전달하면, SDK 는 모든 모델과 호환되는 일반 `ModelSettings` 로 되돌아갑니다.
### Responses WebSocket 전송
기본적으로 OpenAI Responses API 요청은 HTTP 전송을 사용합니다. OpenAI 기반 모델을 사용할 때 websocket 전송을 활성화할 수 있습니다.
기본적으로 OpenAI Responses API 요청은 HTTP 전송을 사용합니다. OpenAI 기반 모델 사용 시 websocket 전송을 선택할 수 있습니다.
```python
from agents import set_default_openai_responses_transport
@@ -87,11 +87,11 @@ from agents import set_default_openai_responses_transport
set_default_openai_responses_transport("websocket")
```
이는 기본 OpenAI 제공자에서 확인되는 OpenAI Responses 모델(예: `"gpt-5.2"` 같은 문자열 모델 이름 포함)에 영향을 줍니다.
이는 기본 OpenAI 제공자에서 해석되는 OpenAI Responses 모델( `"gpt-5.2"` 같은 문자열 모델 이름 포함)에 영향을 줍니다.
전송 방식 선택은 SDK 가 모델 이름을 모델 인스턴스로 해석할 때 이루어집니다. 구체적인 [`Model`][agents.models.interface.Model] 객체를 전달하면 해당 전송은 이미 고정됩니다: [`OpenAIResponsesWSModel`][agents.models.openai_responses.OpenAIResponsesWSModel]은 websocket, [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]은 HTTP, [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]은 Chat Completions 를 사용합니다. `RunConfig(model_provider=...)` 를 전달하면 전역 기본값 대신 해당 제공자가 전송 선택을 제어합니다.
전송 방식 선택은 SDK 가 모델 이름을 모델 인스턴스로 해석할 때 이루어집니다. 구체적인 [`Model`][agents.models.interface.Model] 객체를 전달하면 전송 방식은 이미 고정됩니다: [`OpenAIResponsesWSModel`][agents.models.openai_responses.OpenAIResponsesWSModel]은 websocket 을 사용하고, [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]은 HTTP 를 사용하며, [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]은 Chat Completions 를 유지합니다. `RunConfig(model_provider=...)` 를 전달하면 전역 기본값 대신 해당 제공자가 전송 방식 선택을 제어합니다.
제공자별 또는 실행별로 websocket 전송을 구성할 수도 있습니다:
제공자별 또는 실행별로 websocket 전송을 설정할 수도 있습니다:
```python
from agents import Agent, OpenAIProvider, RunConfig, Runner
@@ -110,38 +110,38 @@ result = await Runner.run(
)
```
접두사 기반 모델 라우팅이 필요하다면(예: 하나의 실행에서 `openai/...` 와 `litellm/...` 모델 이름을 혼합), [`MultiProvider`][agents.MultiProvider]를 사용하고 대신 `openai_use_responses_websocket=True` 를 설정하세요.
모델 이름 접두사 기반 라우팅(예: 한 번의 실행에서 `openai/...` 와 `litellm/...` 혼합)이 필요하면, [`MultiProvider`][agents.MultiProvider] 를 사용하고 대신 `openai_use_responses_websocket=True` 를 설정하세요.
사용자 지정 OpenAI 호환 엔드포인트 또는 프록시를 사용하는 경우 websocket 전송에도 호환되는 websocket `/responses` 엔드포인트가 필요합니다. 이러한 설정에서는 `websocket_base_url` 을 명시적으로 설정해야 할 수 있습니다.
사용자 정의 OpenAI 호환 엔드포인트나 프록시를 사용하는 경우, websocket 전송에도 호환되는 websocket `/responses` 엔드포인트가 필요합니다. 이런 설정에서는 `websocket_base_url` 을 명시적으로 설정해야 할 수 있습니다.
참고:
- 이것은 websocket 전송을 사용하는 Responses API 이며, [Realtime API](../realtime/guide.md)가 아닙니다. Chat Completions 또는 Responses websocket `/responses` 엔드포인트를 지원하지 않는 비 OpenAI 제공자에는 적용되지 않습니다
- 이는 websocket 전송 기반 Responses API 이며, [Realtime API](../realtime/guide.md)가 아닙니다. Chat Completions 또는 Responses websocket `/responses` 엔드포인트를 지원하지 않는 OpenAI 이외 제공자에는 적용되지 않습니다
- 환경에 아직 없다면 `websockets` 패키지를 설치하세요
- websocket 전송을 활성화한 뒤 [`Runner.run_streamed()`][agents.run.Runner.run_streamed]를 바로 사용할 수 있습니다. 동일한 websocket 연결을 여러 턴(중첩된 agent-as-tool 호출 포함)에서 재사용하고 싶다면 [`responses_websocket_session()`][agents.responses_websocket_session] 헬퍼를 권장합니다. [에이전트 실행](../running_agents.md) 가이드와 [`examples/basic/stream_ws.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/stream_ws.py)를 참고하세요
- websocket 전송을 활성화한 후 [`Runner.run_streamed()`][agents.run.Runner.run_streamed] 를 직접 사용할 수 있습니다. 여러 턴 워크플로에서 같은 websocket 연결을 턴 간(중첩된 agent-as-tool 호출 포함) 재사용하려면 [`responses_websocket_session()`][agents.responses_websocket_session] 헬퍼 사용을 권장합니다. [에이전트 실행](../running_agents.md) 가이드와 [`examples/basic/stream_ws.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/stream_ws.py)를 참고하세요
## 비 OpenAI 모델
## OpenAI 이외 모델
대부분의 다른 비 OpenAI 모델은 [LiteLLM 통합](./litellm.md)을 통해 사용할 수 있습니다. 먼저 litellm 의존성 그룹을 설치하세요:
대부분의 OpenAI 이외 모델은 [LiteLLM 통합](./litellm.md)을 통해 사용할 수 있습니다. 먼저 litellm 의존성 그룹을 설치하세요:
```bash
pip install "openai-agents[litellm]"
```
그다음 `litellm/` 접두사를 사용해 [지원 모델](https://docs.litellm.ai/docs/providers) 중 아무 모델이나 사용할 수 있습니다:
그다음 `litellm/` 접두사를 사용해 [지원되는 모델](https://docs.litellm.ai/docs/providers) 중 아무 것이나 사용할 수 있습니다:
```python
claude_agent = Agent(model="litellm/anthropic/claude-3-5-sonnet-20240620", ...)
gemini_agent = Agent(model="litellm/gemini/gemini-2.5-flash-preview-04-17", ...)
```
### 비 OpenAI 모델을 사용하는 다른 방법
### OpenAI 이외 모델 사용의 다른 방법
다음 3가지 추가 방식으로 다른 LLM 제공자를 통합할 수 있습니다(코드 예제는 [여기](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)):
다음 3 가지 방법으로도 다른 LLM 제공자를 통합할 수 있습니다(코드 예제는 [여기](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/) 참고):
1. [`set_default_openai_client`][agents.set_default_openai_client]는 `AsyncOpenAI` 인스턴스를 LLM 클라이언트로 전역 사용하려는 경우에 유용합니다. LLM 제공자가 OpenAI 호환 API 엔드포인트를 제공하고 `base_url` 및 `api_key` 를 설정할 수 있는 경우를 위한 방식입니다. 구성 가능한 예시는 [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py)를 참고하세요
2. [`ModelProvider`][agents.models.interface.ModelProvider]는 `Runner.run` 수준에서 사용합니다. 이를 통해 "이 실행의 모든 에이전트에 사용자 지정 모델 제공자를 사용"하도록 지정할 수 있습니다. 구성 가능한 예시는 [examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py)를 참고하세요
3. [`Agent.model`][agents.agent.Agent.model]을 사용하면 특정 Agent 인스턴스에 모델을 지정할 수 있습니다. 이를 통해 에이전트별로 서로 다른 제공자를 조합할 수 있습니다. 구성 가능한 예시는 [examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py)를 참고하세요. 사용 가능한 대부분의 모델을 쉽게 사용하는 방법은 [LiteLLM 통합](./litellm.md)입니다
1. [`set_default_openai_client`][agents.set_default_openai_client] 는 `AsyncOpenAI` 인스턴스를 LLM 클라이언트로 전역 사용하고 싶을 때 유용합니다. LLM 제공자가 OpenAI 호환 API 엔드포인트를 제공하고 `base_url` 및 `api_key` 를 설정할 수 있는 경우에 해당합니다. 설정 가능한 예시는 [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py) 를 참고하세요
2. [`ModelProvider`][agents.models.interface.ModelProvider] 는 `Runner.run` 수준에서 사용합니다. 이를 통해 "이 실행의 모든 에이전트에 커스텀 모델 제공자를 사용"하도록 지정할 수 있습니다. 설정 가능한 예시는 [examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py) 를 참고하세요
3. [`Agent.model`][agents.agent.Agent.model] 을 사용하면 특정 Agent 인스턴스에 모델을 지정할 수 있습니다. 이를 통해 서로 다른 에이전트에 서로 다른 제공자를 혼합해 사용할 수 있습니다. 설정 가능한 예시는 [examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py) 를 참고하세요. 사용 가능한 대부분의 모델을 쉽게 사용하는 방법은 [LiteLLM 통합](./litellm.md)입니다
`platform.openai.com` 의 API 키가 없는 경우에는 `set_tracing_disabled()` 로 트레이싱을 비활성화하거나, [다른 트레이싱 프로세서](../tracing.md)를 설정하는 것을 권장합니다.
@@ -151,15 +151,15 @@ gemini_agent = Agent(model="litellm/gemini/gemini-2.5-flash-preview-04-17", ...)
## 고급 모델 선택 및 혼합
하나의 워크플로 안에서 에이전트별로 서로 다른 모델을 사용하고 싶을 수 있습니다. 예를 들어 분류에는 더 작고 빠른 모델을, 복잡한 작업에는 더 크고 성능이 높은 모델을 사용할 수 있습니다. [`Agent`][agents.Agent]를 구성할 때 다음 중 하나로 특정 모델을 선택할 수 있습니다:
단일 워크플로 내에서 에이전트별로 서로 다른 모델을 사용하고 싶을 수 있습니다. 예를 들어 분류에는 더 작고 빠른 모델을, 복잡한 작업에는 더 크고 성능이 높은 모델을 사용할 수 있습니다. [`Agent`][agents.Agent] 를 구성할 때 다음 중 하나로 특정 모델을 선택할 수 있습니다:
1. 모델 이름 전달
2. 임의의 모델 이름 + 해당 이름을 Model 인스턴스로 매핑할 수 있는 [`ModelProvider`][agents.models.interface.ModelProvider] 전달
2. 모델 이름 + 해당 이름을 Model 인스턴스로 매핑할 수 있는 [`ModelProvider`][agents.models.interface.ModelProvider] 전달
3. [`Model`][agents.models.interface.Model] 구현을 직접 제공
!!!note
SDK 는 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 과 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] 형태를 모두 지원하지만, 두 형태는 지원 기능과 도구 집합이 다르므로 워크플로별로 하나의 모델 형태만 사용하는 것을 권장합니다. 워크플로에서 모델 형태 혼합이 필요하다면, 사용하는 모든 기능이 두 형태 모두에서 사용 가능한지 확인하세요
SDK 는 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 과 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] 형태를 모두 지원하지만, 두 형태가 지원하는 기능 및 도구 집합이 다르므로 워크플로마다 단일 모델 형태 사용을 권장합니다. 워크플로에서 모델 형태 혼합이 필요하다면, 사용하는 모든 기능이 양쪽 모두에서 제공되는지 확인하세요
```python
from agents import Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel
@@ -195,7 +195,7 @@ async def main():
1. OpenAI 모델 이름을 직접 설정합니다
2. [`Model`][agents.models.interface.Model] 구현을 제공합니다
에이전트에 사용할 모델을 더 세부적으로 구성하려면 temperature 같은 선택적 모델 구성 매개변수를 제공하는 [`ModelSettings`][agents.models.interface.ModelSettings]를 전달할 수 있습니다.
에이전트에 사용되는 모델을 더 세부적으로 구성하려면, temperature 같은 선택적 모델 구성 매개변수를 제공하는 [`ModelSettings`][agents.models.interface.ModelSettings] 를 전달할 수 있습니다.
```python
from agents import Agent, ModelSettings
@@ -208,7 +208,37 @@ english_agent = Agent(
)
```
또한 OpenAI Responses API 를 사용할 때 [추가 선택 매개변수](https://platform.openai.com/docs/api-reference/responses/create)가 몇 가지 더 있습니다(예: `user`, `service_tier` 등). 이것들이 최상위 레벨에 없다면 `extra_args` 로 전달할 수 있습니다.
#### 일반적인 고급 `ModelSettings` 옵션
OpenAI Responses API 를 사용할 때는 여러 요청 필드에 이미 직접 대응되는 `ModelSettings` 필드가 있으므로, 해당 경우 `extra_args` 가 필요하지 않습니다.
| 필드 | 용도 |
| --- | --- |
| `parallel_tool_calls` | 같은 턴에서 여러 도구 호출을 허용하거나 금지 |
| `truncation` | 컨텍스트 초과 시 실패 대신 Responses API 가 가장 오래된 대화 항목을 삭제하도록 `"auto"` 설정 |
| `prompt_cache_retention` | 예: `"24h"` 처럼 캐시된 프롬프트 접두사 유지 시간을 늘림 |
| `response_include` | `web_search_call.action.sources`, `file_search_call.results`, `reasoning.encrypted_content` 같은 더 풍부한 응답 페이로드 요청 |
| `top_logprobs` | 출력 텍스트의 상위 토큰 logprobs 요청. SDK 는 `message.output_text.logprobs` 도 자동 추가 |
```python
from agents import Agent, ModelSettings
research_agent = Agent(
name="Research agent",
model="gpt-5.2",
model_settings=ModelSettings(
parallel_tool_calls=False,
truncation="auto",
prompt_cache_retention="24h",
response_include=["web_search_call.action.sources"],
top_logprobs=5,
),
)
```
SDK 가 아직 최상위에서 직접 노출하지 않는 제공자별 또는 신규 요청 필드가 필요할 때는 `extra_args` 를 사용하세요.
또한 OpenAI 의 Responses API 를 사용할 때 [다른 선택적 매개변수 몇 가지](https://platform.openai.com/docs/api-reference/responses/create)(예: `user`, `service_tier` 등)가 있습니다. 이들이 최상위에 없다면 `extra_args` 로 전달할 수 있습니다.
```python
from agents import Agent, ModelSettings
@@ -224,21 +254,21 @@ english_agent = Agent(
)
```
## 비 OpenAI 제공자 문제 해결
## OpenAI 이외 제공자 문제 해결
### 트레이싱 클라이언트 오류 401
트레이싱 관련 오류가 발생한다면, 이는 트레이스가 OpenAI 서버로 업로드되는데 OpenAI API 키가 없기 때문입니다. 해결 방법은 세 가지입니다:
트레이싱 관련 오류가 발생하는 경우, 트레이스가 OpenAI 서버로 업로드되는데 OpenAI API 키가 없기 때문입니다. 해결 방법은 세 가지입니다:
1. 트레이싱을 완전히 비활성화: [`set_tracing_disabled(True)`][agents.set_tracing_disabled]
2. 트레이싱용 OpenAI 키 설정: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]. 이 API 키는 트레이스 업로드에만 사용되며 [platform.openai.com](https://platform.openai.com/)에서 발급된 키여야 합니다
3. 비 OpenAI 트레이스 프로세서 사용. [트레이싱 문서](../tracing.md#custom-tracing-processors)를 참고하세요
1. 트레이싱 완전 비활성화: [`set_tracing_disabled(True)`][agents.set_tracing_disabled]
2. 트레이싱용 OpenAI 키 설정: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]. 이 API 키는 트레이스 업로드에만 사용되며 [platform.openai.com](https://platform.openai.com/) 발급 키여야 합니다
3. OpenAI 이외 트레이스 프로세서 사용. [트레이싱 문서](../tracing.md#custom-tracing-processors) 참고
### Responses API 지원
SDK 는 기본적으로 Responses API 를 사용하지만, 대부분의 다른 LLM 제공자는 아직 이를 지원하지 않습니다. 그 결과 404 또는 유사한 문제가 발생할 수 있습니다. 해결 방법은 두 가지입니다:
SDK 는 기본적으로 Responses API 를 사용하지만, 대부분의 다른 LLM 제공자는 아직 이를 지원하지 않습니다. 그 결과 404 또는 유사한 이슈가 발생할 수 있습니다. 해결 방법은 두 가지입니다:
1. [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api] 호출. 환경 변수로 `OPENAI_API_KEY` 및 `OPENAI_BASE_URL` 을 설정하는 경우에 동작합니다
1. [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api] 호출. 이 방법은 환경 변수로 `OPENAI_API_KEY` 와 `OPENAI_BASE_URL` 을 설정하는 경우 동작합니다
2. [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] 사용. 예시는 [여기](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)에 있습니다
### structured outputs 지원
@@ -251,12 +281,12 @@ BadRequestError: Error code: 400 - {'error': {'message': "'response_format.type'
```
이는 일부 모델 제공자의 한계입니다. JSON 출력은 지원하지만 출력에 사용할 `json_schema` 지정은 허용하지 않습니다. 현재 이 문제를 해결 중이지만, JSON schema 출력을 지원하는 제공자를 사용하는 것을 권장합니다. 그렇지 않으면 잘못된 JSON 때문에 앱이 자주 중단될 수 있습니다.
이는 일부 모델 제공자의 한계입니다. JSON 출력은 지원하지만 출력에 사용할 `json_schema` 지정은 허용하지 않습니다. 이 문제는 현재 수정 작업 중이지만, JSON schema 출력을 지원하는 제공자 사용을 권장합니다. 그렇지 않으면 잘못된 JSON 때문에 앱이 자주 중단될 수 있습니다.
## 제공자 간 모델 혼합
모델 제공자 간 기능 차이를 인지하지 않으면 오류가 발생할 수 있습니다. 예를 들어 OpenAI 는 structured outputs, 멀티모달 입력, 호스팅 파일 검색 및 웹 검색을 지원하지만 많은 다른 제공자는 이러한 기능을 지원하지 않습니다. 다음 제한 사항에 유의하세요:
모델 제공자 간 기능 차이를 인지하지 못하면 오류가 발생할 수 있습니다. 예를 들어 OpenAI 는 structured outputs, 멀티모달 입력, 호스팅 파일 검색 및 웹 검색을 지원하지만 많은 다른 제공자는 이를 지원하지 않습니다. 다음 제한 사항에 유의하세요:
- 지원하지 않는 제공자에 지원되지 않는 `tools` 를 보내지 마세요
- 텍스트 전용 모델을 호출하기 전에 멀티모달 입력을 필터링하세요
- 지원하지 않는 제공자에는 해당 `tools` 를 보내지 마세요
- 텍스트 전용 모델 호출 전에 멀티모달 입력을 필터링하세요
- structured JSON 출력을 지원하지 않는 제공자는 가끔 유효하지 않은 JSON 을 생성할 수 있다는 점에 유의하세요
docs/ko/sessions/index.md
+84 -53
View File
@@ -4,11 +4,11 @@ search:
---
# 세션
Agents SDK 는 내장 세션 메모리를 제공하여 여러 에이전트 실행에 걸쳐 대화 기록을 자동으로 유지하므로, 턴 간 `.to_input_list()` 를 수동으로 처리할 필요가 없습니다.
Agents SDK 는 여러 에이전트 실행 전반에서 대화 기록을 자동으로 유지하는 내장 세션 메모리를 제공하여, 턴 간 `.to_input_list()` 를 수동으로 처리할 필요를 없애줍니다
세션은 특정 세션의 대화 기록을 저장하여, 명시적인 수동 메모리 관리 없이도 에이전트가 컨텍스트를 유지할 수 있게 합니다. 이는 에이전트가 이전 상호작용을 기억해야 하는 채팅 애플리케이션이나 멀티턴 대화를 구축할 때 특히 유용합니다.
세션은 특정 세션의 대화 기록을 저장하므로, 명시적인 수동 메모리 관리 없이도 에이전트가 컨텍스트를 유지할 수 있습니다. 이는 에이전트가 이전 상호작용을 기억해야 하는 채팅 애플리케이션이나 멀티턴 대화를 구축할 때 특히 유용합니다
SDK 가 클라이언트 측 메모리를 대신 관리하길 원할 때 세션을 사용하세요. 이미 `conversation_id` 또는 `previous_response_id` 로 OpenAI 서버 관리 상태를 사용 중이라면, 보통 같은 대화에 대해 세션이 추가로 필요하지 않습니다.
SDK 가 클라이언트 측 메모리를 대신 관리하도록 하려면 세션을 사용하세요. 이미 `conversation_id` 또는 `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)
@@ -67,11 +67,11 @@ if result.interruptions:
세션 메모리가 활성화되면:
1. **각 실행 전**: 러너가 세션의 대화 기록을 자동으로 조회하고 입력 항목 앞에 추가합니다
2. **각 실행 후**: 실행 중 생성된 모든 새 항목(사용자 입력, 어시스턴트 응답, 도구 호출 등)이 세션에 자동 저장됩니다
3. **컨텍스트 보존**: 동일한 세션으로 수행되는 각 후속 실행에는 전체 대화 기록이 포함되어, 에이전트가 컨텍스트를 유지할 수 있습니다
1. **각 실행 전**: 러너가 세션의 대화 기록을 자동으로 조회하여 입력 항목 앞에 추가합니다
2. **각 실행 후**: 실행 중 생성된 모든 새 항목(사용자 입력, 어시스턴트 응답, 도구 호출 등)이 세션에 자동으로 저장됩니다
3. **컨텍스트 유지**: 동일 세션으로 수행되는 각 후속 실행에는 전체 대화 기록이 포함되어 에이전트가 컨텍스트를 유지할 수 있습니다
이로써 실행 간 `.to_input_list()` 를 수동 호출하고 대화 상태를 관리할 필요가 없어집니다.
이로써 `.to_input_list()` 를 수동 호출하고 실행 간 대화 상태를 관리할 필요가 없어집니다
## 기록과 새 입력 병합 제어
@@ -80,12 +80,12 @@ if result.interruptions:
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`: 현재 턴의 새 입력 항목
모델로 전송할 최종 입력 항목 리스트를 반환하세요.
모델로 전송할 최종 입력 항목 리스트를 반환하세요
```python
from agents import Agent, RunConfig, Runner, SQLiteSession
@@ -107,11 +107,11 @@ result = await Runner.run(
)
```
세션이 항목을 저장하는 방식은 변경하지 않으면서, 기록의 사용자 지정 가지치기, 재정렬 또는 선택적 포함이 필요할 때 사용하세요.
이는 세션이 항목을 저장하는 방식을 바꾸지 않고도 사용자 지정 가지치기, 재정렬 또는 기록의 선택적 포함이 필요할 때 사용합니다
## 조회 기록 제한
각 실행 전에 가져올 기록량을 제어하려면 [`SessionSettings`][agents.memory.SessionSettings] 를 사용하세요.
각 실행 전에 가져올 기록의 양을 제어하려면 [`SessionSettings`][agents.memory.SessionSettings] 를 사용하세요
- `SessionSettings(limit=None)` (기본값): 사용 가능한 모든 세션 항목 조회
- `SessionSettings(limit=N)`: 가장 최근 `N` 개 항목만 조회
@@ -132,7 +132,7 @@ result = await Runner.run(
)
```
세션 구현이 기본 세션 설정을 노출하는 경우, `RunConfig.session_settings` 는 해당 실행에서 `None` 이 아닌 값을 재정의합니다. 이는 긴 대화에서 세션의 기본 동작을 바꾸지 않고 조회 크기를 제한하고 싶을 때 유용합니다.
세션 구현이 기본 세션 설정을 노출하는 경우, `RunConfig.session_settings` 는 해당 실행에서 `None` 이 아닌 값을 우선 적용합니다. 이는 긴 대화에서 세션의 기본 동작을 바꾸지 않고 조회 크기를 제한하고 싶을 때 유용합니다
## 메모리 작업
@@ -163,7 +163,7 @@ print(last_item) # {"role": "assistant", "content": "Hi there!"}
await session.clear_session()
```
### 수정 시 pop_item 사용
### 수정에 pop_item 사용
`pop_item` 메서드는 대화의 마지막 항목을 되돌리거나 수정하려는 경우 특히 유용합니다:
@@ -200,24 +200,25 @@ SDK 는 다양한 사용 사례를 위한 여러 세션 구현을 제공합니
### 내장 세션 구현 선택
아래 상세 예제를 읽기 전에 시작점을 고르기 위해 이 표를 사용하세요.
아래의 상세 예제를 읽기 전에 시작점을 고르려면 이 표를 사용하세요
| Session type | Best for | Notes |
| --- | --- | --- |
| `SQLiteSession` | 로컬 개발 및 단순 앱 | 내장형, 경량, 파일 기반 또는 인메모리 |
| `AsyncSQLiteSession` | `aiosqlite` 를 사용하는 비동기 SQLite | 비동기 드라이버 지원 확장 백엔드 |
| `RedisSession` | 워커/서비스 간 공유 메모리 | 저지연 분산 배포에 적합 |
| `SQLAlchemySession` | 기존 데이터베이스가 있는 프로덕션 앱 | SQLAlchemy 지원 데이터베이스와 동작 |
| `OpenAIConversationsSession` | OpenAI 의 서버 관리 스토리지 | OpenAI Conversations API 기반 기록 |
| `SQLAlchemySession` | 기존 데이터베이스가 있는 프로덕션 앱 | SQLAlchemy 지원 데이터베이스에서 동작 |
| `DaprSession` | Dapr 사이드카 기반 클라우드 네이티브 배포 | 다중 상태 스토어 + TTL 및 일관성 제어 지원 |
| `OpenAIConversationsSession` | OpenAI 의 서버 관리 저장소 | OpenAI Conversations API 기반 기록 |
| `OpenAIResponsesCompactionSession` | 자동 압축이 필요한 긴 대화 | 다른 세션 백엔드를 감싸는 래퍼 |
| `AdvancedSQLiteSession` | SQLite + 브랜칭/분석 | 더 많은 기능 세트, 전용 페이지 참고 |
| `EncryptedSession` | 다른 세션 위의 암호화 + TTL | 래퍼, 먼저 기반 백엔드 선택 필요 |
| `AdvancedSQLiteSession` | 브랜칭/분석 기능을 더한 SQLite | 더 많은 기능 집합, 전용 페이지 참조 |
| `EncryptedSession` | 다른 세션 위의 암호화 + TTL | 래퍼이며 먼저 기반 백엔드를 선택해야 함 |
일부 구현은 추가 세부 정보가 있는 전용 페이지를 가지며, 해당 하위 섹션에 인라인으로 링크되어 있습니다.
일부 구현에는 추가 세부 사항이 포함된 전용 페이지가 있으며, 해당 하위 섹션에 인라인으로 링크되어 있습니다
### OpenAI Conversations API 세션
`OpenAIConversationsSession` 을 통해 [OpenAI's Conversations API](https://platform.openai.com/docs/api-reference/conversations) 를 사용하세요.
`OpenAIConversationsSession` 을 통해 [OpenAI's Conversations API](https://platform.openai.com/docs/api-reference/conversations) 를 사용하세요
```python
from agents import Agent, Runner, OpenAIConversationsSession
@@ -253,7 +254,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` 을 이것으로 감싸지 마세요. 두 기능은 기록을 서로 다른 방식으로 관리합니다
#### 일반적인 사용법(자동 압축)
@@ -272,15 +273,15 @@ result = await Runner.run(agent, "Hello", session=session)
print(result.final_output)
```
기본적으로 후보 임계값에 도달하면 각 턴 후 압축이 실행됩니다.
기본적으로 후보 임계값에 도달하면 각 턴 이후 압축이 실행됩니다
`compaction_mode="previous_response_id"` 는 이미 Responses API 응답 ID 로 턴을 체이닝하고 있을 때 가장 잘 동작합니다. 반면 `compaction_mode="input"` 은 현재 세션 항목에서 압축 요청을 재구성하므로, 응답 체인을 사용할 수 없거나 세션 내용을 단일 진실 공급원으로 삼고 싶을 때 유용합니다. 기본값 `"auto"` 는 사용 가능한 가장 안전한 옵션을 선택합니다.
`compaction_mode="previous_response_id"` 는 Responses API response ID 로 이미 턴을 연결하고 있을 때 가장 잘 동작합니다. `compaction_mode="input"` 은 대신 현재 세션 항목에서 압축 요청을 재구성하며, response 체인을 사용할 수 없거나 세션 내용을 단일 진실 공급원으로 삼고 싶을 때 유용합니다. 기본값 `"auto"` 는 사용 가능한 옵션 중 가장 안전한 것을 선택합니다
#### 자동 압축은 스트리밍을 블로킹할 수 있음
#### 자동 압축은 스트리밍을 지연시킬 수 있음
압축은 세션 기록을 지우고 다시 쓰므로, SDK 는 실행 완료로 간주하기 전에 압축이 끝날 때까지 기다립니다. 스트리밍 모드에서는 압축이 무거울 경우 마지막 출력 토큰 이후에도 `run.stream_events()` 가 몇 초 동안 열려 있을 수 있음을 의미합니다.
압축은 세션 기록을 지우고 다시 쓰므로, SDK 는 실행 완료로 간주하기 전에 압축이 끝날 때까지 기다립니다. 스트리밍 모드에서는 압축이 무거운 경우 마지막 출력 토큰 이후에도 `run.stream_events()` 가 몇 초 동안 열린 상태로 유지될 수 있습니다
저지연 스트리밍이나 빠른 턴 전환이 필요하면 자동 압축을 비활성화하고 턴 사이(또는 유휴 시간)에 `run_compaction()` 을 직접 호출하세요. 자체 기준에 따라 압축 강제 시점을 결정할 수 있습니다.
저지연 스트리밍이나 빠른 턴 전환이 필요하다면 자동 압축을 비활성화하고 턴 사이(또는 유휴 시간)에 `run_compaction()` 을 직접 호출하세요. 자체 기준에 따라 압축 강제 시점을 결정할 수 있습니다
```python
from agents import Agent, Runner, SQLiteSession
@@ -303,7 +304,7 @@ await session.run_compaction({"force": True})
### SQLite 세션
SQLite 를 사용하는 기본 경량 세션 구현:
SQLite 를 사용하는 기본 경량 세션 구현입니다:
```python
from agents import SQLiteSession
@@ -324,7 +325,7 @@ result = await Runner.run(
### 비동기 SQLite 세션
`aiosqlite` 기반 영속성이 필요할 때 `AsyncSQLiteSession` 을 사용하세요.
`aiosqlite` 기반 SQLite 영속성이 필요하면 `AsyncSQLiteSession` 을 사용하세요
```bash
pip install aiosqlite
@@ -341,7 +342,7 @@ result = await Runner.run(agent, "Hello", session=session)
### Redis 세션
여러 워커 또는 서비스 간 공유 세션 메모리가 필요하면 `RedisSession` 을 사용하세요.
여러 워커 또는 서비스 간 공유 세션 메모리가 필요하면 `RedisSession` 을 사용하세요
```bash
pip install openai-agents[redis]
@@ -379,13 +380,43 @@ 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 Sessions](sqlalchemy_session.md) 를 참조하세요
### Dapr 세션
이미 Dapr 사이드카를 실행 중이거나, 에이전트 코드를 변경하지 않고 서로 다른 상태 스토어 백엔드 간에 이동 가능한 세션 저장소가 필요하다면 `DaprSession` 을 사용하세요
```bash
pip install openai-agents[dapr]
```
```python
from agents import Agent, Runner
from agents.extensions.memory import DaprSession
agent = Agent(name="Assistant")
async with DaprSession.from_address(
"user_123",
state_store_name="statestore",
dapr_address="localhost:50001",
) as session:
result = await Runner.run(agent, "Hello", session=session)
print(result.final_output)
```
참고:
- `from_address(...)` 는 Dapr 클라이언트를 생성하고 소유합니다. 앱에서 이미 클라이언트를 관리 중이라면 `dapr_client=...` 와 함께 `DaprSession(...)` 을 직접 생성하세요
- 스토어가 TTL 을 지원할 때 오래된 세션 데이터가 자동 만료되도록 `ttl=...` 을 전달하세요
- 더 강한 write 후 read 보장이 필요하면 `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) 를 참조하세요
### 고급 SQLite 세션
대화 브랜칭, 사용량 분석, 구조화된 쿼리를 포함한 강화된 SQLite 세션:
대화 브랜칭, 사용량 분석, 구조화된 쿼리를 지원하는 향상된 SQLite 세션:
```python
from agents.extensions.memory import AdvancedSQLiteSession
@@ -405,7 +436,7 @@ 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 Sessions](advanced_sqlite_session.md) 를 참조하세요
### 암호화 세션
@@ -432,17 +463,17 @@ session = EncryptedSession(
result = await Runner.run(agent, "Hello", session=session)
```
자세한 문서는 [Encrypted Sessions](encrypted_session.md) 를 참고하세요.
자세한 문서는 [Encrypted Sessions](encrypted_session.md) 를 참조하세요
### 기타 세션 유형
내장 옵션이 몇 가지 더 있습니다. `examples/memory/` 및 `extensions/memory/` 아래 소스 코드를 참고하세요.
내장 옵션이 몇 가지 더 있습니다. `examples/memory/` 및 `extensions/memory/` 아래 소스 코드를 참조하세요
## 운영 패턴
### 세션 ID 네이밍
### 세션 ID 명명
대화 정리에 도움이 되는 의미 있는 세션 ID 를 사용하세요:
대화를 정리하는 데 도움이 되는 의미 있는 세션 ID 를 사용하세요:
- 사용자 기반: `"user_12345"`
- 스레드 기반: `"thread_abc123"`
@@ -452,13 +483,13 @@ 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 상태 저장소 세션 (`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)용 커스텀 세션 백엔드 구현 고려
- `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)용 사용자 정의 세션 백엔드 구현 고려
### 다중 세션
@@ -506,7 +537,7 @@ result2 = await Runner.run(
## 전체 예제
아래는 세션 메모리가 동작하는 전체 예제입니다:
세션 메모리가 실제로 동작하는 전체 예제입니다:
```python
import asyncio
@@ -568,7 +599,7 @@ if __name__ == "__main__":
asyncio.run(main())
```
## 커스텀 세션 구현
## 사용자 정의 세션 구현
[`Session`][agents.memory.session.Session] 프로토콜을 따르는 클래스를 만들어 자체 세션 메모리를 구현할 수 있습니다:
@@ -619,13 +650,13 @@ 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] - 프로토콜 인터페이스
- [`OpenAIConversationsSession`][agents.memory.OpenAIConversationsSession] - OpenAI Conversations API 구현
@@ -634,6 +665,6 @@ 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 기반 구현
- [`DaprSession`][agents.extensions.memory.dapr_session.DaprSession] - Dapr 상태 저장소 구현
- [`AdvancedSQLiteSession`][agents.extensions.memory.advanced_sqlite_session.AdvancedSQLiteSession] - 브랜칭 및 분석 기능이 있는 강화된 SQLite
- [`EncryptedSession`][agents.extensions.memory.encrypt_session.EncryptedSession] - 모든 세션용 암호화 래퍼
- [`DaprSession`][agents.extensions.memory.dapr_session.DaprSession] - Dapr 상태 스토어 구현
- [`AdvancedSQLiteSession`][agents.extensions.memory.advanced_sqlite_session.AdvancedSQLiteSession] - 브랜칭 및 분석이 포함된 향상된 SQLite
- [`EncryptedSession`][agents.extensions.memory.encrypt_session.EncryptedSession] - 모든 세션을 위한 암호화 래퍼
docs/zh/examples.md
+45 -43
View File
@@ -2,88 +2,90 @@
search:
exclude: true
---
# 代码示例
# 示例
欢迎在 [repo](https://github.com/openai/openai-agents-python/tree/main/examples) 的代码示例部分查看 SDK 的多种示例实现。这些代码示例按多个目录组织，用于展示不同的模式与能力。
请在 [repo](https://github.com/openai/openai-agents-python/tree/main/examples) 的示例部分查看 SDK 的多种 sample code。示例被组织为多个目录，展示了不同的模式和能力。
## 目录
- **[agent_patterns](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns):**
此目录下的代码示例展示了常见的智能体设计模式，例如：
- **[agent_patterns](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns)：**
该目录中的示例说明了常见的智能体设计模式，例如：
- 确定性工作流
- Agents as tools
- 并行智能体执行
- 条件化工具使用
- 条件式工具使用
- 输入/输出安全防护措施
- LLM 作为裁判
- LLM 作为评判者
- 路由
- 流式传输安全防护措施
- **[basic](https://github.com/openai/openai-agents-python/tree/main/examples/basic):**
这些代码示例展示 SDK 的基础能力，例如：
- **[basic](https://github.com/openai/openai-agents-python/tree/main/examples/basic)：**
这些示例展示了 SDK 的基础能力，例如：
- Hello world 代码示例（默认模型、GPT-5、开源权重模型）
- Hello World 示例（默认模型、GPT-5、开放权重模型）
- 智能体生命周期管理
- 动态系统提示词
- 流式传输输出（文本、条目、函数调用参数）
- 使用共享的跨轮次会话辅助工具进行 Responses websocket 传输（`examples/basic/stream_ws.py`）
- 跨轮次共享会话辅助器的 Responses websocket 传输（`examples/basic/stream_ws.py`）
- 提示词模板
- 文件处理（本地与远程、图片与 PDF）
- 用量追踪
- 文件处理（本地和远程、图像和 PDF）
- 使用量追踪
- 非严格输出类型
- 之前的 response ID 用法
- 先前响应 ID 的使用
- **[customer_service](https://github.com/openai/openai-agents-python/tree/main/examples/customer_service):**
面向航空公司的示例客服系统。
- **[customer_service](https://github.com/openai/openai-agents-python/tree/main/examples/customer_service)：**
航空公司客户服务系统示例。
- **[financial_research_agent](https://github.com/openai/openai-agents-python/tree/main/examples/financial_research_agent):**
金融研究智能体，展示使用智能体与工具的结构化研究工作流，用于金融数据分析。
- **[financial_research_agent](https://github.com/openai/openai-agents-python/tree/main/examples/financial_research_agent)：**
一个金融研究智能体，演示了用于金融数据分析的、由智能体和工具构成的结构化研究工作流。
- **[handoffs](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs):**
查看结合消息过滤的智能体任务转移实践代码示例。
- **[handoffs](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs)：**
查看带有消息过滤的智能体任务转移实践示例。
- **[hosted_mcp](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp):**
展示如何使用托管的 MCP（Model Context Protocol）连接器与审批的代码示例。
- **[hosted_mcp](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp)：**
演示如何使用托管 MCP（Model context protocol）连接器和审批的示例。
- **[mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp):**
学习如何使用 MCP（Model Context Protocol）构建智能体，包括：
- **[mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp)：**
了解如何使用 MCP（Model context protocol）构建智能体，包括：
- 文件系统代码示例
- Git 代码示例
- MCP 提示词服务器代码示例
- SSE（Server-Sent Events）代码示例
- 可流式 HTTP 代码示例
- 文件系统示例
- Git 示例
- MCP 提示词服务示例
- SSE（服务端发送事件）示例
- 可流式 HTTP 示例
- **[memory](https://github.com/openai/openai-agents-python/tree/main/examples/memory):**
不同智能体记忆实现的代码示例，包括：
- **[memory](https://github.com/openai/openai-agents-python/tree/main/examples/memory)：**
不同智能体内存实现的示例，包括：
- SQLite 会话存储
- 高级 SQLite 会话存储
- Redis 会话存储
- SQLAlchemy 会话存储
- Dapr 状态存储会话存储
- 加密会话存储
- OpenAI 会话存储
- OpenAI Conversations 会话存储
- Responses 压缩会话存储
- **[model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):**
探索如何在 SDK 中使用非 OpenAI 模型，包括自定义 provider 与 LiteLLM 集成。
- **[model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers)：**
探索如何在 SDK 中使用非 OpenAI 模型，包括自定义提供方和 LiteLLM 集成。
- **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):**
展示如何使用 SDK 构建实时体验的代码示例，包括：
- **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime)：**
展示如何使用 SDK 构建实时体验的示例，包括：
- Web 应用
- 命令行界面
- Twilio 集成
- Twilio SIP 集成
- **[reasoning_content](https://github.com/openai/openai-agents-python/tree/main/examples/reasoning_content):**
展示如何使用推理内容与 structured outputs 的代码示例。
- **[reasoning_content](https://github.com/openai/openai-agents-python/tree/main/examples/reasoning_content)：**
演示如何处理推理内容和 structured outputs 的示例。
- **[research_bot](https://github.com/openai/openai-agents-python/tree/main/examples/research_bot):**
简易深度研究克隆项目，展示复杂的多智能体研究工作流。
- **[research_bot](https://github.com/openai/openai-agents-python/tree/main/examples/research_bot)：**
简单的深度研究克隆，演示了复杂的多智能体研究工作流。
- **[tools](https://github.com/openai/openai-agents-python/tree/main/examples/tools):**
学习如何实现 由OpenAI托管的工具 与实验性的 Codex 工具能力，例如：
- **[tools](https://github.com/openai/openai-agents-python/tree/main/examples/tools)：**
了解如何实现由OpenAI托管的工具和实验性 Codex 工具能力，例如：
- 网络检索，以及带过滤器的网络检索
- 文件检索
@@ -95,5 +97,5 @@ search:
- 实验性 Codex 工具工作流（`examples/tools/codex.py`）
- 实验性 Codex 同线程工作流（`examples/tools/codex_same_thread.py`）
- **[voice](https://github.com/openai/openai-agents-python/tree/main/examples/voice):**
查看语音智能体的代码示例，使用我们的 TTS 与 STT 模型，包括流式语音代码示例。
- **[voice](https://github.com/openai/openai-agents-python/tree/main/examples/voice)：**
查看语音智能体示例，使用我们的 TTS 和 STT 模型，包括流式语音示例。
docs/zh/models/index.md
+67 -37
View File
@@ -4,18 +4,18 @@ search:
---
# 模型
Agents SDK 开箱即用地支持两种形式的 OpenAI 模型：
Agents SDK 开箱即用地支持两种 OpenAI 模型形态：
- **推荐**：[`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]，使用新的 [Responses API](https://platform.openai.com/docs/api-reference/responses) 调用 OpenAI API。
- [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]，使用 [Chat Completions API](https://platform.openai.com/docs/api-reference/chat) 调用 OpenAI API。
## 模型设置选择
请根据你的配置按以下顺序使用本页：
根据你的设置，按以下顺序使用本页：
| 目标 | 从这里开始 |
| --- | --- |
| 使用 SDK 默认配置的 OpenAI 托管模型 | [OpenAI 模型](#openai-models) |
| 使用 SDK 默认设置的 OpenAI 托管模型 | [OpenAI 模型](#openai-models) |
| 通过 websocket 传输使用 OpenAI Responses API | [Responses WebSocket 传输](#responses-websocket-transport) |
| 使用非 OpenAI 提供方 | [非 OpenAI 模型](#non-openai-models) |
| 在一个工作流中混用模型/提供方 | [高级模型选择与混用](#advanced-model-selection-and-mixing) 和 [跨提供方混用模型](#mixing-models-across-providers) |
@@ -23,20 +23,20 @@ Agents SDK 开箱即用地支持两种形式的 OpenAI 模型：
## OpenAI 模型
当你在初始化 `Agent` 时未指定模型，将使用默认模型。当前默认值是 [`gpt-4.1`](https://platform.openai.com/docs/models/gpt-4.1)，以兼顾兼容性与低延迟。如果你有权限访问，我们建议将智能体设置为 [`gpt-5.2`](https://platform.openai.com/docs/models/gpt-5.2) 以获得更高质量，同时显式设置 `model_settings`。
当你初始化 `Agent` 时未指定模型，将使用默认模型。当前默认值为 [`gpt-4.1`](https://platform.openai.com/docs/models/gpt-4.1)，以兼顾兼容性和低延迟。如果你有权限，我们建议将智能体设置为 [`gpt-5.2`](https://platform.openai.com/docs/models/gpt-5.2) 以获得更高质量，同时显式设置 `model_settings`。
如果你想切换到其他模型（如 [`gpt-5.2`](https://platform.openai.com/docs/models/gpt-5.2)），有两种方式配置智能体。
### 默认模型
首先，如果你希望对所有未设置自定义模型的智能体始终使用某个特定模型，请在运行智能体前设置 `OPENAI_DEFAULT_MODEL` 环境变量。
首先，如果你希望所有未设置自定义模型的智能体始终使用某个特定模型，请在运行智能体前设置 `OPENAI_DEFAULT_MODEL` 环境变量。
```bash
export OPENAI_DEFAULT_MODEL=gpt-5.2
python3 my_awesome_agent.py
```
其次，你可以通过 `RunConfig` 为一次运行设置默认模型。如果你未为智能体设置模型，则会使用本次运行的模型。
其次，你可以通过 `RunConfig` 为一次运行设置默认模型。如果你未为某个智能体设置模型，将使用此次运行的模型。
```python
from agents import Agent, RunConfig, Runner
@@ -55,7 +55,7 @@ result = await Runner.run(
#### GPT-5.x 模型
当你以这种方式使用任意 GPT-5.x 模型（如 [`gpt-5.2`](https://platform.openai.com/docs/models/gpt-5.2)）时，SDK 会应用默认 `ModelSettings`。它会设置在大多数场景下效果最佳的配置。要调整默认模型的推理强度，请传入你自己的 `ModelSettings`：
当你以这种方式使用任意 GPT-5.x 模型（如 [`gpt-5.2`](https://platform.openai.com/docs/models/gpt-5.2)）时，SDK 会应用默认 `ModelSettings`。它会设置在大多数用例下表现最好的配置。若要调整默认模型的推理强度，请传入你自己的 `ModelSettings`：
```python
from openai.types.shared import Reasoning
@@ -71,11 +71,11 @@ my_agent = Agent(
)
```
为获得更低延迟，建议在 `gpt-5.2` 上使用 `reasoning.effort="none"`。gpt-4.1 系列（包括 mini 和 nano 变体）在构建交互式智能体应用时也依然是可靠选择。
为获得更低延迟，建议在 `gpt-5.2` 上使用 `reasoning.effort="none"`。gpt-4.1 系列（包括 mini 和 nano 变体）也仍是构建交互式智能体应用的可靠选择。
#### 非 GPT-5 模型
如果你传入非 GPT-5 的模型名且未提供自定义 `model_settings`，SDK 会回退到与任意模型兼容的通用 `ModelSettings`。
如果你传入非 GPT-5 模型名称且未提供自定义 `model_settings`，SDK 会回退到与任意模型兼容的通用 `ModelSettings`。
### Responses WebSocket 传输
@@ -87,11 +87,11 @@ from agents import set_default_openai_responses_transport
set_default_openai_responses_transport("websocket")
```
这会影响由默认 OpenAI 提供方解析的 OpenAI Responses 模型（包括如 `"gpt-5.2"` 这样的字符串模型名）。
这会影响由默认 OpenAI 提供方解析的 OpenAI Responses 模型（包括字符串模型名，如 `"gpt-5.2"`）。
传输方式的选择发生在 SDK 将模型名解析为模型实例时。如果你传入具体的 [`Model`][agents.models.interface.Model] 对象，其传输方式已固定：[`OpenAIResponsesWSModel`][agents.models.openai_responses.OpenAIResponsesWSModel] 使用 websocket，[`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 使用 HTTP，[`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] 则保持使用 Chat Completions。如果你传入 `RunConfig(model_provider=...)`，则由该提供方控制传输方式选择，而不是全局默认值。
传输方式的选择发生在 SDK 将模型名称解析为模型实例时。如果你传入具体的 [`Model`][agents.models.interface.Model] 对象，其传输方式已固定：[`OpenAIResponsesWSModel`][agents.models.openai_responses.OpenAIResponsesWSModel] 使用 websocket，[`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 使用 HTTP，[`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] 则保持 Chat Completions。若你传入 `RunConfig(model_provider=...)`，则由该提供方控制传输选择，而不是全局默认值。
你也可以按提供方或按单次运行配置 websocket 传输：
你还可以按提供方或按运行配置 websocket 传输：
```python
from agents import Agent, OpenAIProvider, RunConfig, Runner
@@ -110,15 +110,15 @@ result = await Runner.run(
)
```
如果你需要基于前缀的模型路由（例如在一次运行中混用 `openai/...` 与 `litellm/...` 模型名），请改用 [`MultiProvider`][agents.MultiProvider] 并在其中设置 `openai_use_responses_websocket=True`。
如果你需要基于前缀的模型路由（例如在一次运行中混用 `openai/...` 和 `litellm/...` 模型名），请改用 [`MultiProvider`][agents.MultiProvider]，并在其中设置 `openai_use_responses_websocket=True`。
如果你使用自定义的 OpenAI 兼容端点或代理，websocket 传输还要求存在兼容的 websocket `/responses` 端点。在这些配置下，你可能需要显式设置 `websocket_base_url`。
如果你使用自定义 OpenAI 兼容端点或代理，websocket 传输还要求有兼容的 websocket `/responses` 端点。在这些设置下，你可能需要显式设置 `websocket_base_url`。
注意：
- 这里指的是通过 websocket 传输的 Responses API，而不是 [Realtime API](../realtime/guide.md)。除非支持 Responses websocket `/responses` 端点，否则这不适用于 Chat Completions 或非 OpenAI 提供方。
- 这是基于 websocket 传输的 Responses API，不是 [Realtime API](../realtime/guide.md)。除非支持 Responses websocket `/responses` 端点，否则它不适用于 Chat Completions 或非 OpenAI 提供方。
- 如果你的环境中尚未安装，请安装 `websockets` 包。
- 启用 websocket 传输后，你可以直接使用 [`Runner.run_streamed()`][agents.run.Runner.run_streamed]。对于希望在多轮工作流（以及嵌套的 agent-as-tool 调用）中复用同一 websocket 连接的场景，建议使用 [`responses_websocket_session()`][agents.responses_websocket_session] 辅助函数。参见 [运行智能体](../running_agents.md) 指南和 [`examples/basic/stream_ws.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/stream_ws.py)。
- 启用 websocket 传输后，你可以直接使用 [`Runner.run_streamed()`][agents.run.Runner.run_streamed]。对于希望在多轮工作流中复用同一 websocket 连接（以及嵌套的 agent-as-tool 调用）的场景，建议使用 [`responses_websocket_session()`][agents.responses_websocket_session] 辅助方法。参见 [运行智能体](../running_agents.md) 指南和 [`examples/basic/stream_ws.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/stream_ws.py)。
## 非 OpenAI 模型
@@ -128,7 +128,7 @@ result = await Runner.run(
pip install "openai-agents[litellm]"
```
然后，使用任意[支持的模型](https://docs.litellm.ai/docs/providers)，并加上 `litellm/` 前缀：
然后，使用任意[受支持模型](https://docs.litellm.ai/docs/providers)，并加上 `litellm/` 前缀：
```python
claude_agent = Agent(model="litellm/anthropic/claude-3-5-sonnet-20240620", ...)
@@ -137,13 +137,13 @@ gemini_agent = Agent(model="litellm/gemini/gemini-2.5-flash-preview-04-17", ...)
### 使用非 OpenAI 模型的其他方式
你还可以通过另外 3 种方式集成其他 LLM 提供方（示例见[这里](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)）：
你还可以通过另外 3 种方式集成其他 LLM 提供方（代码示例见[这里](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)）：
1. [`set_default_openai_client`][agents.set_default_openai_client] 适用于你希望全局使用 `AsyncOpenAI` 实例作为 LLM 客户端的情况。适合 LLM 提供方具备 OpenAI 兼容 API 端点，且你可以设置 `base_url` 与 `api_key` 的场景。可配置示例见 [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py)。
2. [`ModelProvider`][agents.models.interface.ModelProvider] 位于 `Runner.run` 层级。这让你可以声明“本次运行中的所有智能体都使用自定义模型提供方”。可配置示例见 [examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py)。
3. [`Agent.model`][agents.agent.Agent.model] 允许你在特定 Agent 实例上指定模型。这使你能够为不同智能体混用不同提供方。可配置示例见 [examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py)。使用多数可用模型的简便方式是通过 [LiteLLM 集成](./litellm.md)。
1. [`set_default_openai_client`][agents.set_default_openai_client] 适用于你希望在全局使用某个 `AsyncOpenAI` 实例作为 LLM 客户端的场景。适用于 LLM 提供方提供 OpenAI 兼容 API 端点，且你可以设置 `base_url` 和 `api_key` 的情况。可配置示例见 [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py)。
2. [`ModelProvider`][agents.models.interface.ModelProvider] 位于 `Runner.run` 层级。这让你可以指定“在本次运行中所有智能体都使用自定义模型提供方”。可配置示例见 [examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py)。
3. [`Agent.model`][agents.agent.Agent.model] 允许你在特定 Agent 实例上指定模型。这让你可以为不同智能体混合搭配不同提供方。可配置示例见 [examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py)。使用大多数可用模型的简便方式是通过 [LiteLLM 集成](./litellm.md)。
在你没有 `platform.openai.com` API key 的情况下，我们建议通过 `set_tracing_disabled()` 关闭追踪，或配置[其他追踪进程](../tracing.md)。
在你没有来自 `platform.openai.com` 的 API key 时，我们建议通过 `set_tracing_disabled()` 禁用追踪，或设置[不同的追踪进程](../tracing.md)。
!!! note
@@ -151,15 +151,15 @@ gemini_agent = Agent(model="litellm/gemini/gemini-2.5-flash-preview-04-17", ...)
## 高级模型选择与混用
在单个工作流中，你可能希望为每个智能体使用不同模型。例如，你可以为分流使用更小、更快的模型，同时为复杂任务使用更大、能力更强的模型。配置 [`Agent`][agents.Agent] 时，你可以通过以下方式之一选择特定模型：
在单个工作流中，你可能希望为每个智能体使用不同模型。例如，你可以在分流阶段使用更小、更快的模型，而在复杂任务中使用更大、能力更强的模型。配置 [`Agent`][agents.Agent] 时，你可以通过以下方式之一选择特定模型：
1. 传入模型名称。
2. 传入任意模型名 + 可将该名称映射为 Model 实例的 [`ModelProvider`][agents.models.interface.ModelProvider]。
3. 直接提供 [`Model`][agents.models.interface.Model] 实现。
2. 传入任意模型名称 + 可将该名称映射为 Model 实例的 [`ModelProvider`][agents.models.interface.ModelProvider]。
3. 直接提供一个 [`Model`][agents.models.interface.Model] 实现。
!!!note
虽然我们的 SDK 同时支持 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 与 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] 两种形态，但我们建议在每个工作流中使用单一模型形态，因为两者支持的功能和工具集合不同。如果你的工作流需要混用不同模型形态，请确保你使用的所有功能在两者上都可用。
虽然我们的 SDK 同时支持 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 和 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] 两种形态，但我们建议每个工作流使用单一模型形态，因为两种形态支持的功能和工具集合不同。如果你的工作流必须混用模型形态，请确保你使用的所有功能在两者中都可用。
```python
from agents import Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel
@@ -195,7 +195,7 @@ async def main():
1. 直接设置 OpenAI 模型名称。
2. 提供一个 [`Model`][agents.models.interface.Model] 实现。
当你希望进一步配置智能体使用的模型时，可以传入 [`ModelSettings`][agents.models.interface.ModelSettings]，它提供了可选的模型配置参数，如 temperature。
当你希望进一步配置智能体使用的模型时，可以传入 [`ModelSettings`][agents.models.interface.ModelSettings]，它提供了如 temperature 等可选模型配置参数。
```python
from agents import Agent, ModelSettings
@@ -208,7 +208,37 @@ english_agent = Agent(
)
```
此外，当你使用 OpenAI 的 Responses API 时，[还有一些其他可选参数](https://platform.openai.com/docs/api-reference/responses/create)（例如 `user`、`service_tier` 等）。如果它们在顶层不可用，你也可以通过 `extra_args` 传入。
#### 常见高级 `ModelSettings` 选项
当你使用 OpenAI Responses API 时，多个请求字段在 `ModelSettings` 中已有直接对应字段，因此无需为它们使用 `extra_args`。
| 字段 | 用途 |
| --- | --- |
| `parallel_tool_calls` | 允许或禁止在同一轮中进行多个工具调用。 |
| `truncation` | 设为 `"auto"`，可让 Responses API 在上下文将溢出时丢弃最旧的会话项，而不是直接失败。 |
| `prompt_cache_retention` | 让已缓存的提示词前缀保留更久，例如设为 `"24h"`。 |
| `response_include` | 请求更丰富的响应负载，例如 `web_search_call.action.sources`、`file_search_call.results` 或 `reasoning.encrypted_content`。 |
| `top_logprobs` | 为输出文本请求 top-token logprobs。SDK 也会自动添加 `message.output_text.logprobs`。 |
```python
from agents import Agent, ModelSettings
research_agent = Agent(
name="Research agent",
model="gpt-5.2",
model_settings=ModelSettings(
parallel_tool_calls=False,
truncation="auto",
prompt_cache_retention="24h",
response_include=["web_search_call.action.sources"],
top_logprobs=5,
),
)
```
当你需要提供方特有字段，或 SDK 尚未在顶层直接暴露的较新请求字段时，请使用 `extra_args`。
另外，当你使用 OpenAI 的 Responses API 时，[还有一些其他可选参数](https://platform.openai.com/docs/api-reference/responses/create)（例如 `user`、`service_tier` 等）。如果它们在顶层不可用，也可以通过 `extra_args` 传入。
```python
from agents import Agent, ModelSettings
@@ -228,22 +258,22 @@ english_agent = Agent(
### 追踪客户端错误 401
如果你遇到与追踪相关的错误，是因为 trace 会上传到 OpenAI 服务端，而你没有 OpenAI API key。你有三种解决方式：
如果你遇到与追踪相关的错误，这是因为追踪数据会上传到 OpenAI 服务，而你没有 OpenAI API key。你有三种解决方式：
1. 完全禁用追踪：[`set_tracing_disabled(True)`][agents.set_tracing_disabled]。
2. 为追踪设置 OpenAI key：[`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]。该 API key 仅用于上传 trace，且必须来自 [platform.openai.com](https://platform.openai.com/)。
3. 使用非 OpenAI 追踪进程。参见 [追踪文档](../tracing.md#custom-tracing-processors)。
2. 为追踪设置 OpenAI key：[`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]。此 API key 仅用于上传追踪数据，且必须来自 [platform.openai.com](https://platform.openai.com/)。
3. 使用非 OpenAI 的追踪进程。参见[追踪文档](../tracing.md#custom-tracing-processors)。
### Responses API 支持
SDK 默认使用 Responses API，但大多数其他 LLM 提供方尚不支持。因此你可能会看到 404 或类似问题。你有两种解决方式：
1. 调用 [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api]。当你通过环境变量设置 `OPENAI_API_KEY` 和 `OPENAI_BASE_URL` 时可用。
2. 使用 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]。示例见[这里](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)。
2. 使用 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]。代码示例见[这里](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)。
### structured outputs 支持
部分模型提供方不支持 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)。这有时会导致如下所示的错误：
某些模型提供方不支持 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)。这有时会导致类似如下错误：
```
@@ -251,12 +281,12 @@ BadRequestError: Error code: 400 - {'error': {'message': "'response_format.type'
```
这是某些模型提供方的短板——它们支持 JSON 输出，但不允许你为输出指定要使用的 `json_schema`。我们正在修复这一问题，但建议你依赖支持 JSON schema 输出的提供方，否则应用会经常因 JSON 格式错误而中断。
这是某些模型提供方的短板——它们支持 JSON 输出，但不允许你指定用于输出的 `json_schema`。我们正在修复这一问题，但建议你依赖支持 JSON schema 输出的提供方，否则应用经常会因 JSON 格式错误而中断。
## 跨提供方混用模型
你需要注意不同模型提供方的功能差异，否则可能遇到错误。例如，OpenAI 支持 structured outputs、多模态输入，以及托管的文件检索和网络检索，但许多其他提供方不支持这些能力。请注意以下限制：
你需要了解不同模型提供方的功能差异，否则可能遇到错误。例如，OpenAI 支持 structured outputs、多模态输入，以及托管式文件检索和网络检索，但许多其他提供方不支持这些功能。请注意以下限制：
- 不要向不支持的提供方发送其无法理解的 `tools`
- 在调用仅支持文本的模型前，先过滤掉多模态输入
- 注意不支持结构化 JSON 输出的提供方会偶尔生成无效 JSON
- 在调用纯文本模型前，过滤掉多模态输入
- 注意：不支持结构化 JSON 输出的提供方会偶尔产生无效 JSON
docs/zh/sessions/index.md
+92 -61
View File
@@ -4,11 +4,11 @@ search:
---
# 会话
Agents SDK 提供了内置会话内存，可在多次智能体运行之间自动维护对话历史，无需在轮次之间手动处理 `.to_input_list()`。
Agents SDK 提供内置会话记忆功能，可在多次智能体运行间自动维护对话历史，免去在轮次之间手动处理 `.to_input_list()` 的需要。
会话会为特定会话存储对话历史，使智能体无需显式手动管理内存即可保持上下文。这对于构建聊天应用或多轮对话尤其有用，因为你希望智能体记住之前的交互。
会话会为特定会话存储对话历史，使智能体在无需显式手动管理记忆的情况下保持上下文。这对于构建聊天应用或多轮对话尤其实用，因为你希望智能体记住先前交互。
当你希望 SDK 为你管理客户端内存时，请使用会话。如果你已经在使用 OpenAI 通过 `conversation_id` 或 `previous_response_id` 管理的服务端状态，通常不需要再为同一对话额外使用会话。
当你希望 SDK 为你管理客户端侧记忆时，请使用会话。如果你已经在使用 OpenAI 服务端管理状态（通过 `conversation_id` 或 `previous_response_id`），通常不需要再为同一对话额外使用会话。
## 快速开始
@@ -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)
@@ -63,26 +63,26 @@ if result.interruptions:
result = await Runner.run(agent, state, session=session)
```
## 会话核心行为
## 核心会话行为
启用会话内存后：
启用会话记忆后：
1. **每次运行前**：运行器会自动获取该会话的对话历史，并将其前置到输入项之前。
1. **每次运行前**：运行器会自动检索该会话的对话历史，并将其前置到输入项之前。
2. **每次运行后**：运行期间生成的所有新项（用户输入、助手回复、工具调用等）都会自动存入会话。
3. **上下文保留**：后续每次使用同一会话的运行都会包含完整对话历史，从而使智能体能够保持上下文。
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`：当前轮次的新输入项
返回应发送给模型的最终输入项列表。
@@ -107,16 +107,16 @@ result = await Runner.run(
)
```
当你需要自定义裁剪、重排或选择性包含历史，同时不改变会话存储项方式时，可使用此方法。
当你需要自定义裁剪、重排或选择性包含历史内容，同时又不改变会话存储项方式时，可使用此功能。
## 限制检索历史
使用 [`SessionSettings`][agents.memory.SessionSettings] 控制每次运行前拉取多少历史。
使用 [`SessionSettings`][agents.memory.SessionSettings] 控制每次运行前获取多少历史。
- `SessionSettings(limit=None)`（默认）：检索会话中所有可用项
- `SessionSettings(limit=N)`：仅检索最近的 `N` 项
- `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
@@ -132,13 +132,13 @@ result = await Runner.run(
)
```
如果你的会话实现暴露了默认会话设置，`RunConfig.session_settings` 会覆盖该次运行中所有非 `None` 的值。这对于长对话非常有用，你可以在不改变会话默认行为的情况下限制检索规模。
如果你的会话实现暴露了默认会话设置，则 `RunConfig.session_settings` 会覆盖该次运行中所有非 `None` 的值。这对长对话很有用：你可以在不改变会话默认行为的前提下限制检索规模。
## 内存操作
## 记忆操作
### 基本操作
会话支持若干用于管理对话历史的操作：
会话支持多种管理对话历史的操作：
```python
from agents import SQLiteSession
@@ -165,7 +165,7 @@ await session.clear_session()
### 使用 pop_item 进行修正
当你想撤销或修改对话中的最后一项时，`pop_item` 方法尤其有用：
当你希望撤销或修改对话中的最后一项时，`pop_item` 方法尤为有用：
```python
from agents import Agent, Runner, SQLiteSession
@@ -196,24 +196,25 @@ print(f"Agent: {result.final_output}")
## 内置会话实现
SDK 针对不同用例提供了多种会话实现：
SDK 针对不同使用场景提供了多种会话实现：
### 选择内置会话实现
在阅读下方详细示例前，请先用此表选择一个起点。
在阅读下方详细示例前，可先用此表选择一个起点。
| 会话类型 | 最适用场景 | 说明 |
| --- | --- | --- |
| `SQLiteSession` | 本地开发和简单应用 | 内置、轻量，支持文件存储或内存存储 |
| `SQLiteSession` | 本地开发和简单应用 | 内置、轻量、支持文件或内存后端 |
| `AsyncSQLiteSession` | 使用 `aiosqlite` 的异步 SQLite | 扩展后端，支持异步驱动 |
| `RedisSession` | 跨 worker/服务的共享内存 | 适合低延迟分布式部署 |
| `RedisSession` | 跨 worker/服务共享记忆 | 适合低延迟分布式部署 |
| `SQLAlchemySession` | 使用现有数据库的生产应用 | 适用于 SQLAlchemy 支持的数据库 |
| `OpenAIConversationsSession` | OpenAI 中的服务端托管存储 | 基于 OpenAI Conversations API 的历史存储 |
| `OpenAIResponsesCompactionSession` | 带自动压缩的长对话 | 对其他会话后端的封装器 |
| `AdvancedSQLiteSession` | SQLite + 分支/分析能力 | 功能更重；见专门页面 |
| `EncryptedSession` | 在其他会话之上提供加密 + TTL | 封装器；先选择底层后端 |
| `DaprSession` | 带 Dapr sidecar 的云原生部署 | 支持多种状态存储，并提供 TTL 与一致性控制 |
| `OpenAIConversationsSession` | OpenAI 的服务端托管存储 | 基于 OpenAI Conversations API 的历史 |
| `OpenAIResponsesCompactionSession` | 需要自动压缩的长对话 | 对另一会话后端的封装 |
| `AdvancedSQLiteSession` | SQLite + 分支/分析能力 | 功能更重；详见专页 |
| `EncryptedSession` | 在另一会话之上提供加密 + TTL | 封装器；需先选择底层后端 |
部分实现有包含更多细节的专门页面；在各自小节中已内联链接。
部分实现有专门页面提供更多细节；其链接已在对应小节内给出。
### OpenAI Conversations API 会话
@@ -253,7 +254,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` 外层；这两种特性以不同方式管理历史。
#### 典型用法（自动压缩）
@@ -274,13 +275,13 @@ print(result.final_output)
默认情况下，一旦达到候选阈值，每轮后都会执行压缩。
当你已经使用 Responses API 的响应 ID 串联轮次时，`compaction_mode="previous_response_id"` 效果最佳。`compaction_mode="input"` 会改为基于当前会话项重建压缩请求，这在响应链不可用或你希望以会话内容为准时很有用。默认的 `"auto"` 会选择可用且最安全的方式。
当你已经通过 Responses API 的 response ID 串联轮次时，`compaction_mode="previous_response_id"` 效果最佳。`compaction_mode="input"` 则改为从当前会话项重建压缩请求，适用于 response 链不可用，或你希望以会话内容作为事实来源时。默认 `"auto"` 会选择最安全的可用方案。
#### 自动压缩可能阻塞流式传输
压缩会清空并重写会话历史，因此 SDK 会等待压缩完成后才认为该次运行结束。在流式模式下，这意味着若压缩较重，`run.stream_events()` 在最后一个输出 token 后可能还会保持开启几秒。
压缩会清空并重写会话历史，因此 SDK 会等待压缩完成后才将运行视为结束。在流式模式下，这意味着如果压缩负载较重，`run.stream_events()` 在最后一个输出 token 后可能还会保持打开数秒。
如果你希望低延迟流式传输或更快轮次切换，请禁用自动压缩，并在轮次之间（或空闲时）自行调用 `run_compaction()`。你可以根据自己的标准决定何时强制压缩。
如果你希望低延迟流式传输或快速轮转，请关闭自动压缩，并在轮次之间（或空闲时）自行调用 `run_compaction()`。你可以根据自己的标准决定何时强制压缩。
```python
from agents import Agent, Runner, SQLiteSession
@@ -303,7 +304,7 @@ await session.run_compaction({"force": True})
### SQLite 会话
默认的轻量会话实现，基于 SQLite：
默认的轻量级 SQLite 会话实现：
```python
from agents import SQLiteSession
@@ -324,7 +325,7 @@ result = await Runner.run(
### 异步 SQLite 会话
当你希望使用由 `aiosqlite` 支撑的 SQLite 持久化时，请使用 `AsyncSQLiteSession`。
当你需要由 `aiosqlite` 支持持久化的 SQLite 时，使用 `AsyncSQLiteSession`。
```bash
pip install aiosqlite
@@ -341,7 +342,7 @@ result = await Runner.run(agent, "Hello", session=session)
### Redis 会话
使用 `RedisSession` 在多个 worker 或服务之间共享会话内存。
使用 `RedisSession` 在多个 worker 或服务之间共享会话记忆。
```bash
pip install openai-agents[redis]
@@ -379,13 +380,43 @@ engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/db")
session = SQLAlchemySession("user_123", engine=engine, create_tables=True)
```
详见 [SQLAlchemy 会话](sqlalchemy_session.md) 文档。
详见 [SQLAlchemy Sessions](sqlalchemy_session.md) 文档。
### Dapr 会话
当你已在运行 Dapr sidecar，或希望会话存储可在不同状态存储后端间迁移且无需修改智能体代码时，使用 `DaprSession`。
```bash
pip install openai-agents[dapr]
```
```python
from agents import Agent, Runner
from agents.extensions.memory import DaprSession
agent = Agent(name="Assistant")
async with DaprSession.from_address(
"user_123",
state_store_name="statestore",
dapr_address="localhost:50001",
) as session:
result = await Runner.run(agent, "Hello", session=session)
print(result.final_output)
```
说明：
- `from_address(...)` 会为你创建并持有 Dapr 客户端。若你的应用已自行管理客户端，请直接通过 `dapr_client=...` 构造 `DaprSession(...)`。
- 传入 `ttl=...` 可在后端状态存储支持 TTL 时，让其自动过期旧会话数据。
- 当你需要更强的写后读保证时，传入 `consistency=DAPR_CONSISTENCY_STRONG`。
- Dapr Python SDK 也会检查 HTTP sidecar 端点。在本地开发中，请使用 `--dapr-http-port 3500` 启动 Dapr，并同时配置 `dapr_address` 中使用的 gRPC 端口。
- 完整搭建流程（包括本地组件与故障排查）请参见 [`examples/memory/dapr_session_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/dapr_session_example.py)。
### 高级 SQLite 会话
增强型 SQLite 会话，支持对话分支、使用分析和结构化查询：
增强版 SQLite 会话，支持对话分支、用量分析和结构化查询：
```python
from agents.extensions.memory import AdvancedSQLiteSession
@@ -405,11 +436,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) 文档。
详见 [Advanced SQLite Sessions](advanced_sqlite_session.md) 文档。
### 加密会话
适用于任意会话实现的透明加密封装器：
适用于任意会话实现的透明加密封装：
```python
from agents.extensions.memory import EncryptedSession, SQLAlchemySession
@@ -432,33 +463,33 @@ session = EncryptedSession(
result = await Runner.run(agent, "Hello", session=session)
```
详见 [加密会话](encrypted_session.md) 文档。
详见 [Encrypted Sessions](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")`）
- 对临时对话使用内存 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")`）
- 对共享、低延迟会话记忆使用 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()`）
- 若要为任意会话增加透明加密和基于 TTL 的过期机制，使用加密会话（`EncryptedSession(session_id, underlying_session, encryption_key)`）
- 对于更高级用例，可考虑为其他生产系统（例如 Django）实现自定义会话后端
- 使用加密会话（`EncryptedSession(session_id, underlying_session, encryption_key)`）将任意会话封装为透明加密并支持基于 TTL 的过期
- 对更高级场景，可考虑为其他生产系统（如 Django）实现自定义会话后端
### 多会话
@@ -506,7 +537,7 @@ result2 = await Runner.run(
## 完整示例
下面是一个展示会话内存实际效果的完整示例：
以下是一个展示会话记忆实际效果的完整示例：
```python
import asyncio
@@ -570,7 +601,7 @@ if __name__ == "__main__":
## 自定义会话实现
你可以通过创建符合 [`Session`][agents.memory.session.Session] 协议的类，实现自己的会话内存：
你可以通过创建遵循 [`Session`][agents.memory.session.Session] 协议的类来实现自己的会话记忆：
```python
from agents.memory.session import SessionABC
@@ -615,25 +646,25 @@ result = await Runner.run(
## 社区会话实现
社区已开发了额外的会话实现：
社区已开发出额外的会话实现：
| Package | Description |
| Package | 描述 |
|---------|-------------|
| [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 ORM 的会话，适用于 Django 支持的任意数据库（PostgreSQL、MySQL、SQLite 等） |
如果你构建了会话实现，欢迎提交文档 PR 将其添加到这里！
## 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 驱动实现
- [`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] - 适用于任意会话的加密封装