diff --git a/docs/ja/models/index.md b/docs/ja/models/index.md index 58e482a0b4..90e76acd8c 100644 --- a/docs/ja/models/index.md +++ b/docs/ja/models/index.md @@ -4,29 +4,29 @@ 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]。 ## モデル設定の選択 -ご自身の設定に合う、最もシンプルな方法から始めてください。 +設定に合う最もシンプルな方法から始めてください。 | やりたいこと | 推奨される方法 | 詳細 | | --- | --- | --- | -| OpenAI モデルのみを使用する | デフォルトの OpenAI プロバイダーを Responses モデルパスで使用する | [OpenAI モデル](#openai-models) | -| OpenAI Responses API を websocket トランスポート経由で使用する | Responses モデルパスを維持し、websocket トランスポートを有効にする | [Responses WebSocket トランスポート](#responses-websocket-transport) | -| OpenAI 以外のプロバイダーを 1 つ使用する | 組み込みのプロバイダー統合ポイントから始める | [OpenAI 以外のモデル](#non-openai-models) | -| エージェント間でモデルまたはプロバイダーを混在させる | 実行ごと、またはエージェントごとにプロバイダーを選択し、機能差を確認する | [1 つのワークフローでモデルを混在させる](#mixing-models-in-one-workflow) と [プロバイダー間でモデルを混在させる](#mixing-models-across-providers) | -| OpenAI Responses の高度なリクエスト設定を調整する | OpenAI Responses パスで `ModelSettings` を使用する | [高度な OpenAI Responses 設定](#advanced-openai-responses-settings) | -| OpenAI 以外または混在プロバイダーのルーティングにサードパーティアダプターを使用する | サポートされている beta アダプターを比較し、出荷予定のプロバイダーパスを検証する | [サードパーティアダプター](#third-party-adapters) | +| OpenAI モデルのみを使用する | デフォルトの OpenAI プロバイダーを Responses モデルの経路で使用する | [OpenAI モデル](#openai-models) | +| websocket トランスポート経由で OpenAI Responses API を使用する | Responses モデルの経路を維持し、websocket トランスポートを有効にする | [Responses WebSocket トランスポート](#responses-websocket-transport) | +| 1 つの非 OpenAI プロバイダーを使用する | 組み込みのプロバイダー統合ポイントから始める | [非 OpenAI モデル](#non-openai-models) | +| エージェント間でモデルやプロバイダーを混在させる | 実行ごと、またはエージェントごとにプロバイダーを選択し、機能の違いを確認する | [1 つのワークフローでのモデルの混在](#mixing-models-in-one-workflow) と [プロバイダー間でのモデルの混在](#mixing-models-across-providers) | +| 高度な OpenAI Responses リクエスト設定を調整する | OpenAI Responses の経路で `ModelSettings` を使用する | [高度な OpenAI Responses 設定](#advanced-openai-responses-settings) | +| 非 OpenAI または混在プロバイダーのルーティングにサードパーティアダプターを使用する | サポートされているベータ版アダプターを比較し、提供予定のプロバイダー経路を検証する | [サードパーティアダプター](#third-party-adapters) | ## OpenAI モデル -OpenAI のみを使用するほとんどのアプリでは、デフォルトの OpenAI プロバイダーで文字列のモデル名を使用し、Responses モデルパスに留まることを推奨します。 +ほとんどの OpenAI のみのアプリでは、デフォルトの OpenAI プロバイダーで文字列のモデル名を使用し、Responses モデルの経路に留まることを推奨します。 -`Agent` の初期化時にモデルを指定しない場合、デフォルトモデルが使用されます。現在のデフォルトは、低レイテンシのエージェントワークフロー向けに、`reasoning.effort="none"` および `verbosity="low"` を設定した [`gpt-5.4-mini`](https://developers.openai.com/api/docs/models/gpt-5.4-mini) です。アクセス権がある場合は、明示的な `model_settings` を維持しつつ、より高品質な [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) をエージェントに設定することを推奨します。 +`Agent` の初期化時にモデルを指定しない場合、デフォルトモデルが使用されます。現在のデフォルトは、低レイテンシのエージェントワークフロー向けに、`reasoning.effort="none"` と `verbosity="low"` を設定した [`gpt-5.4-mini`](https://developers.openai.com/api/docs/models/gpt-5.4-mini) です。アクセス権がある場合は、明示的な `model_settings` を維持しつつ、より高い品質のためにエージェントを [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) に設定することを推奨します。 [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) のような他のモデルに切り替えたい場合、エージェントを設定する方法は 2 つあります。 @@ -39,7 +39,7 @@ export OPENAI_DEFAULT_MODEL=gpt-5.5 python3 my_awesome_agent.py ``` -次に、`RunConfig` を介して実行のデフォルトモデルを設定できます。エージェントにモデルを設定しない場合、この実行のモデルが使用されます。 +次に、`RunConfig` を使って実行のデフォルトモデルを設定できます。エージェントにモデルを設定していない場合、この実行のモデルが使用されます。 ```python from agents import Agent, RunConfig, Runner @@ -58,7 +58,7 @@ result = await Runner.run( #### GPT-5 モデル -この方法で [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) などの GPT-5 モデルを使用すると、SDK はデフォルトの `ModelSettings` を適用します。ほとんどのユースケースで最適に動作する設定が適用されます。デフォルトモデルの推論 effort を調整するには、独自の `ModelSettings` を渡します。 +この方法で [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) などの GPT-5 モデルを使用すると、SDK はデフォルトの `ModelSettings` を適用します。ほとんどのユースケースで最適に機能する設定が使用されます。デフォルトモデルの reasoning effort を調整するには、独自の `ModelSettings` を渡します。 ```python from openai.types.shared import Reasoning @@ -74,35 +74,35 @@ my_agent = Agent( ) ``` -低レイテンシを重視する場合は、GPT-5 モデルで `reasoning.effort="none"` を使用することを推奨します。 +より低いレイテンシのためには、GPT-5 モデルで `reasoning.effort="none"` を使用することを推奨します。 -#### ComputerTool モデル選択 +#### ComputerTool のモデル選択 -エージェントに [`ComputerTool`][agents.tool.ComputerTool] が含まれる場合、実際の Responses リクエストで有効なモデルによって、SDK が送信する computer-tool ペイロードが決まります。明示的な `gpt-5.5` リクエストでは GA 組み込みの `computer` ツールが使用され、明示的な `computer-use-preview` リクエストでは従来の `computer_use_preview` ペイロードが維持されます。 +エージェントに [`ComputerTool`][agents.tool.ComputerTool] が含まれている場合、実際の Responses リクエストで有効なモデルにより、SDK が送信する computer-tool ペイロードが決まります。明示的な `gpt-5.5` リクエストでは GA 組み込みの `computer` ツールが使用され、明示的な `computer-use-preview` リクエストでは古い `computer_use_preview` ペイロードが維持されます。 -主な例外は、プロンプト管理の呼び出しです。プロンプトテンプレートがモデルを所有し、SDK がリクエストから `model` を省略する場合、SDK はプロンプトがどのモデルに固定しているかを推測しないよう、preview 互換の computer ペイロードをデフォルトにします。このフローで GA パスを維持するには、リクエストで `model="gpt-5.5"` を明示するか、`ModelSettings(tool_choice="computer")` または `ModelSettings(tool_choice="computer_use")` で GA セレクターを強制します。 +主な例外はプロンプト管理の呼び出しです。プロンプトテンプレートがモデルを所有し、SDK がリクエストから `model` を省略する場合、SDK はプロンプトがどのモデルに固定しているかを推測しないよう、プレビュー互換の computer ペイロードをデフォルトにします。このフローで GA 経路を維持するには、リクエストで `model="gpt-5.5"` を明示するか、`ModelSettings(tool_choice="computer")` または `ModelSettings(tool_choice="computer_use")` で GA セレクターを強制します。 -登録済みの [`ComputerTool`][agents.tool.ComputerTool] がある場合、`tool_choice="computer"`、`"computer_use"`、`"computer_use_preview"` は、有効なリクエストモデルに一致する組み込みセレクターへ正規化されます。`ComputerTool` が登録されていない場合、これらの文字列は通常の関数名と同様に動作し続けます。 +登録済みの [`ComputerTool`][agents.tool.ComputerTool] がある場合、`tool_choice="computer"`、`"computer_use"`、`"computer_use_preview"` は、有効なリクエストモデルに一致する組み込みセレクターへ正規化されます。`ComputerTool` が登録されていない場合、これらの文字列は通常の関数名のように振る舞い続けます。 -Preview 互換リクエストでは、`environment` と表示寸法を事前にシリアライズする必要があります。そのため、[`ComputerProvider`][agents.tool.ComputerProvider] ファクトリを使用するプロンプト管理フローでは、具体的な `Computer` または `AsyncComputer` インスタンスを渡すか、リクエスト送信前に GA セレクターを強制する必要があります。移行の詳細については、[ツール](../tools.md#computertool-and-the-responses-computer-tool) を参照してください。 +プレビュー互換のリクエストでは `environment` と表示寸法を事前にシリアライズする必要があるため、[`ComputerProvider`][agents.tool.ComputerProvider] ファクトリーを使用するプロンプト管理フローでは、具体的な `Computer` または `AsyncComputer` インスタンスを渡すか、リクエスト送信前に GA セレクターを強制する必要があります。移行の詳細については [Tools](../tools.md#computertool-and-the-responses-computer-tool) を参照してください。 -#### GPT-5 以外のモデル +#### 非 GPT-5 モデル -カスタム `model_settings` なしで GPT-5 以外のモデル名を渡した場合、SDK は任意のモデルと互換性のある汎用 `ModelSettings` に戻ります。 +カスタム `model_settings` なしで非 GPT-5 モデル名を渡すと、SDK は任意のモデルと互換性のある汎用の `ModelSettings` に戻します。 -### Responses 限定のツール検索機能 +### Responses のみのツール検索機能 -次のツール機能は、OpenAI Responses モデルでのみサポートされます。 +次のツール機能は OpenAI Responses モデルでのみサポートされます。 - [`ToolSearchTool`][agents.tool.ToolSearchTool] - [`tool_namespace()`][agents.tool.tool_namespace] -- `@function_tool(defer_loading=True)` およびその他の deferred-loading Responses ツールサーフェス +- `@function_tool(defer_loading=True)` およびその他の遅延読み込み Responses ツールサーフェス -これらの機能は、Chat Completions モデルおよび Responses 以外のバックエンドでは拒否されます。deferred-loading ツールを使用する場合は、エージェントに `ToolSearchTool()` を追加し、裸の namespace 名や deferred-only 関数名を強制する代わりに、モデルが `auto` または `required` のツール選択を通じてツールを読み込めるようにしてください。設定の詳細と現在の制約については、[ツール](../tools.md#hosted-tool-search) を参照してください。 +これらの機能は、Chat Completions モデルおよび非 Responses バックエンドでは拒否されます。遅延読み込みツールを使用する場合は、エージェントに `ToolSearchTool()` を追加し、裸の名前空間名や遅延専用の関数名を強制するのではなく、`auto` または `required` のツール選択によってモデルにツールを読み込ませてください。設定の詳細と現在の制約については [Tools](../tools.md#hosted-tool-search) を参照してください。 ### Responses WebSocket トランスポート -デフォルトでは、OpenAI Responses API リクエストは HTTP トランスポートを使用します。OpenAI ベースのモデルを使用している場合、websocket トランスポートを選択できます。 +デフォルトでは、OpenAI Responses API リクエストは HTTP トランスポートを使用します。OpenAI バックのモデルを使用する場合、websocket トランスポートを選択できます。 #### 基本設定 @@ -114,11 +114,11 @@ set_default_openai_responses_transport("websocket") これは、デフォルトの OpenAI プロバイダーによって解決される OpenAI Responses モデル（`"gpt-5.5"` などの文字列モデル名を含む）に影響します。 -トランスポートの選択は、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 @@ -139,7 +139,7 @@ result = await Runner.run( ) ``` -OpenAI ベースのプロバイダーは、任意のエージェント登録設定も受け付けます。これは、OpenAI 設定が harness ID などのプロバイダーレベルの登録メタデータを期待する場合の高度なオプションです。 +OpenAI バックのプロバイダーは、任意のエージェント登録設定も受け付けます。これは、OpenAI 設定が harness ID などのプロバイダーレベル登録メタデータを想定している場合の高度なオプションです。 ```python from agents import ( @@ -165,14 +165,14 @@ result = await Runner.run( #### `MultiProvider` による高度なルーティング -プレフィックスベースのモデルルーティングが必要な場合（たとえば、1 回の実行で `openai/...` と `any-llm/...` のモデル名を混在させる場合）は、[`MultiProvider`][agents.MultiProvider] を使用し、そこで `openai_use_responses_websocket=True` を設定します。 +プレフィックスベースのモデルルーティングが必要な場合（たとえば 1 つの実行で `openai/...` と `any-llm/...` のモデル名を混在させる場合）、[`MultiProvider`][agents.MultiProvider] を使用し、そこで `openai_use_responses_websocket=True` を設定します。 -`MultiProvider` は 2 つの従来のデフォルトを維持しています。 +`MultiProvider` は 2 つの歴史的なデフォルトを維持しています。 - `openai/...` は OpenAI プロバイダーのエイリアスとして扱われるため、`openai/gpt-4.1` はモデル `gpt-4.1` としてルーティングされます。 - 不明なプレフィックスは、そのまま渡されるのではなく `UserError` を発生させます。 -OpenAI 互換エンドポイントが、名前空間付きモデル ID のリテラルを期待している場合は、パススルー動作を明示的に選択します。websocket が有効な設定では、`MultiProvider` でも `openai_use_responses_websocket=True` を維持してください。 +OpenAI 互換エンドポイントがリテラルな名前空間付きモデル ID を期待する場合、OpenAI プロバイダーをそのエンドポイントに向ける際は、パススルー動作を明示的に有効にしてください。websocket が有効な設定では、`MultiProvider` 上でも `openai_use_responses_websocket=True` を維持してください。 ```python from agents import Agent, MultiProvider, RunConfig, Runner @@ -198,39 +198,39 @@ result = await Runner.run( ) ``` -バックエンドがリテラルの `openai/...` 文字列を期待する場合は、`openai_prefix_mode="model_id"` を使用します。バックエンドが `openrouter/openai/gpt-4.1-mini` などの他の名前空間付きモデル ID を期待する場合は、`unknown_prefix_mode="model_id"` を使用します。これらのオプションは、websocket トランスポート外の `MultiProvider` でも機能します。この例で websocket を有効にしているのは、このセクションで説明しているトランスポート設定の一部だからです。同じオプションは [`responses_websocket_session()`][agents.responses_websocket_session] でも利用できます。 +バックエンドがリテラルな `openai/...` 文字列を期待する場合は `openai_prefix_mode="model_id"` を使用します。バックエンドが `openrouter/openai/gpt-4.1-mini` など、他の名前空間付きモデル ID を期待する場合は `unknown_prefix_mode="model_id"` を使用します。これらのオプションは websocket トランスポート以外の `MultiProvider` でも機能します。この例では、このセクションで説明しているトランスポート設定の一部であるため、websocket を有効のままにしています。同じオプションは [`responses_websocket_session()`][agents.responses_websocket_session] でも利用できます。 -`MultiProvider` 経由でルーティングする際に同じプロバイダーレベルの登録メタデータが必要な場合は、`openai_agent_registration=OpenAIAgentRegistrationConfig(...)` を渡すと、基盤となる OpenAI プロバイダーへ転送されます。 +`MultiProvider` 経由でルーティングしながら同じプロバイダーレベル登録メタデータが必要な場合は、`openai_agent_registration=OpenAIAgentRegistrationConfig(...)` を渡すと、基盤となる OpenAI プロバイダーに転送されます。 -カスタムの OpenAI 互換エンドポイントまたはプロキシを使用する場合、websocket トランスポートには互換性のある websocket `/responses` エンドポイントも必要です。そのような設定では、`websocket_base_url` を明示的に設定する必要がある場合があります。 +カスタム OpenAI 互換エンドポイントまたはプロキシを使用する場合、websocket トランスポートには互換性のある websocket `/responses` エンドポイントも必要です。そのような設定では、`websocket_base_url` を明示的に設定する必要がある場合があります。 #### 注記 -- これは websocket トランスポート経由の Responses API であり、[Realtime API](../realtime/guide.md) ではありません。Chat Completions や OpenAI 以外のプロバイダーには、Responses websocket `/responses` エンドポイントをサポートしていない限り適用されません。 +- これは websocket トランスポート経由の Responses API であり、[Realtime API](../realtime/guide.md) ではありません。Chat Completions や非 OpenAI プロバイダーには、Responses websocket `/responses` エンドポイントをサポートしていない限り適用されません。 - 環境でまだ利用できない場合は、`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) を参照してください。 -- 長い推論ターンやレイテンシのスパイクがあるネットワークでは、`responses_websocket_options` で websocket keepalive の動作をカスタマイズしてください。遅延した pong フレームを許容するには `ping_timeout` を増やし、ping を有効にしたままハートビートタイムアウトを無効にするには `ping_timeout=None` を設定します。websocket の低レイテンシより信頼性が重要な場合は、HTTP/SSE トランスポートを優先してください。 +- websocket トランスポートを有効にした後、[`Runner.run_streamed()`][agents.run.Runner.run_streamed] を直接使用できます。複数ターンのワークフローで、同じ websocket 接続をターン間（およびネストされた agent-as-tool 呼び出し）で再利用したい場合は、[`responses_websocket_session()`][agents.responses_websocket_session] ヘルパーを推奨します。[Running agents](../running_agents.md) ガイドと [`examples/basic/stream_ws.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/stream_ws.py) を参照してください。 +- 長い reasoning ターンやレイテンシの急増があるネットワークでは、`responses_websocket_options` で websocket keepalive の動作をカスタマイズしてください。遅延した pong フレームを許容するには `ping_timeout` を増やすか、ping を有効にしたまま heartbeat タイムアウトを無効にするには `ping_timeout=None` を設定します。websocket レイテンシよりも信頼性が重要な場合は、HTTP/SSE トランスポートを優先してください。 -## OpenAI 以外のモデル +## 非 OpenAI モデル -OpenAI 以外のプロバイダーが必要な場合は、SDK の組み込みプロバイダー統合ポイントから始めてください。多くの設定では、サードパーティアダプターを追加しなくてもこれで十分です。各パターンの例は [examples/model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/) にあります。 +非 OpenAI プロバイダーが必要な場合は、SDK の組み込みプロバイダー統合ポイントから始めてください。多くの設定では、サードパーティアダプターを追加しなくてもこれで十分です。各パターンの例は [examples/model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/) にあります。 -### OpenAI 以外のプロバイダーの統合方法 +### 非 OpenAI プロバイダーの統合方法 | アプローチ | 使用する場合 | スコープ | | --- | --- | --- | | [`set_default_openai_client`][agents.set_default_openai_client] | 1 つの OpenAI 互換エンドポイントを、ほとんどまたはすべてのエージェントのデフォルトにしたい場合 | グローバルデフォルト | | [`ModelProvider`][agents.models.interface.ModelProvider] | 1 つのカスタムプロバイダーを単一の実行に適用したい場合 | 実行ごと | -| [`Agent.model`][agents.agent.Agent.model] | エージェントごとに異なるプロバイダーまたは具体的なモデルオブジェクトが必要な場合 | エージェントごと | -| サードパーティアダプター | 組み込みパスでは提供されない、アダプター管理のプロバイダーカバレッジまたはルーティングが必要な場合 | [サードパーティアダプター](#third-party-adapters) を参照 | +| [`Agent.model`][agents.agent.Agent.model] | 異なるエージェントに異なるプロバイダーまたは具体的なモデルオブジェクトが必要な場合 | エージェントごと | +| サードパーティアダプター | 組み込みの経路では提供されない、アダプター管理のプロバイダーカバレッジまたはルーティングが必要な場合 | [サードパーティアダプター](#third-party-adapters) を参照 | -これらの組み込みパスを使用して、他の LLM プロバイダーを統合できます。 +これらの組み込み経路を使って他の LLM プロバイダーを統合できます。 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) を参照してください。 +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) を参照してください。 -`platform.openai.com` の API キーがない場合は、`set_tracing_disabled()` でトレーシングを無効にするか、[別のトレーシングプロセッサー](../tracing.md) を設定することを推奨します。 +`platform.openai.com` の API キーを持っていない場合は、`set_tracing_disabled()` でトレーシングを無効化するか、[別のトレーシングプロセッサー](../tracing.md) を設定することを推奨します。 ``` python from agents import Agent, AsyncOpenAI, OpenAIChatCompletionsModel, set_tracing_disabled @@ -245,11 +245,11 @@ agent= Agent(name="Helping Agent", instructions="You are a Helping Agent", model !!! note - これらの例では、Chat Completions API/モデルを使用しています。これは、多くの LLM プロバイダーがまだ Responses API をサポートしていないためです。ご利用の LLM プロバイダーが Responses をサポートしている場合は、Responses の使用を推奨します。 + これらの例では、多くの LLM プロバイダーがまだ Responses API をサポートしていないため、Chat Completions API/モデルを使用しています。LLM プロバイダーが Responses をサポートしている場合は、Responses を使用することを推奨します。 ## 1 つのワークフローでのモデルの混在 -単一のワークフロー内で、エージェントごとに異なるモデルを使用したい場合があります。たとえば、トリアージには小型で高速なモデルを使用し、複雑なタスクにはより大きく高性能なモデルを使用できます。[`Agent`][agents.Agent] を設定する際、次のいずれかの方法で特定のモデルを選択できます。 +単一のワークフロー内で、各エージェントに異なるモデルを使用したい場合があります。たとえば、トリアージにはより小さく高速なモデルを使用し、複雑なタスクにはより大きく高性能なモデルを使用できます。[`Agent`][agents.Agent] を設定するときは、次のいずれかによって特定のモデルを選択できます。 1. モデル名を渡す。 2. 任意のモデル名と、その名前を Model インスタンスにマッピングできる [`ModelProvider`][agents.models.interface.ModelProvider] を渡す。 @@ -257,7 +257,7 @@ agent= Agent(name="Helping Agent", instructions="You are a Helping Agent", model !!! 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 @@ -293,7 +293,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 @@ -308,20 +308,20 @@ english_agent = Agent( ## 高度な OpenAI Responses 設定 -OpenAI Responses パスを使用していて、より細かな制御が必要な場合は、`ModelSettings` から始めてください。 +OpenAI Responses の経路を使用していて、より細かな制御が必要な場合は、`ModelSettings` から始めてください。 ### 一般的な高度な `ModelSettings` オプション -OpenAI Responses API を使用している場合、いくつかのリクエストフィールドにはすでに直接の `ModelSettings` フィールドがあるため、それらに `extra_args` は不要です。 +OpenAI Responses API を使用している場合、いくつかのリクエストフィールドにはすでに直接対応する `ModelSettings` フィールドがあるため、それらに `extra_args` は不要です。 -- `parallel_tool_calls`: 同じターンで複数のツール呼び出しを許可または禁止します。 -- `truncation`: コンテキストがあふれる場合に失敗する代わりに、Responses API が最も古い会話 item を削除できるようにするには `"auto"` を設定します。 -- `store`: 生成されたレスポンスを後で取得できるようにサーバー側に保存するかどうかを制御します。これは、レスポンス ID に依存するフォローアップワークフローや、`store=False` の場合にローカル入力へフォールバックする必要があるセッション圧縮フローで重要です。 +- `parallel_tool_calls`: 同じターン内で複数のツール呼び出しを許可または禁止します。 +- `truncation`: コンテキストがあふれる場合に失敗するのではなく、Responses API が最も古い会話アイテムを削除できるようにするには `"auto"` を設定します。 +- `store`: 生成されたレスポンスを後で取得できるようサーバー側に保存するかどうかを制御します。これは、レスポンス ID に依存するフォローアップワークフローや、`store=False` の場合にローカル入力へフォールバックする必要がある可能性のあるセッション圧縮フローに関係します。 - `context_management`: `compact_threshold` を使用した Responses 圧縮など、サーバー側のコンテキスト処理を設定します。 -- `prompt_cache_retention`: たとえば `"24h"` を使用して、キャッシュされたプロンプトプレフィックスをより長く保持します。 -- `response_include`: `web_search_call.action.sources`、`file_search_call.results`、`reasoning.encrypted_content` など、よりリッチなレスポンスペイロードを要求します。 +- `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` も自動的に追加します。 -- `retry`: モデル呼び出しに対する runner 管理のリトライ設定を有効にします。[Runner 管理のリトライ](#runner-managed-retries) を参照してください。 +- `retry`: モデル呼び出しに対して runner 管理のリトライ設定を有効にします。[Runner 管理のリトライ](#runner-managed-retries) を参照してください。 ```python from agents import Agent, ModelSettings @@ -341,15 +341,15 @@ research_agent = Agent( ) ``` -`store=False` を設定すると、Responses API はそのレスポンスを後でサーバー側取得できるように保持しません。これはステートレスまたはゼロデータ保持型のフローでは有用ですが、通常であればレスポンス ID を再利用する機能が、代わりにローカル管理の状態に依存する必要があることも意味します。たとえば、[`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession] は、最後のレスポンスが保存されていなかった場合、デフォルトの `"auto"` 圧縮パスを入力ベースの圧縮に切り替えます。[Sessions ガイド](../sessions/index.md#openai-responses-compaction-sessions) を参照してください。 +`store=False` を設定すると、Responses API はそのレスポンスを後でサーバー側で取得できるようには保持しません。これはステートレスまたはゼロデータ保持スタイルのフローに便利ですが、通常であればレスポンス ID を再利用する機能が、代わりにローカル管理の状態に依存する必要があることも意味します。たとえば、[`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession] は、最後のレスポンスが保存されていなかった場合、デフォルトの `"auto"` 圧縮経路を入力ベースの圧縮に切り替えます。[Sessions guide](../sessions/index.md#openai-responses-compaction-sessions) を参照してください。 -サーバー側圧縮は [`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession] とは異なります。`context_management=[{"type": "compaction", "compact_threshold": ...}]` は各 Responses API リクエストと一緒に送信され、レンダリングされたコンテキストがしきい値を超えると、API はレスポンスの一部として圧縮 item を発行できます。`OpenAIResponsesCompactionSession` はターン間でスタンドアロンの `responses.compact` エンドポイントを呼び出し、ローカルセッション履歴を書き換えます。 +サーバー側圧縮は [`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession] とは異なります。`context_management=[{"type": "compaction", "compact_threshold": ...}]` は各 Responses API リクエストとともに送信され、レンダリングされたコンテキストがしきい値を超えると、API はレスポンスの一部として圧縮アイテムを出力できます。`OpenAIResponsesCompactionSession` はターン間でスタンドアロンの `responses.compact` エンドポイントを呼び出し、ローカルセッション履歴を書き換えます。 ### `extra_args` の渡し方 -SDK がまだトップレベルで直接公開していない、プロバイダー固有または新しいリクエストフィールドが必要な場合は、`extra_args` を使用します。 +SDK がまだトップレベルで直接公開していない、プロバイダー固有またはより新しいリクエストフィールドが必要な場合は `extra_args` を使用します。 -また、OpenAI の Responses API を使用する場合、[その他にもいくつかの任意パラメーター](https://platform.openai.com/docs/api-reference/responses/create)（例: `user`、`service_tier` など）があります。これらがトップレベルで利用できない場合も、`extra_args` を使用して渡せます。同じリクエストフィールドを直接の `ModelSettings` フィールドでも設定しないでください。 +また、OpenAI の Responses API を使用する場合、[その他の任意パラメーターがいくつかあります](https://platform.openai.com/docs/api-reference/responses/create)（例: `user`、`service_tier` など）。それらがトップレベルで利用できない場合も、`extra_args` を使って渡せます。同じリクエストフィールドを直接の `ModelSettings` フィールドでも設定しないでください。 ```python from agents import Agent, ModelSettings @@ -367,7 +367,7 @@ english_agent = Agent( ## Runner 管理のリトライ -リトライは runtime のみであり、オプトインです。`ModelSettings(retry=...)` を設定し、リトライポリシーがリトライを選択しない限り、SDK は一般的なモデルリクエストをリトライしません。 +リトライはランタイム専用で、明示的に有効化する必要があります。`ModelSettings(retry=...)` を設定し、リトライポリシーがリトライを選択しない限り、SDK は一般的なモデルリクエストをリトライしません。 ```python from agents import Agent, ModelRetrySettings, ModelSettings, retry_policies @@ -402,78 +402,78 @@ agent = Agent( | フィールド | 型 | 注記 | | --- | --- | --- | | `max_retries` | `int | None` | 初回リクエスト後に許可されるリトライ試行回数。 | -| `backoff` | `ModelRetryBackoffSettings | dict | None` | ポリシーが明示的な遅延を返さずにリトライする場合のデフォルト遅延戦略。 | -| `policy` | `RetryPolicy | None` | リトライするかどうかを決定するコールバック。このフィールドは runtime 専用で、シリアライズされません。 | +| `backoff` | `ModelRetryBackoffSettings | dict | None` | ポリシーが明示的な遅延を返さずにリトライする場合のデフォルト遅延戦略。`backoff.max_delay` は、この計算された backoff 遅延のみを上限設定します。ポリシーが返す明示的な遅延や retry-after ヒントには上限を設けません。 | +| `policy` | `RetryPolicy | None` | リトライするかどうかを決定するコールバック。このフィールドはランタイム専用で、シリアライズされません。 | リトライポリシーは、次を含む [`RetryPolicyContext`][agents.retry.RetryPolicyContext] を受け取ります。 -- `attempt` と `max_retries`: 試行回数を考慮した判断を行うために使用できます。 -- `stream`: ストリーミングと非ストリーミングの動作を分岐するために使用できます。 -- `error`: raw な検査用です。 +- `attempt` と `max_retries` により、試行回数を意識した判断ができます。 +- `stream` により、ストリーミングと非ストリーミングの動作を分岐できます。 +- raw な検査のための `error`。 - `status_code`、`retry_after`、`error_code`、`is_network_error`、`is_timeout`、`is_abort` などの正規化された事実。 - 基盤となるモデルアダプターがリトライ指針を提供できる場合の `provider_advice`。 ポリシーは次のいずれかを返せます。 -- 単純なリトライ判断のための `True` / `False`。 -- 遅延を上書きしたり診断理由を付与したい場合の [`RetryDecision`][agents.retry.RetryDecision]。 +- シンプルなリトライ判断としての `True` / `False`。 +- 遅延を上書きしたり診断理由を添付したりしたい場合の [`RetryDecision`][agents.retry.RetryDecision]。 -SDK は `retry_policies` にすぐ使えるヘルパーをエクスポートしています。 +SDK は `retry_policies` 上に既製のヘルパーをエクスポートしています。 | ヘルパー | 動作 | | --- | --- | -| `retry_policies.never()` | 常にオプトアウトします。 | -| `retry_policies.provider_suggested()` | 利用可能な場合、プロバイダーのリトライ助言に従います。 | +| `retry_policies.never()` | 常にリトライしません。 | +| `retry_policies.provider_suggested()` | 利用可能な場合、プロバイダーのリトライ指針に従います。 | | `retry_policies.network_error()` | 一時的なトランスポート障害およびタイムアウト障害に一致します。 | | `retry_policies.http_status([...])` | 選択した HTTP ステータスコードに一致します。 | -| `retry_policies.retry_after()` | retry-after ヒントが利用可能な場合にのみ、その遅延を使用してリトライします。 | -| `retry_policies.any(...)` | ネストされたいずれかのポリシーがオプトインした場合にリトライします。 | -| `retry_policies.all(...)` | ネストされたすべてのポリシーがオプトインした場合にのみリトライします。 | +| `retry_policies.retry_after()` | retry-after ヒントが利用可能な場合にのみ、その遅延を使ってリトライします。このヘルパーは retry-after 値を明示的なポリシー遅延として扱うため、`backoff.max_delay` はそれを上限設定しません。 | +| `retry_policies.any(...)` | ネストされたポリシーのいずれかが有効にした場合にリトライします。 | +| `retry_policies.all(...)` | ネストされたすべてのポリシーが有効にした場合にのみリトライします。 | -ポリシーを合成する場合、`provider_suggested()` は最も安全な最初の構成要素です。プロバイダーが判別できる場合に、プロバイダーの拒否および replay-safe な承認を保持するためです。 +ポリシーを合成する場合、`provider_suggested()` は、プロバイダーが区別できる場合にプロバイダーの拒否や再実行安全性の承認を保持するため、最も安全な最初の構成要素です。 ##### 安全境界 -一部の失敗は自動的には決してリトライされません。 +一部の失敗は自動的にリトライされません。 - Abort エラー。 -- プロバイダー助言がリプレイを安全でないと示しているリクエスト。 -- 出力がすでに開始され、リプレイが安全でなくなる方法で進行した後のストリーミング実行。 +- プロバイダーの助言が再実行を安全ではないと示すリクエスト。 +- 出力がすでに開始され、再実行が安全でなくなるような形になった後のストリーミング実行。 -`previous_response_id` または `conversation_id` を使用するステートフルなフォローアップリクエストも、より保守的に扱われます。これらのリクエストでは、`network_error()` や `http_status([500])` のような非プロバイダー述語だけでは不十分です。リトライポリシーには、通常 `retry_policies.provider_suggested()` を介した、プロバイダーからの replay-safe な承認を含める必要があります。 +`previous_response_id` または `conversation_id` を使用するステートフルなフォローアップリクエストも、より保守的に扱われます。これらのリクエストでは、`network_error()` や `http_status([500])` などの非プロバイダー述語だけでは十分ではありません。リトライポリシーには、通常 `retry_policies.provider_suggested()` を介して、プロバイダーからの再実行安全性の承認を含める必要があります。 ##### Runner とエージェントのマージ動作 `retry` は runner レベルとエージェントレベルの `ModelSettings` の間でディープマージされます。 -- エージェントは `retry.max_retries` だけを上書きしつつ、runner の `policy` を継承できます。 -- エージェントは `retry.backoff` の一部だけを上書きし、runner の兄弟 backoff フィールドを維持できます。 -- `policy` は runtime 専用なので、シリアライズされた `ModelSettings` では `max_retries` と `backoff` は保持されますが、コールバック自体は省略されます。 +- エージェントは `retry.max_retries` だけを上書きし、runner の `policy` を継承できます。 +- エージェントは `retry.backoff` の一部だけを上書きし、runner から兄弟 backoff フィールドを保持できます。 +- `policy` はランタイム専用であるため、シリアライズされた `ModelSettings` は `max_retries` と `backoff` を保持しますが、コールバック自体は省略します。 -より詳しい例については、[`examples/basic/retry.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry.py) と [adapter-backed retry example](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry_litellm.py) を参照してください。 +より詳しい例については、[`examples/basic/retry.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry.py) と [アダプター backed リトライ例](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry_litellm.py) を参照してください。 -## OpenAI 以外のプロバイダーのトラブルシューティング +## 非 OpenAI プロバイダーのトラブルシューティング ### トレーシングクライアントエラー 401 -トレーシングに関連するエラーが発生する場合、これはトレースが OpenAI サーバーにアップロードされる一方で、OpenAI API キーを持っていないためです。これを解決するには、次の 3 つの選択肢があります。 +トレーシングに関連するエラーが発生する場合、これはトレースが OpenAI サーバーにアップロードされるためであり、OpenAI API キーを持っていないことが原因です。これを解決するには 3 つの選択肢があります。 -1. トレーシングを完全に無効にする: [`set_tracing_disabled(True)`][agents.set_tracing_disabled]。 +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) を参照してください。 +3. 非 OpenAI トレースプロセッサーを使用する。[トレーシングドキュメント](../tracing.md#custom-tracing-processors) を参照してください。 -### Responses API サポート +### Responses API のサポート -SDK はデフォルトで Responses API を使用しますが、多くの他の LLM プロバイダーはまだこれをサポートしていません。その結果、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 サポート +### structured outputs のサポート -一部のモデルプロバイダーは [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) をサポートしていません。この場合、次のようなエラーになることがあります。 +一部のモデルプロバイダーは [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) をサポートしていません。これにより、次のようなエラーが発生することがあります。 ``` @@ -481,34 +481,34 @@ BadRequestError: Error code: 400 - {'error': {'message': "'response_format.type' ``` -これは一部のモデルプロバイダーの制限です。JSON 出力はサポートしていますが、出力に使用する `json_schema` を指定できません。現在この修正に取り組んでいますが、JSON schema 出力をサポートするプロバイダーに依存することを推奨します。そうでない場合、不正な形式の JSON によってアプリが頻繁に壊れるためです。 +これは一部のモデルプロバイダーの制約です。JSON 出力はサポートしていますが、出力に使用する `json_schema` を指定できません。現在この修正に取り組んでいますが、JSON スキーマ出力をサポートするプロバイダーに依存することをおすすめします。そうしないと、不正な形式の JSON によりアプリが頻繁に壊れる可能性があります。 ## プロバイダー間でのモデルの混在 -モデルプロバイダー間の機能差を把握しておく必要があります。そうしないとエラーに遭遇する可能性があります。たとえば、OpenAI は structured outputs、マルチモーダル入力、ホスト型のファイル検索と Web 検索をサポートしていますが、多くの他のプロバイダーはこれらの機能をサポートしていません。次の制限に注意してください。 +モデルプロバイダー間の機能差を把握しておく必要があります。そうしないとエラーに遭遇する可能性があります。たとえば、OpenAI は structured outputs、マルチモーダル入力、ホストされたファイル検索および Web 検索をサポートしていますが、他の多くのプロバイダーはこれらの機能をサポートしていません。次の制限に注意してください。 -- サポートされていない `tools` を、それを理解しないプロバイダーに送信しないでください -- テキストのみのモデルを呼び出す前に、マルチモーダル入力をフィルタリングしてください -- 構造化 JSON 出力をサポートしないプロバイダーは、ときどき無効な JSON を生成することに注意してください。 +- 未対応の `tools` を、それを理解しないプロバイダーに送信しないでください +- テキスト専用モデルを呼び出す前に、マルチモーダル入力を除外してください +- 構造化 JSON 出力をサポートしていないプロバイダーは、ときどき無効な JSON を生成することに注意してください。 ## サードパーティアダプター -サードパーティアダプターを使用するのは、SDK の組み込みプロバイダー統合ポイントでは不十分な場合だけにしてください。この SDK で OpenAI モデルのみを使用している場合は、Any-LLM や LiteLLM ではなく、組み込みの [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] パスを優先してください。サードパーティアダプターは、OpenAI モデルと OpenAI 以外のプロバイダーを組み合わせる必要がある場合、または組み込みパスでは提供されないアダプター管理のプロバイダーカバレッジやルーティングが必要な場合のためのものです。アダプターは SDK と上流のモデルプロバイダーの間に別の互換性レイヤーを追加するため、機能サポートやリクエストセマンティクスはプロバイダーによって異なる場合があります。SDK には現在、best-effort の beta アダプター統合として Any-LLM と LiteLLM が含まれています。 +SDK の組み込みプロバイダー統合ポイントでは不十分な場合にのみ、サードパーティアダプターを使用してください。この SDK で OpenAI モデルのみを使用している場合は、Any-LLM や LiteLLM ではなく、組み込みの [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 経路を優先してください。サードパーティアダプターは、OpenAI モデルを非 OpenAI プロバイダーと組み合わせる必要がある場合、または組み込み経路では提供されないアダプター管理のプロバイダーカバレッジやルーティングが必要な場合のためのものです。アダプターは SDK と上流のモデルプロバイダーの間に別の互換性レイヤーを追加するため、機能サポートやリクエストのセマンティクスはプロバイダーによって異なる場合があります。SDK には現在、ベストエフォートのベータ版アダプター統合として Any-LLM と LiteLLM が含まれています。 ### Any-LLM -Any-LLM サポートは、Any-LLM 管理のプロバイダーカバレッジまたはルーティングが必要な場合に、best-effort の beta として含まれています。 +Any-LLM のサポートは、Any-LLM 管理のプロバイダーカバレッジやルーティングが必要な場合のために、ベストエフォートのベータ版として含まれています。 -上流プロバイダーパスに応じて、Any-LLM は Responses API、Chat Completions 互換 API、またはプロバイダー固有の互換性レイヤーを使用する場合があります。 +上流プロバイダーの経路によって、Any-LLM は Responses API、Chat Completions 互換 API、またはプロバイダー固有の互換性レイヤーを使用する場合があります。 -Any-LLM が必要な場合は、`openai-agents[any-llm]` をインストールし、[`examples/model_providers/any_llm_auto.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/any_llm_auto.py) または [`examples/model_providers/any_llm_provider.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/any_llm_provider.py) から始めてください。[`MultiProvider`][agents.MultiProvider] で `any-llm/...` モデル名を使用したり、`AnyLLMModel` を直接インスタンス化したり、実行スコープで `AnyLLMProvider` を使用したりできます。モデルサーフェスを明示的に固定する必要がある場合は、`AnyLLMModel` を構築するときに `api="responses"` または `api="chat_completions"` を渡します。 +Any-LLM が必要な場合は、`openai-agents[any-llm]` をインストールし、[`examples/model_providers/any_llm_auto.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/any_llm_auto.py) または [`examples/model_providers/any_llm_provider.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/any_llm_provider.py) から始めてください。[`MultiProvider`][agents.MultiProvider] で `any-llm/...` モデル名を使用する、`AnyLLMModel` を直接インスタンス化する、または実行スコープで `AnyLLMProvider` を使用できます。モデルサーフェスを明示的に固定する必要がある場合は、`AnyLLMModel` の構築時に `api="responses"` または `api="chat_completions"` を渡します。 -Any-LLM はサードパーティアダプターレイヤーのままであるため、プロバイダーの依存関係や機能ギャップは SDK ではなく Any-LLM によって上流で定義されます。使用量メトリクスは、上流プロバイダーが返す場合は自動的に伝播されますが、ストリーミングされた Chat Completions バックエンドでは、使用量チャンクを発行する前に `ModelSettings(include_usage=True)` が必要になる場合があります。structured outputs、ツール呼び出し、使用量レポート、または Responses 固有の動作に依存する場合は、デプロイ予定の正確なプロバイダーバックエンドを検証してください。 +Any-LLM はサードパーティアダプターレイヤーのままなので、プロバイダーの依存関係や機能のギャップは SDK ではなく上流の Any-LLM によって定義されます。上流プロバイダーが使用量メトリクスを返す場合、それらは自動的に伝播されますが、ストリーミング Chat Completions バックエンドでは、使用量チャンクを出力する前に `ModelSettings(include_usage=True)` が必要な場合があります。structured outputs、ツール呼び出し、使用量レポート、または Responses 固有の動作に依存する場合は、デプロイ予定の正確なプロバイダーバックエンドを検証してください。 ### LiteLLM -LiteLLM サポートは、LiteLLM 固有のプロバイダーカバレッジまたはルーティングが必要な場合に、best-effort の beta として含まれています。 +LiteLLM のサポートは、LiteLLM 固有のプロバイダーカバレッジやルーティングが必要な場合のために、ベストエフォートのベータ版として含まれています。 -LiteLLM が必要な場合は、`openai-agents[litellm]` をインストールし、[`examples/model_providers/litellm_auto.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/litellm_auto.py) または [`examples/model_providers/litellm_provider.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/litellm_provider.py) から始めてください。`litellm/...` モデル名を使用したり、[`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel] を直接インスタンス化したりできます。 +LiteLLM が必要な場合は、`openai-agents[litellm]` をインストールし、[`examples/model_providers/litellm_auto.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/litellm_auto.py) または [`examples/model_providers/litellm_provider.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/litellm_provider.py) から始めてください。`litellm/...` モデル名を使用するか、[`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel] を直接インスタンス化できます。 -一部の LiteLLM ベースのプロバイダーは、デフォルトでは SDK の使用量メトリクスを設定しません。使用量レポートが必要な場合は、`ModelSettings(include_usage=True)` を渡してください。また、structured outputs、ツール呼び出し、使用量レポート、またはアダプター固有のルーティング動作に依存する場合は、デプロイ予定の正確なプロバイダーバックエンドを検証してください。 \ No newline at end of file +一部の LiteLLM バックのプロバイダーは、デフォルトでは SDK の使用量メトリクスを設定しません。使用量レポートが必要な場合は、`ModelSettings(include_usage=True)` を渡し、structured outputs、ツール呼び出し、使用量レポート、またはアダプター固有のルーティング動作に依存する場合は、デプロイ予定の正確なプロバイダーバックエンドを検証してください。 \ No newline at end of file diff --git a/docs/ko/models/index.md b/docs/ko/models/index.md index 2a53314b3c..b3cd1afd43 100644 --- a/docs/ko/models/index.md +++ b/docs/ko/models/index.md @@ -4,35 +4,35 @@ search: --- # 모델 -Agents SDK는 OpenAI 모델을 두 가지 방식으로 즉시 사용할 수 있도록 지원합니다. +Agents SDK는 OpenAI 모델을 두 가지 방식으로 기본 지원합니다. -- **권장**: 새로운 [Responses API](https://platform.openai.com/docs/api-reference/responses)를 사용해 OpenAI API를 호출하는 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] +- **권장**: 새 [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] ## 모델 설정 선택 -설정에 맞는 가장 간단한 경로부터 시작하세요. +설정에 맞는 가장 단순한 경로부터 시작하세요. -| 수행하려는 작업 | 권장 경로 | 자세히 보기 | +| 원하는 작업 | 권장 경로 | 더 읽어보기 | | --- | --- | --- | -| OpenAI 모델만 사용 | Responses 모델 경로와 함께 기본 OpenAI provider 사용 | [OpenAI 모델](#openai-models) | -| websocket 전송을 통해 OpenAI Responses API 사용 | Responses 모델 경로를 유지하고 websocket 전송 활성화 | [Responses WebSocket 전송](#responses-websocket-transport) | -| OpenAI가 아닌 provider 하나 사용 | 기본 제공 provider 통합 지점부터 시작 | [OpenAI가 아닌 모델](#non-openai-models) | +| OpenAI 모델만 사용 | 기본 OpenAI provider를 Responses 모델 경로와 함께 사용 | [OpenAI 모델](#openai-models) | +| websocket transport로 OpenAI Responses API 사용 | Responses 모델 경로를 유지하고 websocket transport 활성화 | [Responses WebSocket transport](#responses-websocket-transport) | +| 하나의 비 OpenAI provider 사용 | 내장 provider 통합 지점부터 시작 | [비 OpenAI 모델](#non-openai-models) | | 에이전트 간 모델 또는 provider 혼합 | 실행별 또는 에이전트별로 provider를 선택하고 기능 차이 검토 | [하나의 워크플로에서 모델 혼합](#mixing-models-in-one-workflow) 및 [provider 간 모델 혼합](#mixing-models-across-providers) | | 고급 OpenAI Responses 요청 설정 조정 | OpenAI Responses 경로에서 `ModelSettings` 사용 | [고급 OpenAI Responses 설정](#advanced-openai-responses-settings) | -| OpenAI가 아니거나 혼합 provider 라우팅을 위해 타사 어댑터 사용 | 지원되는 베타 어댑터를 비교하고 출시하려는 provider 경로 검증 | [타사 어댑터](#third-party-adapters) | +| 비 OpenAI 또는 혼합 provider 라우팅을 위한 서드파티 어댑터 사용 | 지원되는 베타 어댑터를 비교하고 배포하려는 provider 경로 검증 | [서드파티 어댑터](#third-party-adapters) | ## OpenAI 모델 -대부분의 OpenAI 전용 앱에서는 기본 OpenAI provider와 함께 문자열 모델 이름을 사용하고 Responses 모델 경로를 유지하는 것을 권장합니다. +대부분의 OpenAI 전용 앱에서는 기본 OpenAI provider와 문자열 모델 이름을 사용하고 Responses 모델 경로를 유지하는 것이 권장됩니다. -`Agent`를 초기화할 때 모델을 지정하지 않으면 기본 모델이 사용됩니다. 현재 기본값은 낮은 지연 시간의 에이전트 워크플로를 위해 `reasoning.effort="none"` 및 `verbosity="low"`가 설정된 [`gpt-5.4-mini`](https://developers.openai.com/api/docs/models/gpt-5.4-mini)입니다. 액세스 권한이 있다면 명시적인 `model_settings`를 유지하면서 더 높은 품질을 위해 에이전트를 [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5)로 설정하는 것을 권장합니다. +`Agent`를 초기화할 때 모델을 지정하지 않으면 기본 모델이 사용됩니다. 현재 기본값은 지연 시간이 짧은 에이전트 워크플로를 위해 `reasoning.effort="none"` 및 `verbosity="low"`가 설정된 [`gpt-5.4-mini`](https://developers.openai.com/api/docs/models/gpt-5.4-mini)입니다. 액세스 권한이 있다면, 명시적인 `model_settings`를 유지하면서 더 높은 품질을 위해 에이전트를 [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5)로 설정하는 것을 권장합니다. -[`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) 같은 다른 모델로 전환하려면 에이전트를 구성하는 방법이 두 가지 있습니다. +[`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) 같은 다른 모델로 전환하려면, 에이전트를 구성하는 방법이 두 가지 있습니다. ### 기본 모델 -먼저, 사용자 지정 모델을 설정하지 않은 모든 에이전트에 특정 모델을 일관되게 사용하려면 에이전트를 실행하기 전에 `OPENAI_DEFAULT_MODEL` 환경 변수를 설정하세요. +첫째, 사용자 지정 모델을 설정하지 않은 모든 에이전트에 특정 모델을 일관되게 사용하려면 에이전트를 실행하기 전에 `OPENAI_DEFAULT_MODEL` 환경 변수를 설정하세요. ```bash export OPENAI_DEFAULT_MODEL=gpt-5.5 @@ -58,7 +58,7 @@ result = await Runner.run( #### GPT-5 모델 -이 방식으로 [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) 같은 GPT-5 모델을 사용하면 SDK가 기본 `ModelSettings`를 적용합니다. 대부분의 사용 사례에 가장 잘 맞는 설정을 적용합니다. 기본 모델의 reasoning effort를 조정하려면 직접 `ModelSettings`를 전달하세요. +이 방식으로 [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5)와 같은 GPT-5 모델을 사용하면 SDK가 기본 `ModelSettings`를 적용합니다. 대부분의 사용 사례에 가장 잘 맞는 설정이 적용됩니다. 기본 모델의 reasoning effort를 조정하려면 직접 `ModelSettings`를 전달하세요. ```python from openai.types.shared import Reasoning @@ -74,21 +74,21 @@ my_agent = Agent( ) ``` -더 낮은 지연 시간을 위해서는 GPT-5 모델에서 `reasoning.effort="none"`을 사용하는 것을 권장합니다. +더 낮은 지연 시간을 위해서는 GPT-5 모델에서 `reasoning.effort="none"`을 사용하는 것이 권장됩니다. #### ComputerTool 모델 선택 -에이전트에 [`ComputerTool`][agents.tool.ComputerTool]이 포함된 경우, 실제 Responses 요청의 유효 모델이 SDK가 보내는 computer-tool 페이로드를 결정합니다. 명시적인 `gpt-5.5` 요청은 GA 기본 제공 `computer` 도구를 사용하고, 명시적인 `computer-use-preview` 요청은 기존 `computer_use_preview` 페이로드를 유지합니다. +에이전트에 [`ComputerTool`][agents.tool.ComputerTool]이 포함된 경우 실제 Responses 요청의 유효 모델이 SDK가 전송하는 computer-tool payload를 결정합니다. 명시적인 `gpt-5.5` 요청은 GA 내장 `computer` 도구를 사용하고, 명시적인 `computer-use-preview` 요청은 이전 `computer_use_preview` payload를 유지합니다. -프롬프트가 관리하는 호출이 주요 예외입니다. 프롬프트 템플릿이 모델을 소유하고 SDK가 요청에서 `model`을 생략하는 경우, SDK는 프롬프트가 어떤 모델을 고정하는지 추측하지 않도록 preview 호환 computer 페이로드를 기본값으로 사용합니다. 해당 흐름에서 GA 경로를 유지하려면 요청에 `model="gpt-5.5"`를 명시하거나 `ModelSettings(tool_choice="computer")` 또는 `ModelSettings(tool_choice="computer_use")`로 GA 선택기를 강제하세요. +프롬프트가 관리하는 호출이 주요 예외입니다. 프롬프트 템플릿이 모델을 소유하고 SDK가 요청에서 `model`을 생략하는 경우, SDK는 프롬프트가 어떤 모델을 고정하는지 추측하지 않기 위해 preview 호환 computer payload를 기본값으로 사용합니다. 이 흐름에서 GA 경로를 유지하려면 요청에 `model="gpt-5.5"`를 명시하거나 `ModelSettings(tool_choice="computer")` 또는 `ModelSettings(tool_choice="computer_use")`로 GA selector를 강제하세요. -등록된 [`ComputerTool`][agents.tool.ComputerTool]이 있으면 `tool_choice="computer"`, `"computer_use"`, `"computer_use_preview"`는 유효 요청 모델과 일치하는 기본 제공 선택기로 정규화됩니다. `ComputerTool`이 등록되어 있지 않으면 이러한 문자열은 일반 함수 이름처럼 계속 동작합니다. +등록된 [`ComputerTool`][agents.tool.ComputerTool]이 있으면 `tool_choice="computer"`, `"computer_use"`, `"computer_use_preview"`는 유효 요청 모델과 일치하는 내장 selector로 정규화됩니다. 등록된 `ComputerTool`이 없으면 해당 문자열은 일반 함수 이름처럼 계속 동작합니다. -Preview 호환 요청은 `environment`와 표시 크기를 미리 직렬화해야 하므로, [`ComputerProvider`][agents.tool.ComputerProvider] 팩터리를 사용하는 프롬프트 관리 흐름은 구체적인 `Computer` 또는 `AsyncComputer` 인스턴스를 전달하거나 요청을 보내기 전에 GA 선택기를 강제해야 합니다. 전체 마이그레이션 세부 정보는 [도구](../tools.md#computertool-and-the-responses-computer-tool)를 참조하세요. +Preview 호환 요청은 `environment`와 display dimensions를 미리 직렬화해야 하므로, [`ComputerProvider`][agents.tool.ComputerProvider] factory를 사용하는 프롬프트 관리 흐름은 구체적인 `Computer` 또는 `AsyncComputer` 인스턴스를 전달하거나 요청을 보내기 전에 GA selector를 강제해야 합니다. 전체 마이그레이션 세부 정보는 [도구](../tools.md#computertool-and-the-responses-computer-tool)를 참조하세요. -#### Non-GPT-5 모델 +#### 비 GPT-5 모델 -사용자 지정 `model_settings` 없이 non–GPT-5 모델 이름을 전달하면 SDK는 모든 모델과 호환되는 일반 `ModelSettings`로 되돌아갑니다. +사용자 지정 `model_settings` 없이 비 GPT-5 모델 이름을 전달하면 SDK는 모든 모델과 호환되는 일반 `ModelSettings`로 되돌아갑니다. ### Responses 전용 도구 검색 기능 @@ -98,11 +98,11 @@ Preview 호환 요청은 `environment`와 표시 크기를 미리 직렬화해 - [`tool_namespace()`][agents.tool.tool_namespace] - `@function_tool(defer_loading=True)` 및 기타 지연 로딩 Responses 도구 표면 -이러한 기능은 Chat Completions 모델과 non-Responses 백엔드에서 거부됩니다. 지연 로딩 도구를 사용할 때는 에이전트에 `ToolSearchTool()`을 추가하고, 순수 네임스페이스 이름이나 지연 전용 함수 이름을 강제하는 대신 모델이 `auto` 또는 `required` 도구 선택을 통해 도구를 로드하도록 하세요. 설정 세부 정보와 현재 제약 사항은 [도구](../tools.md#hosted-tool-search)를 참조하세요. +이 기능들은 Chat Completions 모델 및 비 Responses 백엔드에서 거부됩니다. 지연 로딩 도구를 사용할 때는 에이전트에 `ToolSearchTool()`을 추가하고, bare namespace 이름이나 지연 전용 함수 이름을 강제하지 말고 모델이 `auto` 또는 `required` tool choice를 통해 도구를 로드하도록 하세요. 설정 세부 정보와 현재 제약 사항은 [도구](../tools.md#hosted-tool-search)를 참조하세요. -### Responses WebSocket 전송 +### Responses WebSocket transport -기본적으로 OpenAI Responses API 요청은 HTTP 전송을 사용합니다. OpenAI 기반 모델을 사용할 때 websocket 전송을 선택할 수 있습니다. +기본적으로 OpenAI Responses API 요청은 HTTP transport를 사용합니다. OpenAI 기반 모델을 사용할 때 websocket transport를 선택할 수 있습니다. #### 기본 설정 @@ -112,13 +112,13 @@ from agents import set_default_openai_responses_transport set_default_openai_responses_transport("websocket") ``` -이는 기본 OpenAI provider가 확인한 OpenAI Responses 모델(예: `"gpt-5.5"` 같은 문자열 모델 이름 포함)에 영향을 줍니다. +이는 기본 OpenAI provider가 확인한 OpenAI Responses 모델(`"gpt-5.5"` 같은 문자열 모델 이름 포함)에 영향을 줍니다. -전송 선택은 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가 전송 선택을 제어합니다. +Transport 선택은 SDK가 모델 이름을 모델 인스턴스로 확인할 때 발생합니다. 구체적인 [`Model`][agents.models.interface.Model] 객체를 전달하면 해당 transport는 이미 고정되어 있습니다. [`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가 transport 선택을 제어합니다. #### Provider 또는 실행 수준 설정 -provider별 또는 실행별로 websocket 전송을 구성할 수도 있습니다. +Provider별 또는 실행별로 websocket transport를 구성할 수도 있습니다. ```python from agents import Agent, OpenAIProvider, RunConfig, Runner @@ -139,7 +139,7 @@ result = await Runner.run( ) ``` -OpenAI 기반 provider는 선택적 에이전트 등록 구성도 허용합니다. 이는 OpenAI 설정에서 harness ID 같은 provider 수준 등록 메타데이터를 기대하는 경우를 위한 고급 옵션입니다. +OpenAI 기반 provider는 선택적인 에이전트 등록 구성도 허용합니다. 이는 OpenAI 설정에서 harness ID 같은 provider 수준 등록 메타데이터가 필요한 경우를 위한 고급 옵션입니다. ```python from agents import ( @@ -165,14 +165,14 @@ result = await Runner.run( #### `MultiProvider`를 사용한 고급 라우팅 -접두사 기반 모델 라우팅이 필요한 경우(예: 하나의 실행에서 `openai/...`와 `any-llm/...` 모델 이름 혼합) [`MultiProvider`][agents.MultiProvider]를 사용하고 그곳에서 `openai_use_responses_websocket=True`를 설정하세요. +prefix 기반 모델 라우팅이 필요한 경우(예: 하나의 실행에서 `openai/...`와 `any-llm/...` 모델 이름 혼합) [`MultiProvider`][agents.MultiProvider]를 사용하고 여기에 `openai_use_responses_websocket=True`를 설정하세요. `MultiProvider`는 두 가지 기존 기본값을 유지합니다. - `openai/...`는 OpenAI provider의 별칭으로 처리되므로 `openai/gpt-4.1`은 모델 `gpt-4.1`로 라우팅됩니다. -- 알 수 없는 접두사는 그대로 전달되지 않고 `UserError`를 발생시킵니다. +- 알 수 없는 prefix는 그대로 전달되지 않고 `UserError`를 발생시킵니다. -OpenAI provider를 리터럴 네임스페이스 모델 ID를 기대하는 OpenAI 호환 엔드포인트로 지정할 때는 패스스루 동작을 명시적으로 선택하세요. websocket 활성화 설정에서는 `MultiProvider`에도 `openai_use_responses_websocket=True`를 유지하세요. +OpenAI provider가 literal namespaced 모델 ID를 기대하는 OpenAI 호환 엔드포인트를 가리키도록 할 때는 pass-through 동작을 명시적으로 선택하세요. websocket이 활성화된 설정에서는 `MultiProvider`에도 `openai_use_responses_websocket=True`를 유지하세요. ```python from agents import Agent, MultiProvider, RunConfig, Runner @@ -198,37 +198,37 @@ result = await Runner.run( ) ``` -백엔드가 리터럴 `openai/...` 문자열을 기대할 때 `openai_prefix_mode="model_id"`를 사용하세요. 백엔드가 `openrouter/openai/gpt-4.1-mini` 같은 다른 네임스페이스 모델 ID를 기대할 때 `unknown_prefix_mode="model_id"`를 사용하세요. 이러한 옵션은 websocket 전송 외부의 `MultiProvider`에서도 동작합니다. 이 예시는 이 섹션에서 설명하는 전송 설정의 일부이므로 websocket을 활성화한 상태로 유지합니다. 동일한 옵션은 [`responses_websocket_session()`][agents.responses_websocket_session]에서도 사용할 수 있습니다. +백엔드가 literal `openai/...` 문자열을 기대할 때 `openai_prefix_mode="model_id"`를 사용하세요. 백엔드가 `openrouter/openai/gpt-4.1-mini` 같은 다른 namespaced 모델 ID를 기대할 때는 `unknown_prefix_mode="model_id"`를 사용하세요. 이러한 옵션은 websocket transport 외부의 `MultiProvider`에서도 작동합니다. 이 예제는 이 섹션에서 설명하는 transport 설정의 일부이므로 websocket을 활성화한 상태로 유지합니다. 동일한 옵션은 [`responses_websocket_session()`][agents.responses_websocket_session]에서도 사용할 수 있습니다. -`MultiProvider`를 통해 라우팅하면서 동일한 provider 수준 등록 메타데이터가 필요하다면 `openai_agent_registration=OpenAIAgentRegistrationConfig(...)`를 전달하세요. 그러면 기본 OpenAI provider로 전달됩니다. +`MultiProvider`를 통해 라우팅하면서 동일한 provider 수준 등록 메타데이터가 필요한 경우 `openai_agent_registration=OpenAIAgentRegistrationConfig(...)`를 전달하면 내부 OpenAI provider로 전달됩니다. -사용자 지정 OpenAI 호환 엔드포인트 또는 프록시를 사용하는 경우 websocket 전송에는 호환되는 websocket `/responses` 엔드포인트도 필요합니다. 이러한 설정에서는 `websocket_base_url`을 명시적으로 설정해야 할 수 있습니다. +사용자 지정 OpenAI 호환 엔드포인트 또는 프록시를 사용하는 경우 websocket transport에는 호환되는 websocket `/responses` 엔드포인트도 필요합니다. 이러한 설정에서는 `websocket_base_url`을 명시적으로 설정해야 할 수 있습니다. #### 참고 사항 -- 이는 websocket 전송을 통한 Responses API이며, [Realtime API](../realtime/guide.md)가 아닙니다. Responses websocket `/responses` 엔드포인트를 지원하지 않는 한 Chat Completions 또는 OpenAI가 아닌 provider에는 적용되지 않습니다. -- 환경에서 아직 사용할 수 없다면 `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)를 참조하세요. -- 긴 reasoning 턴이나 지연 시간 급증이 있는 네트워크에서는 `responses_websocket_options`로 websocket keepalive 동작을 사용자 지정하세요. 지연된 pong 프레임을 허용하려면 `ping_timeout`을 늘리거나, ping은 활성화한 상태로 heartbeat timeout을 비활성화하려면 `ping_timeout=None`을 설정하세요. websocket 지연 시간보다 안정성이 더 중요할 때는 HTTP/SSE 전송을 선호하세요. +- 이는 websocket transport를 통한 Responses API이지 [Realtime API](../realtime/guide.md)가 아닙니다. Chat Completions 또는 비 OpenAI provider에는 적용되지 않습니다. 단, 이들이 Responses websocket `/responses` 엔드포인트를 지원하는 경우는 예외입니다. +- 환경에 `websockets` 패키지가 아직 없다면 설치하세요. +- websocket transport를 활성화한 직후 [`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)를 참조하세요. +- 긴 reasoning 턴이나 지연 시간 급증이 있는 네트워크에서는 `responses_websocket_options`로 websocket keepalive 동작을 사용자 지정하세요. 지연된 pong 프레임을 허용하려면 `ping_timeout`을 늘리거나, ping은 활성화한 채 heartbeat timeout을 비활성화하려면 `ping_timeout=None`을 설정하세요. websocket 지연 시간보다 신뢰성이 더 중요한 경우 HTTP/SSE transport를 선호하세요. -## OpenAI가 아닌 모델 +## 비 OpenAI 모델 -OpenAI가 아닌 provider가 필요하다면 SDK의 기본 제공 provider 통합 지점부터 시작하세요. 많은 설정에서는 타사 어댑터를 추가하지 않아도 이것으로 충분합니다. 각 패턴의 예시는 [examples/model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)에 있습니다. +비 OpenAI provider가 필요하다면 SDK의 내장 provider 통합 지점부터 시작하세요. 많은 설정에서는 서드파티 어댑터를 추가하지 않아도 이것으로 충분합니다. 각 패턴의 예시는 [examples/model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)에 있습니다. -### OpenAI가 아닌 provider 통합 방법 +### 비 OpenAI provider 통합 방법 | 접근 방식 | 사용 시점 | 범위 | | --- | --- | --- | | [`set_default_openai_client`][agents.set_default_openai_client] | 하나의 OpenAI 호환 엔드포인트가 대부분 또는 모든 에이전트의 기본값이어야 할 때 | 전역 기본값 | | [`ModelProvider`][agents.models.interface.ModelProvider] | 하나의 사용자 지정 provider가 단일 실행에 적용되어야 할 때 | 실행별 | -| [`Agent.model`][agents.agent.Agent.model] | 서로 다른 에이전트에 서로 다른 provider 또는 구체적인 모델 객체가 필요할 때 | 에이전트별 | -| 타사 어댑터 | 기본 제공 경로가 제공하지 않는 어댑터 관리 provider 범위 또는 라우팅이 필요할 때 | [타사 어댑터](#third-party-adapters) 참조 | +| [`Agent.model`][agents.agent.Agent.model] | 서로 다른 에이전트가 서로 다른 provider 또는 구체적인 모델 객체를 필요로 할 때 | 에이전트별 | +| 서드파티 어댑터 | 내장 경로가 제공하지 않는 어댑터 관리 provider 범위 또는 라우팅이 필요할 때 | [서드파티 어댑터](#third-party-adapters) 참조 | -다음 기본 제공 경로로 다른 LLM provider를 통합할 수 있습니다. +다음 내장 경로를 통해 다른 LLM provider를 통합할 수 있습니다. -1. [`set_default_openai_client`][agents.set_default_openai_client]는 `AsyncOpenAI` 인스턴스를 LLM 클라이언트로 전역적으로 사용하려는 경우에 유용합니다. 이는 LLM provider에 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` 수준에 있습니다. 이를 통해 "이 실행의 모든 에이전트에 사용자 지정 모델 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)를 참조하세요. +1. [`set_default_openai_client`][agents.set_default_openai_client]는 `AsyncOpenAI` 인스턴스를 LLM 클라이언트로 전역 사용하려는 경우에 유용합니다. 이는 LLM provider에 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` 수준에 있습니다. 이를 통해 “이 실행의 모든 에이전트에 사용자 지정 모델 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)를 참조하세요. `platform.openai.com`의 API 키가 없는 경우 `set_tracing_disabled()`를 통해 트레이싱을 비활성화하거나 [다른 트레이싱 프로세서](../tracing.md)를 설정하는 것을 권장합니다. @@ -245,19 +245,19 @@ agent= Agent(name="Helping Agent", instructions="You are a Helping Agent", model !!! note - 이 예시에서는 Chat Completions API/모델을 사용합니다. 많은 LLM provider가 아직 Responses API를 지원하지 않기 때문입니다. LLM provider가 이를 지원한다면 Responses 사용을 권장합니다. + 이 예시들에서는 Chat Completions API/모델을 사용합니다. 많은 LLM provider가 아직 Responses API를 지원하지 않기 때문입니다. 사용 중인 LLM provider가 이를 지원한다면 Responses 사용을 권장합니다. ## 하나의 워크플로에서 모델 혼합 -단일 워크플로 내에서 각 에이전트에 서로 다른 모델을 사용하고 싶을 수 있습니다. 예를 들어 분류에는 더 작고 빠른 모델을 사용하고, 복잡한 작업에는 더 크고 성능이 좋은 모델을 사용할 수 있습니다. [`Agent`][agents.Agent]를 구성할 때 다음 중 하나로 특정 모델을 선택할 수 있습니다. +단일 워크플로 내에서 각 에이전트에 서로 다른 모델을 사용하고 싶을 수 있습니다. 예를 들어 triage에는 더 작고 빠른 모델을 사용하고, 복잡한 작업에는 더 크고 성능이 좋은 모델을 사용할 수 있습니다. [`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 @@ -290,10 +290,10 @@ async def main(): print(result.final_output) ``` -1. OpenAI 모델 이름을 직접 설정합니다. +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 @@ -308,20 +308,20 @@ english_agent = Agent( ## 고급 OpenAI Responses 설정 -OpenAI Responses 경로를 사용 중이며 더 많은 제어가 필요하다면 `ModelSettings`부터 시작하세요. +OpenAI Responses 경로를 사용 중이고 더 많은 제어가 필요하다면 `ModelSettings`부터 시작하세요. ### 일반적인 고급 `ModelSettings` 옵션 -OpenAI Responses API를 사용할 때는 여러 요청 필드에 이미 직접적인 `ModelSettings` 필드가 있으므로 해당 필드에는 `extra_args`가 필요하지 않습니다. +OpenAI Responses API를 사용할 때는 여러 요청 필드에 이미 직접 대응되는 `ModelSettings` 필드가 있으므로, 해당 필드에는 `extra_args`가 필요하지 않습니다. - `parallel_tool_calls`: 같은 턴에서 여러 도구 호출을 허용하거나 금지합니다. -- `truncation`: 컨텍스트가 초과될 때 실패하는 대신 Responses API가 가장 오래된 대화 항목을 제거하도록 `"auto"`를 설정합니다. -- `store`: 생성된 응답을 나중에 검색할 수 있도록 서버 측에 저장할지 제어합니다. 이는 응답 ID에 의존하는 후속 워크플로와, `store=False`일 때 로컬 입력으로 폴백해야 할 수 있는 세션 압축 흐름에 중요합니다. -- `context_management`: `compact_threshold`가 있는 Responses 압축 같은 서버 측 컨텍스트 처리를 구성합니다. +- `truncation`: 컨텍스트가 초과될 때 실패하지 않고 Responses API가 가장 오래된 대화 항목을 삭제하도록 하려면 `"auto"`로 설정합니다. +- `store`: 생성된 응답을 나중에 조회할 수 있도록 서버 측에 저장할지 여부를 제어합니다. 이는 응답 ID에 의존하는 후속 워크플로와 `store=False`일 때 로컬 입력으로 fallback해야 할 수 있는 세션 compaction 흐름에 중요합니다. +- `context_management`: `compact_threshold`를 사용한 Responses compaction 등 서버 측 컨텍스트 처리를 구성합니다. - `prompt_cache_retention`: 예를 들어 `"24h"`로 캐시된 프롬프트 prefix를 더 오래 유지합니다. -- `response_include`: `web_search_call.action.sources`, `file_search_call.results`, `reasoning.encrypted_content` 같은 더 풍부한 응답 페이로드를 요청합니다. +- `response_include`: `web_search_call.action.sources`, `file_search_call.results`, `reasoning.encrypted_content` 같은 더 풍부한 응답 payload를 요청합니다. - `top_logprobs`: 출력 텍스트에 대한 top-token logprobs를 요청합니다. SDK는 `message.output_text.logprobs`도 자동으로 추가합니다. -- `retry`: 모델 호출에 runner 관리 재시도 설정을 사용하도록 선택합니다. [Runner 관리 재시도](#runner-managed-retries)를 참조하세요. +- `retry`: 모델 호출에 runner 관리 retry 설정을 사용하도록 선택합니다. [Runner 관리 retry](#runner-managed-retries)를 참조하세요. ```python from agents import Agent, ModelSettings @@ -341,15 +341,15 @@ research_agent = Agent( ) ``` -`store=False`를 설정하면 Responses API는 해당 응답을 나중에 서버 측에서 검색할 수 있도록 유지하지 않습니다. 이는 stateless 또는 zero-data-retention 방식의 흐름에 유용하지만, 응답 ID를 재사용할 수 있는 기능들이 대신 로컬에서 관리되는 상태에 의존해야 함을 의미합니다. 예를 들어 [`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession]은 마지막 응답이 저장되지 않았을 때 기본 `"auto"` 압축 경로를 입력 기반 압축으로 전환합니다. [Sessions 가이드](../sessions/index.md#openai-responses-compaction-sessions)를 참조하세요. +`store=False`로 설정하면 Responses API는 나중에 서버 측에서 조회할 수 있도록 해당 응답을 보관하지 않습니다. 이는 stateless 또는 zero-data-retention 스타일의 흐름에 유용하지만, 그렇지 않으면 응답 ID를 재사용할 기능들이 대신 로컬에서 관리되는 상태에 의존해야 함을 의미합니다. 예를 들어 [`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession]은 마지막 응답이 저장되지 않았을 때 기본 `"auto"` compaction 경로를 입력 기반 compaction으로 전환합니다. [Sessions 가이드](../sessions/index.md#openai-responses-compaction-sessions)를 참조하세요. -서버 측 압축은 [`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession]과 다릅니다. `context_management=[{"type": "compaction", "compact_threshold": ...}]`는 각 Responses API 요청과 함께 전송되며, 렌더링된 컨텍스트가 임계값을 넘으면 API가 응답의 일부로 압축 항목을 내보낼 수 있습니다. `OpenAIResponsesCompactionSession`은 턴 사이에 독립형 `responses.compact` 엔드포인트를 호출하고 로컬 세션 기록을 다시 작성합니다. +서버 측 compaction은 [`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession]과 다릅니다. `context_management=[{"type": "compaction", "compact_threshold": ...}]`는 각 Responses API 요청과 함께 전송되며, 렌더링된 컨텍스트가 임계값을 넘을 때 API가 응답의 일부로 compaction 항목을 내보낼 수 있습니다. `OpenAIResponsesCompactionSession`은 턴 사이에 독립 실행형 `responses.compact` 엔드포인트를 호출하고 로컬 세션 기록을 다시 작성합니다. ### `extra_args` 전달 -SDK가 아직 최상위 수준에서 직접 노출하지 않는 provider별 또는 더 최신의 요청 필드가 필요할 때 `extra_args`를 사용하세요. +SDK가 아직 최상위 수준에서 직접 노출하지 않는 provider별 또는 더 새로운 요청 필드가 필요할 때 `extra_args`를 사용하세요. -또한 OpenAI의 Responses API를 사용할 때 [몇 가지 다른 선택적 매개변수](https://platform.openai.com/docs/api-reference/responses/create)(예: `user`, `service_tier` 등)가 있습니다. 최상위 수준에서 사용할 수 없다면 `extra_args`로 전달할 수도 있습니다. 동일한 요청 필드를 직접 `ModelSettings` 필드로도 설정하지 마세요. +또한 OpenAI의 Responses API를 사용할 때 [몇 가지 다른 선택적 매개변수](https://platform.openai.com/docs/api-reference/responses/create)(예: `user`, `service_tier` 등)가 있습니다. 최상위 수준에서 사용할 수 없다면 `extra_args`를 사용해 이들도 전달할 수 있습니다. 동일한 요청 필드를 직접 `ModelSettings` 필드를 통해 동시에 설정하지 마세요. ```python from agents import Agent, ModelSettings @@ -365,9 +365,9 @@ english_agent = Agent( ) ``` -## Runner 관리 재시도 +## Runner 관리 retry -재시도는 런타임 전용이며 명시적으로 선택해야 합니다. `ModelSettings(retry=...)`를 설정하고 재시도 정책이 재시도를 선택하지 않는 한 SDK는 일반 모델 요청을 재시도하지 않습니다. +Retry는 런타임 전용이며 선택 사항입니다. `ModelSettings(retry=...)`를 설정하고 retry 정책이 retry를 선택하지 않는 한 SDK는 일반 모델 요청을 retry하지 않습니다. ```python from agents import Agent, ModelRetrySettings, ModelSettings, retry_policies @@ -395,85 +395,85 @@ agent = Agent( ) ``` -`ModelRetrySettings`에는 세 가지 필드가 있습니다. +`ModelRetrySettings`에는 세 개의 필드가 있습니다.
| 필드 | 타입 | 참고 | | --- | --- | --- | -| `max_retries` | `int | None` | 최초 요청 이후 허용되는 재시도 횟수 | -| `backoff` | `ModelRetryBackoffSettings | dict | None` | 정책이 명시적 지연 시간을 반환하지 않고 재시도할 때의 기본 지연 전략 | -| `policy` | `RetryPolicy | None` | 재시도 여부를 결정하는 콜백입니다. 이 필드는 런타임 전용이며 직렬화되지 않습니다. | +| `max_retries` | `int | None` | 초기 요청 이후 허용되는 retry 시도 횟수입니다. | +| `backoff` | `ModelRetryBackoffSettings | dict | None` | 정책이 명시적 지연을 반환하지 않고 retry할 때의 기본 지연 전략입니다. `backoff.max_delay`는 이 계산된 backoff 지연에만 상한을 적용합니다. 정책이 반환한 명시적 지연이나 retry-after 힌트에는 상한을 적용하지 않습니다. | +| `policy` | `RetryPolicy | None` | retry 여부를 결정하는 콜백입니다. 이 필드는 런타임 전용이며 직렬화되지 않습니다. |
-재시도 정책은 다음을 포함하는 [`RetryPolicyContext`][agents.retry.RetryPolicyContext]를 받습니다. +Retry 정책은 다음을 포함하는 [`RetryPolicyContext`][agents.retry.RetryPolicyContext]를 받습니다. -- `attempt` 및 `max_retries`: 시도 횟수를 고려한 결정을 할 수 있습니다. +- `attempt` 및 `max_retries`: 시도 횟수를 고려한 결정을 내릴 수 있습니다. - `stream`: 스트리밍 동작과 비스트리밍 동작을 분기할 수 있습니다. -- `error`: 원문 검사용 -- `normalized` 사실 정보: `status_code`, `retry_after`, `error_code`, `is_network_error`, `is_timeout`, `is_abort` 등 -- `provider_advice`: 기본 모델 어댑터가 재시도 가이던스를 제공할 수 있을 때 +- `error`: 원문 검사를 위한 값입니다. +- `status_code`, `retry_after`, `error_code`, `is_network_error`, `is_timeout`, `is_abort` 같은 `normalized` 사실 +- 기본 모델 어댑터가 retry 지침을 제공할 수 있을 때의 `provider_advice` 정책은 다음 중 하나를 반환할 수 있습니다. -- 단순한 재시도 결정을 위한 `True` / `False` -- 지연 시간을 재정의하거나 진단 사유를 첨부하려는 경우 [`RetryDecision`][agents.retry.RetryDecision] +- 단순 retry 결정을 위한 `True` / `False` +- 지연을 override하거나 진단 reason을 첨부하려는 경우 [`RetryDecision`][agents.retry.RetryDecision] SDK는 `retry_policies`에서 바로 사용할 수 있는 헬퍼를 내보냅니다. | 헬퍼 | 동작 | | --- | --- | | `retry_policies.never()` | 항상 선택하지 않습니다. | -| `retry_policies.provider_suggested()` | 사용 가능한 경우 provider 재시도 조언을 따릅니다. | -| `retry_policies.network_error()` | 일시적인 전송 및 timeout 실패와 일치합니다. | -| `retry_policies.http_status([...])` | 선택된 HTTP 상태 코드와 일치합니다. | -| `retry_policies.retry_after()` | retry-after 힌트가 있을 때만 해당 지연 시간을 사용해 재시도합니다. | -| `retry_policies.any(...)` | 중첩된 정책 중 하나라도 선택하면 재시도합니다. | -| `retry_policies.all(...)` | 모든 중첩 정책이 선택할 때만 재시도합니다. | +| `retry_policies.provider_suggested()` | 사용 가능한 경우 provider retry 조언을 따릅니다. | +| `retry_policies.network_error()` | 일시적인 transport 및 timeout 실패와 일치합니다. | +| `retry_policies.http_status([...])` | 선택한 HTTP 상태 코드와 일치합니다. | +| `retry_policies.retry_after()` | retry-after 힌트가 있을 때만 해당 지연을 사용해 retry합니다. 이 헬퍼는 retry-after 값을 명시적인 정책 지연으로 취급하므로 `backoff.max_delay`가 이를 제한하지 않습니다. | +| `retry_policies.any(...)` | 중첩된 정책 중 하나라도 선택하면 retry합니다. | +| `retry_policies.all(...)` | 모든 중첩 정책이 선택할 때만 retry합니다. | -정책을 조합할 때 `provider_suggested()`가 가장 안전한 첫 번째 구성 요소입니다. provider가 이를 구분할 수 있을 때 provider의 거부와 replay-safety 승인을 보존하기 때문입니다. +정책을 조합할 때 `provider_suggested()`는 provider가 이를 구분할 수 있는 경우 provider veto와 replay-safety 승인을 보존하므로 가장 안전한 첫 번째 구성 요소입니다. ##### 안전 경계 -일부 실패는 자동으로 재시도되지 않습니다. +일부 실패는 자동으로 retry되지 않습니다. - Abort 오류 -- provider 조언이 replay를 안전하지 않다고 표시한 요청 -- 출력이 이미 시작되어 replay가 안전하지 않게 된 스트리밍 실행 +- Provider 조언이 replay를 안전하지 않다고 표시한 요청 +- replay를 안전하지 않게 만들 방식으로 출력이 이미 시작된 후의 스트리밍 실행 -`previous_response_id` 또는 `conversation_id`를 사용하는 상태 저장 후속 요청도 더 보수적으로 처리됩니다. 이러한 요청의 경우 `network_error()` 또는 `http_status([500])` 같은 non-provider predicate만으로는 충분하지 않습니다. 재시도 정책에는 일반적으로 `retry_policies.provider_suggested()`를 통해 provider의 replay-safe 승인이 포함되어야 합니다. +`previous_response_id` 또는 `conversation_id`를 사용하는 stateful 후속 요청도 더 보수적으로 처리됩니다. 이러한 요청에서는 `network_error()` 또는 `http_status([500])` 같은 비 provider predicate만으로는 충분하지 않습니다. retry 정책에는 일반적으로 `retry_policies.provider_suggested()`를 통한 provider의 replay-safe 승인이 포함되어야 합니다. ##### Runner와 에이전트 병합 동작 -`retry`는 runner 수준과 에이전트 수준 `ModelSettings` 사이에서 깊게 병합됩니다. +`retry`는 runner 수준 및 에이전트 수준 `ModelSettings` 사이에서 deep-merge됩니다. -- 에이전트는 `retry.max_retries`만 재정의하면서 runner의 `policy`를 계속 상속할 수 있습니다. -- 에이전트는 `retry.backoff`의 일부만 재정의하고 runner의 형제 backoff 필드를 유지할 수 있습니다. +- 에이전트는 `retry.max_retries`만 override하고 runner의 `policy`는 계속 상속할 수 있습니다. +- 에이전트는 `retry.backoff`의 일부만 override하고 runner의 sibling backoff 필드는 유지할 수 있습니다. - `policy`는 런타임 전용이므로 직렬화된 `ModelSettings`는 `max_retries`와 `backoff`를 유지하지만 콜백 자체는 생략합니다. -더 많은 예시는 [`examples/basic/retry.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry.py) 및 [어댑터 기반 재시도 예시](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry_litellm.py)를 참조하세요. +더 자세한 예시는 [`examples/basic/retry.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry.py) 및 [어댑터 기반 retry 예시](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry_litellm.py)를 참조하세요. -## OpenAI가 아닌 provider 문제 해결 +## 비 OpenAI provider 문제 해결 ### 트레이싱 클라이언트 오류 401 -트레이싱과 관련된 오류가 발생한다면 trace가 OpenAI 서버에 업로드되는데 OpenAI API 키가 없기 때문입니다. 이를 해결하는 옵션은 세 가지입니다. +트레이싱 관련 오류가 발생한다면 trace가 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 키는 trace 업로드에만 사용되며 [platform.openai.com](https://platform.openai.com/)에서 발급된 것이어야 합니다. -3. OpenAI가 아닌 trace 프로세서 사용. [트레이싱 문서](../tracing.md#custom-tracing-processors)를 참조하세요. +2. 트레이싱용 OpenAI 키 설정: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]. 이 API 키는 trace 업로드에만 사용되며 [platform.openai.com](https://platform.openai.com/)의 키여야 합니다. +3. 비 OpenAI trace 프로세서를 사용합니다. [트레이싱 문서](../tracing.md#custom-tracing-processors)를 참조하세요. ### Responses API 지원 -SDK는 기본적으로 Responses API를 사용하지만, 다른 많은 LLM provider는 아직 이를 지원하지 않습니다. 그 결과 404 또는 유사한 문제가 발생할 수 있습니다. 해결 방법은 두 가지입니다. +SDK는 기본적으로 Responses API를 사용하지만, 많은 다른 LLM provider가 아직 이를 지원하지 않습니다. 그 결과 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/)에 있습니다. +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 지원 -일부 모델 provider는 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)를 지원하지 않습니다. 이로 인해 때때로 다음과 비슷한 오류가 발생합니다. +일부 모델 provider는 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)를 지원하지 않습니다. 이로 인해 때때로 다음과 같은 오류가 발생합니다. ``` @@ -481,34 +481,34 @@ BadRequestError: Error code: 400 - {'error': {'message': "'response_format.type' ``` -이는 일부 모델 provider의 한계입니다. JSON 출력은 지원하지만 출력에 사용할 `json_schema`를 지정하도록 허용하지 않습니다. 이에 대한 수정 작업을 진행 중이지만, 그렇지 않으면 앱이 잘못된 JSON으로 인해 자주 중단될 수 있으므로 JSON schema 출력을 지원하는 provider에 의존하는 것을 권장합니다. +이는 일부 모델 provider의 한계입니다. JSON 출력은 지원하지만 출력에 사용할 `json_schema`를 지정할 수는 없습니다. 이 문제를 수정하는 작업을 진행 중이지만, 그렇지 않으면 앱이 잘못된 형식의 JSON 때문에 자주 중단될 수 있으므로 JSON schema 출력을 지원하는 provider에 의존하는 것을 권장합니다. ## Provider 간 모델 혼합 -모델 provider 간 기능 차이를 알고 있어야 하며, 그렇지 않으면 오류가 발생할 수 있습니다. 예를 들어 OpenAI는 structured outputs, multimodal input, 호스티드 파일 검색 및 웹 검색을 지원하지만, 다른 많은 provider는 이러한 기능을 지원하지 않습니다. 다음 제한 사항에 유의하세요. +모델 provider 간 기능 차이를 알고 있어야 하며, 그렇지 않으면 오류가 발생할 수 있습니다. 예를 들어 OpenAI는 structured outputs, multimodal input, 호스티드 file search 및 웹 검색을 지원하지만, 많은 다른 provider는 이러한 기능을 지원하지 않습니다. 다음 제한 사항을 유의하세요. -- 지원되지 않는 `tools`를 이해하지 못하는 provider에 보내지 마세요 -- 텍스트 전용 모델을 호출하기 전에 multimodal input을 필터링하세요 +- 지원되지 않는 `tools`를 이를 이해하지 못하는 provider에 보내지 마세요 +- text-only 모델을 호출하기 전에 multimodal input을 필터링하세요 - structured JSON outputs를 지원하지 않는 provider는 가끔 유효하지 않은 JSON을 생성할 수 있음을 유의하세요. -## 타사 어댑터 +## 서드파티 어댑터 -SDK의 기본 제공 provider 통합 지점으로 충분하지 않을 때만 타사 어댑터를 사용하세요. 이 SDK로 OpenAI 모델만 사용한다면 Any-LLM 또는 LiteLLM 대신 기본 제공 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 경로를 선호하세요. 타사 어댑터는 OpenAI 모델을 OpenAI가 아닌 provider와 결합해야 하거나, 기본 제공 경로가 제공하지 않는 어댑터 관리 provider 범위 또는 라우팅이 필요한 경우를 위한 것입니다. 어댑터는 SDK와 upstream 모델 provider 사이에 또 하나의 호환성 계층을 추가하므로 provider별로 기능 지원과 요청 의미가 달라질 수 있습니다. SDK는 현재 Any-LLM과 LiteLLM을 best-effort 베타 어댑터 통합으로 포함합니다. +SDK의 내장 provider 통합 지점이 충분하지 않은 경우에만 서드파티 어댑터를 사용하세요. 이 SDK로 OpenAI 모델만 사용하는 경우 Any-LLM 또는 LiteLLM 대신 내장 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 경로를 선호하세요. 서드파티 어댑터는 OpenAI 모델을 비 OpenAI provider와 결합해야 하거나 내장 경로가 제공하지 않는 어댑터 관리 provider 범위 또는 라우팅이 필요한 경우를 위한 것입니다. 어댑터는 SDK와 upstream 모델 provider 사이에 또 하나의 호환성 계층을 추가하므로 기능 지원과 요청 의미가 provider별로 달라질 수 있습니다. SDK에는 현재 best-effort 베타 어댑터 통합으로 Any-LLM과 LiteLLM이 포함되어 있습니다. ### Any-LLM -Any-LLM 지원은 Any-LLM이 관리하는 provider 범위 또는 라우팅이 필요한 경우를 위해 best-effort 베타 기준으로 포함되어 있습니다. +Any-LLM 지원은 Any-LLM 관리 provider 범위 또는 라우팅이 필요한 경우를 위해 best-effort 베타로 포함됩니다. -upstream provider 경로에 따라 Any-LLM은 Responses API, Chat Completions 호환 API 또는 provider별 호환성 계층을 사용할 수 있습니다. +Upstream provider 경로에 따라 Any-LLM은 Responses API, Chat Completions 호환 API 또는 provider별 호환성 계층을 사용할 수 있습니다. -Any-LLM이 필요하다면 `openai-agents[any-llm]`를 설치한 다음 [`examples/model_providers/any_llm_auto.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/any_llm_auto.py) 또는 [`examples/model_providers/any_llm_provider.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/any_llm_provider.py)부터 시작하세요. [`MultiProvider`][agents.MultiProvider]에서 `any-llm/...` 모델 이름을 사용하거나, `AnyLLMModel`을 직접 인스턴스화하거나, 실행 범위에서 `AnyLLMProvider`를 사용할 수 있습니다. 모델 표면을 명시적으로 고정해야 한다면 `AnyLLMModel`을 생성할 때 `api="responses"` 또는 `api="chat_completions"`를 전달하세요. +Any-LLM이 필요하면 `openai-agents[any-llm]`을 설치한 다음 [`examples/model_providers/any_llm_auto.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/any_llm_auto.py) 또는 [`examples/model_providers/any_llm_provider.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/any_llm_provider.py)에서 시작하세요. [`MultiProvider`][agents.MultiProvider]에서 `any-llm/...` 모델 이름을 사용하거나, `AnyLLMModel`을 직접 인스턴스화하거나, 실행 범위에서 `AnyLLMProvider`를 사용할 수 있습니다. 모델 표면을 명시적으로 고정해야 한다면 `AnyLLMModel`을 생성할 때 `api="responses"` 또는 `api="chat_completions"`를 전달하세요. -Any-LLM은 여전히 타사 어댑터 계층이므로 provider 의존성과 기능 차이는 SDK가 아니라 Any-LLM에 의해 upstream에서 정의됩니다. upstream provider가 사용량 지표를 반환하면 usage metrics는 자동으로 전파되지만, 스트리밍 Chat Completions 백엔드는 usage chunks를 내보내기 전에 `ModelSettings(include_usage=True)`가 필요할 수 있습니다. structured outputs, tool calling, usage reporting 또는 Responses별 동작에 의존한다면 배포하려는 정확한 provider 백엔드를 검증하세요. +Any-LLM은 서드파티 어댑터 계층이므로 provider 의존성과 capability gap은 SDK가 아니라 upstream의 Any-LLM이 정의합니다. Upstream provider가 사용량 metrics를 반환하면 자동으로 전파되지만, 스트리밍 Chat Completions 백엔드는 사용량 chunk를 내보내기 전에 `ModelSettings(include_usage=True)`가 필요할 수 있습니다. structured outputs, tool calling, 사용량 보고 또는 Responses별 동작에 의존한다면 배포하려는 정확한 provider backend를 검증하세요. ### LiteLLM -LiteLLM 지원은 LiteLLM별 provider 범위 또는 라우팅이 필요한 경우를 위해 best-effort 베타 기준으로 포함되어 있습니다. +LiteLLM 지원은 LiteLLM별 provider 범위 또는 라우팅이 필요한 경우를 위해 best-effort 베타로 포함됩니다. -LiteLLM이 필요하다면 `openai-agents[litellm]`를 설치한 다음 [`examples/model_providers/litellm_auto.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/litellm_auto.py) 또는 [`examples/model_providers/litellm_provider.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/litellm_provider.py)부터 시작하세요. `litellm/...` 모델 이름을 사용하거나 [`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel]을 직접 인스턴스화할 수 있습니다. +LiteLLM이 필요하면 `openai-agents[litellm]`을 설치한 다음 [`examples/model_providers/litellm_auto.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/litellm_auto.py) 또는 [`examples/model_providers/litellm_provider.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/litellm_provider.py)에서 시작하세요. `litellm/...` 모델 이름을 사용하거나 [`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel]을 직접 인스턴스화할 수 있습니다. -일부 LiteLLM 기반 provider는 기본적으로 SDK usage metrics를 채우지 않습니다. usage reporting이 필요하다면 `ModelSettings(include_usage=True)`를 전달하고, structured outputs, tool calling, usage reporting 또는 어댑터별 라우팅 동작에 의존한다면 배포하려는 정확한 provider 백엔드를 검증하세요. \ No newline at end of file +일부 LiteLLM 기반 provider는 기본적으로 SDK 사용량 metrics를 채우지 않습니다. 사용량 보고가 필요하다면 `ModelSettings(include_usage=True)`를 전달하고, structured outputs, tool calling, 사용량 보고 또는 어댑터별 라우팅 동작에 의존하는 경우 배포하려는 정확한 provider backend를 검증하세요. \ No newline at end of file diff --git a/docs/zh/models/index.md b/docs/zh/models/index.md index 79f6967c02..b30f776880 100644 --- a/docs/zh/models/index.md +++ b/docs/zh/models/index.md @@ -4,7 +4,7 @@ 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。 @@ -13,22 +13,22 @@ Agents SDK 内置支持两种 OpenAI 模型： 从适合你设置的最简单路径开始： -| 如果你想要…… | 推荐路径 | 阅读更多 | +| 如果你想要... | 推荐路径 | 了解更多 | | --- | --- | --- | -| 仅使用 OpenAI 模型 | 使用默认 OpenAI 提供方和 Responses 模型路径 | [OpenAI 模型](#openai-models) | +| 仅使用 OpenAI 模型 | 使用默认的 OpenAI 提供方和 Responses 模型路径 | [OpenAI 模型](#openai-models) | | 通过 websocket 传输使用 OpenAI Responses API | 保持 Responses 模型路径并启用 websocket 传输 | [Responses WebSocket 传输](#responses-websocket-transport) | | 使用一个非 OpenAI 提供方 | 从内置提供方集成点开始 | [非 OpenAI 模型](#non-openai-models) | -| 在智能体之间混用模型或提供方 | 按每次运行或每个智能体选择提供方，并审查功能差异 | [在一个工作流中混用模型](#mixing-models-in-one-workflow) 和 [跨提供方混用模型](#mixing-models-across-providers) | +| 在多个智能体之间混用模型或提供方 | 按每次运行或每个智能体选择提供方，并查看功能差异 | [在一个工作流中混用模型](#mixing-models-in-one-workflow) 和 [跨提供方混用模型](#mixing-models-across-providers) | | 调整高级 OpenAI Responses 请求设置 | 在 OpenAI Responses 路径上使用 `ModelSettings` | [高级 OpenAI Responses 设置](#advanced-openai-responses-settings) | -| 使用第三方适配器进行非 OpenAI 或混合提供方路由 | 比较受支持的 beta 适配器，并验证你计划发布的提供方路径 | [第三方适配器](#third-party-adapters) | +| 为非 OpenAI 或混合提供方路由使用第三方适配器 | 比较受支持的 beta 适配器，并验证你计划发布的提供方路径 | [第三方适配器](#third-party-adapters) | ## OpenAI 模型 -对于大多数仅使用 OpenAI 的应用，推荐路径是使用字符串模型名称配合默认 OpenAI 提供方，并保持在 Responses 模型路径上。 +对于大多数仅使用 OpenAI 的应用，推荐路径是通过默认 OpenAI 提供方使用字符串模型名称，并保持在 Responses 模型路径上。 -当你初始化 `Agent` 时未指定模型，将使用默认模型。当前默认值是 [`gpt-5.4-mini`](https://developers.openai.com/api/docs/models/gpt-5.4-mini)，并为低延迟智能体工作流设置 `reasoning.effort="none"` 和 `verbosity="low"`。如果你有访问权限，我们建议将智能体设置为 [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5)，以在保持显式 `model_settings` 的同时获得更高质量。 +当你在初始化 `Agent` 时未指定模型，将使用默认模型。默认值目前是 [`gpt-5.4-mini`](https://developers.openai.com/api/docs/models/gpt-5.4-mini)，并为低延迟智能体工作流设置 `reasoning.effort="none"` 和 `verbosity="low"`。如果你有访问权限，我们建议将智能体设置为 [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5)，以在保留显式 `model_settings` 的同时获得更高质量。 -如果你想切换到其他模型，例如 [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5)，有两种方式配置你的智能体。 +如果你想切换到其他模型，例如 [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5)，有两种方式配置智能体。 ### 默认模型 @@ -39,7 +39,7 @@ export OPENAI_DEFAULT_MODEL=gpt-5.5 python3 my_awesome_agent.py ``` -其次，你可以通过 `RunConfig` 为一次运行设置默认模型。如果某个智能体没有设置模型，将使用本次运行的模型。 +其次，你可以通过 `RunConfig` 为一次运行设置默认模型。如果没有为智能体设置模型，将使用此次运行的模型。 ```python from agents import Agent, RunConfig, Runner @@ -58,7 +58,7 @@ result = await Runner.run( #### GPT-5 模型 -当你以这种方式使用任何 GPT-5 模型（例如 [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5)）时，SDK 会应用默认 `ModelSettings`。它会设置最适合大多数用例的选项。若要调整默认模型的推理力度，请传入你自己的 `ModelSettings`： +当你以这种方式使用任何 GPT-5 模型（例如 [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5)）时，SDK 会应用默认的 `ModelSettings`。它会设置适用于大多数用例的最佳选项。若要调整默认模型的推理强度，请传入你自己的 `ModelSettings`： ```python from openai.types.shared import Reasoning @@ -74,35 +74,35 @@ my_agent = Agent( ) ``` -为了降低延迟，建议对 GPT-5 模型使用 `reasoning.effort="none"`。 +为降低延迟，建议在 GPT-5 模型中使用 `reasoning.effort="none"`。 #### ComputerTool 模型选择 -如果智能体包含 [`ComputerTool`][agents.tool.ComputerTool]，实际 Responses 请求上的有效模型会决定 SDK 发送哪种计算机工具负载。显式 `gpt-5.5` 请求使用 GA 内置 `computer` 工具，而显式 `computer-use-preview` 请求会保留较旧的 `computer_use_preview` 负载。 +如果智能体包含 [`ComputerTool`][agents.tool.ComputerTool]，实际 Responses 请求上的有效模型会决定 SDK 发送哪种 computer-tool 载荷。显式的 `gpt-5.5` 请求使用 GA 内置 `computer` 工具，而显式的 `computer-use-preview` 请求保留较旧的 `computer_use_preview` 载荷。 -由提示词管理的调用是主要例外。如果提示词模板拥有模型，而 SDK 在请求中省略 `model`，SDK 会默认使用兼容 preview 的计算机负载，以免猜测该提示词固定了哪个模型。要在该流程中保持 GA 路径，可以在请求中显式设置 `model="gpt-5.5"`，或使用 `ModelSettings(tool_choice="computer")` 或 `ModelSettings(tool_choice="computer_use")` 强制选择 GA。 +由提示词管理的调用是主要例外。如果提示词模板拥有模型，并且 SDK 从请求中省略 `model`，SDK 会默认使用兼容预览版的 computer 载荷，这样它就不会猜测提示词固定了哪个模型。若要在该流程中保持 GA 路径，请在请求中显式设置 `model="gpt-5.5"`，或使用 `ModelSettings(tool_choice="computer")` 或 `ModelSettings(tool_choice="computer_use")` 强制使用 GA 选择器。 注册了 [`ComputerTool`][agents.tool.ComputerTool] 后，`tool_choice="computer"`、`"computer_use"` 和 `"computer_use_preview"` 会被规范化为与有效请求模型匹配的内置选择器。如果未注册 `ComputerTool`，这些字符串会继续像普通函数名称一样运行。 -兼容 preview 的请求必须预先序列化 `environment` 和显示尺寸，因此，使用 [`ComputerProvider`][agents.tool.ComputerProvider] 工厂的提示词管理流程应传入具体的 `Computer` 或 `AsyncComputer` 实例，或在发送请求前强制选择 GA。完整迁移详情请参阅[工具](../tools.md#computertool-and-the-responses-computer-tool)。 +兼容预览版的请求必须预先序列化 `environment` 和显示尺寸，因此使用 [`ComputerProvider`][agents.tool.ComputerProvider] 工厂的提示词管理流程，应传入具体的 `Computer` 或 `AsyncComputer` 实例，或在发送请求前强制使用 GA 选择器。完整迁移详情请参阅[工具](../tools.md#computertool-and-the-responses-computer-tool)。 #### 非 GPT-5 模型 如果你传入非 GPT-5 模型名称且没有自定义 `model_settings`，SDK 会回退到与任何模型兼容的通用 `ModelSettings`。 -### 仅限 Responses 的工具搜索功能 +### 仅 Responses 支持的工具检索功能 -以下工具功能仅支持 OpenAI Responses 模型： +以下工具功能仅受 OpenAI Responses 模型支持： - [`ToolSearchTool`][agents.tool.ToolSearchTool] - [`tool_namespace()`][agents.tool.tool_namespace] -- `@function_tool(defer_loading=True)` 以及其他延迟加载的 Responses 工具表面 +- `@function_tool(defer_loading=True)` 以及其他延迟加载的 Responses 工具界面 -这些功能会在 Chat Completions 模型和非 Responses 后端上被拒绝。使用延迟加载工具时，请将 `ToolSearchTool()` 添加到智能体，并让模型通过 `auto` 或 `required` 工具选择来加载工具，而不是强制使用裸命名空间名称或仅延迟的函数名称。设置详情和当前限制请参阅[工具](../tools.md#hosted-tool-search)。 +这些功能在 Chat Completions 模型和非 Responses 后端上会被拒绝。使用延迟加载工具时，请将 `ToolSearchTool()` 添加到智能体，并让模型通过 `auto` 或 `required` 工具选择加载工具，而不是强制使用裸命名空间名称或仅延迟的函数名称。设置详情和当前限制请参阅[工具](../tools.md#hosted-tool-search)。 ### Responses WebSocket 传输 -默认情况下，OpenAI Responses API 请求使用 HTTP 传输。在使用由 OpenAI 支持的模型时，你可以选择启用 websocket 传输。 +默认情况下，OpenAI Responses API 请求使用 HTTP 传输。使用 OpenAI 支持的模型时，你可以选择启用 websocket 传输。 #### 基本设置 @@ -112,9 +112,9 @@ from agents import set_default_openai_responses_transport set_default_openai_responses_transport("websocket") ``` -这会影响由默认 OpenAI 提供方解析的 OpenAI Responses 模型（包括诸如 `"gpt-5.5"` 的字符串模型名称）。 +这会影响由默认 OpenAI 提供方解析的 OpenAI Responses 模型（包括字符串模型名称，例如 `"gpt-5.5"`）。 -当 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=...)`，则该提供方会控制传输选择，而不是全局默认值。 #### 提供方或运行级设置 @@ -139,7 +139,7 @@ result = await Runner.run( ) ``` -由 OpenAI 支持的提供方还接受可选的智能体注册配置。这是一个高级选项，适用于你的 OpenAI 设置需要提供方级注册元数据（例如 harness ID）的情况。 +OpenAI 支持的提供方还接受可选的智能体注册配置。这是一个高级选项，适用于你的 OpenAI 设置需要提供方级注册元数据（例如 harness ID）的情况。 ```python from agents import ( @@ -165,14 +165,14 @@ result = await Runner.run( #### 使用 `MultiProvider` 的高级路由 -如果你需要基于前缀的模型路由（例如在一次运行中混用 `openai/...` 和 `any-llm/...` 模型名称），请使用 [`MultiProvider`][agents.MultiProvider]，并在其中设置 `openai_use_responses_websocket=True`。 +如果你需要基于前缀的模型路由（例如在一次运行中混用 `openai/...` 和 `any-llm/...` 模型名称），请使用 [`MultiProvider`][agents.MultiProvider]，并在那里设置 `openai_use_responses_websocket=True`。 `MultiProvider` 保留两个历史默认值： -- `openai/...` 被视为 OpenAI 提供方的别名，因此 `openai/gpt-4.1` 会作为模型 `gpt-4.1` 进行路由。 +- `openai/...` 被视为 OpenAI 提供方的别名，因此 `openai/gpt-4.1` 会以模型 `gpt-4.1` 的形式路由。 - 未知前缀会引发 `UserError`，而不是被透传。 -当你将 OpenAI 提供方指向一个期望字面量命名空间模型 ID 的 OpenAI 兼容端点时，请显式选择透传行为。在启用 websocket 的设置中，也要在 `MultiProvider` 上保持 `openai_use_responses_websocket=True`： +当你将 OpenAI 提供方指向期望字面命名空间模型 ID 的 OpenAI 兼容端点时，请显式选择透传行为。在启用了 websocket 的设置中，也要在 `MultiProvider` 上保留 `openai_use_responses_websocket=True`： ```python from agents import Agent, MultiProvider, RunConfig, Runner @@ -198,7 +198,7 @@ result = await Runner.run( ) ``` -当后端期望字面量 `openai/...` 字符串时，使用 `openai_prefix_mode="model_id"`。当后端期望其他命名空间模型 ID（例如 `openrouter/openai/gpt-4.1-mini`）时，使用 `unknown_prefix_mode="model_id"`。这些选项也适用于 websocket 传输之外的 `MultiProvider`；本示例保持启用 websocket，因为它是本节所述传输设置的一部分。相同选项也可用于 [`responses_websocket_session()`][agents.responses_websocket_session]。 +当后端期望字面量 `openai/...` 字符串时，使用 `openai_prefix_mode="model_id"`。当后端期望其他命名空间模型 ID（例如 `openrouter/openai/gpt-4.1-mini`）时，使用 `unknown_prefix_mode="model_id"`。这些选项也适用于 websocket 传输之外的 `MultiProvider`；此示例保持启用 websocket，因为它是本节所述传输设置的一部分。相同选项也可用于 [`responses_websocket_session()`][agents.responses_websocket_session]。 如果你在通过 `MultiProvider` 路由时需要相同的提供方级注册元数据，请传入 `openai_agent_registration=OpenAIAgentRegistrationConfig(...)`，它会被转发到底层 OpenAI 提供方。 @@ -206,10 +206,10 @@ result = await Runner.run( #### 说明 -- 这是通过 websocket 传输的 Responses API，而不是 [Realtime API](../realtime/guide.md)。除非它们支持 Responses websocket `/responses` 端点，否则它不适用于 Chat Completions 或非 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]。对于希望跨轮次（以及嵌套的 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)。 -- 对于较长推理轮次或存在延迟尖峰的网络，请使用 `responses_websocket_options` 自定义 websocket keepalive 行为。增大 `ping_timeout` 以容忍延迟的 pong 帧，或设置 `ping_timeout=None` 以在保持启用 ping 的同时禁用心跳超时。当可靠性比 websocket 延迟更重要时，优先使用 HTTP/SSE 传输。 +- 启用 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)。 +- 对于长推理轮次或存在延迟尖峰的网络，请使用 `responses_websocket_options` 自定义 websocket keepalive 行为。增大 `ping_timeout` 以容忍延迟的 pong 帧，或设置 `ping_timeout=None` 以在保持 ping 启用的同时禁用心跳超时。当可靠性比 websocket 延迟更重要时，优先使用 HTTP/SSE 传输。 ## 非 OpenAI 模型 @@ -217,20 +217,20 @@ result = await Runner.run( ### 非 OpenAI 提供方集成方式 -| 方法 | 使用场景 | 范围 | +| 方法 | 适用场景 | 范围 | | --- | --- | --- | -| [`set_default_openai_client`][agents.set_default_openai_client] | 一个 OpenAI 兼容端点应作为大多数或所有智能体的默认值 | 全局默认 | -| [`ModelProvider`][agents.models.interface.ModelProvider] | 一个自定义提供方应应用于单次运行 | 按运行 | -| [`Agent.model`][agents.agent.Agent.model] | 不同智能体需要不同提供方或具体模型对象 | 按智能体 | -| 第三方适配器 | 你需要适配器管理的提供方覆盖范围或内置路径不提供的路由 | 请参阅[第三方适配器](#third-party-adapters) | +| [`set_default_openai_client`][agents.set_default_openai_client] | 一个 OpenAI 兼容端点应成为大多数或所有智能体的默认端点 | 全局默认 | +| [`ModelProvider`][agents.models.interface.ModelProvider] | 一个自定义提供方应应用于单次运行 | 每次运行 | +| [`Agent.model`][agents.agent.Agent.model] | 不同智能体需要不同提供方或具体模型对象 | 每个智能体 | +| 第三方适配器 | 你需要由适配器管理的提供方覆盖范围或路由，而内置路径无法提供 | 参阅[第三方适配器](#third-party-adapters) | 你可以通过这些内置路径集成其他 LLM 提供方： -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)。 +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)。 -在你没有来自 `platform.openai.com` 的 API 密钥的情况下，我们建议通过 `set_tracing_disabled()` 禁用追踪，或设置[不同的追踪进程](../tracing.md)。 +在你没有来自 `platform.openai.com` 的 API key 的情况下，我们建议通过 `set_tracing_disabled()` 禁用追踪，或设置[不同的追踪进程](../tracing.md)。 ``` python from agents import Agent, AsyncOpenAI, OpenAIChatCompletionsModel, set_tracing_disabled @@ -249,15 +249,15 @@ agent= Agent(name="Helping Agent", instructions="You are a Helping Agent", model ## 在一个工作流中混用模型 -在单个工作流中，你可能希望为每个智能体使用不同模型。例如，你可以使用更小、更快的模型进行分诊，同时使用更大、能力更强的模型处理复杂任务。配置 [`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 @@ -290,7 +290,7 @@ async def main(): print(result.final_output) ``` -1. 直接设置 OpenAI 模型的名称。 +1. 直接设置 OpenAI 模型名称。 2. 提供 [`Model`][agents.models.interface.Model] 实现。 当你想进一步配置智能体使用的模型时，可以传入 [`ModelSettings`][agents.models.interface.ModelSettings]，它提供可选的模型配置参数，例如 temperature。 @@ -308,20 +308,20 @@ english_agent = Agent( ## 高级 OpenAI Responses 设置 -当你在 OpenAI Responses 路径上并需要更多控制时，请从 `ModelSettings` 开始。 +当你使用 OpenAI Responses 路径并需要更多控制时，请从 `ModelSettings` 开始。 -### 常用高级 `ModelSettings` 选项 +### 常见高级 `ModelSettings` 选项 -当你使用 OpenAI Responses API 时，已有多个请求字段具备直接的 `ModelSettings` 字段，因此不需要为它们使用 `extra_args`。 +使用 OpenAI Responses API 时，多个请求字段已经有直接的 `ModelSettings` 字段，因此无需为它们使用 `extra_args`。 -- `parallel_tool_calls`：允许或禁止同一轮次中的多个工具调用。 -- `truncation`：设置为 `"auto"`，让 Responses API 在上下文将溢出时丢弃最旧的对话项，而不是失败。 -- `store`：控制生成的响应是否存储在服务端以供之后检索。这对依赖响应 ID 的后续工作流，以及在 `store=False` 时可能需要回退到本地输入的会话压缩流程很重要。 +- `parallel_tool_calls`：允许或禁止在同一轮中进行多个工具调用。 +- `truncation`：设置为 `"auto"`，让 Responses API 在上下文即将溢出时丢弃最旧的对话项，而不是失败。 +- `store`：控制生成的响应是否存储在服务端以供后续检索。这对于依赖响应 ID 的后续工作流，以及在 `store=False` 时可能需要回退到本地输入的会话压缩流程很重要。 - `context_management`：配置服务端上下文处理，例如带有 `compact_threshold` 的 Responses 压缩。 -- `prompt_cache_retention`：更长时间保留缓存的提示词前缀，例如使用 `"24h"`。 -- `response_include`：请求更丰富的响应负载，例如 `web_search_call.action.sources`、`file_search_call.results` 或 `reasoning.encrypted_content`。 +- `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`。 -- `retry`：选择启用由运行器管理的模型调用重试设置。请参阅[由运行器管理的重试](#runner-managed-retries)。 +- `retry`：选择启用由 runner 管理的模型调用重试设置。请参阅 [Runner 管理的重试](#runner-managed-retries)。 ```python from agents import Agent, ModelSettings @@ -341,15 +341,15 @@ research_agent = Agent( ) ``` -当你设置 `store=False` 时，Responses API 不会保留该响应以供之后服务端检索。这对无状态或零数据保留风格的流程很有用，但也意味着原本会复用响应 ID 的功能需要改为依赖本地管理的状态。例如，当最后一个响应未被存储时，[`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession] 会将其默认 `"auto"` 压缩路径切换为基于输入的压缩。请参阅[会话指南](../sessions/index.md#openai-responses-compaction-sessions)。 +当你设置 `store=False` 时，Responses API 不会保留该响应用于后续服务端检索。这对于无状态或零数据保留风格的流程很有用，但也意味着原本会复用响应 ID 的功能需要改为依赖本地管理的状态。例如，当最后一个响应未被存储时，[`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession] 会将其默认的 `"auto"` 压缩路径切换为基于输入的压缩。请参阅[会话指南](../sessions/index.md#openai-responses-compaction-sessions)。 服务端压缩不同于 [`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession]。`context_management=[{"type": "compaction", "compact_threshold": ...}]` 会随每个 Responses API 请求发送，并且当渲染后的上下文超过阈值时，API 可以将压缩项作为响应的一部分发出。`OpenAIResponsesCompactionSession` 会在轮次之间调用独立的 `responses.compact` 端点，并重写本地会话历史。 ### 传递 `extra_args` -当你需要提供方特定或较新的请求字段，而 SDK 尚未在顶层直接暴露时，请使用 `extra_args`。 +当你需要 SDK 尚未在顶层直接公开的提供方特定或更新的请求字段时，请使用 `extra_args`。 -此外，当你使用 OpenAI 的 Responses API 时，[还有一些其他可选参数](https://platform.openai.com/docs/api-reference/responses/create)（例如 `user`、`service_tier` 等）。如果它们在顶层不可用，也可以使用 `extra_args` 传递它们。不要同时通过直接的 `ModelSettings` 字段设置同一个请求字段。 +此外，当你使用 OpenAI 的 Responses API 时，[还有一些其他可选参数](https://platform.openai.com/docs/api-reference/responses/create)（例如 `user`、`service_tier` 等）。如果它们在顶层不可用，也可以使用 `extra_args` 传递。不要同时通过直接的 `ModelSettings` 字段设置相同的请求字段。 ```python from agents import Agent, ModelSettings @@ -365,9 +365,9 @@ english_agent = Agent( ) ``` -## 由运行器管理的重试 +## Runner 管理的重试 -重试仅在运行时生效，并且需要选择启用。除非你设置 `ModelSettings(retry=...)` 且你的重试策略选择重试，否则 SDK 不会重试通用模型请求。 +重试仅在运行时生效，并且需要选择启用。除非你设置 `ModelSettings(retry=...)` 且你的重试策略选择重试，否则 SDK 不会重试一般模型请求。 ```python from agents import Agent, ModelRetrySettings, ModelSettings, retry_policies @@ -401,79 +401,79 @@ agent = Agent( | 字段 | 类型 | 说明 | | --- | --- | --- | -| `max_retries` | `int | None` | 初始请求之后允许的重试尝试次数。 | -| `backoff` | `ModelRetryBackoffSettings | dict | None` | 当策略在未返回显式延迟的情况下重试时使用的默认延迟策略。 | -| `policy` | `RetryPolicy | None` | 决定是否重试的回调。此字段仅在运行时生效，不会被序列化。 | +| `max_retries` | `int | None` | 初始请求之后允许的重试次数。 | +| `backoff` | `ModelRetryBackoffSettings | dict | None` | 当策略重试且未返回显式延迟时的默认延迟策略。`backoff.max_delay` 仅限制此处计算出的退避延迟。它不会限制策略返回的显式延迟或 retry-after 提示。 | +| `policy` | `RetryPolicy | None` | 决定是否重试的回调。该字段仅在运行时生效，不会被序列化。 | -重试策略会收到一个 [`RetryPolicyContext`][agents.retry.RetryPolicyContext]，其中包含： +重试策略会接收 [`RetryPolicyContext`][agents.retry.RetryPolicyContext]，其中包含： -- `attempt` 和 `max_retries`，以便你根据尝试次数做出决策。 -- `stream`，以便你在流式与非流式行为之间分支。 +- `attempt` 和 `max_retries`，以便你可以做出感知尝试次数的决策。 +- `stream`，以便你可以在流式和非流式行为之间分支。 - `error`，用于原始检查。 - `normalized` 事实，例如 `status_code`、`retry_after`、`error_code`、`is_network_error`、`is_timeout` 和 `is_abort`。 -- 当底层模型适配器能够提供重试指导时的 `provider_advice`。 +- 当底层模型适配器可以提供重试指导时的 `provider_advice`。 策略可以返回： - `True` / `False`，表示简单的重试决策。 -- 当你想覆盖延迟或附加诊断原因时，返回 [`RetryDecision`][agents.retry.RetryDecision]。 +- 当你希望覆盖延迟或附加诊断原因时，返回 [`RetryDecision`][agents.retry.RetryDecision]。 SDK 在 `retry_policies` 上导出开箱即用的辅助函数： | 辅助函数 | 行为 | | --- | --- | | `retry_policies.never()` | 始终选择不重试。 | -| `retry_policies.provider_suggested()` | 在可用时遵循提供方重试建议。 | -| `retry_policies.network_error()` | 匹配瞬态传输和超时故障。 | +| `retry_policies.provider_suggested()` | 在提供方重试建议可用时遵循该建议。 | +| `retry_policies.network_error()` | 匹配暂时性传输和超时故障。 | | `retry_policies.http_status([...])` | 匹配选定的 HTTP 状态码。 | -| `retry_policies.retry_after()` | 仅在存在 retry-after 提示时重试，并使用该延迟。 | +| `retry_policies.retry_after()` | 仅在 retry-after 提示可用时重试，并使用该延迟。此辅助函数将 retry-after 值视为显式策略延迟，因此 `backoff.max_delay` 不会限制它。 | | `retry_policies.any(...)` | 当任一嵌套策略选择重试时重试。 | | `retry_policies.all(...)` | 仅当每个嵌套策略都选择重试时才重试。 | -组合策略时，`provider_suggested()` 是最安全的第一构建块，因为当提供方能够区分时，它会保留提供方否决和重放安全批准。 +组合策略时，`provider_suggested()` 是最安全的首个构建块，因为当提供方能够区分时，它会保留提供方否决和重放安全批准。 ##### 安全边界 -某些故障永远不会自动重试： +某些失败永远不会自动重试： - 中止错误。 - 提供方建议将重放标记为不安全的请求。 -- 已经开始输出且以会使重放不安全的方式进行的流式运行。 +- 输出已经以会使重放不安全的方式开始后的流式运行。 使用 `previous_response_id` 或 `conversation_id` 的有状态后续请求也会被更保守地处理。对于这些请求，仅靠 `network_error()` 或 `http_status([500])` 等非提供方谓词是不够的。重试策略应包含来自提供方的重放安全批准，通常通过 `retry_policies.provider_suggested()` 实现。 -##### 运行器与智能体合并行为 +##### Runner 与智能体的合并行为 -`retry` 会在运行器级和智能体级 `ModelSettings` 之间进行深度合并： +`retry` 会在 runner 级和智能体级 `ModelSettings` 之间进行深度合并： -- 智能体可以仅覆盖 `retry.max_retries`，同时仍继承运行器的 `policy`。 -- 智能体可以仅覆盖 `retry.backoff` 的一部分，并保留来自运行器的同级 backoff 字段。 +- 智能体可以只覆盖 `retry.max_retries`，并仍然继承 runner 的 `policy`。 +- 智能体可以只覆盖 `retry.backoff` 的一部分，并保留来自 runner 的同级 backoff 字段。 - `policy` 仅在运行时生效，因此序列化后的 `ModelSettings` 会保留 `max_retries` 和 `backoff`，但省略回调本身。 -更多示例请参阅 [`examples/basic/retry.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry.py) 和[由适配器支持的重试示例](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry_litellm.py)。 +如需更完整的示例，请参阅 [`examples/basic/retry.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry.py) 和[适配器支持的重试示例](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry_litellm.py)。 ## 非 OpenAI 提供方故障排除 ### 追踪客户端错误 401 -如果你遇到与追踪相关的错误，这是因为 traces 会上传到 OpenAI 服务，而你没有 OpenAI API 密钥。你有三个选项可解决此问题： +如果你遇到与追踪相关的错误，这是因为 traces 会上传到 OpenAI 服务，而你没有 OpenAI API key。你有三个选项来解决此问题： 1. 完全禁用追踪：[`set_tracing_disabled(True)`][agents.set_tracing_disabled]。 -2. 设置用于追踪的 OpenAI 密钥：[`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]。此 API 密钥仅用于上传 traces，且必须来自 [platform.openai.com](https://platform.openai.com/)。 -3. 使用非 OpenAI trace 进程。请参阅[追踪文档](../tracing.md#custom-tracing-processors)。 +2. 为追踪设置 OpenAI key：[`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]。此 API key 仅用于上传 traces，并且必须来自 [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`，此方法可用。 -2. 使用 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]。[此处](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)有示例。 +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 支持 -某些模型提供方不支持 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)。这有时会导致类似如下的错误： +一些模型提供方不支持 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)。这有时会导致类似如下错误： ``` @@ -481,34 +481,34 @@ 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` 发送给无法理解它们的提供方 - 在调用仅支持文本的模型之前，过滤掉多模态输入 - 请注意，不支持结构化 JSON 输出的提供方偶尔会生成无效 JSON。 ## 第三方适配器 -只有当 SDK 的内置提供方集成点不足时，才考虑使用第三方适配器。如果你仅通过此 SDK 使用 OpenAI 模型，请优先使用内置 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 路径，而不是 Any-LLM 或 LiteLLM。第三方适配器适用于你需要将 OpenAI 模型与非 OpenAI 提供方结合，或需要适配器管理的提供方覆盖范围或内置路径不提供的路由的情况。适配器会在 SDK 和上游模型提供方之间增加另一层兼容性，因此功能支持和请求语义可能因提供方而异。SDK 目前包含 Any-LLM 和 LiteLLM，作为尽力而为的 beta 适配器集成。 +仅当 SDK 的内置提供方集成点不足时，才使用第三方适配器。如果你仅使用此 SDK 的 OpenAI 模型，请优先使用内置 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 路径，而不是 Any-LLM 或 LiteLLM。第三方适配器适用于你需要将 OpenAI 模型与非 OpenAI 提供方结合使用，或需要由适配器管理的提供方覆盖范围或路由，而内置路径无法提供的情况。适配器会在 SDK 与上游模型提供方之间增加另一层兼容层，因此功能支持和请求语义可能因提供方而异。SDK 目前包含 Any-LLM 和 LiteLLM，作为尽力而为的 beta 适配器集成。 ### Any-LLM -Any-LLM 支持以尽力而为的 beta 形式提供，适用于你需要由 Any-LLM 管理的提供方覆盖范围或路由的情况。 +Any-LLM 支持以尽力而为的 beta 形式包含在内，适用于你需要由 Any-LLM 管理的提供方覆盖范围或路由的情况。 -根据上游提供方路径，Any-LLM 可能使用 Responses API、Chat Completions 兼容 API 或提供方特定的兼容层。 +根据上游提供方路径，Any-LLM 可能使用 Responses API、Chat Completions 兼容 API，或提供方特定的兼容层。 -如果你需要 Any-LLM，请安装 `openai-agents[any-llm]`，然后从 [`examples/model_providers/any_llm_auto.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/any_llm_auto.py) 或 [`examples/model_providers/any_llm_provider.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/any_llm_provider.py) 开始。你可以将 `any-llm/...` 模型名称与 [`MultiProvider`][agents.MultiProvider] 一起使用，直接实例化 `AnyLLMModel`，或在运行范围使用 `AnyLLMProvider`。如果需要显式固定模型表面，请在构造 `AnyLLMModel` 时传入 `api="responses"` 或 `api="chat_completions"`。 +如果你需要 Any-LLM，请安装 `openai-agents[any-llm]`，然后从 [`examples/model_providers/any_llm_auto.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/any_llm_auto.py) 或 [`examples/model_providers/any_llm_provider.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/any_llm_provider.py) 开始。你可以将 `any-llm/...` 模型名称与 [`MultiProvider`][agents.MultiProvider] 一起使用，直接实例化 `AnyLLMModel`，或在运行范围使用 `AnyLLMProvider`。如果你需要显式固定模型界面，请在构造 `AnyLLMModel` 时传入 `api="responses"` 或 `api="chat_completions"`。 -Any-LLM 仍是第三方适配器层，因此提供方依赖项和能力缺口由上游 Any-LLM 而不是 SDK 定义。当上游提供方返回使用指标时，使用指标会自动传播，但流式 Chat Completions 后端可能需要 `ModelSettings(include_usage=True)` 才会发出使用量块。如果你依赖 structured outputs、工具调用、使用量报告或 Responses 特定行为，请验证你计划部署的确切提供方后端。 +Any-LLM 仍是第三方适配器层，因此提供方依赖和能力差距由上游 Any-LLM 而不是 SDK 定义。当上游提供方返回使用情况指标时，它们会自动传播，但流式 Chat Completions 后端可能需要 `ModelSettings(include_usage=True)` 才会发出使用情况块。如果你依赖 structured outputs、工具调用、使用情况报告或 Responses 特定行为，请验证你计划部署的确切提供方后端。 ### LiteLLM -LiteLLM 支持以尽力而为的 beta 形式提供，适用于你需要 LiteLLM 特定提供方覆盖范围或路由的情况。 +LiteLLM 支持以尽力而为的 beta 形式包含在内，适用于你需要 LiteLLM 特定的提供方覆盖范围或路由的情况。 如果你需要 LiteLLM，请安装 `openai-agents[litellm]`，然后从 [`examples/model_providers/litellm_auto.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/litellm_auto.py) 或 [`examples/model_providers/litellm_provider.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/litellm_provider.py) 开始。你可以使用 `litellm/...` 模型名称，或直接实例化 [`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel]。 -某些由 LiteLLM 支持的提供方默认不会填充 SDK 使用指标。如果你需要使用量报告，请传入 `ModelSettings(include_usage=True)`，并在依赖 structured outputs、工具调用、使用量报告或适配器特定路由行为时，验证你计划部署的确切提供方后端。 \ No newline at end of file +一些 LiteLLM 支持的提供方默认不会填充 SDK 使用情况指标。如果你需要使用情况报告，请传入 `ModelSettings(include_usage=True)`，并且如果你依赖 structured outputs、工具调用、使用情况报告或适配器特定路由行为，请验证你计划部署的确切提供方后端。 \ No newline at end of file