diff --git a/docs/ja/models/index.md b/docs/ja/models/index.md index ffcd13373f..f221dbd95c 100644 --- a/docs/ja/models/index.md +++ b/docs/ja/models/index.md @@ -4,39 +4,42 @@ 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] +- **推奨**: [`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 を呼び出します。 ## モデル設定の選択 -設定に応じて、このページを次の順序で参照してください。 +ご利用の構成に合う最もシンプルな経路から始めてください。 -| Goal | Start here | -| --- | --- | -| SDK デフォルトで OpenAI ホストモデルを使う | [ OpenAI モデル ](#openai-models) | -| websocket トランスポート経由で OpenAI Responses API を使う | [ Responses WebSocket トランスポート ](#responses-websocket-transport) | -| 非 OpenAI プロバイダーを使う | [ 非 OpenAI モデル ](#non-openai-models) | -| 1 つのワークフローでモデル / プロバイダーを混在させる | [ 高度なモデル選択と混在 ](#advanced-model-selection-and-mixing) および [ プロバイダー間でのモデル混在 ](#mixing-models-across-providers) | -| プロバイダー互換性の問題をデバッグする | [ 非 OpenAI プロバイダーのトラブルシューティング ](#troubleshooting-non-openai-providers) | +| 目的 | 推奨経路 | 詳細 | +| --- | --- | --- | +| OpenAI モデルのみを使う | デフォルトの OpenAI provider と Responses モデル経路を使う | [OpenAI モデル](#openai-models) | +| websocket 転送で OpenAI Responses API を使う | Responses モデル経路を維持し、websocket 転送を有効化する | [Responses WebSocket 転送](#responses-websocket-transport) | +| 1 つの non-OpenAI provider を使う | 組み込みの provider 統合ポイントから始める | [non-OpenAI モデル](#non-openai-models) | +| エージェント間でモデルや provider を混在させる | 実行単位またはエージェント単位で provider を選び、機能差を確認する | [1 つのワークフロー内でのモデル混在](#mixing-models-in-one-workflow) および [provider 間でのモデル混在](#mixing-models-across-providers) | +| OpenAI Responses の高度なリクエスト設定を調整する | OpenAI Responses 経路で `ModelSettings` を使う | [高度な OpenAI Responses 設定](#advanced-openai-responses-settings) | +| non-OpenAI Chat Completions provider に LiteLLM を使う | LiteLLM を beta のフォールバックとして扱う | [LiteLLM](#litellm) | ## OpenAI モデル -`Agent` の初期化時にモデルを指定しない場合、デフォルトモデルが使われます。現在のデフォルトは、互換性と低レイテンシのために [`gpt-4.1`](https://developers.openai.com/api/docs/models/gpt-4.1) です。アクセス可能であれば、明示的な `model_settings` を維持しつつ、より高品質な [`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4) をエージェントに設定することを推奨します。 +ほとんどの OpenAI 専用アプリでは、デフォルトの OpenAI provider と文字列のモデル名を使い、Responses モデル経路を維持する方法を推奨します。 -[`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4) のような他のモデルに切り替えたい場合、エージェントを設定する方法は 2 つあります。 +`Agent` 初期化時にモデルを指定しない場合は、デフォルトモデルが使われます。現在のデフォルトは互換性と低遅延のため [`gpt-4.1`](https://developers.openai.com/api/docs/models/gpt-4.1) です。利用可能であれば、明示的な `model_settings` を維持しつつ、より高品質な [`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4) をエージェントに設定することを推奨します。 + +[`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4) のような他モデルに切り替えるには、エージェントを設定する方法が 2 つあります。 ### デフォルトモデル -まず、カスタムモデルを設定していないすべてのエージェントで一貫して特定モデルを使いたい場合は、エージェント実行前に `OPENAI_DEFAULT_MODEL` 環境変数を設定します。 +まず、カスタムモデルを設定しないすべてのエージェントで特定モデルを一貫して使いたい場合は、エージェント実行前に `OPENAI_DEFAULT_MODEL` 環境変数を設定します。 ```bash export OPENAI_DEFAULT_MODEL=gpt-5.4 python3 my_awesome_agent.py ``` -次に、`RunConfig` 経由で実行ごとのデフォルトモデルを設定できます。エージェントにモデルを設定しない場合、この実行のモデルが使われます。 +次に、`RunConfig` で実行ごとのデフォルトモデルを設定できます。エージェントにモデルを設定しなければ、この実行のモデルが使われます。 ```python from agents import Agent, RunConfig, Runner @@ -55,7 +58,7 @@ result = await Runner.run( #### GPT-5 モデル -この方法で [`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4) などの GPT-5 モデルを使う場合、 SDK はデフォルトの `ModelSettings` を適用します。これは多くのユースケースで最適に動作する設定です。デフォルトモデルの推論 effort を調整するには、独自の `ModelSettings` を渡してください。 +この方法で [`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4) のような GPT-5 モデルを使う場合、SDK はデフォルトの `ModelSettings` を適用します。多くのユースケースで最適に動く設定が使われます。デフォルトモデルの推論 effort を調整するには、独自の `ModelSettings` を渡します。 ```python from openai.types.shared import Reasoning @@ -71,35 +74,37 @@ my_agent = Agent( ) ``` -より低レイテンシにするには、`gpt-5.4` で `reasoning.effort="none"` を使うことを推奨します。 gpt-4.1 ファミリー（ mini / nano バリアントを含む）も、インタラクティブなエージェントアプリ構築の有力な選択肢です。 +低遅延のためには、`gpt-5.4` で `reasoning.effort="none"` を使うことを推奨します。gpt-4.1 ファミリー（ mini / nano を含む）も、対話型エージェントアプリ構築において有力な選択肢です。 -#### ComputerTool のモデル選択 +#### ComputerTool モデル選択 -エージェントに [`ComputerTool`][agents.tool.ComputerTool] が含まれる場合、実際の Responses リクエストで有効なモデルによって、 SDK が送信するコンピュータツール payload が決まります。明示的な `gpt-5.4` リクエストでは GA の組み込み `computer` ツールを使い、明示的な `computer-use-preview` リクエストでは従来の `computer_use_preview` payload を維持します。 +エージェントに [`ComputerTool`][agents.tool.ComputerTool] が含まれる場合、実際の Responses リクエストで有効なモデルによって、SDK が送信する computer-tool ペイロードが決まります。明示的な `gpt-5.4` リクエストでは GA の組み込み `computer` ツールを使い、明示的な `computer-use-preview` リクエストでは従来の `computer_use_preview` ペイロードを維持します。 -主な例外は prompt 管理呼び出しです。 prompt template がモデルを保持し、 SDK がリクエストから `model` を省略する場合、 SDK は prompt がどのモデルに固定されているかを推測しないよう、 preview 互換のコンピュータ payload をデフォルトで使います。このフローで GA パスを維持するには、リクエストで `model="gpt-5.4"` を明示するか、`ModelSettings(tool_choice="computer")` または `ModelSettings(tool_choice="computer_use")` で GA セレクターを強制します。 +主な例外は prompt 管理型呼び出しです。prompt テンプレートがモデルを所有し、SDK がリクエストから `model` を省略する場合、SDK は prompt がどのモデルに固定されているかを推測しないため、preview 互換の computer ペイロードをデフォルトで使います。このフローで GA 経路を維持するには、リクエストで `model="gpt-5.4"` を明示するか、`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] factory を使う prompt 管理フローでは、具体的な `Computer` または `AsyncComputer` インスタンスを渡すか、リクエスト送信前に GA セレクターを強制してください。移行の詳細は [ Tools ](../tools.md#computertool-and-the-responses-computer-tool) を参照してください。 +preview 互換リクエストでは `environment` と表示寸法を先にシリアライズする必要があるため、[`ComputerProvider`][agents.tool.ComputerProvider] ファクトリーを使う prompt 管理フローでは、具体的な `Computer` または `AsyncComputer` インスタンスを渡すか、リクエスト送信前に GA セレクターを強制する必要があります。移行の詳細は [Tools](../tools.md#computertool-and-the-responses-computer-tool) を参照してください。 -#### 非 GPT-5 モデル +#### non-GPT-5 モデル -カスタム `model_settings` なしで非 GPT-5 モデル名を渡すと、 SDK はどのモデルとも互換な汎用 `ModelSettings` に戻ります。 +カスタム `model_settings` なしで non–GPT-5 モデル名を渡すと、SDK は任意モデル互換の汎用 `ModelSettings` に戻ります。 -### Responses 専用のツール検索機能 +### 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 モデルおよび non-Responses バックエンドでは拒否されます。遅延読み込みツールを使う場合は、エージェントに `ToolSearchTool()` を追加し、素の namespace 名や遅延専用関数名を強制する代わりに、`auto` または `required` の tool choice でモデルにツールを読み込ませてください。設定詳細と現時点の制約は [Tools](../tools.md#hosted-tool-search) を参照してください。 -これらの機能は Chat Completions モデルと、非 Responses バックエンドでは拒否されます。遅延読み込みツールを使う場合は、`ToolSearchTool()` をエージェントに追加し、素の namespace 名や遅延専用関数名を強制する代わりに、`auto` または `required` の tool choice でモデルにツールを読み込ませてください。設定詳細と現在の制約は [ Tools ](../tools.md#hosted-tool-search) を参照してください。 +### Responses WebSocket 転送 -### Responses WebSocket トランスポート +デフォルトでは、OpenAI Responses API リクエストは HTTP 転送を使います。OpenAI バックエンドのモデル使用時には websocket 転送を有効化できます。 -デフォルトでは、 OpenAI Responses API リクエストは HTTP トランスポートを使います。 OpenAI バックドモデルを使う場合、 websocket トランスポートを有効化できます。 +#### 基本設定 ```python from agents import set_default_openai_responses_transport @@ -107,11 +112,13 @@ from agents import set_default_openai_responses_transport set_default_openai_responses_transport("websocket") ``` -これは、デフォルト OpenAI プロバイダーで解決される OpenAI Responses モデル（`"gpt-5.4"` のような文字列モデル名を含む）に影響します。 +これは、デフォルト OpenAI provider で解決される OpenAI Responses モデル（ `"gpt-5.4"` のような文字列モデル名を含む）に影響します。 -トランスポートの選択は、 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=...)` を渡す場合は、グローバルデフォルトではなくその provider が転送選択を制御します。 -プロバイダーごと / 実行ごとに websocket トランスポートを設定することもできます。 +#### provider / 実行レベル設定 + +websocket 転送は provider 単位または実行単位でも設定できます。 ```python from agents import Agent, OpenAIProvider, RunConfig, Runner @@ -130,14 +137,16 @@ result = await Runner.run( ) ``` -プレフィックスベースのモデルルーティングが必要な場合（例: 1 回の実行で `openai/...` と `litellm/...` を混在）、代わりに [`MultiProvider`][agents.MultiProvider] を使い、そこで `openai_use_responses_websocket=True` を設定してください。 +#### `MultiProvider` による高度なルーティング + +接頭辞ベースのモデルルーティングが必要な場合（例: 1 回の実行で `openai/...` と `litellm/...` のモデル名を混在させる）、[`MultiProvider`][agents.MultiProvider] を使い、そこで `openai_use_responses_websocket=True` を設定してください。 -`MultiProvider` は、過去からの 2 つのデフォルトを維持します。 +`MultiProvider` は 2 つの従来デフォルトを維持しています。 -- `openai/...` は OpenAI プロバイダーのエイリアスとして扱われるため、`openai/gpt-4.1` はモデル `gpt-4.1` としてルーティングされます。 -- 未知のプレフィックスは透過渡しされず、`UserError` を送出します。 +- `openai/...` は OpenAI provider のエイリアスとして扱われるため、`openai/gpt-4.1` はモデル `gpt-4.1` としてルーティングされます。 +- 未知の接頭辞はそのまま渡されず、`UserError` を発生させます。 -OpenAI 互換エンドポイントが、名前空間付きモデル ID のリテラルを期待する場合は、明示的に pass-through 動作を有効化してください。 websocket 有効構成では、`MultiProvider` 側でも `openai_use_responses_websocket=True` を維持してください。 +OpenAI 互換エンドポイントで、名前空間付きモデル ID の文字列をそのまま期待する場合は、明示的に pass-through 動作を有効化してください。websocket 有効構成では、`MultiProvider` 側でも `openai_use_responses_websocket=True` を維持してください。 ```python from agents import Agent, MultiProvider, RunConfig, Runner @@ -163,56 +172,52 @@ 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] でも利用可能です。 -カスタム OpenAI 互換エンドポイントやプロキシを使う場合、 websocket トランスポートには互換の websocket `/responses` エンドポイントも必要です。その構成では `websocket_base_url` を明示設定する必要がある場合があります。 +カスタムの OpenAI 互換エンドポイントや proxy を使う場合、websocket 転送には互換 websocket `/responses` エンドポイントも必要です。このような構成では `websocket_base_url` の明示設定が必要になることがあります。 -注意事項: +#### 注記 -- これは 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 ](../running_agents.md) ガイドと [`examples/basic/stream_ws.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/stream_ws.py) を参照してください。 +- これは websocket 転送上の Responses API であり、[Realtime API](../realtime/guide.md) ではありません。Chat Completions や、Responses websocket `/responses` エンドポイントをサポートしない non-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](../running_agents.md) ガイドと [`examples/basic/stream_ws.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/stream_ws.py) を参照してください。 -## 非 OpenAI モデル +## non-OpenAI モデル -多くの非 OpenAI モデルは [ LiteLLM integration ](./litellm.md) で利用できます。まず litellm 依存グループをインストールします。 +non-OpenAI provider が必要な場合は、まず SDK の組み込み provider 統合ポイントから始めてください。多くの構成では LiteLLM 追加なしで十分です。各パターンの例は [examples/model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/) にあります。 -```bash -pip install "openai-agents[litellm]" -``` +### non-OpenAI provider 統合方法 -次に、`litellm/` プレフィックス付きで任意の [ 対応モデル ](https://docs.litellm.ai/docs/providers) を使います。 - -```python -claude_agent = Agent(model="litellm/anthropic/claude-3-5-sonnet-20240620", ...) -gemini_agent = Agent(model="litellm/gemini/gemini-2.5-flash-preview-04-17", ...) -``` - -### 非 OpenAI モデルを使う他の方法 +| アプローチ | 使用する場面 | スコープ | +| --- | --- | --- | +| [`set_default_openai_client`][agents.set_default_openai_client] | 1 つの OpenAI 互換エンドポイントを、ほとんどまたはすべてのエージェントのデフォルトにしたい | グローバルデフォルト | +| [`ModelProvider`][agents.models.interface.ModelProvider] | 1 つのカスタム provider を単一実行に適用したい | 実行単位 | +| [`Agent.model`][agents.agent.Agent.model] | エージェントごとに異なる provider または具体的モデルオブジェクトが必要 | エージェント単位 | +| LiteLLM (beta) | LiteLLM 固有の provider カバレッジやルーティングが必要 | [LiteLLM](#litellm) を参照 | -他の LLM プロバイダーを統合する方法はさらに 3 つあります（コード例は [ こちら ](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)）。 +これらの組み込み経路で他の LLM provider を統合できます。 -1. [`set_default_openai_client`][agents.set_default_openai_client] は、`AsyncOpenAI` インスタンスを LLM クライアントとしてグローバルに使いたい場合に有用です。これは LLM プロバイダーが OpenAI 互換 API エンドポイントを持ち、`base_url` と `api_key` を設定できる場合に適しています。設定可能なコード例は [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py) を参照してください。 -2. [`ModelProvider`][agents.models.interface.ModelProvider] は `Runner.run` レベルです。これにより「この実行のすべてのエージェントでカスタムモデルプロバイダーを使う」と指定できます。設定可能なコード例は [examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py) を参照してください。 -3. [`Agent.model`][agents.agent.Agent.model] では特定の Agent インスタンスにモデルを指定できます。これにより、エージェントごとに異なるプロバイダーを混在できます。設定可能なコード例は [examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py) を参照してください。利用可能な多くのモデルを簡単に使う方法として、[ LiteLLM integration ](./litellm.md) があります。 +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` レベルです。これにより「この実行の全エージェントでカスタム model 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 key を持っていない場合は、`set_tracing_disabled()` でトレーシングを無効化するか、[ 別のトレーシングプロセッサー ](../tracing.md) を設定することを推奨します。 +`platform.openai.com` の API key がない場合は、`set_tracing_disabled()` でトレーシングを無効化するか、[別のトレーシングプロセッサー](../tracing.md) を設定することを推奨します。 !!! note - これらのコード例では、ほとんどの LLM プロバイダーがまだ Responses API をサポートしていないため、 Chat Completions API / model を使っています。 LLM プロバイダーが対応している場合は Responses の利用を推奨します。 + これらの例では、Chat Completions API / model を使っています。多くの LLM provider がまだ Responses API をサポートしていないためです。LLM provider が対応している場合は Responses の利用を推奨します。 -## 高度なモデル選択と混在 +## 1 つのワークフロー内でのモデル混在 -単一ワークフロー内で、エージェントごとに異なるモデルを使いたい場合があります。たとえば、トリアージには小型で高速なモデルを使い、複雑なタスクには大型で高性能なモデルを使えます。[`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 +!!! 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 @@ -248,7 +253,7 @@ async def main(): 1. OpenAI モデル名を直接設定します。 2. [`Model`][agents.models.interface.Model] 実装を提供します。 -エージェントで使うモデルをさらに設定したい場合は [`ModelSettings`][agents.models.interface.ModelSettings] を渡せます。これにより temperature などの任意のモデル設定パラメーターを指定できます。 +エージェントで使うモデルをさらに設定したい場合は、temperature などの任意モデル設定パラメーターを提供する [`ModelSettings`][agents.models.interface.ModelSettings] を渡せます。 ```python from agents import Agent, ModelSettings @@ -261,19 +266,21 @@ english_agent = Agent( ) ``` -#### 一般的な高度 `ModelSettings` オプション +## 高度な OpenAI Responses 設定 -OpenAI Responses API を使う場合、いくつかのリクエストフィールドにはすでに `ModelSettings` の直接フィールドがあるため、それらに `extra_args` は不要です。 +OpenAI Responses 経路でより細かな制御が必要な場合は、`ModelSettings` から始めてください。 -| Field | Use it for | -| --- | --- | -| `parallel_tool_calls` | 同一ターンでの複数ツール呼び出しを許可 / 禁止します。 | -| `truncation` | コンテキストが溢れる際に失敗する代わりに、 Responses API が最も古い会話項目を破棄できるよう `"auto"` を設定します。 | -| `store` | 生成レスポンスを後で取得できるようサーバー側に保存するかを制御します。これは response ID に依存するフォローアップワークフローや、`store=False` のときにローカル入力へフォールバックが必要なセッション compact 化フローで重要です。 | -| `prompt_cache_retention` | たとえば `"24h"` で、キャッシュされた prompt 接頭辞をより長く保持します。 | -| `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) を参照してください。 | +### 一般的な高度 `ModelSettings` オプション + +OpenAI Responses API 利用時は、いくつかのリクエストフィールドに直接対応する `ModelSettings` フィールドがすでにあるため、それらに `extra_args` は不要です。 + +- `parallel_tool_calls`: 同一ターンでの複数 tool call を許可 / 禁止します。 +- `truncation`: `"auto"` を設定すると、コンテキスト超過時に失敗せず、Responses API が最も古い会話項目を削除します。 +- `store`: 生成レスポンスを後続取得のためサーバー側に保存するかを制御します。レスポンス ID に依存するフォローアップワークフローや、`store=False` 時にローカル入力へフォールバックが必要なセッション圧縮フローで重要です。 +- `prompt_cache_retention`: たとえば `"24h"` のように、キャッシュされた prompt 接頭辞をより長く保持します。 +- `response_include`: `web_search_call.action.sources`、`file_search_call.results`、`reasoning.encrypted_content` など、より豊富なレスポンスペイロードを要求します。 +- `top_logprobs`: 出力テキストの上位 token logprobs を要求します。SDK は `message.output_text.logprobs` も自動追加します。 +- `retry`: モデル呼び出しに対する runner 管理 retry 設定を有効化します。[Runner 管理リトライ](#runner-managed-retries) を参照してください。 ```python from agents import Agent, ModelSettings @@ -292,11 +299,31 @@ research_agent = Agent( ) ``` -`store=False` を設定すると、 Responses API はそのレスポンスを後でサーバー側取得できる状態に保持しません。これは stateless または zero-data-retention 形式のフローで有用ですが、通常 response ID を再利用する機能は代わりにローカル管理状態へ依存する必要があります。たとえば [`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession] は、最後のレスポンスが保存されていない場合、デフォルト `"auto"` compact 化パスを input ベース compact 化へ切り替えます。[ 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"` 圧縮経路を入力ベース圧縮へ切り替えます。[Sessions ガイド](../sessions/index.md#openai-responses-compaction-sessions) を参照してください。 + +### `extra_args` の受け渡し + +SDK がまだトップレベルで直接公開していない provider 固有または新しいリクエストフィールドが必要な場合は `extra_args` を使います。 + +また OpenAI の Responses API を使う場合、[他にもいくつかの任意パラメーター](https://platform.openai.com/docs/api-reference/responses/create)（例: `user`、`service_tier` など）があります。トップレベルにない場合は、`extra_args` で渡せます。 + +```python +from agents import Agent, ModelSettings + +english_agent = Agent( + name="English agent", + instructions="You only speak English", + model="gpt-4.1", + model_settings=ModelSettings( + temperature=0.1, + extra_args={"service_tier": "flex", "user": "user_12345"}, + ), +) +``` -#### Runner 管理リトライ +## Runner 管理リトライ -リトライは実行時専用で opt-in です。`ModelSettings(retry=...)` を設定し、かつリトライポリシーがリトライを選択しない限り、 SDK は一般的なモデルリクエストをリトライしません。 +リトライは実行時限定で、明示的な opt-in です。`ModelSettings(retry=...)` を設定し、かつ retry policy が再試行を選択しない限り、SDK は一般的なモデルリクエストをリトライしません。 ```python from agents import Agent, ModelRetrySettings, ModelSettings, retry_policies @@ -326,97 +353,83 @@ agent = Agent( `ModelRetrySettings` には 3 つのフィールドがあります。 -| Field | Type | Notes | +
+ +| フィールド | 型 | 注記 | | --- | --- | --- | -| `max_retries` | `int \| None` | 初回リクエスト後に許可されるリトライ試行回数。 | -| `backoff` | `ModelRetryBackoffSettings \| dict \| None` | ポリシーが明示的遅延を返さずにリトライする場合のデフォルト遅延戦略。 | -| `policy` | `RetryPolicy \| None` | リトライ可否を決定するコールバック。このフィールドは実行時専用でシリアライズされません。 | +| `max_retries` | `int | None` | 初回リクエスト後に許可される再試行回数です。 | +| `backoff` | `ModelRetryBackoffSettings | dict | None` | policy が明示的 delay を返さずに再試行するときのデフォルト遅延戦略です。 | +| `policy` | `RetryPolicy | None` | 再試行するかを決めるコールバックです。このフィールドは実行時限定でシリアライズされません。 | -リトライポリシーは [`RetryPolicyContext`][agents.retry.RetryPolicyContext] を受け取ります。内容は次の通りです。 +
-- `attempt` と `max_retries`（試行回数に応じた判断のため） -- `stream`（ストリーミング / 非ストリーミングで分岐するため） -- `error`（raw 検査用） -- `normalized` 情報（`status_code`、`retry_after`、`error_code`、`is_network_error`、`is_timeout`、`is_abort`） -- 基盤モデル adapter がリトライ指針を提供できる場合の `provider_advice` +retry policy は [`RetryPolicyContext`][agents.retry.RetryPolicyContext] を受け取ります。内容は以下です。 -ポリシーは次のいずれかを返せます。 +- `attempt` と `max_retries`（試行回数に応じた判断に使用）。 +- `stream`（streamed / non-streamed で分岐可能）。 +- `error`（raw 検査用）。 +- `status_code`、`retry_after`、`error_code`、`is_network_error`、`is_timeout`、`is_abort` などの `normalized` 情報。 +- 下位モデルアダプターが retry ガイダンスを提供できる場合の `provider_advice`。 -- 単純なリトライ判断としての `True` / `False` -- 遅延上書きや診断理由付与をしたい場合の [`RetryDecision`][agents.retry.RetryDecision] +policy は次のいずれかを返せます。 + +- 単純な再試行判定としての `True` / `False`。 +- delay 上書きや診断理由付与を行いたい場合の [`RetryDecision`][agents.retry.RetryDecision]。 SDK は `retry_policies` に既製ヘルパーを提供しています。 -| Helper | Behavior | +| ヘルパー | 振る舞い | | --- | --- | -| `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.never()` | 常に opt-out します。 | +| `retry_policies.provider_suggested()` | 利用可能な場合、provider の retry 推奨に従います。 | +| `retry_policies.network_error()` | 一時的な転送 / timeout 障害に一致します。 | +| `retry_policies.http_status([...])` | 選択した HTTP status code に一致します。 | +| `retry_policies.retry_after()` | retry-after ヒントがある場合のみ、その delay で再試行します。 | +| `retry_policies.any(...)` | ネスト policy のいずれかが opt-in したとき再試行します。 | +| `retry_policies.all(...)` | ネスト policy のすべてが opt-in したときのみ再試行します。 | -ポリシーを合成する際、`provider_suggested()` は最も安全な最初の構成要素です。これは、プロバイダーが区別可能な場合に veto と replay-safety 承認を保持するためです。 +policy を組み合わせる場合、`provider_suggested()` は最も安全な最初の構成要素です。provider が判別可能な場合、provider veto と replay-safety 承認を保持できるためです。 -##### 安全性境界 +##### 安全境界 -次の障害は自動リトライされません。 +次の障害は自動再試行されません。 - Abort エラー。 -- プロバイダー指針が replay を unsafe と示すリクエスト。 -- 出力開始後で replay が unsafe になるストリーミング実行。 - -`previous_response_id` や `conversation_id` を使う stateful なフォローアップリクエストも、より保守的に扱われます。これらでは `network_error()` や `http_status([500])` のような非プロバイダー述語だけでは不十分です。通常、`retry_policies.provider_suggested()` を通じた provider 側 replay-safe 承認をリトライポリシーに含める必要があります。 +- provider アドバイスが replay unsafe と判定したリクエスト。 +- 出力がすでに始まっており replay が unsafe になる streamed 実行。 -##### Runner と agent のマージ動作 +`previous_response_id` または `conversation_id` を使う状態付きフォローアップリクエストも、より保守的に扱われます。これらのリクエストでは `network_error()` や `http_status([500])` のような非 provider 判定だけでは不十分です。retry policy には通常 `retry_policies.provider_suggested()` を通じた provider の replay-safe 承認を含める必要があります。 -`retry` は runner レベルと agent レベルの `ModelSettings` 間で deep-merge されます。 +##### Runner とエージェントのマージ挙動 -- agent は `retry.max_retries` のみ上書きし、runner の `policy` を継承できます。 -- agent は `retry.backoff` の一部のみ上書きし、backoff の兄弟フィールドを runner から維持できます。 -- `policy` は実行時専用のため、シリアライズされた `ModelSettings` には `max_retries` と `backoff` は残り、コールバック自体は含まれません。 +`retry` は runner レベルとエージェントレベルの `ModelSettings` 間で deep-merge されます。 -より完全なコード例は [`examples/basic/retry.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry.py) と [`examples/basic/retry_litellm.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry_litellm.py) を参照してください。 +- エージェントは `retry.max_retries` のみを上書きしつつ、runner の `policy` を継承できます。 +- エージェントは `retry.backoff` の一部のみを上書きし、他の backoff フィールドは runner から維持できます。 +- `policy` は実行時限定のため、シリアライズされた `ModelSettings` は `max_retries` と `backoff` を保持し、コールバック自体は省略します。 -SDK がまだトップレベルで直接公開していないプロバイダー固有または新しいリクエストフィールドが必要な場合は `extra_args` を使ってください。 +より完全な例は [`examples/basic/retry.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry.py) と [`examples/basic/retry_litellm.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry_litellm.py) を参照してください。 -また OpenAI の Responses API を使う場合、[ ほかにもいくつか任意パラメーター ](https://platform.openai.com/docs/api-reference/responses/create)（例: `user`、`service_tier` など）があります。トップレベルで利用できない場合は、同様に `extra_args` で渡せます。 - -```python -from agents import Agent, ModelSettings - -english_agent = Agent( - name="English agent", - instructions="You only speak English", - model="gpt-4.1", - model_settings=ModelSettings( - temperature=0.1, - extra_args={"service_tier": "flex", "user": "user_12345"}, - ), -) -``` - -## 非 OpenAI プロバイダーのトラブルシューティング +## non-OpenAI provider のトラブルシューティング ### トレーシングクライアントエラー 401 -トレーシング関連エラーが出る場合、トレースは OpenAI サーバーにアップロードされる一方で、 OpenAI API key がないことが原因です。解決方法は 3 つあります。 +トレーシング関連エラーが出る場合、トレースが OpenAI サーバーへアップロードされる一方で OpenAI API key がないことが原因です。解決方法は 3 つあります。 -1. トレーシングを完全に無効化する: [`set_tracing_disabled(True)`][agents.set_tracing_disabled] -2. トレーシング用 OpenAI key を設定する: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]。この API key はトレースアップロードのみに使われ、[platform.openai.com](https://platform.openai.com/) のものが必要です。 -3. 非 OpenAI トレースプロセッサーを使う。[ トレーシングドキュメント ](../tracing.md#custom-tracing-processors) を参照してください。 +1. トレーシングを完全に無効化する: [`set_tracing_disabled(True)`][agents.set_tracing_disabled]。 +2. トレーシング用 OpenAI key を設定する: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]。この API key はトレースアップロード専用で、[platform.openai.com](https://platform.openai.com/) 由来である必要があります。 +3. non-OpenAI トレースプロセッサーを使う。[tracing docs](../tracing.md#custom-tracing-processors) を参照してください。 ### Responses API サポート -SDK はデフォルトで Responses API を使いますが、他の多くの LLM プロバイダーはまだ未対応です。その結果、404 などの問題が発生する場合があります。解決方法は 2 つあります。 +SDK はデフォルトで Responses API を使いますが、多くの他 LLM provider はまだ対応していません。その結果 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/) にあります。 +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) をサポートしていません。これにより、ときどき次のようなエラーになります。 +一部の model provider は [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) をサポートしていません。これにより、次のようなエラーが出る場合があります。 ``` @@ -424,12 +437,24 @@ BadRequestError: Error code: 400 - {'error': {'message': "'response_format.type' ``` -これは一部モデルプロバイダー側の制限です。 JSON 出力はサポートしていても、出力に使う `json_schema` を指定できません。この問題の修正に取り組んでいますが、 JSON schema 出力をサポートするプロバイダーへの依存を推奨します。そうでない場合、不正な JSON によりアプリが頻繁に壊れるためです。 +これは一部 model provider 側の制約です。JSON 出力はサポートしていても、出力に使う `json_schema` の指定を許可しません。この問題の修正に取り組んでいますが、JSON schema 出力をサポートする provider の利用を推奨します。そうでない場合、アプリは不正な JSON によって頻繁に壊れる可能性があります。 + +## provider 間でのモデル混在 + +model provider 間の機能差を把握していないとエラーになる可能性があります。たとえば OpenAI は structured outputs、マルチモーダル入力、ホスト型ファイル検索と Web 検索をサポートしますが、多くの他 provider はこれらをサポートしません。次の制約に注意してください。 + +- 未対応 provider に、未対応の `tools` を送らない +- テキスト専用モデル呼び出し前に、マルチモーダル入力を除外する +- structured JSON 出力非対応 provider は、ときどき不正な JSON を生成する点に注意する + +## LiteLLM + +LiteLLM サポートは、non-OpenAI provider を Agents SDK ワークフローへ取り込む必要があるケース向けに、best-effort の beta として提供されています。 + +この SDK で OpenAI モデルを使う場合は、LiteLLM ではなく組み込みの [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 経路を推奨します。 -## プロバイダー間でのモデル混在 +OpenAI モデルと non-OpenAI provider を組み合わせる必要があり、とくに Chat Completions 互換 API 経由で使う場合、LiteLLM は beta オプションとして利用できますが、すべての構成で最適とは限りません。 -モデルプロバイダー間の機能差を理解しておく必要があります。そうしないとエラーになる可能性があります。たとえば OpenAI は structured outputs、マルチモーダル入力、ホスト型ファイル検索と Web 検索をサポートしますが、他の多くのプロバイダーはこれらに未対応です。次の制限に注意してください。 +non-OpenAI provider で 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] を直接インスタンス化できます。 -- 未対応プロバイダーに未対応の `tools` を送らない -- text-only モデルを呼び出す前にマルチモーダル入力を除外する -- structured JSON 出力をサポートしないプロバイダーは、ときどき無効な JSON を生成することを認識しておく \ No newline at end of file +LiteLLM のレスポンスで SDK の usage metrics を埋めたい場合は、`ModelSettings(include_usage=True)` を渡してください。 \ No newline at end of file diff --git a/docs/ja/models/litellm.md b/docs/ja/models/litellm.md index c2e992b381..ff56dcc7ae 100644 --- a/docs/ja/models/litellm.md +++ b/docs/ja/models/litellm.md @@ -2,103 +2,12 @@ search: exclude: true --- -# LiteLLM による任意モデルの使用 +# LiteLLM -!!! note + - LiteLLM 統合は ベータ です。特に小規模なモデルプロバイダーでは問題が発生する可能性があります。問題があれば [GitHub issues](https://github.com/openai/openai-agents-python/issues) からご報告ください。迅速に修正します。 +このページは [Models の LiteLLM セクション](index.md#litellm)に移動しました。 -[LiteLLM](https://docs.litellm.ai/docs/) は、単一のインターフェースで 100 以上のモデルを利用できるライブラリです。Agents SDK で任意の AI モデルを使えるようにするため、LiteLLM 統合を追加しました。 - -## セットアップ - -`litellm` を利用可能にする必要があります。オプションの `litellm` 依存関係グループをインストールしてください。 - -```bash -pip install "openai-agents[litellm]" -``` - -完了したら、任意の エージェント で [`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel] を使用できます。 - -## 例 - -これは完全に動作するサンプルです。実行するとモデル名と API キーの入力を求められます。例えば次のように入力できます。 - -- モデルに `openai/gpt-4.1`、OpenAI の API キー -- モデルに `anthropic/claude-3-5-sonnet-20240620`、Anthropic の API キー -- など - -LiteLLM でサポートされているモデルの一覧は、[プロバイダーのドキュメント](https://docs.litellm.ai/docs/providers)をご覧ください。 - -```python -from __future__ import annotations - -import asyncio - -from agents import Agent, Runner, function_tool, set_tracing_disabled -from agents.extensions.models.litellm_model import LitellmModel - -@function_tool -def get_weather(city: str): - print(f"[debug] getting weather for {city}") - return f"The weather in {city} is sunny." - - -async def main(model: str, api_key: str): - agent = Agent( - name="Assistant", - instructions="You only respond in haikus.", - model=LitellmModel(model=model, api_key=api_key), - tools=[get_weather], - ) - - result = await Runner.run(agent, "What's the weather in Tokyo?") - print(result.final_output) - - -if __name__ == "__main__": - # First try to get model/api key from args - import argparse - - parser = argparse.ArgumentParser() - parser.add_argument("--model", type=str, required=False) - parser.add_argument("--api-key", type=str, required=False) - args = parser.parse_args() - - model = args.model - if not model: - model = input("Enter a model name for Litellm: ") - - api_key = args.api_key - if not api_key: - api_key = input("Enter an API key for Litellm: ") - - asyncio.run(main(model, api_key)) -``` - -## 使用状況データの追跡 - -LiteLLM のレスポンスを Agents SDK の使用状況メトリクスに反映させたい場合は、エージェント作成時に `ModelSettings(include_usage=True)` を渡してください。 - -```python -from agents import Agent, ModelSettings -from agents.extensions.models.litellm_model import LitellmModel - -agent = Agent( - name="Assistant", - model=LitellmModel(model="your/model", api_key="..."), - model_settings=ModelSettings(include_usage=True), -) -``` - -`include_usage=True` の場合、LiteLLM のリクエストは、組み込みの OpenAI モデルと同様に、`result.context_wrapper.usage` を通じてトークン数およびリクエスト数をレポートします。 - -## トラブルシューティング - -LiteLLM のレスポンスで Pydantic シリアライザーの警告が表示される場合は、次を設定して小さな互換性パッチを有効にしてください。 - -```bash -export OPENAI_AGENTS_ENABLE_LITELLM_SERIALIZER_PATCH=true -``` - -このオプトインのフラグは、既知の LiteLLM シリアライザー警告を抑制しつつ通常の動作を維持します。不要な場合はオフにしてください（未設定または `false`）。 \ No newline at end of file +自動的にリダイレクトされない場合は、上記のリンクを使用してください。 \ No newline at end of file diff --git a/docs/ja/usage.md b/docs/ja/usage.md index 326b17cf54..1c1e1d5328 100644 --- a/docs/ja/usage.md +++ b/docs/ja/usage.md @@ -4,7 +4,7 @@ search: --- # 使用方法 -Agents SDK は、すべての実行におけるトークン使用量を自動的に追跡します。実行コンテキストからアクセスでき、コスト監視、制限の適用、分析記録に利用できます。 +Agents SDK は、実行ごとのトークン使用量を自動的に追跡します。実行コンテキストからアクセスでき、コスト監視、制限の適用、分析記録に利用できます。 ## 追跡対象 @@ -12,14 +12,14 @@ Agents SDK は、すべての実行におけるトークン使用量を自動的 - **input_tokens**: 送信された入力トークン総数 - **output_tokens**: 受信した出力トークン総数 - **total_tokens**: 入力 + 出力 -- **request_usage_entries**: リクエストごとの使用量内訳のリスト +- **request_usage_entries**: リクエストごとの使用量内訳の一覧 - **details**: - `input_tokens_details.cached_tokens` - `output_tokens_details.reasoning_tokens` -## 実行から使用量にアクセスする方法 +## 実行からの使用量へのアクセス -`Runner.run(...)` の後、`result.context_wrapper.usage` から使用量にアクセスします。 +`Runner.run(...)` の後、`result.context_wrapper.usage` で使用量にアクセスします。 ```python result = await Runner.run(agent, "What's the weather in Tokyo?") @@ -33,9 +33,9 @@ print("Total tokens:", usage.total_tokens) 使用量は、実行中のすべてのモデル呼び出し（ツール呼び出しとハンドオフを含む）で集計されます。 -### LiteLLM モデルで使用量を有効化する方法 +### LiteLLM モデルでの使用量の有効化 -LiteLLM プロバイダーは、デフォルトでは使用量メトリクスを報告しません。[`LitellmModel`](models/litellm.md) を使用している場合は、LiteLLM のレスポンスで `result.context_wrapper.usage` が埋まるように、エージェントに `ModelSettings(include_usage=True)` を渡してください。 +LiteLLM プロバイダーは、デフォルトでは使用量メトリクスを報告しません。[`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel] を使用している場合は、LiteLLM のレスポンスが `result.context_wrapper.usage` を埋めるよう、エージェントに `ModelSettings(include_usage=True)` を渡してください。設定手順とコード例については、Models ガイドの [LiteLLM note](models/index.md#litellm) を参照してください。 ```python from agents import Agent, ModelSettings, Runner @@ -53,7 +53,7 @@ print(result.context_wrapper.usage.total_tokens) ## リクエストごとの使用量追跡 -SDK は、`request_usage_entries` 内で各 API リクエストの使用量を自動的に追跡します。これは、詳細なコスト計算やコンテキストウィンドウ消費量の監視に役立ちます。 +SDK は、`request_usage_entries` 内の API リクエストごとの使用量を自動追跡します。これは詳細なコスト計算やコンテキストウィンドウ消費量の監視に有用です。 ```python result = await Runner.run(agent, "What's the weather in Tokyo?") @@ -62,9 +62,9 @@ for i, request in enumerate(result.context_wrapper.usage.request_usage_entries): print(f"Request {i + 1}: {request.input_tokens} in, {request.output_tokens} out") ``` -## セッションで使用量にアクセスする方法 +## セッションでの使用量へのアクセス -`Session`（例: `SQLiteSession`）を使用する場合、`Runner.run(...)` の各呼び出しは、その特定の実行に対する使用量を返します。セッションはコンテキスト用に会話履歴を維持しますが、各実行の使用量は独立しています。 +`Session`（例: `SQLiteSession`）を使用する場合、`Runner.run(...)` の各呼び出しはその特定の実行に対する使用量を返します。セッションは文脈のために会話履歴を維持しますが、各実行の使用量は独立しています。 ```python session = SQLiteSession("my_conversation") @@ -76,11 +76,11 @@ second = await Runner.run(agent, "Can you elaborate?", session=session) print(second.context_wrapper.usage.total_tokens) # Usage for second run ``` -セッションは実行間で会話コンテキストを保持しますが、各 `Runner.run()` 呼び出しで返される使用量メトリクスは、その特定の実行のみを表す点に注意してください。セッションでは、以前のメッセージが各実行の入力として再投入される場合があり、その結果、後続ターンの入力トークン数に影響します。 +セッションは実行間で会話コンテキストを保持しますが、各 `Runner.run()` 呼び出しで返される使用量メトリクスは、その特定の実行のみを表します。セッションでは、前のメッセージが各実行の入力として再投入される場合があり、その結果、後続ターンの入力トークン数に影響します。 -## フックで使用量を利用する方法 +## フックでの使用量の利用 -`RunHooks` を使用している場合、各フックに渡される `context` オブジェクトには `usage` が含まれます。これにより、ライフサイクルの重要なタイミングで使用量をログ記録できます。 +`RunHooks` を使用している場合、各フックに渡される `context` オブジェクトには `usage` が含まれます。これにより、ライフサイクルの重要なタイミングで使用量を記録できます。 ```python class MyHooks(RunHooks): @@ -91,9 +91,9 @@ class MyHooks(RunHooks): ## API リファレンス -詳細な API ドキュメントは以下を参照してください。 +詳細な API ドキュメントは次を参照してください。 - [`Usage`][agents.usage.Usage] - 使用量追跡データ構造 - [`RequestUsage`][agents.usage.RequestUsage] - リクエストごとの使用量詳細 - [`RunContextWrapper`][agents.run.RunContextWrapper] - 実行コンテキストから使用量にアクセス -- [`RunHooks`][agents.run.RunHooks] - 使用量追跡ライフサイクルにフックする \ No newline at end of file +- [`RunHooks`][agents.run.RunHooks] - 使用量追跡ライフサイクルへのフック \ No newline at end of file diff --git a/docs/ko/models/index.md b/docs/ko/models/index.md index 209379aef8..24013778b1 100644 --- a/docs/ko/models/index.md +++ b/docs/ko/models/index.md @@ -4,39 +4,42 @@ 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를 호출합니다 +- **권장**: 새 [Responses API](https://platform.openai.com/docs/api-reference/responses)를 사용해 OpenAI API 를 호출하는 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] +- [Chat Completions API](https://platform.openai.com/docs/api-reference/chat)를 사용해 OpenAI API 를 호출하는 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] ## 모델 설정 선택 -설정에 따라 이 페이지를 다음 순서로 사용하세요: +사용 환경에 맞는 가장 단순한 경로부터 시작하세요: -| 목표 | 시작 위치 | -| --- | --- | -| SDK 기본값으로 OpenAI 호스팅 모델 사용 | [OpenAI 모델](#openai-models) | -| websocket 전송으로 OpenAI Responses API 사용 | [Responses WebSocket 전송](#responses-websocket-transport) | -| OpenAI 이외 제공자 사용 | [OpenAI 이외 모델](#non-openai-models) | -| 하나의 워크플로우에서 모델/제공자 혼합 | [고급 모델 선택 및 혼합](#advanced-model-selection-and-mixing) 및 [제공자 간 모델 혼합](#mixing-models-across-providers) | -| 제공자 호환성 문제 디버깅 | [OpenAI 이외 제공자 문제 해결](#troubleshooting-non-openai-providers) | +| 다음을 하려는 경우 | 권장 경로 | 자세히 보기 | +| --- | --- | --- | +| OpenAI 모델만 사용 | 기본 OpenAI provider 와 Responses 모델 경로 사용 | [OpenAI 모델](#openai-models) | +| websocket 전송으로 OpenAI Responses API 사용 | Responses 모델 경로를 유지하고 websocket 전송 활성화 | [Responses WebSocket 전송](#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 가 아닌 Chat Completions provider 에 LiteLLM 사용 | LiteLLM 을 베타 대체 옵션으로 사용 | [LiteLLM](#litellm) | ## OpenAI 모델 -`Agent`를 초기화할 때 모델을 지정하지 않으면 기본 모델이 사용됩니다. 현재 기본값은 호환성과 낮은 지연 시간을 위해 [`gpt-4.1`](https://developers.openai.com/api/docs/models/gpt-4.1)입니다. 접근 권한이 있다면, 명시적인 `model_settings`를 유지하면서 더 높은 품질을 위해 에이전트를 [`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4)로 설정하는 것을 권장합니다. +대부분의 OpenAI 전용 앱에서는 기본 OpenAI provider 와 문자열 모델 이름을 사용하고, Responses 모델 경로를 유지하는 것을 권장합니다. -[`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4) 같은 다른 모델로 전환하려면, 에이전트를 구성하는 방법은 두 가지입니다. +`Agent` 를 초기화할 때 모델을 지정하지 않으면 기본 모델이 사용됩니다. 현재 기본값은 호환성과 낮은 지연 시간을 위해 [`gpt-4.1`](https://developers.openai.com/api/docs/models/gpt-4.1)입니다. 접근 권한이 있다면, 명시적인 `model_settings` 를 유지하면서 더 높은 품질을 위해 에이전트를 [`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4)로 설정하는 것을 권장합니다. + +[`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4) 같은 다른 모델로 전환하려면 에이전트를 구성하는 방법이 두 가지 있습니다. ### 기본 모델 -첫째, 사용자 지정 모델을 설정하지 않은 모든 에이전트에서 특정 모델을 일관되게 사용하려면, 에이전트 실행 전에 `OPENAI_DEFAULT_MODEL` 환경 변수를 설정하세요. +첫째, 사용자 지정 모델을 설정하지 않은 모든 에이전트에서 특정 모델을 일관되게 사용하려면, 에이전트를 실행하기 전에 `OPENAI_DEFAULT_MODEL` 환경 변수를 설정하세요. ```bash export OPENAI_DEFAULT_MODEL=gpt-5.4 python3 my_awesome_agent.py ``` -둘째, `RunConfig`를 통해 실행 단위 기본 모델을 설정할 수 있습니다. 에이전트에 모델을 설정하지 않으면 이 실행의 모델이 사용됩니다. +둘째, `RunConfig` 를 통해 실행 단위 기본 모델을 설정할 수 있습니다. 에이전트에 모델을 설정하지 않으면 이 실행의 모델이 사용됩니다. ```python from agents import Agent, RunConfig, Runner @@ -55,7 +58,7 @@ result = await Runner.run( #### GPT-5 모델 -이 방식으로 [`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4) 같은 GPT-5 모델을 사용하면, SDK가 기본 `ModelSettings`를 적용합니다. 대부분의 사용 사례에서 가장 잘 동작하는 값으로 설정됩니다. 기본 모델의 추론 강도를 조정하려면 사용자 지정 `ModelSettings`를 전달하세요: +이 방식으로 [`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4) 같은 GPT-5 모델을 사용하면 SDK 가 기본 `ModelSettings` 를 적용합니다. 대부분의 사용 사례에서 가장 잘 작동하는 값을 설정합니다. 기본 모델의 reasoning effort 를 조정하려면 자체 `ModelSettings` 를 전달하세요: ```python from openai.types.shared import Reasoning @@ -71,21 +74,21 @@ my_agent = Agent( ) ``` -더 낮은 지연 시간을 위해 `gpt-5.4`에서 `reasoning.effort="none"` 사용을 권장합니다. gpt-4.1 계열(미니 및 나노 변형 포함)도 대화형 에이전트 앱 구축에 여전히 좋은 선택입니다. +더 낮은 지연 시간을 위해 `gpt-5.4` 에서 `reasoning.effort="none"` 사용을 권장합니다. gpt-4.1 계열( mini 및 nano 변형 포함)도 인터랙티브 에이전트 앱 구축에 여전히 좋은 선택입니다. #### ComputerTool 모델 선택 -에이전트에 [`ComputerTool`][agents.tool.ComputerTool]이 포함되어 있으면, 실제 Responses 요청에서의 유효 모델이 SDK가 전송할 컴퓨터 도구 페이로드를 결정합니다. 명시적 `gpt-5.4` 요청은 GA 내장 `computer` 도구를 사용하고, 명시적 `computer-use-preview` 요청은 기존 `computer_use_preview` 페이로드를 유지합니다. +에이전트가 [`ComputerTool`][agents.tool.ComputerTool] 을 포함하면, 실제 Responses 요청에서의 유효 모델이 SDK 가 어떤 컴퓨터 도구 페이로드를 보내는지 결정합니다. 명시적 `gpt-5.4` 요청은 GA 내장 `computer` 도구를 사용하고, 명시적 `computer-use-preview` 요청은 기존 `computer_use_preview` 페이로드를 유지합니다. -주요 예외는 프롬프트 관리 호출입니다. 프롬프트 템플릿이 모델을 소유하고 SDK가 요청에서 `model`을 생략하면, SDK는 프롬프트가 어떤 모델에 고정되어 있는지 추측하지 않기 위해 preview 호환 컴퓨터 페이로드를 기본으로 사용합니다. 이 흐름에서 GA 경로를 유지하려면, 요청에 `model="gpt-5.4"`를 명시하거나 `ModelSettings(tool_choice="computer")` 또는 `ModelSettings(tool_choice="computer_use")`로 GA 선택기를 강제하세요. +주요 예외는 프롬프트 관리 호출입니다. 프롬프트 템플릿이 모델을 소유하고 SDK 가 요청에서 `model` 을 생략하면, SDK 는 프롬프트가 고정한 모델을 추측하지 않기 위해 preview 호환 컴퓨터 페이로드를 기본값으로 사용합니다. 이 흐름에서 GA 경로를 유지하려면 요청에서 `model="gpt-5.4"` 를 명시하거나, `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)를 참조하세요. +preview 호환 요청은 `environment` 및 디스플레이 크기를 먼저 직렬화해야 하므로, [`ComputerProvider`][agents.tool.ComputerProvider] 팩토리를 사용하는 프롬프트 관리 흐름에서는 구체적인 `Computer` 또는 `AsyncComputer` 인스턴스를 전달하거나 요청 전 GA 선택기를 강제해야 합니다. 전체 마이그레이션 세부 사항은 [도구](../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 전용 도구 검색 기능 @@ -95,23 +98,27 @@ 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()` 을 추가하고, 네임스페이스 이름 또는 지연 전용 함수 이름을 강제하기보다 `auto` 또는 `required` tool choice 를 통해 모델이 도구를 로드하도록 하세요. 설정 세부 사항과 현재 제약은 [도구](../tools.md#hosted-tool-search)를 참고하세요. ### Responses WebSocket 전송 기본적으로 OpenAI Responses API 요청은 HTTP 전송을 사용합니다. OpenAI 기반 모델 사용 시 websocket 전송을 활성화할 수 있습니다. +#### 기본 설정 + ```python from agents import set_default_openai_responses_transport set_default_openai_responses_transport("websocket") ``` -이는 기본 OpenAI 제공자가 해석한 OpenAI Responses 모델(예: `"gpt-5.4"` 같은 문자열 모델 이름 포함)에 영향을 줍니다. +이는 기본 OpenAI provider 로 해석되는 OpenAI Responses 모델( `"gpt-5.4"` 같은 문자열 모델 이름 포함)에 영향을 줍니다. -전송 방식 선택은 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=...)` 를 전달하면 전역 기본값 대신 해당 provider 가 전송 선택을 제어합니다. -제공자별 또는 실행별 websocket 전송 설정도 가능합니다: +#### provider 또는 실행 수준 설정 + +provider 단위 또는 실행 단위로 websocket 전송을 구성할 수도 있습니다: ```python from agents import Agent, OpenAIProvider, RunConfig, Runner @@ -130,14 +137,16 @@ result = await Runner.run( ) ``` -접두사 기반 모델 라우팅이 필요하면(예: 한 번의 실행에서 `openai/...`와 `litellm/...` 모델 이름 혼합), 대신 [`MultiProvider`][agents.MultiProvider]를 사용하고 `openai_use_responses_websocket=True`를 설정하세요. +#### `MultiProvider` 를 사용한 고급 라우팅 + +접두사 기반 모델 라우팅이 필요하다면(예: 하나의 실행에서 `openai/...` 와 `litellm/...` 모델 이름 혼합), [`MultiProvider`][agents.MultiProvider] 를 사용하고 그곳에서 `openai_use_responses_websocket=True` 를 설정하세요. -`MultiProvider`는 두 가지 기존 기본값을 유지합니다: +`MultiProvider` 는 두 가지 기존 기본값을 유지합니다: -- `openai/...`는 OpenAI 제공자의 별칭으로 처리되므로, `openai/gpt-4.1`은 모델 `gpt-4.1`로 라우팅됩니다 -- 알 수 없는 접두사는 그대로 전달되지 않고 `UserError`를 발생시킵니다 +- `openai/...` 는 OpenAI provider 의 별칭으로 처리되므로 `openai/gpt-4.1` 은 `gpt-4.1` 모델로 라우팅됩니다 +- 알 수 없는 접두사는 그대로 전달되지 않고 `UserError` 를 발생시킵니다 -OpenAI 제공자를 리터럴 네임스페이스 모델 ID를 기대하는 OpenAI 호환 엔드포인트로 지정하는 경우, 명시적으로 pass-through 동작을 활성화하세요. websocket 활성 구성에서는 `MultiProvider`에도 `openai_use_responses_websocket=True`를 유지하세요: +OpenAI 호환 엔드포인트가 리터럴 네임스페이스 모델 ID 를 기대하는 경우, 명시적으로 pass-through 동작을 활성화하세요. websocket 활성화 구성에서는 `MultiProvider` 에서도 `openai_use_responses_websocket=True` 를 유지하세요: ```python from agents import Agent, MultiProvider, RunConfig, Runner @@ -163,56 +172,52 @@ 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] 에서도 사용할 수 있습니다. -사용자 지정 OpenAI 호환 엔드포인트 또는 프록시를 사용하는 경우, websocket 전송에는 호환되는 websocket `/responses` 엔드포인트도 필요합니다. 이러한 구성에서는 `websocket_base_url`을 명시적으로 설정해야 할 수 있습니다. +사용자 지정 OpenAI 호환 엔드포인트나 프록시를 사용하는 경우, websocket 전송에는 호환되는 websocket `/responses` 엔드포인트도 필요합니다. 이런 구성에서는 `websocket_base_url` 을 명시적으로 설정해야 할 수 있습니다. -참고: +#### 참고 사항 -- 이는 websocket 전송 위의 Responses API이며, [Realtime API](../realtime/guide.md)가 아닙니다. Chat Completions 또는 Responses websocket `/responses` 엔드포인트를 지원하지 않는 OpenAI 이외 제공자에는 적용되지 않습니다 -- 환경에 `websockets` 패키지가 없으면 설치하세요 -- websocket 전송 활성화 후 [`Runner.run_streamed()`][agents.run.Runner.run_streamed]를 직접 사용할 수 있습니다. 여러 턴 워크플로우에서 턴 간(및 중첩된 agent-as-tool 호출 간) 동일한 websocket 연결을 재사용하려면 [`responses_websocket_session()`][agents.responses_websocket_session] 헬퍼를 권장합니다. [에이전트 실행](../running_agents.md) 가이드와 [`examples/basic/stream_ws.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/stream_ws.py)를 참조하세요 +- 이는 websocket 전송 위의 Responses API 이며, [Realtime API](../realtime/guide.md)가 아닙니다. Chat Completions 또는 Responses websocket `/responses` 엔드포인트를 지원하지 않는 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)를 참고하세요 -## OpenAI 이외 모델 +## OpenAI 가 아닌 모델 -대부분의 OpenAI 이외 모델은 [LiteLLM 통합](./litellm.md)을 통해 사용할 수 있습니다. 먼저 litellm 의존성 그룹을 설치하세요: +OpenAI 가 아닌 provider 가 필요하면 SDK 의 내장 provider 통합 지점부터 시작하세요. 많은 설정에서는 LiteLLM 을 추가하지 않아도 충분합니다. 각 패턴의 예시는 [examples/model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)에 있습니다. -```bash -pip install "openai-agents[litellm]" -``` +### OpenAI 가 아닌 provider 통합 방법 -그다음 `litellm/` 접두사와 함께 [지원되는 모델](https://docs.litellm.ai/docs/providers)을 사용하세요: - -```python -claude_agent = Agent(model="litellm/anthropic/claude-3-5-sonnet-20240620", ...) -gemini_agent = Agent(model="litellm/gemini/gemini-2.5-flash-preview-04-17", ...) -``` - -### OpenAI 이외 모델을 사용하는 다른 방법 +| 접근 방식 | 사용 시점 | 범위 | +| --- | --- | --- | +| [`set_default_openai_client`][agents.set_default_openai_client] | 하나의 OpenAI 호환 엔드포인트를 대부분 또는 모든 에이전트의 기본값으로 써야 할 때 | 전역 기본값 | +| [`ModelProvider`][agents.models.interface.ModelProvider] | 하나의 사용자 지정 provider 를 단일 실행에 적용해야 할 때 | 실행별 | +| [`Agent.model`][agents.agent.Agent.model] | 서로 다른 에이전트에 서로 다른 provider 또는 구체적 모델 객체가 필요할 때 | 에이전트별 | +| LiteLLM (베타) | LiteLLM 고유의 provider 범위 또는 라우팅이 필요할 때 | [LiteLLM](#litellm) 참고 | -다음 3가지 방식으로 다른 LLM 제공자를 통합할 수 있습니다(예제는 [여기](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)): +다음 내장 경로로 다른 LLM provider 를 통합할 수 있습니다: -1. [`set_default_openai_client`][agents.set_default_openai_client]는 LLM 클라이언트로 `AsyncOpenAI` 인스턴스를 전역 사용하려는 경우 유용합니다. LLM 제공자가 OpenAI 호환 API 엔드포인트를 제공하고 `base_url` 및 `api_key`를 설정할 수 있을 때 사용합니다. 구성 가능한 예제는 [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py)를 참조하세요 -2. [`ModelProvider`][agents.models.interface.ModelProvider]는 `Runner.run` 수준에서 사용됩니다. 이를 통해 "이번 실행의 모든 에이전트에 사용자 지정 모델 제공자를 사용"하도록 설정할 수 있습니다. 구성 가능한 예제는 [examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py)를 참조하세요 -3. [`Agent.model`][agents.agent.Agent.model]을 사용하면 특정 Agent 인스턴스에 모델을 지정할 수 있습니다. 이를 통해 에이전트별로 서로 다른 제공자를 혼합해 사용할 수 있습니다. 구성 가능한 예제는 [examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py)를 참조하세요. 사용 가능한 대부분의 모델을 쉽게 사용하는 방법은 [LiteLLM 통합](./litellm.md)입니다 +1. [`set_default_openai_client`][agents.set_default_openai_client] 는 `AsyncOpenAI` 인스턴스를 LLM 클라이언트로 전역 사용하려는 경우에 유용합니다. LLM 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)를 설정하는 것을 권장합니다. +`platform.openai.com` 의 API 키가 없는 경우, `set_tracing_disabled()` 로 트레이싱을 비활성화하거나 [다른 트레이싱 프로세서](../tracing.md)를 설정하는 것을 권장합니다. !!! note - 이 예제들에서는 대부분의 LLM 제공자가 아직 Responses API를 지원하지 않기 때문에 Chat Completions API/모델을 사용합니다. LLM 제공자가 이를 지원한다면 Responses 사용을 권장합니다 + 이 예시들에서는 Chat Completions API/모델을 사용합니다. 많은 LLM provider 가 아직 Responses API 를 지원하지 않기 때문입니다. LLM provider 가 이를 지원한다면 Responses 사용을 권장합니다 -## 고급 모델 선택 및 혼합 +## 하나의 워크플로에서 모델 혼합 -하나의 워크플로우 내에서 에이전트별로 다른 모델을 사용하고 싶을 수 있습니다. 예를 들어, 분류에는 더 작고 빠른 모델을 사용하고 복잡한 작업에는 더 크고 성능이 높은 모델을 사용할 수 있습니다. [`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 +!!! 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 @@ -248,7 +253,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 @@ -261,19 +266,21 @@ english_agent = Agent( ) ``` -#### 일반적인 고급 `ModelSettings` 옵션 +## 고급 OpenAI Responses 설정 -OpenAI Responses API를 사용할 때는 여러 요청 필드가 이미 `ModelSettings`에 직접 매핑되어 있어 `extra_args`가 필요하지 않습니다. +OpenAI Responses 경로에서 더 세밀한 제어가 필요하면 `ModelSettings` 부터 시작하세요. -| 필드 | 용도 | -| --- | --- | -| `parallel_tool_calls` | 같은 턴에서 여러 도구 호출을 허용하거나 금지합니다 | -| `truncation` | 컨텍스트 초과 시 실패 대신 가장 오래된 대화 항목을 삭제하도록 Responses API에 `"auto"`를 설정합니다 | -| `store` | 생성된 응답을 이후 조회를 위해 서버 측에 저장할지 제어합니다. 이는 응답 ID에 의존하는 후속 워크플로우와, `store=False`일 때 로컬 입력으로 폴백해야 할 수 있는 세션 압축 흐름에 중요합니다 | -| `prompt_cache_retention` | 예: `"24h"`처럼 캐시된 프롬프트 접두사를 더 오래 유지합니다 | -| `response_include` | `web_search_call.action.sources`, `file_search_call.results`, `reasoning.encrypted_content` 같은 더 풍부한 응답 페이로드를 요청합니다 | -| `top_logprobs` | 출력 텍스트에 대한 상위 토큰 logprobs를 요청합니다. SDK는 `message.output_text.logprobs`도 자동으로 추가합니다 | -| `retry` | 모델 호출에 대해 러너 관리 재시도 설정을 활성화합니다. [Runner 관리 재시도](#runner-managed-retries)를 참조하세요 | +### 공통 고급 `ModelSettings` 옵션 + +OpenAI Responses API 를 사용하는 경우, 여러 요청 필드가 이미 `ModelSettings` 에 직접 대응되므로 이를 위해 `extra_args` 를 사용할 필요가 없습니다. + +- `parallel_tool_calls`: 같은 턴에서 여러 도구 호출을 허용하거나 금지 +- `truncation`: 컨텍스트가 넘쳐 실패하는 대신 Responses API 가 가장 오래된 대화 항목을 삭제하도록 `"auto"` 설정 +- `store`: 생성된 응답을 나중에 조회할 수 있도록 서버 측에 저장할지 제어. 이는 응답 ID 에 의존하는 후속 워크플로와 `store=False` 일 때 로컬 입력으로 폴백이 필요할 수 있는 세션 압축 흐름에 중요합니다 +- `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) 참고 ```python from agents import Agent, ModelSettings @@ -292,11 +299,31 @@ 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 는 해당 응답을 나중에 서버 측에서 조회 가능하게 유지하지 않습니다. 이는 stateless 또는 zero-data-retention 스타일 흐름에 유용하지만, 그렇지 않으면 응답 ID 를 재사용하던 기능이 대신 로컬 관리 상태에 의존해야 함을 의미합니다. 예를 들어 [`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession] 은 마지막 응답이 저장되지 않았을 때 기본 `"auto"` 압축 경로를 입력 기반 압축으로 전환합니다. [세션 가이드](../sessions/index.md#openai-responses-compaction-sessions)를 참고하세요. + +### `extra_args` 전달 + +SDK 가 아직 최상위에서 직접 노출하지 않는 provider 전용 또는 최신 요청 필드가 필요할 때 `extra_args` 를 사용하세요. + +또한 OpenAI Responses API 사용 시 [다른 선택적 매개변수](https://platform.openai.com/docs/api-reference/responses/create) (예: `user`, `service_tier` 등)가 있습니다. 이들이 최상위에 없으면 `extra_args` 로 전달할 수 있습니다. + +```python +from agents import Agent, ModelSettings + +english_agent = Agent( + name="English agent", + instructions="You only speak English", + model="gpt-4.1", + model_settings=ModelSettings( + temperature=0.1, + extra_args={"service_tier": "flex", "user": "user_12345"}, + ), +) +``` -#### Runner 관리 재시도 +## Runner 관리 재시도 -재시도는 런타임 전용이며 opt-in입니다. SDK는 `ModelSettings(retry=...)`를 설정하고 재시도 정책이 재시도를 선택한 경우에만 일반 모델 요청을 재시도합니다. +재시도는 런타임 전용이며 옵트인입니다. `ModelSettings(retry=...)` 를 설정하고 재시도 정책이 재시도를 선택하지 않는 한 SDK 는 일반 모델 요청을 재시도하지 않습니다. ```python from agents import Agent, ModelRetrySettings, ModelSettings, retry_policies @@ -324,99 +351,85 @@ agent = Agent( ) ``` -`ModelRetrySettings`에는 세 필드가 있습니다: +`ModelRetrySettings` 에는 세 가지 필드가 있습니다: + +
| 필드 | 타입 | 참고 | | --- | --- | --- | -| `max_retries` | `int \| None` | 초기 요청 이후 허용되는 재시도 횟수 | -| `backoff` | `ModelRetryBackoffSettings \| dict \| None` | 정책이 명시적 지연 없이 재시도할 때 사용하는 기본 지연 전략 | -| `policy` | `RetryPolicy \| None` | 재시도 여부를 결정하는 콜백입니다. 이 필드는 런타임 전용이며 직렬화되지 않습니다 | +| `max_retries` | `int | None` | 초기 요청 이후 허용되는 재시도 횟수 | +| `backoff` | `ModelRetryBackoffSettings | dict | None` | 정책이 명시적 지연을 반환하지 않고 재시도할 때의 기본 지연 전략 | +| `policy` | `RetryPolicy | None` | 재시도 여부를 결정하는 콜백. 이 필드는 런타임 전용이며 직렬화되지 않습니다 | -재시도 정책은 [`RetryPolicyContext`][agents.retry.RetryPolicyContext]를 입력받으며 다음을 포함합니다: +
-- `attempt`와 `max_retries`로 시도 횟수 인지형 판단 가능 -- `stream`으로 스트리밍/비스트리밍 분기 가능 -- 원문 검사용 `error` -- `status_code`, `retry_after`, `error_code`, `is_network_error`, `is_timeout`, `is_abort` 같은 정규화 정보 `normalized` -- 기본 모델 어댑터가 재시도 가이드를 제공할 수 있을 때의 `provider_advice` +재시도 정책은 다음 정보를 가진 [`RetryPolicyContext`][agents.retry.RetryPolicyContext] 를 받습니다: + +- `attempt` 와 `max_retries` 로 시도 횟수 인지형 결정 가능 +- `stream` 으로 스트리밍/비스트리밍 동작 분기 가능 +- 원문 확인을 위한 `error` +- `status_code`, `retry_after`, `error_code`, `is_network_error`, `is_timeout`, `is_abort` 같은 `normalized` 정보 +- 기본 모델 어댑터가 재시도 가이드를 제공할 수 있는 경우 `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.network_error()` | 일시적 전송/타임아웃 실패와 일치합니다 | -| `retry_policies.http_status([...])` | 선택한 HTTP 상태 코드와 일치합니다 | -| `retry_policies.retry_after()` | retry-after 힌트가 있을 때만 해당 지연으로 재시도합니다 | -| `retry_policies.any(...)` | 중첩 정책 중 하나라도 활성화하면 재시도합니다 | -| `retry_policies.all(...)` | 중첩 정책 모두 활성화해야 재시도합니다 | +| `retry_policies.never()` | 항상 비활성화 | +| `retry_policies.provider_suggested()` | 가능할 때 provider 재시도 권고를 따름 | +| `retry_policies.network_error()` | 일시적 전송/타임아웃 실패와 매칭 | +| `retry_policies.http_status([...])` | 선택한 HTTP 상태 코드와 매칭 | +| `retry_policies.retry_after()` | retry-after 힌트가 있을 때만 해당 지연으로 재시도 | +| `retry_policies.any(...)` | 중첩 정책 중 하나라도 활성화하면 재시도 | +| `retry_policies.all(...)` | 중첩 정책 모두 활성화할 때만 재시도 | -정책을 조합할 때 `provider_suggested()`는 제공자가 구분 가능한 경우 제공자 veto와 재실행 안전 승인(replay-safety approvals)을 보존하므로 가장 안전한 첫 구성요소입니다. +정책을 조합할 때 `provider_suggested()` 가 가장 안전한 첫 구성 요소입니다. provider 가 구분 가능한 경우 provider veto 와 replay-safe 승인 정보를 보존하기 때문입니다. ##### 안전 경계 일부 실패는 자동 재시도되지 않습니다: -- 중단 오류 -- 제공자 권고에서 재실행이 안전하지 않다고 표시된 요청 -- 출력이 이미 시작되어 재실행이 안전하지 않은 스트리밍 실행 - -`previous_response_id` 또는 `conversation_id`를 사용하는 상태 기반 후속 요청도 더 보수적으로 처리됩니다. 이러한 요청에서는 `network_error()`나 `http_status([500])` 같은 비제공자 조건만으로는 충분하지 않습니다. 재시도 정책에는 일반적으로 `retry_policies.provider_suggested()`를 통한 제공자 기반 재실행 안전 승인이 포함되어야 합니다. +- Abort 오류 +- provider 권고가 replay 를 안전하지 않다고 표시한 요청 +- replay 가 안전하지 않게 되는 방식으로 출력이 이미 시작된 이후의 스트리밍 실행 -##### Runner 및 agent 병합 동작 +`previous_response_id` 또는 `conversation_id` 를 사용하는 상태 기반 후속 요청도 더 보수적으로 처리됩니다. 이런 요청에서는 `network_error()` 나 `http_status([500])` 같은 비-provider 조건만으로는 충분하지 않습니다. 재시도 정책에 일반적으로 `retry_policies.provider_suggested()` 를 통한 replay-safe provider 승인이 포함되어야 합니다. -`retry`는 러너 수준과 에이전트 수준 `ModelSettings` 사이에서 깊은 병합(deep-merge)됩니다: +##### Runner 와 에이전트 병합 동작 -- 에이전트는 `retry.max_retries`만 재정의하고 러너의 `policy`를 상속할 수 있습니다 -- 에이전트는 `retry.backoff` 일부만 재정의하고 나머지 backoff 필드를 러너에서 유지할 수 있습니다 -- `policy`는 런타임 전용이므로, 직렬화된 `ModelSettings`에는 `max_retries`와 `backoff`만 유지되고 콜백 자체는 제외됩니다 +`retry` 는 runner 수준과 에이전트 수준 `ModelSettings` 사이에서 deep-merge 됩니다: -더 완전한 예제는 [`examples/basic/retry.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry.py) 및 [`examples/basic/retry_litellm.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry_litellm.py)를 참조하세요. +- 에이전트는 `retry.max_retries` 만 재정의하고 runner 의 `policy` 를 상속할 수 있습니다 +- 에이전트는 `retry.backoff` 의 일부만 재정의하고 runner 의 같은 수준 다른 backoff 필드를 유지할 수 있습니다 +- `policy` 는 런타임 전용이므로 직렬화된 `ModelSettings` 는 `max_retries` 와 `backoff` 는 유지하지만 콜백 자체는 생략합니다 -SDK가 아직 최상위로 직접 노출하지 않는 제공자별 또는 최신 요청 필드가 필요할 때는 `extra_args`를 사용하세요. +더 자세한 예시는 [`examples/basic/retry.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry.py) 및 [`examples/basic/retry_litellm.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry_litellm.py)를 참고하세요. -또한 OpenAI Responses API 사용 시 [다른 선택적 매개변수](https://platform.openai.com/docs/api-reference/responses/create) (`user`, `service_tier` 등)도 있습니다. 최상위에 없으면 `extra_args`로 전달할 수 있습니다. - -```python -from agents import Agent, ModelSettings - -english_agent = Agent( - name="English agent", - instructions="You only speak English", - model="gpt-4.1", - model_settings=ModelSettings( - temperature=0.1, - extra_args={"service_tier": "flex", "user": "user_12345"}, - ), -) -``` - -## OpenAI 이외 제공자 문제 해결 +## OpenAI 가 아닌 provider 문제 해결 ### 트레이싱 클라이언트 오류 401 트레이싱 관련 오류가 발생하면, 트레이스가 OpenAI 서버로 업로드되는데 OpenAI API 키가 없기 때문입니다. 해결 방법은 세 가지입니다: -1. 트레이싱 완전 비활성화: [`set_tracing_disabled(True)`][agents.set_tracing_disabled] -2. 트레이싱용 OpenAI 키 설정: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]. 이 API 키는 트레이스 업로드에만 사용되며 [platform.openai.com](https://platform.openai.com/)의 키여야 합니다 -3. OpenAI 이외 트레이스 프로세서 사용: [트레이싱 문서](../tracing.md#custom-tracing-processors) 참조 +1. 트레이싱을 완전히 비활성화: [`set_tracing_disabled(True)`][agents.set_tracing_disabled] +2. 트레이싱용 OpenAI 키 설정: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]. 이 API 키는 트레이스 업로드에만 사용되며 [platform.openai.com](https://platform.openai.com/) 의 키여야 합니다 +3. OpenAI 가 아닌 트레이스 프로세서 사용. [트레이싱 문서](../tracing.md#custom-tracing-processors) 참고 ### Responses API 지원 -SDK는 기본적으로 Responses API를 사용하지만, 대부분의 다른 LLM 제공자는 아직 이를 지원하지 않습니다. 그 결과 404 또는 유사한 문제가 발생할 수 있습니다. 해결 방법은 두 가지입니다: +SDK 는 기본적으로 Responses API 를 사용하지만, 많은 다른 LLM 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 지원 +### structured outputs 지원 -일부 모델 제공자는 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)를 지원하지 않습니다. 이로 인해 다음과 같은 오류가 발생할 수 있습니다: +일부 모델 provider 는 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)를 지원하지 않습니다. 이 경우 다음과 유사한 오류가 발생할 수 있습니다: ``` @@ -424,12 +437,24 @@ BadRequestError: Error code: 400 - {'error': {'message': "'response_format.type' ``` -이는 일부 모델 제공자의 한계입니다. JSON 출력은 지원하지만 출력에 사용할 `json_schema` 지정은 허용하지 않습니다. 이에 대한 수정 작업을 진행 중이지만, JSON schema 출력을 지원하는 제공자를 사용하는 것을 권장합니다. 그렇지 않으면 잘못된 JSON으로 인해 앱이 자주 깨질 수 있습니다. +이것은 일부 모델 provider 의 한계입니다. JSON 출력은 지원하지만 출력에 사용할 `json_schema` 지정은 허용하지 않습니다. 이 문제를 해결 중이지만, JSON schema 출력을 지원하는 provider 에 의존하는 것을 권장합니다. 그렇지 않으면 잘못된 JSON 때문에 앱이 자주 깨질 수 있습니다. -## 제공자 간 모델 혼합 +## provider 간 모델 혼합 -모델 제공자 간 기능 차이를 인지해야 하며, 그렇지 않으면 오류가 발생할 수 있습니다. 예를 들어 OpenAI는 structured outputs, 멀티모달 입력, 호스티드 파일 검색 및 웹 검색을 지원하지만 다른 많은 제공자는 이러한 기능을 지원하지 않습니다. 다음 제한 사항을 유의하세요: +모델 provider 간 기능 차이를 인지해야 하며, 그렇지 않으면 오류가 발생할 수 있습니다. 예를 들어 OpenAI 는 structured outputs, 멀티모달 입력, 호스티드 file search 및 web search 를 지원하지만 많은 다른 provider 는 이러한 기능을 지원하지 않습니다. 다음 제한 사항에 유의하세요: -- 지원하지 않는 `tools`를 이해하지 못하는 제공자에게 보내지 마세요 +- 지원하지 않는 provider 에는 지원되지 않는 `tools` 를 보내지 마세요 - 텍스트 전용 모델 호출 전에 멀티모달 입력을 필터링하세요 -- structured JSON 출력을 지원하지 않는 제공자는 때때로 유효하지 않은 JSON을 생성할 수 있음을 유의하세요 \ No newline at end of file +- structured JSON 출력 미지원 provider 는 때때로 유효하지 않은 JSON 을 생성할 수 있음을 유의하세요 + +## LiteLLM + +LiteLLM 지원은 OpenAI 가 아닌 provider 를 Agents SDK 워크플로에 포함해야 하는 경우를 위한 best-effort 베타 기능으로 제공됩니다. + +이 SDK 와 함께 OpenAI 모델을 사용하는 경우 LiteLLM 대신 내장 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 경로를 권장합니다. + +OpenAI 모델과 OpenAI 가 아닌 provider 를 함께 사용해야 하는 경우, 특히 Chat Completions 호환 API 를 통해 사용한다면 LiteLLM 을 베타 옵션으로 사용할 수 있지만 모든 설정에서 최적 선택은 아닐 수 있습니다. + +OpenAI 가 아닌 provider 에 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)` 를 전달하세요. \ No newline at end of file diff --git a/docs/ko/models/litellm.md b/docs/ko/models/litellm.md index 109d4cc372..c610be0644 100644 --- a/docs/ko/models/litellm.md +++ b/docs/ko/models/litellm.md @@ -2,103 +2,12 @@ search: exclude: true --- -# LiteLLM를 통한 임의 모델 사용 +# LiteLLM -!!! note + - LiteLLM 통합은 베타 단계입니다. 특히 소규모 모델 제공업체에서 문제가 발생할 수 있습니다. 문제가 있으면 [GitHub 이슈](https://github.com/openai/openai-agents-python/issues)로 보고해 주세요. 신속히 수정하겠습니다. +이 페이지는 [Models의 LiteLLM 섹션](index.md#litellm)(으)로 이동되었습니다 -[LiteLLM](https://docs.litellm.ai/docs/)은 단일 인터페이스로 100개 이상의 모델을 사용할 수 있게 해주는 라이브러리입니다. Agents SDK에서 어떤 AI 모델이든 사용할 수 있도록 LiteLLM 통합을 추가했습니다. - -## 설정 - -`litellm`이 사용 가능한지 확인해야 합니다. 선택적 `litellm` 종속성 그룹을 설치하여 진행할 수 있습니다: - -```bash -pip install "openai-agents[litellm]" -``` - -설치가 완료되면, 어떤 에이전트에서도 [`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel]을 사용할 수 있습니다. - -## 예제 - -다음은 완전하게 동작하는 예제입니다. 실행하면 모델 이름과 API 키를 입력하라는 메시지가 표시됩니다. 예를 들어 다음과 같이 입력할 수 있습니다: - -- `openai/gpt-4.1` 모델과 OpenAI API 키 -- `anthropic/claude-3-5-sonnet-20240620` 모델과 Anthropic API 키 -- 등 - -LiteLLM에서 지원하는 전체 모델 목록은 [litellm providers 문서](https://docs.litellm.ai/docs/providers)를 참고하세요. - -```python -from __future__ import annotations - -import asyncio - -from agents import Agent, Runner, function_tool, set_tracing_disabled -from agents.extensions.models.litellm_model import LitellmModel - -@function_tool -def get_weather(city: str): - print(f"[debug] getting weather for {city}") - return f"The weather in {city} is sunny." - - -async def main(model: str, api_key: str): - agent = Agent( - name="Assistant", - instructions="You only respond in haikus.", - model=LitellmModel(model=model, api_key=api_key), - tools=[get_weather], - ) - - result = await Runner.run(agent, "What's the weather in Tokyo?") - print(result.final_output) - - -if __name__ == "__main__": - # First try to get model/api key from args - import argparse - - parser = argparse.ArgumentParser() - parser.add_argument("--model", type=str, required=False) - parser.add_argument("--api-key", type=str, required=False) - args = parser.parse_args() - - model = args.model - if not model: - model = input("Enter a model name for Litellm: ") - - api_key = args.api_key - if not api_key: - api_key = input("Enter an API key for Litellm: ") - - asyncio.run(main(model, api_key)) -``` - -## 사용량 데이터 추적 - -LiteLLM 응답으로 Agents SDK 사용량 메트릭을 채우려면, 에이전트를 생성할 때 `ModelSettings(include_usage=True)`를 전달하세요. - -```python -from agents import Agent, ModelSettings -from agents.extensions.models.litellm_model import LitellmModel - -agent = Agent( - name="Assistant", - model=LitellmModel(model="your/model", api_key="..."), - model_settings=ModelSettings(include_usage=True), -) -``` - -`include_usage=True`를 사용하면, LiteLLM 요청은 기본 제공 OpenAI 모델과 마찬가지로 `result.context_wrapper.usage`를 통해 토큰 및 요청 수를 보고합니다. - -## 문제 해결 - -LiteLLM 응답에서 Pydantic 직렬화 경고가 보이는 경우, 다음 설정으로 작은 호환성 패치를 활성화하세요: - -```bash -export OPENAI_AGENTS_ENABLE_LITELLM_SERIALIZER_PATCH=true -``` - -이 옵트인 플래그는 알려진 LiteLLM 직렬화 경고를 억제하면서 정상 동작을 유지합니다. 필요하지 않다면 끄세요(설정 해제 또는 `false`). \ No newline at end of file +자동으로 리디렉션되지 않으면 위 링크를 사용하세요 \ No newline at end of file diff --git a/docs/ko/usage.md b/docs/ko/usage.md index 9a20bc651e..7994c3ae88 100644 --- a/docs/ko/usage.md +++ b/docs/ko/usage.md @@ -2,24 +2,24 @@ search: exclude: true --- -# 사용량 +# 사용법 -Agents SDK는 모든 실행의 토큰 사용량을 자동으로 추적합니다. 실행 컨텍스트에서 이를 확인하여 비용 모니터링, 제한 적용, 분석 기록에 활용할 수 있습니다. +Agents SDK는 모든 실행의 토큰 사용량을 자동으로 추적합니다. 실행 컨텍스트에서 이를 확인하고 비용 모니터링, 한도 적용, 분석 기록에 활용할 수 있습니다 ## 추적 항목 - **requests**: 수행된 LLM API 호출 수 -- **input_tokens**: 전송된 전체 입력 토큰 수 -- **output_tokens**: 수신된 전체 출력 토큰 수 +- **input_tokens**: 전송된 총 입력 토큰 수 +- **output_tokens**: 수신된 총 출력 토큰 수 - **total_tokens**: 입력 + 출력 -- **request_usage_entries**: 요청별 사용량 상세 내역 목록 +- **request_usage_entries**: 요청별 사용량 세부 내역 목록 - **details**: - `input_tokens_details.cached_tokens` - `output_tokens_details.reasoning_tokens` -## 실행에서 사용량 접근 +## 실행에서 사용량 액세스 -`Runner.run(...)` 이후 `result.context_wrapper.usage`를 통해 사용량에 접근할 수 있습니다. +`Runner.run(...)` 이후 `result.context_wrapper.usage`로 사용량에 액세스합니다 ```python result = await Runner.run(agent, "What's the weather in Tokyo?") @@ -31,11 +31,11 @@ print("Output tokens:", usage.output_tokens) print("Total tokens:", usage.total_tokens) ``` -사용량은 실행 중 발생한 모든 모델 호출(도구 호출 및 핸드오프 포함)에 대해 집계됩니다. +사용량은 실행 중 발생한 모든 모델 호출(도구 호출 및 핸드오프 포함)에 대해 집계됩니다 ### LiteLLM 모델에서 사용량 활성화 -LiteLLM provider는 기본적으로 사용량 메트릭을 보고하지 않습니다. [`LitellmModel`](models/litellm.md)을 사용하는 경우, 에이전트에 `ModelSettings(include_usage=True)`를 전달하여 LiteLLM 응답이 `result.context_wrapper.usage`를 채우도록 하세요. +LiteLLM 제공자는 기본적으로 사용량 지표를 보고하지 않습니다. [`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel]을 사용하는 경우, LiteLLM 응답이 `result.context_wrapper.usage`를 채우도록 에이전트에 `ModelSettings(include_usage=True)`를 전달하세요. 설정 안내와 코드 예제는 Models 가이드의 [LiteLLM note](models/index.md#litellm)를 참고하세요 ```python from agents import Agent, ModelSettings, Runner @@ -53,7 +53,7 @@ print(result.context_wrapper.usage.total_tokens) ## 요청별 사용량 추적 -SDK는 각 API 요청의 사용량을 `request_usage_entries`에서 자동으로 추적하므로, 상세한 비용 계산과 컨텍스트 윈도우 소비량 모니터링에 유용합니다. +SDK는 `request_usage_entries`에서 각 API 요청의 사용량을 자동으로 추적하며, 이는 상세 비용 계산과 컨텍스트 윈도우 사용량 모니터링에 유용합니다 ```python result = await Runner.run(agent, "What's the weather in Tokyo?") @@ -62,9 +62,9 @@ for i, request in enumerate(result.context_wrapper.usage.request_usage_entries): print(f"Request {i + 1}: {request.input_tokens} in, {request.output_tokens} out") ``` -## 세션에서 사용량 접근 +## 세션에서 사용량 액세스 -`Session`(예: `SQLiteSession`)을 사용할 때 `Runner.run(...)`를 호출할 때마다 해당 실행에 대한 사용량이 반환됩니다. 세션은 컨텍스트를 위해 대화 기록을 유지하지만, 각 실행의 사용량은 서로 독립적입니다. +`Session`(예: `SQLiteSession`)을 사용할 때 `Runner.run(...)`을 호출할 때마다 해당 실행에 대한 사용량이 반환됩니다. 세션은 컨텍스트를 위해 대화 기록을 유지하지만, 각 실행의 사용량은 서로 독립적입니다 ```python session = SQLiteSession("my_conversation") @@ -76,11 +76,11 @@ second = await Runner.run(agent, "Can you elaborate?", session=session) print(second.context_wrapper.usage.total_tokens) # Usage for second run ``` -세션은 실행 간 대화 컨텍스트를 유지하지만, 각 `Runner.run()` 호출에서 반환되는 사용량 메트릭은 해당 실행만을 나타냅니다. 세션에서는 이전 메시지가 각 실행의 입력으로 다시 제공될 수 있으며, 이는 이후 턴의 입력 토큰 수에 영향을 줍니다. +세션은 실행 간 대화 컨텍스트를 보존하지만, 각 `Runner.run()` 호출에서 반환되는 사용량 지표는 해당 실행만을 나타냅니다. 세션에서는 이전 메시지가 각 실행의 입력으로 다시 전달될 수 있으며, 이는 이후 턴의 입력 토큰 수에 영향을 줍니다 -## 훅에서 사용량 사용 +## 훅에서 사용량 활용 -`RunHooks`를 사용하는 경우, 각 훅에 전달되는 `context` 객체에 `usage`가 포함됩니다. 이를 통해 라이프사이클의 주요 시점에서 사용량을 로깅할 수 있습니다. +`RunHooks`를 사용하는 경우 각 훅에 전달되는 `context` 객체에 `usage`가 포함됩니다. 이를 통해 주요 라이프사이클 시점에 사용량을 기록할 수 있습니다 ```python class MyHooks(RunHooks): @@ -91,9 +91,9 @@ class MyHooks(RunHooks): ## API 레퍼런스 -자세한 API 문서는 다음을 참조하세요: +자세한 API 문서는 다음을 참고하세요: - [`Usage`][agents.usage.Usage] - 사용량 추적 데이터 구조 - [`RequestUsage`][agents.usage.RequestUsage] - 요청별 사용량 세부 정보 -- [`RunContextWrapper`][agents.run.RunContextWrapper] - 실행 컨텍스트에서 사용량 접근 +- [`RunContextWrapper`][agents.run.RunContextWrapper] - 실행 컨텍스트에서 사용량 액세스 - [`RunHooks`][agents.run.RunHooks] - 사용량 추적 라이프사이클에 훅 연결 \ No newline at end of file diff --git a/docs/zh/models/index.md b/docs/zh/models/index.md index f326602f75..0f2f1cfbab 100644 --- a/docs/zh/models/index.md +++ b/docs/zh/models/index.md @@ -4,39 +4,42 @@ 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。 +- **推荐**：[`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]，使用新的 [Responses API](https://platform.openai.com/docs/api-reference/responses) 调用 OpenAI API。 +- [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]，使用 [Chat Completions API](https://platform.openai.com/docs/api-reference/chat) 调用 OpenAI API。 ## 模型设置选择 -根据你的设置，请按以下顺序使用本页： +先从最适合你当前设置的最简单路径开始： -| 目标 | 从这里开始 | -| --- | --- | -| 使用 SDK 默认配置的 OpenAI 托管模型 | [OpenAI 模型](#openai-models) | -| 通过 websocket 传输使用 OpenAI Responses API | [Responses WebSocket 传输](#responses-websocket-transport) | -| 使用非 OpenAI 提供方 | [非 OpenAI 模型](#non-openai-models) | -| 在一个工作流中混用模型/提供方 | [高级模型选择与混用](#advanced-model-selection-and-mixing) 和 [跨提供方混用模型](#mixing-models-across-providers) | -| 调试提供方兼容性问题 | [非 OpenAI 提供方故障排查](#troubleshooting-non-openai-providers) | +| 如果你想要…… | 推荐路径 | 了解更多 | +| --- | --- | --- | +| 仅使用 OpenAI 模型 | 使用默认 OpenAI provider 的 Responses 模型路径 | [OpenAI 模型](#openai-models) | +| 通过 websocket 传输使用 OpenAI Responses API | 保持 Responses 模型路径并启用 websocket 传输 | [Responses WebSocket 传输](#responses-websocket-transport) | +| 使用一个非 OpenAI provider | 从内置 provider 集成点开始 | [非 OpenAI 模型](#non-openai-models) | +| 在多个智能体之间混用模型或 provider | 按每次 run 或每个智能体选择 provider，并检查功能差异 | [在单个工作流中混用模型](#mixing-models-in-one-workflow) 和 [跨 provider 混用模型](#mixing-models-across-providers) | +| 调整高级 OpenAI Responses 请求设置 | 在 OpenAI Responses 路径上使用 `ModelSettings` | [高级 OpenAI Responses 设置](#advanced-openai-responses-settings) | +| 为非 OpenAI Chat Completions provider 使用 LiteLLM | 将 LiteLLM 视为 beta 备用方案 | [LiteLLM](#litellm) | ## OpenAI 模型 -当你在初始化 `Agent` 时未指定模型，将使用默认模型。当前默认值是 [`gpt-4.1`](https://developers.openai.com/api/docs/models/gpt-4.1)，以兼顾兼容性和低延迟。如果你有权限，我们建议将智能体设置为 [`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4) 以获得更高质量，同时保持显式的 `model_settings`。 +对于大多数仅使用 OpenAI 的应用，推荐路径是使用字符串模型名称配合默认 OpenAI provider，并保持在 Responses 模型路径上。 -如果你想切换到其他模型（如 [`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4)），有两种方式配置你的智能体。 +当你在初始化 `Agent` 时未指定模型，将使用默认模型。当前默认模型是 [`gpt-4.1`](https://developers.openai.com/api/docs/models/gpt-4.1)，以兼顾兼容性和低延迟。如果你有权限，我们建议将智能体设置为 [`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4) 以获得更高质量，同时保持显式 `model_settings`。 + +如果你想切换到 [`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4) 等其他模型，可通过两种方式配置智能体。 ### 默认模型 -首先，如果你希望所有未设置自定义模型的智能体始终使用某个特定模型，请在运行智能体前设置 `OPENAI_DEFAULT_MODEL` 环境变量。 +首先，如果你希望所有未设置自定义模型的智能体都持续使用某个特定模型，请在运行智能体前设置 `OPENAI_DEFAULT_MODEL` 环境变量。 ```bash export OPENAI_DEFAULT_MODEL=gpt-5.4 python3 my_awesome_agent.py ``` -其次，你可以通过 `RunConfig` 为一次运行设置默认模型。如果未为某个智能体设置模型，将使用该次运行的模型。 +其次，你可以通过 `RunConfig` 为一次 run 设置默认模型。如果你未为智能体设置模型，将使用该 run 的模型。 ```python from agents import Agent, RunConfig, Runner @@ -55,7 +58,7 @@ result = await Runner.run( #### GPT-5 模型 -当你以这种方式使用任意 GPT-5 模型（如 [`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4)）时，SDK 会应用默认的 `ModelSettings`。它会设置对大多数使用场景效果最佳的配置。若要调整默认模型的推理强度，请传入你自己的 `ModelSettings`： +当你以这种方式使用任意 GPT-5 模型（如 [`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4)）时，SDK 会应用默认 `ModelSettings`。它会设置最适合大多数用例的选项。若要调整默认模型的推理强度，请传入你自己的 `ModelSettings`： ```python from openai.types.shared import Reasoning @@ -71,21 +74,21 @@ my_agent = Agent( ) ``` -为了更低延迟，建议在 `gpt-5.4` 上使用 `reasoning.effort="none"`。gpt-4.1 系列（包括 mini 和 nano 变体）同样仍是构建交互式智能体应用的可靠选择。 +为了降低延迟，建议在 `gpt-5.4` 上使用 `reasoning.effort="none"`。gpt-4.1 系列（包括 mini 和 nano 变体）在构建交互式智能体应用时也依然是稳健选择。 #### ComputerTool 模型选择 -如果智能体包含 [`ComputerTool`][agents.tool.ComputerTool]，实际 Responses 请求中生效的模型决定 SDK 发送哪种计算机工具负载。显式 `gpt-5.4` 请求会使用 GA 内置 `computer` 工具，而显式 `computer-use-preview` 请求会保留旧的 `computer_use_preview` 负载。 +如果智能体包含 [`ComputerTool`][agents.tool.ComputerTool]，则实际 Responses 请求中生效的模型会决定 SDK 发送哪种 computer-tool 载荷。显式 `gpt-5.4` 请求会使用 GA 内置 `computer` 工具，而显式 `computer-use-preview` 请求会保留旧的 `computer_use_preview` 载荷。 -由提示词管理的调用是主要例外。如果提示模板持有模型且 SDK 在请求中省略 `model`，SDK 会默认使用与 preview 兼容的计算机负载，以避免猜测提示词绑定了哪个模型。要在该流程中保持 GA 路径，可在请求中显式设置 `model="gpt-5.4"`，或通过 `ModelSettings(tool_choice="computer")` 或 `ModelSettings(tool_choice="computer_use")` 强制使用 GA 选择器。 +由提示词管理的调用是主要例外。如果提示词模板持有模型且 SDK 在请求中省略 `model`，SDK 会默认使用与 preview 兼容的 computer 载荷，以避免猜测提示词绑定了哪个模型。要在该流程中保持 GA 路径，可在请求中显式设置 `model="gpt-5.4"`，或通过 `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)。 +与 preview 兼容的请求必须预先序列化 `environment` 和显示尺寸，因此使用 [`ComputerProvider`][agents.tool.ComputerProvider] 工厂的提示词管理流程应在发送请求前传入具体的 `Computer` 或 `AsyncComputer` 实例，或强制 GA 选择器。完整迁移细节见 [工具](../tools.md#computertool-and-the-responses-computer-tool)。 #### 非 GPT-5 模型 -如果你传入非 GPT-5 模型名称且未自定义 `model_settings`，SDK 会回退为兼容任意模型的通用 `ModelSettings`。 +如果你传入非 GPT-5 模型名且未自定义 `model_settings`，SDK 会回退为与任意模型兼容的通用 `ModelSettings`。 ### 仅 Responses 的工具检索功能 @@ -93,25 +96,29 @@ my_agent = Agent( - [`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 传输。 +#### 基础设置 + ```python from agents import set_default_openai_responses_transport set_default_openai_responses_transport("websocket") ``` -这会影响由默认 OpenAI 提供方解析的 OpenAI Responses 模型（包括字符串模型名，如 `"gpt-5.4"`）。 +这会影响由默认 OpenAI provider 解析的 OpenAI Responses 模型（包括 `"gpt-5.4"` 这样的字符串模型名）。 -传输方式会在 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=...)`，则由该 provider 控制传输选择，而不是全局默认值。 -你也可以按提供方或按运行配置 websocket 传输： +#### Provider 或 run 级设置 + +你也可以按 provider 或按 run 配置 websocket 传输： ```python from agents import Agent, OpenAIProvider, RunConfig, Runner @@ -130,14 +137,16 @@ result = await Runner.run( ) ``` -如果你需要基于前缀的模型路由（例如在一次运行中混用 `openai/...` 和 `litellm/...` 模型名），请改用 [`MultiProvider`][agents.MultiProvider] 并在其中设置 `openai_use_responses_websocket=True`。 +#### 使用 `MultiProvider` 的高级路由 + +如果你需要基于前缀的模型路由（例如在一次 run 中混用 `openai/...` 和 `litellm/...` 模型名），请使用 [`MultiProvider`][agents.MultiProvider]，并在其中设置 `openai_use_responses_websocket=True`。 -`MultiProvider` 保留两个历史默认行为： +`MultiProvider` 保留了两个历史默认行为： -- `openai/...` 被视为 OpenAI 提供方的别名，因此 `openai/gpt-4.1` 会按模型 `gpt-4.1` 路由。 -- 未知前缀会触发 `UserError`，而不是透传。 +- `openai/...` 被视为 OpenAI provider 的别名，因此 `openai/gpt-4.1` 会被路由为模型 `gpt-4.1`。 +- 未知前缀会抛出 `UserError`，而不是透传。 -当你将 OpenAI 提供方指向一个期望字面命名空间模型 ID 的 OpenAI 兼容端点时，请显式启用透传行为。在启用 websocket 的设置中，也要在 `MultiProvider` 上保留 `openai_use_responses_websocket=True`： +当你将 OpenAI provider 指向一个期望字面命名空间模型 ID 的 OpenAI 兼容端点时，请显式启用透传行为。在启用 websocket 的设置中，也要在 `MultiProvider` 上保持 `openai_use_responses_websocket=True`： ```python from agents import Agent, MultiProvider, RunConfig, Runner @@ -163,56 +172,52 @@ 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]。 -如果你使用自定义 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` 端点。 -- 如果环境中尚未安装，请安装 `websockets` 包。 -- 启用 websocket 传输后，你可以直接使用 [`Runner.run_streamed()`][agents.run.Runner.run_streamed]。对于希望在多轮工作流（以及嵌套的 Agents-as-tools 调用）中复用同一 websocket 连接的场景，推荐使用 [`responses_websocket_session()`][agents.responses_websocket_session] 辅助函数。参见 [运行智能体](../running_agents.md) 指南和 [`examples/basic/stream_ws.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/stream_ws.py)。 +- 这是通过 websocket 传输的 Responses API，不是 [Realtime API](../realtime/guide.md)。它不适用于 Chat Completions 或非 OpenAI provider，除非它们支持 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)。 ## 非 OpenAI 模型 -你可以通过 [LiteLLM 集成](./litellm.md) 使用大多数其他非 OpenAI 模型。首先，安装 litellm 依赖组： +如果你需要非 OpenAI provider，请先从 SDK 内置 provider 集成点开始。在很多设置中，无需添加 LiteLLM 就足够了。每种模式的示例位于 [examples/model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)。 -```bash -pip install "openai-agents[litellm]" -``` +### 非 OpenAI provider 集成方式 -然后，使用任意[受支持模型](https://docs.litellm.ai/docs/providers)，并加上 `litellm/` 前缀： - -```python -claude_agent = Agent(model="litellm/anthropic/claude-3-5-sonnet-20240620", ...) -gemini_agent = Agent(model="litellm/gemini/gemini-2.5-flash-preview-04-17", ...) -``` - -### 使用非 OpenAI 模型的其他方式 +| 方式 | 适用场景 | 范围 | +| --- | --- | --- | +| [`set_default_openai_client`][agents.set_default_openai_client] | 一个 OpenAI 兼容端点应作为大多数或全部智能体的默认值 | 全局默认 | +| [`ModelProvider`][agents.models.interface.ModelProvider] | 一个自定义 provider 应用于单次 run | 每次 run | +| [`Agent.model`][agents.agent.Agent.model] | 不同智能体需要不同 provider 或具体模型对象 | 每个智能体 | +| LiteLLM（beta） | 你需要 LiteLLM 特有的 provider 覆盖或路由 | 见 [LiteLLM](#litellm) | -你还可以通过另外 3 种方式集成其他 LLM 提供方（代码示例见[此处](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)）： +你可以通过这些内置路径集成其他 LLM provider： -1. [`set_default_openai_client`][agents.set_default_openai_client] 适用于你希望全局使用 `AsyncOpenAI` 实例作为 LLM 客户端的情况。这适用于 LLM 提供方拥有 OpenAI 兼容 API 端点，且你可以设置 `base_url` 与 `api_key` 的场景。可配置示例见 [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py)。 -2. [`ModelProvider`][agents.models.interface.ModelProvider] 位于 `Runner.run` 层级。这让你可以指定“本次运行中的所有智能体都使用自定义模型提供方”。可配置示例见 [examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py)。 -3. [`Agent.model`][agents.agent.Agent.model] 允许你在特定 Agent 实例上指定模型。这使你能够为不同智能体混用不同提供方。可配置示例见 [examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py)。使用多数可用模型的简单方式是通过 [LiteLLM 集成](./litellm.md)。 +1. 在你希望全局使用 `AsyncOpenAI` 实例作为 LLM 客户端时，[`set_default_openai_client`][agents.set_default_openai_client] 很有用。这适用于 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` 层级。这让你可以指定“本次 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 key 时，我们建议通过 `set_tracing_disabled()` 禁用追踪，或配置[不同的追踪进程](../tracing.md)。 +在你没有 `platform.openai.com` API key 的情况下，我们建议通过 `set_tracing_disabled()` 禁用追踪，或设置[其他追踪进程](../tracing.md)。 !!! note - 在这些示例中，我们使用 Chat Completions API/模型，因为大多数 LLM 提供方尚不支持 Responses API。如果你的 LLM 提供方支持它，我们建议使用 Responses。 + 在这些示例中，我们使用 Chat Completions API/模型，因为许多 LLM provider 仍不支持 Responses API。如果你的 LLM provider 支持，我们建议使用 Responses。 -## 高级模型选择与混用 +## 在单个工作流中混用模型 -在单个工作流中，你可能希望为每个智能体使用不同模型。例如，你可以为分流使用更小、更快的模型，同时为复杂任务使用更大、能力更强的模型。配置 [`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 +!!! 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 @@ -246,9 +251,9 @@ async def main(): ``` 1. 直接设置 OpenAI 模型名称。 -2. 提供一个 [`Model`][agents.models.interface.Model] 实现。 +2. 提供 [`Model`][agents.models.interface.Model] 实现。 -当你想进一步配置智能体使用的模型时，可以传入 [`ModelSettings`][agents.models.interface.ModelSettings]，它提供如 temperature 等可选模型配置参数。 +当你希望进一步配置某个智能体使用的模型时，可以传入 [`ModelSettings`][agents.models.interface.ModelSettings]，它提供诸如 temperature 等可选模型配置参数。 ```python from agents import Agent, ModelSettings @@ -261,19 +266,21 @@ english_agent = Agent( ) ``` -#### 常见高级 `ModelSettings` 选项 +## 高级 OpenAI Responses 设置 -当你使用 OpenAI Responses API 时，若干请求字段已在 `ModelSettings` 中有直接对应字段，因此你无需为它们使用 `extra_args`。 +当你使用 OpenAI Responses 路径并需要更精细控制时，请从 `ModelSettings` 开始。 -| 字段 | 用途 | -| --- | --- | -| `parallel_tool_calls` | 允许或禁止在同一轮中进行多次工具调用。 | -| `truncation` | 设置为 `"auto"`，让 Responses API 在上下文将溢出时丢弃最旧的会话项，而不是失败。 | -| `store` | 控制是否将生成的响应存储在服务端以供后续检索。这会影响依赖 response ID 的后续工作流，以及在 `store=False` 时可能需要回退到本地输入的会话压缩流程。 | -| `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)。 | +### 常见高级 `ModelSettings` 选项 + +使用 OpenAI Responses API 时，若干请求字段在 `ModelSettings` 中已有直接对应字段，因此无需通过 `extra_args` 传递。 + +- `parallel_tool_calls`：允许或禁止同一轮中的多个工具调用。 +- `truncation`：设置为 `"auto"`，让 Responses API 在上下文将溢出时丢弃最旧的会话项，而不是直接失败。 +- `store`：控制是否将生成的响应存储在服务端以便后续检索。这会影响依赖 response ID 的后续工作流，以及在 `store=False` 时可能需要回退到本地输入的会话压缩流程。 +- `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)。 ```python from agents import Agent, ModelSettings @@ -292,11 +299,31 @@ research_agent = Agent( ) ``` -当你设置 `store=False` 时，Responses API 不会保留该响应供后续服务端检索。这对无状态或零数据保留风格流程很有用，但也意味着原本可复用 response ID 的功能需要改为依赖本地管理状态。例如，当上一次响应未被存储时，[`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession] 会将其默认 `"auto"` 压缩路径切换为基于输入的压缩。参见[会话指南](../sessions/index.md#openai-responses-compaction-sessions)。 +当你设置 `store=False` 时，Responses API 不会保留该响应供后续服务端检索。这对无状态或零数据保留风格流程很有用，但也意味着原本可复用 response ID 的功能需要改为依赖本地管理状态。例如，当上一条响应未存储时，[`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession] 会将其默认 `"auto"` 压缩路径切换为基于输入的压缩。参见[会话指南](../sessions/index.md#openai-responses-compaction-sessions)。 + +### 传递 `extra_args` + +当你需要 SDK 顶层尚未直接暴露的 provider 特定字段或较新的请求字段时，请使用 `extra_args`。 + +另外，当你使用 OpenAI 的 Responses API 时，[还有一些其他可选参数](https://platform.openai.com/docs/api-reference/responses/create)（如 `user`、`service_tier` 等）。如果它们在顶层不可用，也可用 `extra_args` 传递。 + +```python +from agents import Agent, ModelSettings + +english_agent = Agent( + name="English agent", + instructions="You only speak English", + model="gpt-4.1", + model_settings=ModelSettings( + temperature=0.1, + extra_args={"service_tier": "flex", "user": "user_12345"}, + ), +) +``` -#### Runner 管理的重试 +## 由 Runner 管理的重试 -重试是仅运行时功能，并且是选择启用。除非你设置 `ModelSettings(retry=...)` 且重试策略决定重试，否则 SDK 不会重试常规模型请求。 +重试是仅运行时生效并需显式启用的功能。除非你设置 `ModelSettings(retry=...)` 且重试策略选择重试，否则 SDK 不会重试一般模型请求。 ```python from agents import Agent, ModelRetrySettings, ModelSettings, retry_policies @@ -326,23 +353,27 @@ agent = Agent( `ModelRetrySettings` 有三个字段： +
+ | 字段 | 类型 | 说明 | | --- | --- | --- | -| `max_retries` | `int \| None` | 初始请求后允许的重试次数。 | -| `backoff` | `ModelRetryBackoffSettings \| dict \| None` | 当策略决定重试但未返回显式延迟时使用的默认延迟策略。 | -| `policy` | `RetryPolicy \| None` | 决定是否重试的回调。此字段仅运行时有效，不会被序列化。 | +| `max_retries` | `int | None` | 初始请求之后允许的重试次数。 | +| `backoff` | `ModelRetryBackoffSettings | dict | None` | 当策略重试但未返回显式延迟时的默认延迟策略。 | +| `policy` | `RetryPolicy | None` | 决定是否重试的回调。该字段仅在运行时使用，不会被序列化。 | -重试策略会收到一个 [`RetryPolicyContext`][agents.retry.RetryPolicyContext]，其中包含： +
-- `attempt` 和 `max_retries`，便于你做基于尝试次数的决策。 -- `stream`，便于区分流式与非流式行为。 +重试策略会接收一个 [`RetryPolicyContext`][agents.retry.RetryPolicyContext]，其中包含： + +- `attempt` 和 `max_retries`，便于你基于尝试次数决策。 +- `stream`，用于在流式与非流式行为之间分支。 - `error`，用于原始检查。 -- 规范化信息，如 `status_code`、`retry_after`、`error_code`、`is_network_error`、`is_timeout` 和 `is_abort`。 -- 当底层模型适配器可提供重试建议时的 `provider_advice`。 +- `normalized` 事实，例如 `status_code`、`retry_after`、`error_code`、`is_network_error`、`is_timeout` 和 `is_abort`。 +- 当底层模型适配器可提供重试指引时的 `provider_advice`。 策略可返回： -- `True` / `False`，用于简单重试决策。 +- `True` / `False`，用于简单的重试决策。 - [`RetryDecision`][agents.retry.RetryDecision]，用于覆盖延迟或附加诊断原因。 SDK 在 `retry_policies` 中导出了一组现成辅助函数： @@ -350,58 +381,40 @@ SDK 在 `retry_policies` 中导出了一组现成辅助函数： | 辅助函数 | 行为 | | --- | --- | | `retry_policies.never()` | 始终不重试。 | -| `retry_policies.provider_suggested()` | 在可用时遵循提供方重试建议。 | -| `retry_policies.network_error()` | 匹配暂时性传输错误和超时失败。 | -| `retry_policies.http_status([...])` | 匹配指定 HTTP 状态码。 | -| `retry_policies.retry_after()` | 仅在存在 retry-after 提示时重试，并使用该延迟。 | +| `retry_policies.provider_suggested()` | 若可用则遵循 provider 的重试建议。 | +| `retry_policies.network_error()` | 匹配瞬时传输错误与超时失败。 | +| `retry_policies.http_status([...])` | 匹配选定的 HTTP 状态码。 | +| `retry_policies.retry_after()` | 仅当存在 retry-after 提示时重试，并使用该延迟。 | | `retry_policies.any(...)` | 任一嵌套策略选择重试即重试。 | -| `retry_policies.all(...)` | 仅当所有嵌套策略都选择重试才重试。 | +| `retry_policies.all(...)` | 仅当所有嵌套策略都选择重试时才重试。 | -组合策略时，`provider_suggested()` 是最安全的首个构件，因为当提供方能够区分时，它会保留提供方否决和可重放安全批准。 +组合策略时，`provider_suggested()` 是最安全的首个构件，因为当 provider 能区分时，它可保留 provider 的否决与重放安全批准。 ##### 安全边界 某些失败永远不会自动重试： -- 中止错误。 -- 提供方建议将重放标记为不安全的请求。 -- 流式运行中输出已开始且重放会不安全的情况。 +- Abort 错误。 +- provider 建议标记重放不安全的请求。 +- 流式 run 中输出已开始且重放会不安全的情况。 -使用 `previous_response_id` 或 `conversation_id` 的有状态后续请求也会被更保守地处理。对于这类请求，仅有 `network_error()` 或 `http_status([500])` 等非提供方谓词并不足够。重试策略应包含来自提供方的可重放安全批准，通常通过 `retry_policies.provider_suggested()`。 +使用 `previous_response_id` 或 `conversation_id` 的有状态后续请求也会被更保守地处理。对于这些请求，仅使用 `network_error()` 或 `http_status([500])` 等非 provider 谓词本身并不足够。重试策略应包含来自 provider 的重放安全批准，通常通过 `retry_policies.provider_suggested()`。 ##### Runner 与智能体合并行为 -`retry` 会在 Runner 级与智能体级 `ModelSettings` 之间做深度合并： +在 runner 级和智能体级 `ModelSettings` 之间，`retry` 会进行深度合并： -- 智能体可仅覆盖 `retry.max_retries`，并继承 Runner 的 `policy`。 -- 智能体可仅覆盖 `retry.backoff` 的一部分，并保留来自 Runner 的同级 backoff 字段。 -- `policy` 仅运行时有效，因此序列化后的 `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) 和 [`examples/basic/retry_litellm.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry_litellm.py)。 -当你需要 SDK 尚未在顶层直接暴露的提供方特定字段或较新请求字段时，请使用 `extra_args`。 - -另外，当你使用 OpenAI 的 Responses API 时，[还有一些其他可选参数](https://platform.openai.com/docs/api-reference/responses/create)（例如 `user`、`service_tier` 等）。如果它们在顶层不可用，也可以通过 `extra_args` 传递。 - -```python -from agents import Agent, ModelSettings - -english_agent = Agent( - name="English agent", - instructions="You only speak English", - model="gpt-4.1", - model_settings=ModelSettings( - temperature=0.1, - extra_args={"service_tier": "flex", "user": "user_12345"}, - ), -) -``` - -## 非 OpenAI 提供方故障排查 +## 非 OpenAI provider 故障排查 ### 追踪客户端错误 401 -如果你遇到与追踪相关的错误，这是因为追踪会上传到 OpenAI 服务端，而你没有 OpenAI API key。你有三种解决方式： +如果你遇到与追踪相关的错误，是因为追踪数据会上传到 OpenAI 服务端，而你没有 OpenAI API key。你有三种解决方案： 1. 完全禁用追踪：[`set_tracing_disabled(True)`][agents.set_tracing_disabled]。 2. 为追踪设置 OpenAI key：[`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]。该 API key 仅用于上传追踪，且必须来自 [platform.openai.com](https://platform.openai.com/)。 @@ -409,14 +422,14 @@ english_agent = Agent( ### Responses API 支持 -SDK 默认使用 Responses API，但多数其他 LLM 提供方尚不支持。因此你可能会看到 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 支持 -某些模型提供方不支持 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)。有时会导致类似如下错误： +某些模型 provider 不支持 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)。这有时会导致类似如下错误： ``` @@ -424,12 +437,24 @@ BadRequestError: Error code: 400 - {'error': {'message': "'response_format.type' ``` -这是某些模型提供方的不足——它们支持 JSON 输出，但不允许你指定输出所用的 `json_schema`。我们正在修复这个问题，但建议依赖支持 JSON schema 输出的提供方，否则你的应用会经常因 JSON 格式错误而中断。 +这是某些模型 provider 的不足——它们支持 JSON 输出，但不允许你指定用于输出的 `json_schema`。我们正在修复这一问题，但建议你依赖支持 JSON schema 输出的 provider，否则应用会经常因 JSON 格式错误而中断。 + +## 跨 provider 混用模型 + +你需要了解不同模型 provider 的功能差异，否则可能遇到错误。例如，OpenAI 支持 structured outputs、多模态输入、托管文件检索和网络检索，但许多其他 provider 不支持这些功能。请注意以下限制： + +- 不要向不支持的 provider 发送其无法理解的 `tools` +- 在调用仅文本模型前，先过滤掉多模态输入 +- 注意不支持 structured JSON 输出的 provider 偶尔会生成无效 JSON + +## LiteLLM + +对于需要将非 OpenAI provider 引入 Agents SDK 工作流的场景，LiteLLM 支持以尽力而为的 beta 形式提供。 + +如果你在此 SDK 中使用 OpenAI 模型，我们建议使用内置 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 路径，而非 LiteLLM。 -## 跨提供方混用模型 +如果你需要将 OpenAI 模型与非 OpenAI provider 组合使用，尤其是通过 Chat Completions 兼容 API，LiteLLM 可作为 beta 选项，但未必是每种设置下的最优选择。 -你需要了解不同模型提供方之间的功能差异，否则可能遇到错误。例如，OpenAI 支持 structured outputs、多模态输入、托管文件检索和网络检索，但许多其他提供方不支持这些功能。请注意以下限制： +如果你需要为非 OpenAI provider 使用 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]。 -- 不要向不理解这些 `tools` 的提供方发送不受支持的 `tools` -- 在调用仅支持文本的模型前，过滤掉多模态输入 -- 注意：不支持结构化 JSON 输出的提供方会偶尔生成无效 JSON。 \ No newline at end of file +如果你希望 LiteLLM 响应填充 SDK 的用量指标，请传入 `ModelSettings(include_usage=True)`。 \ No newline at end of file diff --git a/docs/zh/models/litellm.md b/docs/zh/models/litellm.md index a69ab37f2f..3352d3966e 100644 --- a/docs/zh/models/litellm.md +++ b/docs/zh/models/litellm.md @@ -2,103 +2,12 @@ search: exclude: true --- -# 通过 LiteLLM 使用任意模型 +# LiteLLM -!!! note + - LiteLLM 集成处于测试版。您可能会在某些模型提供商（尤其是较小的提供商）上遇到问题。请通过 [Github issues](https://github.com/openai/openai-agents-python/issues) 报告问题，我们会尽快修复。 +本页面已移动到[模型中的 LiteLLM 部分](index.md#litellm)。 -[LiteLLM](https://docs.litellm.ai/docs/) 是一个库，允许您通过统一接口使用 100+ 款模型。我们在 Agents SDK 中加入了 LiteLLM 集成，以便您使用任意 AI 模型。 - -## 设置 - -您需要确保可用 `litellm`。可以通过安装可选的 `litellm` 依赖组实现： - -```bash -pip install "openai-agents[litellm]" -``` - -完成后，您可以在任意智能体中使用 [`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel]。 - -## 示例 - -这是一个可直接运行的示例。运行时会提示输入模型名称和 API 密钥。例如，您可以输入： - -- 模型使用 `openai/gpt-4.1`，并提供您的 OpenAI API 密钥 -- 模型使用 `anthropic/claude-3-5-sonnet-20240620`，并提供您的 Anthropic API 密钥 -- 等等 - -有关 LiteLLM 支持的完整模型列表，请参见 [litellm providers 文档](https://docs.litellm.ai/docs/providers)。 - -```python -from __future__ import annotations - -import asyncio - -from agents import Agent, Runner, function_tool, set_tracing_disabled -from agents.extensions.models.litellm_model import LitellmModel - -@function_tool -def get_weather(city: str): - print(f"[debug] getting weather for {city}") - return f"The weather in {city} is sunny." - - -async def main(model: str, api_key: str): - agent = Agent( - name="Assistant", - instructions="You only respond in haikus.", - model=LitellmModel(model=model, api_key=api_key), - tools=[get_weather], - ) - - result = await Runner.run(agent, "What's the weather in Tokyo?") - print(result.final_output) - - -if __name__ == "__main__": - # First try to get model/api key from args - import argparse - - parser = argparse.ArgumentParser() - parser.add_argument("--model", type=str, required=False) - parser.add_argument("--api-key", type=str, required=False) - args = parser.parse_args() - - model = args.model - if not model: - model = input("Enter a model name for Litellm: ") - - api_key = args.api_key - if not api_key: - api_key = input("Enter an API key for Litellm: ") - - asyncio.run(main(model, api_key)) -``` - -## 使用数据追踪 - -如果希望 LiteLLM 的响应填充 Agents SDK 的使用指标，请在创建智能体时传入 `ModelSettings(include_usage=True)`。 - -```python -from agents import Agent, ModelSettings -from agents.extensions.models.litellm_model import LitellmModel - -agent = Agent( - name="Assistant", - model=LitellmModel(model="your/model", api_key="..."), - model_settings=ModelSettings(include_usage=True), -) -``` - -使用 `include_usage=True` 后，LiteLLM 请求会通过 `result.context_wrapper.usage` 报告 token 和请求计数，与内置的 OpenAI 模型一致。 - -## 疑难解答 - -如果您看到来自 LiteLLM 响应的 Pydantic 序列化器警告，请通过设置下述选项启用一个小型兼容性补丁： - -```bash -export OPENAI_AGENTS_ENABLE_LITELLM_SERIALIZER_PATCH=true -``` - -该自选开关会抑制已知的 LiteLLM 序列化器警告，同时保持正常行为。如果不需要，可将其关闭（未设置或 `false`）。 \ No newline at end of file +如果未自动重定向，请使用上方链接。 \ No newline at end of file diff --git a/docs/zh/usage.md b/docs/zh/usage.md index 961b8872b0..b02d7097e0 100644 --- a/docs/zh/usage.md +++ b/docs/zh/usage.md @@ -4,22 +4,22 @@ search: --- # 用法 -Agents SDK 会自动跟踪每次运行的 token 使用情况。你可以从运行上下文中访问它，并用它来监控成本、强制限制或记录分析数据。 +Agents SDK 会自动追踪每次运行的 token 使用量。你可以从运行上下文中访问它，并用它来监控成本、实施限制或记录分析数据。 -## 跟踪内容 +## 追踪内容 - **requests**: 发起的 LLM API 调用次数 - **input_tokens**: 发送的输入 token 总数 - **output_tokens**: 接收的输出 token 总数 - **total_tokens**: 输入 + 输出 -- **request_usage_entries**: 按请求划分的使用情况明细列表 +- **request_usage_entries**: 按请求划分的使用量明细列表 - **details**: - `input_tokens_details.cached_tokens` - `output_tokens_details.reasoning_tokens` -## 从运行中访问 usage +## 从运行中访问使用量 -在 `Runner.run(...)` 之后，通过 `result.context_wrapper.usage` 访问 usage。 +在 `Runner.run(...)` 之后，可通过 `result.context_wrapper.usage` 访问使用量。 ```python result = await Runner.run(agent, "What's the weather in Tokyo?") @@ -31,11 +31,11 @@ print("Output tokens:", usage.output_tokens) print("Total tokens:", usage.total_tokens) ``` -usage 会聚合该次运行期间的所有模型调用（包括工具调用和任务转移）。 +使用量会聚合该次运行期间的所有模型调用（包括工具调用和任务转移）。 -### 使用 LiteLLM 模型启用 usage +### 为 LiteLLM 模型启用使用量追踪 -LiteLLM 提供方默认不会上报 usage 指标。使用 [`LitellmModel`](models/litellm.md) 时，请向你的智能体传入 `ModelSettings(include_usage=True)`，这样 LiteLLM 的响应才会填充 `result.context_wrapper.usage`。 +LiteLLM 提供方默认不会上报使用量指标。使用 [`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel] 时，请向你的智能体传入 `ModelSettings(include_usage=True)`，以便 LiteLLM 响应填充 `result.context_wrapper.usage`。有关设置指南和示例，请参阅模型指南中的 [LiteLLM 说明](models/index.md#litellm)。 ```python from agents import Agent, ModelSettings, Runner @@ -51,9 +51,9 @@ result = await Runner.run(agent, "What's the weather in Tokyo?") print(result.context_wrapper.usage.total_tokens) ``` -## 按请求 usage 跟踪 +## 按请求追踪使用量 -SDK 会自动在 `request_usage_entries` 中跟踪每个 API 请求的 usage，这对于精细化成本计算和监控上下文窗口消耗非常有用。 +SDK 会自动在 `request_usage_entries` 中追踪每个 API 请求的使用量，这有助于进行精细化成本计算和上下文窗口消耗监控。 ```python result = await Runner.run(agent, "What's the weather in Tokyo?") @@ -62,9 +62,9 @@ for i, request in enumerate(result.context_wrapper.usage.request_usage_entries): print(f"Request {i + 1}: {request.input_tokens} in, {request.output_tokens} out") ``` -## 在会话中访问 usage +## 在会话中访问使用量 -当你使用 `Session`（例如 `SQLiteSession`）时，每次调用 `Runner.run(...)` 都会返回该次运行的 usage。会话会为上下文维护对话历史，但每次运行的 usage 是独立的。 +使用 `Session`（例如 `SQLiteSession`）时，每次调用 `Runner.run(...)` 都会返回该次运行对应的使用量。会话会为上下文维护对话历史，但每次运行的使用量彼此独立。 ```python session = SQLiteSession("my_conversation") @@ -76,11 +76,11 @@ second = await Runner.run(agent, "Can you elaborate?", session=session) print(second.context_wrapper.usage.total_tokens) # Usage for second run ``` -请注意，虽然会话会在多次运行之间保留对话上下文，但每次 `Runner.run()` 调用返回的 usage 指标仅代表该次执行。在会话中，之前的消息可能会在每次运行时作为输入再次提供，这会影响后续轮次的输入 token 计数。 +请注意，虽然会话会在多次运行之间保留对话上下文，但每次 `Runner.run()` 调用返回的使用量指标仅代表该次执行。在会话中，之前的消息可能会在每次运行时作为输入重新提供，这会影响后续轮次中的输入 token 计数。 -## 在 hooks 中使用 usage +## 在 hooks 中使用使用量 -如果你在使用 `RunHooks`，传递给每个 hook 的 `context` 对象都包含 `usage`。这让你可以在关键生命周期节点记录 usage。 +如果你正在使用 `RunHooks`，传递给每个 hook 的 `context` 对象都包含 `usage`。这使你可以在关键生命周期节点记录使用量。 ```python class MyHooks(RunHooks): @@ -91,9 +91,9 @@ class MyHooks(RunHooks): ## API 参考 -详细 API 文档请参阅： +有关详细 API 文档，请参阅： -- [`Usage`][agents.usage.Usage] - usage 跟踪数据结构 -- [`RequestUsage`][agents.usage.RequestUsage] - 按请求划分的 usage 详情 -- [`RunContextWrapper`][agents.run.RunContextWrapper] - 从运行上下文访问 usage -- [`RunHooks`][agents.run.RunHooks] - 挂接 usage 跟踪生命周期 \ No newline at end of file +- [`Usage`][agents.usage.Usage] - 使用量追踪数据结构 +- [`RequestUsage`][agents.usage.RequestUsage] - 按请求划分的使用量详情 +- [`RunContextWrapper`][agents.run.RunContextWrapper] - 从运行上下文访问使用量 +- [`RunHooks`][agents.run.RunHooks] - 接入使用量追踪生命周期 hooks \ No newline at end of file