From dc897424fd7afc3ddee0f154b7ca3408839ecbe6 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Thu, 12 Mar 2026 09:03:47 +0000 Subject: [PATCH] Update all translated document pages --- docs/ja/examples.md | 64 ++++++----- docs/ja/models/index.md | 218 ++++++++++++++++++++++++----------- docs/ja/running_agents.md | 236 +++++++++++++++++++------------------- docs/ko/examples.md | 58 +++++----- docs/ko/models/index.md | 224 +++++++++++++++++++++++++----------- docs/ko/running_agents.md | 201 ++++++++++++++++---------------- docs/zh/examples.md | 60 +++++----- docs/zh/models/index.md | 202 ++++++++++++++++++++++---------- docs/zh/running_agents.md | 199 ++++++++++++++++---------------- 9 files changed, 867 insertions(+), 595 deletions(-) diff --git a/docs/ja/examples.md b/docs/ja/examples.md index 35b5004f97..f765de1045 100644 --- a/docs/ja/examples.md +++ b/docs/ja/examples.md @@ -4,7 +4,7 @@ search: --- # コード例 -[repo](https://github.com/openai/openai-agents-python/tree/main/examples) の examples セクションで、 SDK のさまざまなサンプル実装を確認できます。examples は、異なるパターンと機能を示す複数のカテゴリーに整理されています。 +[repo](https://github.com/openai/openai-agents-python/tree/main/examples) の examples セクションで、SDK のさまざまなサンプル実装をご覧いただけます。examples は、異なるパターンと機能を示す複数のカテゴリーに整理されています。 ## カテゴリー @@ -13,46 +13,48 @@ search: - 決定論的ワークフロー - Agents as tools - - エージェントの並列実行 + - 並列エージェント実行 - 条件付きツール使用 - - 入出力ガードレール - - 審判としての LLM + - 入力 / 出力ガードレール + - 判定者としての LLM - ルーティング - ストリーミングガードレール - **[basic](https://github.com/openai/openai-agents-python/tree/main/examples/basic):** これらのコード例では、次のような SDK の基本機能を紹介しています。 - - Hello world のコード例 ( デフォルトモデル、 GPT-5、 open-weight モデル ) + - Hello World のコード例（デフォルトモデル、GPT-5、open-weight model） - エージェントライフサイクル管理 - 動的システムプロンプト - - ストリーミング出力 ( テキスト、項目、関数呼び出し引数 ) - - ターン間で共有セッションヘルパーを使用する Responses websocket transport (`examples/basic/stream_ws.py`) + - ストリーミング出力（text、items、function call args） + - ターン間で共有セッションヘルパーを使う Responses websocket transport（`examples/basic/stream_ws.py`） - プロンプトテンプレート - - ファイル処理 ( ローカルおよびリモート、画像および PDF ) - - 使用状況トラッキング + - ファイル処理（ローカル / リモート、画像 / PDF） + - 使用状況追跡 + - Runner 管理の retry 設定（`examples/basic/retry.py`） + - LiteLLM を使った Runner 管理の retry（`examples/basic/retry_litellm.py`） - 非 strict な出力型 - - 以前の response ID の使用 + - 前回 response ID の使用 - **[customer_service](https://github.com/openai/openai-agents-python/tree/main/examples/customer_service):** 航空会社向けのカスタマーサービスシステムのコード例です。 - **[financial_research_agent](https://github.com/openai/openai-agents-python/tree/main/examples/financial_research_agent):** - 金融データ分析向けのエージェントとツールを使った構造化リサーチワークフローを示す、金融リサーチエージェントです。 + 金融データ分析のためのエージェントとツールを使った構造化された調査ワークフローを示す、financial research agent です。 - **[handoffs](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs):** - メッセージフィルタリングを伴うエージェントハンドオフの実践的なコード例をご覧ください。 + メッセージフィルタリングを用いたエージェントのハンドオフの実践的なコード例をご覧ください。 - **[hosted_mcp](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp):** - hosted MCP (Model Context Protocol) コネクターと承認の使用方法を示すコード例です。 + hosted MCP（Model context protocol）コネクタと承認の使い方を示すコード例です。 - **[mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp):** - MCP (Model Context Protocol) を用いたエージェントの構築方法を学べます。内容は次のとおりです。 + MCP（Model context protocol）を使ってエージェントを構築する方法を学べます。内容は次のとおりです。 - - ファイルシステムのコード例 + - Filesystem のコード例 - Git のコード例 - MCP prompt server のコード例 - - SSE (Server-Sent Events) のコード例 + - SSE（Server-Sent Events）のコード例 - Streamable HTTP のコード例 - **[memory](https://github.com/openai/openai-agents-python/tree/main/examples/memory):** @@ -68,36 +70,36 @@ search: - Responses compaction セッションストレージ - **[model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):** - カスタムプロバイダーや LiteLLM 連携を含め、 SDK で OpenAI 以外のモデルを使う方法を確認できます。 + カスタムプロバイダーや LiteLLM 統合を含め、SDK で非 OpenAI モデルを使う方法を紹介します。 - **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):** SDK を使ってリアルタイム体験を構築する方法を示すコード例です。内容は次のとおりです。 - - 構造化テキストおよび画像メッセージを使った Web アプリケーションパターン - - コマンドラインの音声ループと再生処理 - - WebSocket 経由の Twilio Media Streams 連携 - - Realtime Calls API attach フローを使用した Twilio SIP 連携 + - 構造化 text / image メッセージを使った Web アプリケーションパターン + - コマンドライン音声ループと再生処理 + - WebSocket 経由の Twilio Media Streams 統合 + - Realtime Calls API の attach フローを使った Twilio SIP 統合 - **[reasoning_content](https://github.com/openai/openai-agents-python/tree/main/examples/reasoning_content):** reasoning content と structured outputs の扱い方を示すコード例です。 - **[research_bot](https://github.com/openai/openai-agents-python/tree/main/examples/research_bot):** - 複雑なマルチエージェントリサーチワークフローを示す、シンプルな ディープリサーチ クローンです。 + 複雑なマルチエージェント調査ワークフローを示す、シンプルなディープリサーチ clone です。 - **[tools](https://github.com/openai/openai-agents-python/tree/main/examples/tools):** - OAI hosted tools と、次のような実験的な Codex ツール機能の実装方法を学べます。 + 次のような OpenAI がホストするツールと実験的な Codex tooling の実装方法を学べます。 - Web 検索 とフィルター付き Web 検索 - ファイル検索 - - Code interpreter - - インラインスキル付き hosted container shell (`examples/tools/container_shell_inline_skill.py`) - - スキル参照付き hosted container shell (`examples/tools/container_shell_skill_reference.py`) - - ローカルスキル付き local shell (`examples/tools/local_shell_skill.py`) - - namespace と遅延ツールを使う tool search (`examples/tools/tool_search.py`) + - Code Interpreter + - インラインスキル付き hosted container shell（`examples/tools/container_shell_inline_skill.py`） + - スキル参照付き hosted container shell（`examples/tools/container_shell_skill_reference.py`） + - ローカルスキル付き local shell（`examples/tools/local_shell_skill.py`） + - namespace と deferred tools を使った tool search（`examples/tools/tool_search.py`） - コンピュータ操作 - 画像生成 - - 実験的な Codex ツールワークフロー (`examples/tools/codex.py`) - - 実験的な Codex 同一スレッドワークフロー (`examples/tools/codex_same_thread.py`) + - 実験的な Codex ツールワークフロー（`examples/tools/codex.py`） + - 実験的な Codex same-thread ワークフロー（`examples/tools/codex_same_thread.py`） - **[voice](https://github.com/openai/openai-agents-python/tree/main/examples/voice):** - ストリーミング音声のコード例を含む、 TTS と STT モデルを使用した音声エージェントのコード例をご覧ください。 \ No newline at end of file + ストリーミング音声のコード例を含む、TTS / STT モデルを使った音声エージェントのコード例をご覧ください。 \ No newline at end of file diff --git a/docs/ja/models/index.md b/docs/ja/models/index.md index d633118999..f7dbbfece0 100644 --- a/docs/ja/models/index.md +++ b/docs/ja/models/index.md @@ -4,39 +4,39 @@ search: --- # モデル -Agents SDK には、OpenAI モデルをすぐに使える形で 2 種類サポートしています。 +Agents SDK には、すぐに使える OpenAI モデルのサポートが 2 種類あります。 -- **推奨**: [`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]。 ## モデル設定の選択 -設定に応じて、このページを次の順序で参照してください。 +設定に応じて、次の順序でこのページを参照してください。 -| Goal | Start here | +| 目標 | 開始位置 | | --- | --- | -| SDK 既定値で OpenAI ホストモデルを使う | [OpenAI モデル](#openai-models) | +| 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) | +| 1 つのワークフローでモデル / プロバイダーを混在させる | [高度なモデル選択と混在](#advanced-model-selection-and-mixing) と [プロバイダー間でのモデル混在](#mixing-models-across-providers) | | プロバイダー互換性の問題をデバッグする | [非 OpenAI プロバイダーのトラブルシューティング](#troubleshooting-non-openai-providers) | ## 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) をエージェントに設定することを推奨します。 +`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 つあります。 +[`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 +55,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,21 +71,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 が送信するコンピュータツールの 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] ファクトリーを使う 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 モデル -カスタム `model_settings` なしで GPT-5 以外のモデル名を渡した場合、SDK は任意モデルと互換性のある汎用 `ModelSettings` に戻ります。 +カスタム `model_settings` なしで非 GPT-5 モデル名を渡すと、SDK は任意モデル互換の汎用 `ModelSettings` に戻ります。 ### Responses 専用のツール検索機能 @@ -93,13 +93,13 @@ preview 互換リクエストでは、`environment` と表示サイズを先に - [`ToolSearchTool`][agents.tool.ToolSearchTool] - [`tool_namespace()`][agents.tool.tool_namespace] -- `@function_tool(defer_loading=True)` およびその他の deferred-loading Responses ツール surface +- `@function_tool(defer_loading=True)` とその他の deferred-loading Responses ツール機能 -これらの機能は Chat Completions モデルおよび非 Responses バックエンドでは拒否されます。deferred-loading ツールを使う場合は、エージェントに `ToolSearchTool()` を追加し、名前空間名のみや deferred 専用関数名を強制するのではなく、`auto` または `required` の tool choice でモデルにツールをロードさせてください。設定詳細と現時点の制約は [Tools](../tools.md#hosted-tool-search) を参照してください。 +これらは Chat Completions モデルおよび非 Responses バックエンドでは拒否されます。deferred-loading ツールを使う場合は、エージェントに `ToolSearchTool()` を追加し、モデルが `auto` または `required` の tool choice でツールを読み込むようにしてください。名前空間名のみや deferred 専用関数名の強制は避けてください。設定詳細と現在の制約は [Tools](../tools.md#hosted-tool-search) を参照してください。 ### 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 +107,11 @@ from agents import set_default_openai_responses_transport set_default_openai_responses_transport("websocket") ``` -これは、既定の OpenAI プロバイダーで解決される OpenAI Responses モデル（`"gpt-5.4"` のような文字列モデル名を含む）に影響します。 +これは、デフォルト OpenAI プロバイダーで解決される 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=...)` を渡す場合は、グローバルデフォルトではなくそのプロバイダーがトランスポート選択を制御します。 -プロバイダー単位または実行単位で websocket トランスポートを設定することもできます。 +websocket トランスポートは、プロバイダー単位または実行単位でも設定できます。 ```python from agents import Agent, OpenAIProvider, RunConfig, Runner @@ -130,14 +130,14 @@ result = await Runner.run( ) ``` -プレフィックスベースのモデルルーティングが必要な場合（例: 1 回の実行で `openai/...` と `litellm/...` のモデル名を混在）、代わりに [`MultiProvider`][agents.MultiProvider] を使い、そこで `openai_use_responses_websocket=True` を設定してください。 +プレフィックスベースのモデルルーティング（例: 1 回の実行で `openai/...` と `litellm/...` を混在） が必要な場合は、[`MultiProvider`][agents.MultiProvider] を使い、そこで `openai_use_responses_websocket=True` を設定してください。 -`MultiProvider` は 2 つの歴史的既定値を維持しています。 +`MultiProvider` は 2 つの過去互換デフォルトを維持します。 - `openai/...` は OpenAI プロバイダーのエイリアスとして扱われるため、`openai/gpt-4.1` はモデル `gpt-4.1` としてルーティングされます。 -- 未知のプレフィックスはそのまま渡されず、`UserError` を発生させます。 +- 不明なプレフィックスはパススルーされず、`UserError` を発生させます。 -OpenAI 互換 endpoint で、リテラルな名前空間付きモデル ID を期待する場合は、明示的に pass-through 動作を有効化してください。websocket 有効構成では、`MultiProvider` 側でも `openai_use_responses_websocket=True` を維持してください。 +OpenAI 互換エンドポイントで、名前空間付きモデル ID の文字列そのものを期待する場合は、明示的にパススルー動作を有効化してください。websocket 有効構成では、`MultiProvider` 側でも `openai_use_responses_websocket=True` を維持します。 ```python from agents import Agent, MultiProvider, RunConfig, Runner @@ -163,25 +163,25 @@ 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 互換 endpoint または proxy を使う場合、websocket トランスポートには互換性のある websocket `/responses` endpoint も必要です。これらの構成では `websocket_base_url` を明示設定する必要がある場合があります。 +カスタム OpenAI 互換エンドポイントやプロキシを使う場合、websocket トランスポートには互換性のある websocket `/responses` エンドポイントも必要です。これらの構成では `websocket_base_url` を明示的に設定する必要がある場合があります。 -注意点: +注意: -- これは websocket トランスポート上の Responses API であり、[Realtime API](../realtime/guide.md) ではありません。Chat Completions や、Responses websocket `/responses` endpoint をサポートしない非 OpenAI プロバイダーには適用されません。 -- 環境で利用可能でない場合は `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` エンドポイントをサポートしない非 OpenAI プロバイダーには適用されません。 +- 環境で未導入の場合は `websockets` パッケージをインストールしてください。 +- websocket トランスポート有効化後は [`Runner.run_streamed()`][agents.run.Runner.run_streamed] を直接使えます。複数ターンのワークフローで同一 websocket 接続をターン間（およびネストした Agents-as-tools 呼び出し）で再利用したい場合は、[`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 モデル -ほとんどの非 OpenAI モデルは [LiteLLM integration](./litellm.md) 経由で利用できます。まず、litellm dependency group をインストールします。 +ほとんどの非 OpenAI モデルは [LiteLLM integration](./litellm.md) 経由で利用できます。まず、litellm 依存グループをインストールします。 ```bash pip install "openai-agents[litellm]" ``` -次に、`litellm/` プレフィックス付きで任意の [supported models](https://docs.litellm.ai/docs/providers) を使います。 +次に、`litellm/` プレフィックスで任意の [対応モデル](https://docs.litellm.ai/docs/providers) を使います。 ```python claude_agent = Agent(model="litellm/anthropic/claude-3-5-sonnet-20240620", ...) @@ -190,21 +190,21 @@ gemini_agent = Agent(model="litellm/gemini/gemini-2.5-flash-preview-04-17", ...) ### 非 OpenAI モデルを使う他の方法 -他の LLM プロバイダーは、さらに 3 つの方法で統合できます（コード例は [こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)）。 +他の LLM プロバイダーはさらに 3 つの方法で統合できます（例は [こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)）。 -1. [`set_default_openai_client`][agents.set_default_openai_client] は、`AsyncOpenAI` のインスタンスを LLM クライアントとしてグローバルに使いたい場合に便利です。これは LLM プロバイダーが OpenAI 互換 API endpoint を持ち、`base_url` と `api_key` を設定できる場合向けです。設定可能な例は [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py) を参照してください。 -2. [`ModelProvider`][agents.models.interface.ModelProvider] は `Runner.run` レベルです。これにより「この実行のすべてのエージェントでカスタムモデルプロバイダーを使う」と指定できます。設定可能な例は [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 プロバイダーが 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) もあります。 -`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 / model を使っています。LLM プロバイダーが対応している場合は、Responses の使用を推奨します。 + これらの例では、ほとんどの LLM プロバイダーがまだ Responses API をサポートしていないため、Chat Completions API / モデルを使っています。LLM プロバイダーが対応している場合は Responses の使用を推奨します。 ## 高度なモデル選択と混在 -1 つのワークフロー内で、エージェントごとに異なるモデルを使いたい場合があります。たとえば、トリアージには小型で高速なモデルを使い、複雑なタスクにはより大型で高性能なモデルを使えます。[`Agent`][agents.Agent] を設定する際は、次のいずれかで特定モデルを選択できます。 +1 つのワークフロー内で、エージェントごとに異なるモデルを使いたい場合があります。たとえば、トリアージには小型で高速なモデルを使い、複雑なタスクには大型で高性能なモデルを使えます。[`Agent`][agents.Agent] を設定する際は、次のいずれかで特定モデルを選択できます。 1. モデル名を渡す。 2. 任意のモデル名 + その名前を Model インスタンスにマップできる [`ModelProvider`][agents.models.interface.ModelProvider] を渡す。 @@ -212,7 +212,7 @@ gemini_agent = Agent(model="litellm/gemini/gemini-2.5-flash-preview-04-17", ...) !!!note - SDK は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] と [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] の両方の shape をサポートしていますが、2 つの shape はサポートする機能とツールのセットが異なるため、ワークフローごとに 1 つのモデル shape を使うことを推奨します。ワークフローでモデル shape の混在が必要な場合は、使用中のすべての機能が両方で利用可能であることを確認してください。 + SDK は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] と [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] の両方をサポートしますが、2 つは対応機能とツールセットが異なるため、各ワークフローでは単一のモデル形状を使うことを推奨します。モデル形状を混在させる必要がある場合は、使っている機能が両方で利用可能であることを確認してください。 ```python from agents import Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel @@ -248,7 +248,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,17 +261,18 @@ english_agent = Agent( ) ``` -#### 一般的な高度な `ModelSettings` オプション +#### 一般的な高度 `ModelSettings` オプション OpenAI Responses API を使う場合、いくつかのリクエストフィールドにはすでに直接対応する `ModelSettings` フィールドがあるため、それらに `extra_args` は不要です。 -| Field | Use it for | +| フィールド | 用途 | | --- | --- | -| `parallel_tool_calls` | 同一ターンで複数のツール呼び出しを許可または禁止します。 | -| `truncation` | コンテキスト超過時に失敗する代わりに、Responses API に最も古い会話項目を削除させるには `"auto"` を設定します。 | -| `prompt_cache_retention` | たとえば `"24h"` のように、キャッシュされた prompt prefix をより長く保持します。 | -| `response_include` | `web_search_call.action.sources`、`file_search_call.results`、`reasoning.encrypted_content` など、よりリッチな response payload を要求します。 | +| `parallel_tool_calls` | 同一ターンで複数ツール呼び出しを許可 / 禁止します。 | +| `truncation` | コンテキスト超過時に失敗させず、Responses API が古い会話項目を削除できるよう `"auto"` を設定します。 | +| `prompt_cache_retention` | たとえば `"24h"` で、キャッシュ済みプロンプト接頭辞をより長く保持します。 | +| `response_include` | `web_search_call.action.sources`、`file_search_call.results`、`reasoning.encrypted_content` など、より豊富なレスポンスペイロードを要求します。 | | `top_logprobs` | 出力テキストの top-token logprobs を要求します。SDK は `message.output_text.logprobs` も自動追加します。 | +| `retry` | モデル呼び出しで Runner 管理の再試行設定を有効化します。[Runner 管理再試行](#runner-managed-retries) を参照してください。 | ```python from agents import Agent, ModelSettings @@ -289,9 +290,94 @@ research_agent = Agent( ) ``` -プロバイダー固有、または SDK がまだトップレベルで直接公開していない新しいリクエストフィールドが必要な場合は `extra_args` を使ってください。 +#### Runner 管理再試行 -また、OpenAI の Responses API を使う場合、[他にもいくつかの任意パラメーター](https://platform.openai.com/docs/api-reference/responses/create)（例: `user`、`service_tier` など）があります。トップレベルで利用できない場合は、これらも `extra_args` で渡せます。 +再試行は実行時限定で、明示的に有効化する必要があります。`ModelSettings(retry=...)` を設定し、かつ再試行ポリシーが再試行を選択しない限り、SDK は一般的なモデルリクエストを再試行しません。 + +```python +from agents import Agent, ModelRetrySettings, ModelSettings, retry_policies + +agent = Agent( + name="Assistant", + model="gpt-5.4", + model_settings=ModelSettings( + retry=ModelRetrySettings( + max_retries=4, + backoff={ + "initial_delay": 0.5, + "max_delay": 5.0, + "multiplier": 2.0, + "jitter": True, + }, + policy=retry_policies.any( + retry_policies.provider_suggested(), + retry_policies.retry_after(), + retry_policies.network_error(), + retry_policies.http_status([408, 409, 429, 500, 502, 503, 504]), + ), + ) + ), +) +``` + +`ModelRetrySettings` には 3 つのフィールドがあります。 + +| フィールド | 型 | 注記 | +| --- | --- | --- | +| `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` + +ポリシーは次のいずれかを返せます。 + +- 単純な再試行判定の `True` / `False` +- 遅延上書きや診断理由付与を行いたい場合の [`RetryDecision`][agents.retry.RetryDecision] + +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(...)` | ネストされたポリシーすべてが有効な場合のみ再試行。 | + +ポリシーを合成する場合、`provider_suggested()` は最初の構成要素として最も安全です。これは、プロバイダーが区別可能な場合に veto と replay-safety 承認を保持するためです。 + +##### 安全性境界 + +一部の失敗は自動再試行されません。 + +- Abort エラー。 +- プロバイダー指針で replay が unsafe とされたリクエスト。 +- 出力開始後で replay が unsafe になるストリーミング実行。 + +`previous_response_id` または `conversation_id` を使う状態保持の後続リクエストも、より保守的に扱われます。これらでは `network_error()` や `http_status([500])` のような非プロバイダー述語だけでは不十分です。再試行ポリシーには、通常 `retry_policies.provider_suggested()` を通じたプロバイダーの replay-safe 承認を含める必要があります。 + +##### Runner とエージェントのマージ挙動 + +`retry` は Runner レベルとエージェントレベルの `ModelSettings` 間で深くマージされます。 + +- エージェントは `retry.max_retries` のみ上書きし、Runner の `policy` を継承できます。 +- エージェントは `retry.backoff` の一部のみ上書きし、兄弟 backoff フィールドを Runner から維持できます。 +- `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 @@ -311,22 +397,22 @@ english_agent = Agent( ### トレーシングクライアントエラー 401 -トレーシング関連エラーが出る場合、trace が OpenAI サーバーにアップロードされる一方で OpenAI API キーがないことが原因です。解決方法は 3 つあります。 +トレーシング関連エラーが出る場合、トレースが OpenAI サーバーへアップロードされる一方で OpenAI API キーがないことが原因です。解決方法は 3 つあります。 1. トレーシングを完全に無効化する: [`set_tracing_disabled(True)`][agents.set_tracing_disabled]。 -2. トレーシング用 OpenAI キーを設定する: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]。この API キーは trace のアップロードにのみ使われ、[platform.openai.com](https://platform.openai.com/) のキーである必要があります。 -3. 非 OpenAI のトレーシングプロセッサーを使う。[トレーシング docs](../tracing.md#custom-tracing-processors) を参照してください。 +2. トレーシング用 OpenAI キーを設定する: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]。この API キーはトレースアップロードにのみ使われ、[platform.openai.com](https://platform.openai.com/) のものが必要です。 +3. 非 OpenAI のトレースプロセッサーを使う。[トレーシングドキュメント](../tracing.md#custom-tracing-processors) を参照してください。 ### Responses API サポート -SDK は既定で Responses API を使いますが、ほとんどの他 LLM プロバイダーはまだ対応していません。その結果、404 などの問題が発生する場合があります。解決には次の 2 つの方法があります。 +SDK はデフォルトで Responses API を使いますが、ほとんどの他 LLM プロバイダーはまだ対応していません。その結果、404 などの問題が発生することがあります。解決には 2 つの方法があります。 -1. [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api] を呼び出す。これは、環境変数で `OPENAI_API_KEY` と `OPENAI_BASE_URL` を設定している場合に機能します。 -2. [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] を使う。コード例は [こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/) にあります。 +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) をサポートしていません。これにより、次のようなエラーが発生することがあります。 +一部のモデルプロバイダーは [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) をサポートしていません。これにより、次のようなエラーが発生する場合があります。 ``` @@ -334,12 +420,12 @@ BadRequestError: Error code: 400 - {'error': {'message': "'response_format.type' ``` -これは一部モデルプロバイダーの制約です。JSON 出力はサポートしていても、出力に使う `json_schema` を指定できません。現在修正を進めていますが、JSON schema 出力をサポートするプロバイダーの利用を推奨します。そうでない場合、形式不正な JSON によりアプリが頻繁に壊れるためです。 +これは一部モデルプロバイダーの制約です。JSON 出力はサポートしていても、出力で使う `json_schema` を指定できません。この問題の修正を進めていますが、JSON schema 出力をサポートするプロバイダーへの依存を推奨します。そうでない場合、不正な JSON によりアプリが頻繁に壊れる可能性があります。 ## プロバイダー間でのモデル混在 -モデルプロバイダー間の機能差を把握しておく必要があります。そうしないとエラーになる場合があります。たとえば OpenAI は structured outputs、マルチモーダル入力、ホスト型ファイル検索と Web 検索をサポートしていますが、他の多くのプロバイダーはこれらをサポートしていません。次の制約に注意してください。 +モデルプロバイダー間の機能差を把握しておく必要があります。把握していないとエラーが発生する可能性があります。たとえば OpenAI は structured outputs、マルチモーダル入力、ホスト型ファイル検索と Web 検索をサポートしますが、多くの他プロバイダーはこれらをサポートしません。次の制約に注意してください。 - 非対応の `tools` を理解しないプロバイダーに送らない -- テキスト専用モデルを呼ぶ前にマルチモーダル入力を除外する -- structured JSON 出力をサポートしないプロバイダーは、ときどき無効な JSON を生成する点に注意する \ No newline at end of file +- テキスト専用モデル呼び出し前にマルチモーダル入力を除外する +- structured JSON 出力非対応プロバイダーは無効な JSON を時折生成する可能性があることを認識する \ No newline at end of file diff --git a/docs/ja/running_agents.md b/docs/ja/running_agents.md index 97d94cbcc4..88bc32b952 100644 --- a/docs/ja/running_agents.md +++ b/docs/ja/running_agents.md @@ -4,11 +4,11 @@ search: --- # エージェントの実行 -エージェントは [`Runner`][agents.run.Runner] クラスを通じて実行できます。選択肢は 3 つあります。 +[`Runner`][agents.run.Runner] クラスを介してエージェントを実行できます。方法は 3 つあります。 1. [`Runner.run()`][agents.run.Runner.run]。非同期で実行され、[`RunResult`][agents.result.RunResult] を返します。 -2. [`Runner.run_sync()`][agents.run.Runner.run_sync]。同期メソッドで、内部では `.run()` を実行するだけです。 -3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed]。非同期で実行され、[`RunResultStreaming`][agents.result.RunResultStreaming] を返します。LLM をストリーミングモードで呼び出し、受信したイベントをそのままストリーミングします。 +2. [`Runner.run_sync()`][agents.run.Runner.run_sync]。同期メソッドで、内部的には `.run()` を実行するだけです。 +3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed]。非同期で実行され、[`RunResultStreaming`][agents.result.RunResultStreaming] を返します。ストリーミングモードで LLM を呼び出し、受信したイベントをそのままストリーミングします。 ```python from agents import Agent, Runner @@ -23,46 +23,46 @@ async def main(): # Infinite loop's dance ``` -詳しくは [実行結果ガイド](results.md) をご覧ください。 +詳細は [結果ガイド](results.md) を参照してください。 ## Runner のライフサイクルと設定 ### エージェントループ -`Runner` の run メソッドを使う際は、開始エージェントと入力を渡します。入力には次を指定できます。 +`Runner` の run メソッドを使うときは、開始エージェントと入力を渡します。入力には次を指定できます。 -- 文字列（ユーザーメッセージとして扱われます） +- 文字列 (ユーザーメッセージとして扱われます) - OpenAI Responses API 形式の入力アイテムのリスト - 中断された実行を再開する場合の [`RunState`][agents.run_state.RunState] -その後、runner は次のループを実行します。 +その後、Runner は次のループを実行します。 1. 現在の入力を使って、現在のエージェントに対して LLM を呼び出します。 2. LLM が出力を生成します。 - 1. LLM が `final_output` を返した場合、ループを終了して実行結果を返します。 + 1. LLM が `final_output` を返した場合、ループは終了し、結果を返します。 2. LLM がハンドオフを行った場合、現在のエージェントと入力を更新し、ループを再実行します。 - 3. LLM がツール呼び出しを生成した場合、そのツール呼び出しを実行し、結果を追加してループを再実行します。 + 3. LLM がツール呼び出しを生成した場合、それらを実行し、結果を追記してループを再実行します。 3. 渡された `max_turns` を超えた場合、[`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] 例外を送出します。 !!! note - LLM の出力を「最終出力」とみなす条件は、期待する型のテキスト出力を生成し、かつツール呼び出しがないことです。 + LLM 出力を「最終出力」とみなす条件は、期待された型のテキスト出力を生成し、かつツール呼び出しがないことです。 ### ストリーミング -ストリーミングを使うと、LLM 実行中のストリーミングイベントも受け取れます。ストリーム完了後、[`RunResultStreaming`][agents.result.RunResultStreaming] には、その実行に関する完全な情報（生成されたすべての新しい出力を含む）が格納されます。ストリーミングイベントは `.stream_events()` で取得できます。詳しくは [ストリーミングガイド](streaming.md) をご覧ください。 +ストリーミングを使うと、LLM 実行中のストリーミングイベントも受け取れます。ストリーム完了後、[`RunResultStreaming`][agents.result.RunResultStreaming] には、生成されたすべての新しい出力を含む実行の完全な情報が入ります。ストリーミングイベントは `.stream_events()` で取得できます。詳細は [ストリーミングガイド](streaming.md) を参照してください。 -#### Responses WebSocket トランスポート（任意ヘルパー） +#### Responses WebSocket トランスポート (任意ヘルパー) -OpenAI Responses websocket transport を有効化した場合でも、通常の `Runner` API をそのまま使用できます。接続再利用には websocket session helper を推奨しますが、必須ではありません。 +OpenAI Responses websocket トランスポートを有効化しても、通常の `Runner` API をそのまま使えます。接続再利用には websocket session helper の利用を推奨しますが、必須ではありません。 -これは websocket transport 経由の Responses API であり、[Realtime API](realtime/guide.md) ではありません。 +これは websocket トランスポート上の Responses API であり、[Realtime API](realtime/guide.md) ではありません。 -トランスポート選択ルールや、具体的なモデルオブジェクト / カスタムプロバイダーに関する注意点は [Models](models/index.md#responses-websocket-transport) をご覧ください。 +トランスポート選択ルールと、具体的な model オブジェクトや custom provider に関する注意点は、[Models](models/index.md#responses-websocket-transport) を参照してください。 -##### パターン 1: session helper なし（動作可） +##### パターン 1: session helper なし (動作可) -websocket transport だけ使いたく、共有 provider / session の管理を SDK に任せる必要がない場合に使用します。 +websocket トランスポートだけ使いたい場合、また SDK に共有 provider / session を管理させる必要がない場合に使います。 ```python import asyncio @@ -85,11 +85,11 @@ async def main(): asyncio.run(main()) ``` -このパターンは単発実行には問題ありません。`Runner.run()` / `Runner.run_streamed()` を繰り返し呼ぶ場合、同じ `RunConfig` / provider インスタンスを手動で再利用しない限り、実行ごとに再接続される可能性があります。 +このパターンは単発実行には問題ありません。`Runner.run()` / `Runner.run_streamed()` を繰り返し呼ぶ場合、同じ `RunConfig` / provider インスタンスを手動で再利用しない限り、各実行で再接続が発生する可能性があります。 -##### パターン 2: `responses_websocket_session()` を使用（複数ターン再利用に推奨） +##### パターン 2: `responses_websocket_session()` を使用 (マルチターン再利用に推奨) -複数の実行で websocket 対応 provider と `RunConfig` を共有したい場合は [`responses_websocket_session()`][agents.responses_websocket_session] を使います（同じ `run_config` を継承するネストした agent-as-tool 呼び出しを含む）。 +複数実行間で websocket 対応 provider と `RunConfig` を共有したい場合 (同じ `run_config` を継承するネストされた agent-as-tool 呼び出しを含む) は [`responses_websocket_session()`][agents.responses_websocket_session] を使います。 ```python import asyncio @@ -117,63 +117,63 @@ async def main(): asyncio.run(main()) ``` -コンテキストを終了する前に、ストリーミング実行結果の消費を完了してください。websocket リクエストが進行中のままコンテキストを終了すると、共有接続が強制クローズされる可能性があります。 +ストリーミング結果の消費は context を抜ける前に完了してください。websocket リクエストが進行中のまま context を終了すると、共有接続が強制的に閉じられる可能性があります。 -### 実行設定 +### RunConfig `run_config` パラメーターを使うと、エージェント実行のグローバル設定をいくつか構成できます。 -#### 共通の実行設定カテゴリー +#### 共通の run_config カテゴリー -`RunConfig` を使うと、各エージェント定義を変更せずに 1 回の実行だけ挙動を上書きできます。 +`RunConfig` を使うと、各エージェント定義を変更せずに、単一実行の挙動を上書きできます。 -##### モデル、プロバイダー、セッションのデフォルト +##### model / provider / session の既定値 -- [`model`][agents.run.RunConfig.model]: 各 Agent の `model` 設定に関係なく、グローバルな LLM モデルを設定できます。 -- [`model_provider`][agents.run.RunConfig.model_provider]: モデル名を解決するモデルプロバイダーです。デフォルトは OpenAI です。 -- [`model_settings`][agents.run.RunConfig.model_settings]: エージェント固有の設定を上書きします。たとえば、グローバルな `temperature` や `top_p` を設定できます。 -- [`session_settings`][agents.run.RunConfig.session_settings]: 実行中に履歴を取得する際、セッションレベルのデフォルト（例: `SessionSettings(limit=...)`）を上書きします。 -- [`session_input_callback`][agents.run.RunConfig.session_input_callback]: Sessions 使用時、各ターン前に新しいユーザー入力とセッション履歴をどうマージするかをカスタマイズします。コールバックは同期 / 非同期のどちらでも可能です。 +- [`model`][agents.run.RunConfig.model]: 各 Agent の `model` 設定に関係なく、グローバルで使う LLM model を設定できます。 +- [`model_provider`][agents.run.RunConfig.model_provider]: model 名の解決に使う model provider で、既定は OpenAI です。 +- [`model_settings`][agents.run.RunConfig.model_settings]: エージェント固有設定を上書きします。例えばグローバルな `temperature` や `top_p` を設定できます。 +- [`session_settings`][agents.run.RunConfig.session_settings]: 実行中に履歴を取得する際の session レベル既定値 (例: `SessionSettings(limit=...)`) を上書きします。 +- [`session_input_callback`][agents.run.RunConfig.session_input_callback]: Sessions 使用時に、各ターン前に新規ユーザー入力を session 履歴へどうマージするかをカスタマイズします。callback は同期 / 非同期のどちらでも可能です。 -##### ガードレール、ハンドオフ、モデル入力整形 +##### ガードレール / ハンドオフ / model 入力整形 - [`input_guardrails`][agents.run.RunConfig.input_guardrails], [`output_guardrails`][agents.run.RunConfig.output_guardrails]: すべての実行に含める入力 / 出力ガードレールのリストです。 -- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: ハンドオフ側に未設定の場合に全ハンドオフへ適用するグローバル入力フィルターです。新しいエージェントに送る入力を編集できます。詳細は [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] のドキュメントをご覧ください。 -- [`nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]: 次のエージェント呼び出し前に、それまでの transcript を 1 つの assistant メッセージへ折りたたむ opt-in beta 機能です。ネストしたハンドオフの安定化中のためデフォルトは無効です。有効化は `True`、raw transcript をそのまま渡す場合は `False` のままにします。[Runner methods][agents.run.Runner] は `RunConfig` 未指定時に自動作成されるため、クイックスタートやコード例ではデフォルトで無効のままです。明示的な [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] コールバックは引き続き優先されます。個別ハンドオフでは [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history] でこの設定を上書きできます。 -- [`handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper]: `nest_handoff_history` を有効化したときに、正規化済み transcript（履歴 + ハンドオフ項目）を受け取る任意の callable です。次のエージェントへ渡す入力アイテムの**正確な**リストを返す必要があり、完全なハンドオフフィルターを書かずに組み込み要約を置き換えられます。 -- [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter]: モデル呼び出し直前に、完全に準備されたモデル入力（instructions と入力アイテム）を編集するフックです。例: 履歴のトリミングやシステムプロンプトの注入。 -- [`reasoning_item_id_policy`][agents.run.RunConfig.reasoning_item_id_policy]: runner が過去出力を次ターンのモデル入力へ変換するとき、reasoning item ID を保持するか省略するかを制御します。 +- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: ハンドオフ側に既存設定がない場合、すべてのハンドオフに適用されるグローバル入力フィルターです。新しいエージェントへ送る入力を編集できます。詳細は [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] のドキュメントを参照してください。 +- [`nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]: 次のエージェント呼び出し前に、直前までの transcript を 1 つの assistant message に折りたたむ opt-in beta です。ネストされたハンドオフの安定化中のため既定では無効です。有効化は `True`、raw transcript をそのまま渡す場合は `False` にします。[Runner methods][agents.run.Runner] は `RunConfig` 未指定時に自動作成するため、quickstart や examples では既定で無効のままです。また明示的な [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] callback は引き続き優先されます。個別ハンドオフでは [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history] で上書きできます。 +- [`handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper]: `nest_handoff_history` を有効化した際に、正規化 transcript (履歴 + ハンドオフ項目) を受け取る任意 callable です。次エージェントへ渡す入力アイテムの正確なリストを返す必要があり、完全な handoff filter を書かずに組み込み要約を置き換えられます。 +- [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter]: model 呼び出し直前に、完全に準備された model 入力 (`instructions` と入力アイテム) を編集する hook です。例: 履歴のトリミングやシステムプロンプト注入。 +- [`reasoning_item_id_policy`][agents.run.RunConfig.reasoning_item_id_policy]: Runner が過去出力を次ターンの model 入力へ変換する際に、reasoning item ID を保持するか省略するかを制御します。 ##### トレーシングと可観測性 -- [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]: 実行全体の [トレーシング](tracing.md) を無効化できます。 -- [`tracing`][agents.run.RunConfig.tracing]: この実行の exporter、processor、またはトレーシング metadata を上書きするために [`TracingConfig`][agents.tracing.TracingConfig] を渡します。 -- [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]: LLM やツール呼び出しの入出力など、機微な可能性のあるデータをトレースに含めるかを設定します。 -- [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]: 実行のトレーシング workflow 名、trace ID、trace group ID を設定します。少なくとも `workflow_name` の設定を推奨します。group ID は複数実行のトレースを関連付けるための任意フィールドです。 +- [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]: 実行全体の [トレーシング](tracing.md) を無効にできます。 +- [`tracing`][agents.run.RunConfig.tracing]: この実行の exporter / processor / tracing metadata を上書きする [`TracingConfig`][agents.tracing.TracingConfig] を渡します。 +- [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]: LLM やツール呼び出しの入出力など、機微データをトレースに含めるかを設定します。 +- [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]: この実行のトレーシング workflow 名、trace ID、trace group ID を設定します。少なくとも `workflow_name` の設定を推奨します。group ID は任意で、複数実行にまたがるトレース関連付けに使えます。 - [`trace_metadata`][agents.run.RunConfig.trace_metadata]: すべてのトレースに含める metadata です。 -##### ツール承認とツールエラー時の挙動 +##### ツール承認とツールエラー挙動 -- [`tool_error_formatter`][agents.run.RunConfig.tool_error_formatter]: 承認フローでツール呼び出しが拒否された際、モデルに見えるメッセージをカスタマイズします。 +- [`tool_error_formatter`][agents.run.RunConfig.tool_error_formatter]: 承認フローでツール呼び出しが拒否された際に、model に見えるメッセージをカスタマイズします。 -ネストしたハンドオフは opt-in beta として利用できます。折りたたみ transcript 挙動を有効化するには `RunConfig(nest_handoff_history=True)` を渡すか、特定のハンドオフに対して `handoff(..., nest_handoff_history=True)` を設定します。raw transcript（デフォルト）を維持したい場合は、このフラグを設定しないか、必要どおり会話をそのまま転送する `handoff_input_filter`（または `handoff_history_mapper`）を指定してください。カスタム mapper を書かずに生成要約のラッパーテキストを変更したい場合は [`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers] を呼び出します（デフォルトへ戻すには [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers]）。 +ネストされたハンドオフは opt-in beta として利用できます。折りたたみ transcript の挙動は `RunConfig(nest_handoff_history=True)` を渡すか、特定のハンドオフで `handoff(..., nest_handoff_history=True)` を設定すると有効になります。raw transcript (既定) を維持したい場合は、フラグを未設定のままにするか、必要どおりに会話をそのまま転送する `handoff_input_filter` (または `handoff_history_mapper`) を指定してください。custom mapper を書かずに生成要約のラッパーテキストを変更するには、[`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers] を呼びます (既定値復元は [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers])。 -#### 実行設定の詳細 +#### RunConfig 詳細 ##### `tool_error_formatter` -`tool_error_formatter` を使うと、承認フローでツール呼び出しが拒否されたときにモデルへ返すメッセージをカスタマイズできます。 +`tool_error_formatter` を使うと、承認フローでツール呼び出しが拒否されたときに model へ返すメッセージをカスタマイズできます。 -formatter は次を含む [`ToolErrorFormatterArgs`][agents.run_config.ToolErrorFormatterArgs] を受け取ります。 +formatter は以下を含む [`ToolErrorFormatterArgs`][agents.run_config.ToolErrorFormatterArgs] を受け取ります。 - `kind`: エラーカテゴリー。現時点では `"approval_rejected"` です。 -- `tool_type`: ツールランタイム（`"function"`、`"computer"`、`"shell"`、`"apply_patch"`）。 +- `tool_type`: ツール runtime (`"function"`、`"computer"`、`"shell"`、`"apply_patch"`)。 - `tool_name`: ツール名。 - `call_id`: ツール呼び出し ID。 -- `default_message`: SDK のデフォルトのモデル表示メッセージ。 -- `run_context`: アクティブな実行コンテキストラッパー。 +- `default_message`: SDK 既定の model 向けメッセージ。 +- `run_context`: アクティブな run context wrapper。 -メッセージを置き換える文字列、または SDK デフォルトを使う場合は `None` を返します。 +文字列を返すとメッセージを置換し、`None` を返すと SDK 既定値を使います。 ```python from agents import Agent, RunConfig, Runner, ToolErrorFormatterArgs @@ -198,57 +198,56 @@ result = Runner.run_sync( ##### `reasoning_item_id_policy` -`reasoning_item_id_policy` は、runner が履歴を次へ引き継ぐ際（例: `RunResult.to_input_list()` や session バック実行）に、reasoning item を次ターンのモデル入力へどう変換するかを制御します。 +`reasoning_item_id_policy` は、Runner が履歴を引き継ぐ際 (例: `RunResult.to_input_list()` や session-backed 実行) に、reasoning item を次ターン model 入力へどう変換するかを制御します。 -- `None` または `"preserve"`（デフォルト）: reasoning item ID を保持します。 -- `"omit"`: 生成される次ターン入力から reasoning item ID を取り除きます。 +- `None` または `"preserve"` (既定): reasoning item ID を保持します。 +- `"omit"`: 生成される次ターン入力から reasoning item ID を削除します。 -`"omit"` は主に、reasoning item が `id` 付きで送信される一方、必須の後続 item がない場合に起きる Responses API の 400 エラー群への opt-in 緩和策です（例: `Item 'rs_...' of type 'reasoning' was provided without its required following item.`）。 +`"omit"` は主に、reasoning item が `id` 付きで送信されたが必須の後続 item がない場合に発生する Responses API 400 エラー群への opt-in 緩和策として使います (例: `Item 'rs_...' of type 'reasoning' was provided without its required following item.`)。 -この問題は、SDK が過去出力からフォローアップ入力を構築する複数ターンのエージェント実行（session 永続化、サーバー管理会話 delta、ストリーミング / 非ストリーミングのフォローアップターン、resume パスを含む）で、reasoning item ID が保持される一方、そのプロバイダーが対応する後続 item とのペア維持を要求する場合に発生し得ます。 +これは、SDK が過去出力から follow-up 入力を構築するマルチターンエージェント実行時に発生し得ます (session 永続化、サーバー管理 conversation delta、streamed / non-streamed follow-up ターン、resume 経路を含む)。reasoning item ID が保持され、provider 側で対応する後続 item とのペア維持が要求される場合です。 -`reasoning_item_id_policy="omit"` を設定すると、reasoning の内容は維持しつつ reasoning item の `id` を除去するため、SDK 生成のフォローアップ入力でその API 不変条件に触れなくなります。 +`reasoning_item_id_policy="omit"` を設定すると reasoning 内容は維持しつつ reasoning item `id` を削除するため、SDK 生成 follow-up 入力でこの API 不変条件に抵触するのを回避できます。 -スコープに関する注意: +適用範囲の注意: -- 変更対象は、SDK がフォローアップ入力構築時に生成 / 転送する reasoning item のみです。 -- ユーザーが指定した初期入力 item は書き換えません。 -- `call_model_input_filter` は、このポリシー適用後でも意図的に reasoning ID を再導入できます。 +- 影響するのは、SDK が follow-up 入力構築時に生成 / 転送する reasoning item のみです。 +- ユーザー提供の初期入力アイテムは書き換えません。 +- `call_model_input_filter` は、この policy 適用後に意図的に reasoning ID を再導入できます。 -## 状態と会話の管理 +## 状態と会話管理 ### メモリ戦略の選択 -次のターンへ状態を引き継ぐ一般的な方法は 4 つあります。 +状態を次ターンへ引き継ぐ一般的な方法は 4 つあります。 -| 戦略 | 状態の保存場所 | 最適な用途 | 次ターンで渡すもの | +| Strategy | Where state lives | Best for | What you pass on the next turn | | --- | --- | --- | --- | -| `result.to_input_list()` | アプリメモリ | 小規模なチャットループ、完全な手動制御、任意のプロバイダー | `result.to_input_list()` のリスト + 次のユーザーメッセージ | -| `session` | ユーザーのストレージ + SDK | 永続チャット状態、再開可能な実行、カスタムストア | 同じ `session` インスタンス、または同じストアを指す別インスタンス | -| `conversation_id` | OpenAI Conversations API | ワーカー / サービス間で共有したい、名前付きのサーバー側会話 | 同じ `conversation_id` + 新しいユーザーターンのみ | -| `previous_response_id` | OpenAI Responses API | 会話リソースを作らない軽量なサーバー管理継続 | `result.last_response_id` + 新しいユーザーターンのみ | +| `result.to_input_list()` | アプリメモリ内 | 小規模チャットループ、完全手動制御、任意 provider | `result.to_input_list()` のリスト + 次のユーザーメッセージ | +| `session` | 自身のストレージ + SDK | 永続チャット状態、再開可能実行、カスタムストア | 同じ `session` インスタンス、または同じ store を指す別インスタンス | +| `conversation_id` | OpenAI Conversations API | ワーカー / サービス間で共有したい名前付きサーバー側会話 | 同じ `conversation_id` + 新しいユーザーターンのみ | +| `previous_response_id` | OpenAI Responses API | conversation リソースを作らない軽量なサーバー管理継続 | `result.last_response_id` + 新しいユーザーターンのみ | -`result.to_input_list()` と `session` はクライアント管理です。`conversation_id` と `previous_response_id` は OpenAI 管理で、OpenAI Responses API 使用時にのみ適用されます。ほとんどのアプリケーションでは、1 つの会話につき 1 つの永続化戦略を選んでください。クライアント管理履歴と OpenAI 管理状態を混在させると、意図的に両レイヤーを突き合わせない限り文脈が重複する可能性があります。 +`result.to_input_list()` と `session` はクライアント管理です。`conversation_id` と `previous_response_id` は OpenAI 管理で、OpenAI Responses API 使用時のみ適用されます。多くのアプリでは、1 つの会話につき 1 つの永続化戦略を選ぶのが適切です。クライアント管理履歴と OpenAI 管理状態を混在させると、意図的に両レイヤーを調停しない限り、コンテキスト重複が起こる可能性があります。 !!! note Session 永続化は、サーバー管理会話設定 - （`conversation_id`、`previous_response_id`、`auto_previous_response_id`）と - 同一実行では併用できません。 - 呼び出しごとにどちらか 1 つを選択してください。 + (`conversation_id`、`previous_response_id`、`auto_previous_response_id`) と + 同じ実行内で併用できません。呼び出しごとに 1 つの方式を選んでください。 ### 会話 / チャットスレッド -いずれの run メソッド呼び出しでも、1 つ以上のエージェント実行（つまり 1 回以上の LLM 呼び出し）が行われる可能性がありますが、チャット会話としては 1 つの論理ターンを表します。例: +いずれの run メソッドも、結果として 1 つ以上のエージェント実行 (つまり 1 回以上の LLM 呼び出し) を含む可能性がありますが、チャット会話上は 1 つの論理ターンを表します。例: -1. ユーザーターン: ユーザーがテキストを入力 -2. Runner 実行: 最初のエージェントが LLM を呼び出し、ツールを実行し、2 番目のエージェントへハンドオフし、2 番目のエージェントがさらにツールを実行して出力を生成 +1. ユーザーターン: ユーザーがテキスト入力 +2. Runner 実行: 最初のエージェントが LLM 呼び出し、ツール実行、2 番目エージェントへハンドオフ、2 番目エージェントがさらにツール実行し、その後出力を生成 -エージェント実行の終了後、何をユーザーに見せるか選べます。たとえば、エージェントが生成した新規 item をすべて見せることも、最終出力だけ見せることもできます。いずれの場合も、ユーザーが追質問したら再度 run メソッドを呼び出せます。 +エージェント実行の最後に、ユーザーへ何を表示するかを選べます。例えば、エージェントが生成したすべての新規アイテムを表示することも、最終出力だけ表示することもできます。どちらの場合でも、その後ユーザーが追質問したら、run メソッドを再度呼び出せます。 #### 手動の会話管理 -[`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] メソッドで次ターン入力を取得し、会話履歴を手動管理できます。 +[`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] メソッドを使って次ターン入力を取得し、会話履歴を手動管理できます。 ```python async def main(): @@ -270,7 +269,7 @@ async def main(): #### Sessions による自動会話管理 -よりシンプルな方法として、[Sessions](sessions/index.md) を使うと `.to_input_list()` を手動で呼ばずに会話履歴を自動処理できます。 +より簡単な方法として、[Sessions](sessions/index.md) を使うと `.to_input_list()` を手動で呼ばずに会話履歴を自動処理できます。 ```python from agents import Agent, Runner, SQLiteSession @@ -294,24 +293,23 @@ async def main(): # California ``` -Sessions は次を自動で行います。 +Sessions は自動的に次を行います。 - 各実行前に会話履歴を取得 -- 各実行後に新しいメッセージを保存 -- 異なる session ID ごとに別会話を維持 - -詳細は [Sessions ドキュメント](sessions/index.md) をご覧ください。 +- 各実行後に新規メッセージを保存 +- session ID ごとに別々の会話を維持 +詳細は [Sessions ドキュメント](sessions/index.md) を参照してください。 #### サーバー管理会話 -`to_input_list()` や `Sessions` でローカル管理する代わりに、OpenAI の会話状態機能でサーバー側に会話状態を管理させることもできます。これにより、過去メッセージを毎回すべて再送しなくても会話履歴を保持できます。以下のいずれのサーバー管理方式でも、各リクエストでは新しいターンの入力のみを渡し、保存済み ID を再利用します。詳細は [OpenAI Conversation state guide](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses) をご覧ください。 +`to_input_list()` や `Sessions` でローカル処理する代わりに、OpenAI conversation state 機能でサーバー側会話状態を管理することもできます。これにより、過去メッセージを毎回手動で再送せずに会話履歴を保持できます。以下のいずれのサーバー管理方式でも、各リクエストでは新規ターン入力のみを渡し、保存済み ID を再利用します。詳細は [OpenAI Conversation state guide](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses) を参照してください。 OpenAI はターン間状態追跡の方法を 2 つ提供します。 -##### 1. `conversation_id` を使用 +##### 1. `conversation_id` の使用 -まず OpenAI Conversations API で会話を作成し、その ID を以降の呼び出しで再利用します。 +最初に OpenAI Conversations API で会話を作成し、その ID を以降のすべての呼び出しで再利用します。 ```python from agents import Agent, Runner @@ -332,9 +330,9 @@ async def main(): print(f"Assistant: {result.final_output}") ``` -##### 2. `previous_response_id` を使用 +##### 2. `previous_response_id` の使用 -もう 1 つの方法は **response chaining** で、各ターンを前ターンの response ID へ明示的に関連付けます。 +もう 1 つは **response chaining** で、各ターンを前ターンの response ID に明示的に連結します。 ```python from agents import Agent, Runner @@ -359,29 +357,33 @@ async def main(): print(f"Assistant: {result.final_output}") ``` -実行が承認待ちで一時停止し、[`RunState`][agents.run_state.RunState] から再開する場合でも、 +実行が承認待ちで一時停止し、[`RunState`][agents.run_state.RunState] から再開する場合、 SDK は保存済みの `conversation_id` / `previous_response_id` / `auto_previous_response_id` -設定を維持するため、再開ターンは同じサーバー管理会話で継続されます。 +設定を保持するため、再開ターンも同じサーバー管理会話で継続されます。 -`conversation_id` と `previous_response_id` は相互排他です。システム間共有可能な名前付き会話リソースが必要なら `conversation_id` を使ってください。ターン間の最軽量な Responses API 継続プリミティブを使いたい場合は `previous_response_id` を使ってください。 +`conversation_id` と `previous_response_id` は排他的です。システム間で共有可能な名前付き会話リソースが必要なら `conversation_id` を使います。ターン間で最も軽量な Responses API 継続プリミティブが必要なら `previous_response_id` を使います。 !!! note SDK は `conversation_locked` エラーをバックオフ付きで自動リトライします。サーバー管理 - 会話実行では、リトライ前に内部の会話トラッカー入力を巻き戻すため、 - 同じ準備済み item を重複なく再送できます。 + 会話実行では、リトライ前に内部 conversation-tracker 入力を巻き戻し、同じ + 準備済みアイテムを重複なく再送できるようにします。 + + ローカルな session ベース実行 (`conversation_id`、 + `previous_response_id`、`auto_previous_response_id` とは併用不可) でも、SDK は + リトライ後の履歴重複を減らすため、直近で永続化した入力アイテムのベストエフォート + ロールバックを行います。 - ローカルな session ベース実行（`conversation_id`、 - `previous_response_id`、`auto_previous_response_id` と併用不可）でも、SDK はベストエフォートで - 直近に永続化された入力 item をロールバックし、リトライ後の履歴重複を減らします。 + この互換性リトライは `ModelSettings.retry` 未設定でも実行されます。model リクエストに対する + より広い opt-in リトライ挙動は、[Runner 管理リトライ](models/index.md#runner-managed-retries) を参照してください。 ## フックとカスタマイズ ### call model input filter -`call_model_input_filter` を使うと、モデル呼び出し直前にモデル入力を編集できます。このフックは現在のエージェント、コンテキスト、結合済み入力 item（存在する場合は session 履歴を含む）を受け取り、新しい `ModelInputData` を返します。 +`call_model_input_filter` を使うと、model 呼び出し直前の model 入力を編集できます。この hook は現在のエージェント、context、および (存在する場合は session 履歴を含む) 結合済み入力アイテムを受け取り、新しい `ModelInputData` を返します。 -戻り値は [`ModelInputData`][agents.run.ModelInputData] オブジェクトである必要があります。その `input` フィールドは必須で、入力 item のリストでなければなりません。これ以外の形を返すと `UserError` が発生します。 +返り値は [`ModelInputData`][agents.run.ModelInputData] オブジェクトである必要があります。`input` フィールドは必須で、入力アイテムのリストでなければなりません。それ以外の形を返すと `UserError` が発生します。 ```python from agents import Agent, Runner, RunConfig @@ -400,19 +402,19 @@ result = Runner.run_sync( ) ``` -runner は準備済み入力リストのコピーをフックへ渡すため、呼び出し元の元リストをインプレース変更せずに、トリミング / 置換 / 並べ替えができます。 +Runner は準備済み入力リストのコピーを hook に渡すため、呼び出し元の元リストをインプレース変更せずに、トリミング / 置換 / 並べ替えができます。 -session を使用している場合、`call_model_input_filter` は session 履歴の読み込みと現在ターンとのマージが完了した後に実行されます。より前段のマージ処理自体をカスタマイズしたい場合は [`session_input_callback`][agents.run.RunConfig.session_input_callback] を使用してください。 +session を使っている場合、`call_model_input_filter` は session 履歴の読み込みと現在ターンへのマージが完了した後に実行されます。より前段のマージ処理自体をカスタマイズしたい場合は [`session_input_callback`][agents.run.RunConfig.session_input_callback] を使ってください。 -`conversation_id`、`previous_response_id`、`auto_previous_response_id` による OpenAI サーバー管理会話状態を使っている場合、このフックは次の Responses API 呼び出し向けに準備されたペイロードに対して実行されます。そのペイロードは、過去履歴の完全再送ではなく、新ターンの差分のみを表している場合があります。返した item のみが、そのサーバー管理継続で送信済みとしてマークされます。 +`conversation_id`、`previous_response_id`、`auto_previous_response_id` を使った OpenAI サーバー管理会話状態を使う場合、この hook は次の Responses API 呼び出し向けに準備された payload に対して実行されます。その payload は、過去履歴の完全再送ではなく新規ターン差分のみを表すことがあります。サーバー管理継続で送信済みとして扱われるのは、あなたが返したアイテムだけです。 -機微データのマスキング、長い履歴のトリミング、追加のシステムガイダンス挿入などのために、`run_config` 経由で実行ごとにこのフックを設定してください。 +機微データのマスキング、長い履歴のトリミング、追加システムガイダンスの注入には、`run_config` で実行単位にこの hook を設定してください。 ## エラーと復旧 ### エラーハンドラー -すべての `Runner` エントリーポイントは、エラー種別をキーとする辞書 `error_handlers` を受け取れます。現時点でサポートされるキーは `"max_turns"` です。`MaxTurnsExceeded` を送出せず、制御された最終出力を返したい場合に使用します。 +すべての `Runner` エントリーポイントは、エラー種別をキーに持つ dict `error_handlers` を受け付けます。現在サポートされるキーは `"max_turns"` です。`MaxTurnsExceeded` を送出せず、制御された最終出力を返したい場合に使います。 ```python from agents import ( @@ -441,35 +443,35 @@ result = Runner.run_sync( print(result.final_output) ``` -フォールバック出力を会話履歴へ追加したくない場合は、`include_in_history=False` を設定してください。 +フォールバック出力を会話履歴に追加したくない場合は `include_in_history=False` を設定します。 ## Durable execution 連携と human-in-the-loop -ツール承認の一時停止 / 再開パターンについては、専用の [Human-in-the-loop ガイド](human_in_the_loop.md) から始めてください。 -以下の連携は、実行が長時間待機、リトライ、プロセス再起動をまたぐ場合の durable なオーケストレーション向けです。 +ツール承認の一時停止 / 再開パターンは、専用の [Human-in-the-loop ガイド](human_in_the_loop.md) から始めてください。 +以下の連携は、長時間待機、リトライ、プロセス再起動をまたぐ可能性がある Durable なオーケストレーション向けです。 ### Temporal -Agents SDK の [Temporal](https://temporal.io/) 連携を使うと、human-in-the-loop タスクを含む durable で長時間実行されるワークフローを実行できます。Temporal と Agents SDK が連携して長時間タスクを完了するデモは [この動画](https://www.youtube.com/watch?v=fFBZqzT4DD8) を、ドキュメントは [こちら](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/openai_agents) をご覧ください。 +Agents SDK の [Temporal](https://temporal.io/) 連携を使うと、human-in-the-loop タスクを含む Durable で長時間実行のワークフローを実行できます。Temporal と Agents SDK が連携して長時間タスクを完了するデモは [この動画](https://www.youtube.com/watch?v=fFBZqzT4DD8) を参照し、ドキュメントは [こちら](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/openai_agents) を参照してください。 ### Restate -Agents SDK の [Restate](https://restate.dev/) 連携を使うと、人手承認、ハンドオフ、セッション管理を含む軽量で durable なエージェントを実行できます。この連携には依存関係として Restate の single-binary runtime が必要で、プロセス / コンテナまたは serverless functions としてのエージェント実行をサポートします。 -詳細は [overview](https://www.restate.dev/blog/durable-orchestration-for-ai-agents-with-restate-and-openai-sdk) または [docs](https://docs.restate.dev/ai) をご覧ください。 +Agents SDK の [Restate](https://restate.dev/) 連携を使うと、human approval、ハンドオフ、session 管理を含む軽量で Durable なエージェントを実行できます。この連携には依存関係として Restate の single-binary runtime が必要で、エージェントを process / container または serverless function として実行できます。 +詳細は [概要](https://www.restate.dev/blog/durable-orchestration-for-ai-agents-with-restate-and-openai-sdk) または [ドキュメント](https://docs.restate.dev/ai) を参照してください。 ### DBOS -Agents SDK の [DBOS](https://dbos.dev/) 連携を使うと、障害や再起動をまたいで進捗を保持する信頼性の高いエージェントを実行できます。長時間実行エージェント、human-in-the-loop ワークフロー、ハンドオフをサポートします。同期 / 非同期メソッドの両方に対応しています。この連携に必要なのは SQLite または Postgres データベースのみです。詳細は連携の [repo](https://github.com/dbos-inc/dbos-openai-agents) と [docs](https://docs.dbos.dev/integrations/openai-agents) をご覧ください。 +Agents SDK の [DBOS](https://dbos.dev/) 連携を使うと、障害や再起動をまたいで進行状況を保持する信頼性の高いエージェントを実行できます。長時間実行エージェント、human-in-the-loop ワークフロー、ハンドオフをサポートします。同期 / 非同期メソッドの両方をサポートします。この連携に必要なのは SQLite または Postgres データベースのみです。詳細は連携 [repo](https://github.com/dbos-inc/dbos-openai-agents) と [ドキュメント](https://docs.dbos.dev/integrations/openai-agents) を参照してください。 ## 例外 SDK は特定のケースで例外を送出します。完全な一覧は [`agents.exceptions`][] にあります。概要は次のとおりです。 -- [`AgentsException`][agents.exceptions.AgentsException]: SDK 内で送出されるすべての例外の基底クラスです。ほかの具体的な例外はすべてこの型から派生します。 -- [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]: エージェント実行が `Runner.run`、`Runner.run_sync`、`Runner.run_streamed` メソッドに渡された `max_turns` 制限を超えたときに送出されます。指定ターン数内でエージェントがタスクを完了できなかったことを示します。 -- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]: 基盤モデル（LLM）が予期しない、または無効な出力を生成したときに発生します。例: - - 不正な JSON: 特に特定の `output_type` が定義されている場合に、ツール呼び出しまたは直接出力でモデルが不正な JSON 構造を返したとき。 - - 予期しないツール関連の失敗: モデルが期待どおりの方法でツールを使えないとき -- [`ToolTimeoutError`][agents.exceptions.ToolTimeoutError]: 関数ツール呼び出しが設定済みタイムアウトを超過し、ツールが `timeout_behavior="raise_exception"` を使っているときに送出されます。 -- [`UserError`][agents.exceptions.UserError]: SDK 使用時にユーザー（SDK を使ってコードを書く人）が誤りをしたときに送出されます。通常はコード実装ミス、無効な設定、または SDK API の誤用が原因です。 -- [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]: 入力ガードレールまたは出力ガードレールの条件が満たされたときにそれぞれ送出されます。入力ガードレールは処理前の受信メッセージをチェックし、出力ガードレールは配信前のエージェント最終応答をチェックします。 \ No newline at end of file +- [`AgentsException`][agents.exceptions.AgentsException]: SDK 内で送出されるすべての例外の基底クラスです。ほかのすべての具体例外がこの型から派生します。 +- [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]: エージェント実行が `Runner.run`、`Runner.run_sync`、`Runner.run_streamed` に渡した `max_turns` 上限を超えたときに送出されます。指定された対話ターン数内でタスクを完了できなかったことを示します。 +- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]: 基盤 model (LLM) が予期しない、または無効な出力を生成したときに発生します。例: + - 不正な JSON: ツール呼び出し用、または直接出力内の JSON 構造が不正な場合。特に特定の `output_type` が定義されている場合。 + - 想定外のツール関連失敗: model が想定どおりにツールを使えない場合 +- [`ToolTimeoutError`][agents.exceptions.ToolTimeoutError]: 関数ツール呼び出しが設定タイムアウトを超過し、ツールが `timeout_behavior="raise_exception"` を使っている場合に送出されます。 +- [`UserError`][agents.exceptions.UserError]: SDK 使用中に、あなた (SDK を使ってコードを書く人) が誤りをしたときに送出されます。通常はコード実装不備、無効な設定、または SDK API の誤用が原因です。 +- [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]: 入力ガードレールまたは出力ガードレールの条件が満たされたときに、それぞれ送出されます。入力ガードレールは処理前の受信メッセージを検査し、出力ガードレールは配信前のエージェント最終応答を検査します。 \ No newline at end of file diff --git a/docs/ko/examples.md b/docs/ko/examples.md index fc06dd2390..f6063b69e7 100644 --- a/docs/ko/examples.md +++ b/docs/ko/examples.md @@ -4,7 +4,7 @@ search: --- # 코드 예제 -[repo](https://github.com/openai/openai-agents-python/tree/main/examples)의 examples 섹션에서 SDK의 다양한 샘플 구현을 확인해 보세요. examples는 여러 카테고리로 구성되어 있으며, 서로 다른 패턴과 기능을 보여줍니다. +[repo](https://github.com/openai/openai-agents-python/tree/main/examples)의 예제 섹션에서 SDK의 다양한 샘플 구현을 확인해 보세요. 예제는 서로 다른 패턴과 기능을 보여주는 여러 카테고리로 구성되어 있습니다. ## 카테고리 @@ -16,38 +16,40 @@ search: - 병렬 에이전트 실행 - 조건부 도구 사용 - 입력/출력 가드레일 - - 심판으로서의 LLM + - 심사자로서의 LLM - 라우팅 - 스트리밍 가드레일 - **[basic](https://github.com/openai/openai-agents-python/tree/main/examples/basic):** - 이 예제들은 다음과 같은 SDK의 기초 기능을 보여줍니다 + 이 예제들은 SDK의 기본 기능을 보여줍니다. 예시는 다음과 같습니다 - - Hello world 예제 (기본 모델, GPT-5, 오픈 웨이트 모델) - - 에이전트 수명 주기 관리 + - Hello World 예제 (기본 모델, GPT-5, 오픈 웨이트 모델) + - 에이전트 라이프사이클 관리 - 동적 시스템 프롬프트 - - 스트리밍 출력(텍스트, 항목, 함수 호출 인수) + - 스트리밍 출력 (텍스트, 항목, 함수 호출 인수) - 턴 간 공유 세션 헬퍼를 사용하는 Responses websocket 전송 (`examples/basic/stream_ws.py`) - 프롬프트 템플릿 - - 파일 처리(로컬 및 원격, 이미지 및 PDF) + - 파일 처리 (로컬 및 원격, 이미지 및 PDF) - 사용량 추적 + - Runner 관리 재시도 설정 (`examples/basic/retry.py`) + - LiteLLM을 사용한 Runner 관리 재시도 (`examples/basic/retry_litellm.py`) - 비엄격 출력 타입 - 이전 응답 ID 사용 - **[customer_service](https://github.com/openai/openai-agents-python/tree/main/examples/customer_service):** - 항공사를 위한 고객 서비스 시스템 예제입니다 + 항공사를 위한 예시 고객 서비스 시스템입니다 - **[financial_research_agent](https://github.com/openai/openai-agents-python/tree/main/examples/financial_research_agent):** - 금융 데이터 분석을 위한 에이전트와 도구를 사용해 구조화된 연구 워크플로를 보여주는 금융 리서치 에이전트입니다 + 재무 데이터 분석을 위한 에이전트와 도구를 활용한 구조화된 리서치 워크플로를 보여주는 재무 리서치 에이전트입니다 - **[handoffs](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs):** - 메시지 필터링이 포함된 에이전트 핸드오프의 실용적인 예제를 확인해 보세요 + 메시지 필터링을 사용한 에이전트 핸드오프의 실용적인 예제를 확인하세요 - **[hosted_mcp](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp):** 호스티드 MCP (Model context protocol) 커넥터와 승인 사용 방법을 보여주는 예제입니다 - **[mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp):** - MCP (Model context protocol)로 에이전트를 구축하는 방법을 알아보세요. 포함 내용은 다음과 같습니다 + 다음을 포함해 MCP (Model context protocol)로 에이전트를 빌드하는 방법을 알아보세요 - 파일시스템 예제 - Git 예제 @@ -56,38 +58,38 @@ search: - 스트리밍 가능한 HTTP 예제 - **[memory](https://github.com/openai/openai-agents-python/tree/main/examples/memory):** - 에이전트를 위한 다양한 메모리 구현 예제입니다. 포함 내용은 다음과 같습니다 + 다음을 포함한 에이전트용 다양한 메모리 구현 예제입니다 - - SQLite 세션 스토리지 - - 고급 SQLite 세션 스토리지 - - Redis 세션 스토리지 - - SQLAlchemy 세션 스토리지 - - Dapr 상태 저장소 세션 스토리지 - - 암호화된 세션 스토리지 - - OpenAI Conversations 세션 스토리지 - - Responses 컴팩션 세션 스토리지 + - SQLite 세션 저장소 + - 고급 SQLite 세션 저장소 + - Redis 세션 저장소 + - SQLAlchemy 세션 저장소 + - Dapr 상태 저장소 세션 저장소 + - 암호화된 세션 저장소 + - OpenAI Conversations 세션 저장소 + - Responses 컴팩션 세션 저장소 - **[model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):** - 커스텀 제공자와 LiteLLM 통합을 포함해 SDK에서 OpenAI 이외 모델을 사용하는 방법을 살펴보세요 + 커스텀 provider 및 LiteLLM 통합을 포함해 SDK와 함께 OpenAI가 아닌 모델을 사용하는 방법을 살펴보세요 - **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):** - 다음을 포함해 SDK로 실시간 경험을 구축하는 방법을 보여주는 예제입니다 + 다음을 포함해 SDK를 사용하여 실시간 경험을 구축하는 방법을 보여주는 예제입니다 - 구조화된 텍스트 및 이미지 메시지를 사용하는 웹 애플리케이션 패턴 - 명령줄 오디오 루프 및 재생 처리 - WebSocket을 통한 Twilio Media Streams 통합 - - Realtime Calls API attach 플로를 사용하는 Twilio SIP 통합 + - Realtime Calls API attach 플로우를 사용하는 Twilio SIP 통합 - **[reasoning_content](https://github.com/openai/openai-agents-python/tree/main/examples/reasoning_content):** - reasoning content 및 structured outputs를 다루는 방법을 보여주는 예제입니다 + reasoning content 및 structured outputs 작업 방법을 보여주는 예제입니다 - **[research_bot](https://github.com/openai/openai-agents-python/tree/main/examples/research_bot):** - 복잡한 멀티 에이전트 연구 워크플로를 보여주는 간단한 딥 리서치 클론입니다 + 복잡한 멀티 에이전트 리서치 워크플로를 보여주는 간단한 딥 리서치 클론입니다 - **[tools](https://github.com/openai/openai-agents-python/tree/main/examples/tools):** - 다음과 같은 OAI hosted tools 및 실험적 Codex 도구를 구현하는 방법을 알아보세요 + 다음과 같은 OpenAI 호스트하는 도구 및 실험적 Codex 도구 기능 구현 방법을 알아보세요 - - 웹 검색 및 필터가 있는 웹 검색 + - 웹 검색 및 필터를 적용한 웹 검색 - 파일 검색 - 코드 인터프리터 - 인라인 스킬을 사용하는 호스티드 컨테이너 셸 (`examples/tools/container_shell_inline_skill.py`) @@ -100,4 +102,4 @@ search: - 실험적 Codex 동일 스레드 워크플로 (`examples/tools/codex_same_thread.py`) - **[voice](https://github.com/openai/openai-agents-python/tree/main/examples/voice):** - 스트리밍 음성 예제를 포함해 TTS 및 STT 모델을 사용하는 음성 에이전트 예제를 확인해 보세요 \ No newline at end of file + 스트리밍 음성 예제를 포함해 TTS 및 STT 모델을 사용하는 음성 에이전트 예제를 확인하세요 \ No newline at end of file diff --git a/docs/ko/models/index.md b/docs/ko/models/index.md index ae3687f205..f76747cab5 100644 --- a/docs/ko/models/index.md +++ b/docs/ko/models/index.md @@ -4,39 +4,39 @@ search: --- # 모델 -Agents SDK는 OpenAI 모델을 두 가지 방식으로 즉시 사용할 수 있도록 지원합니다 +Agents SDK 는 기본으로 OpenAI 모델을 다음 두 가지 방식으로 지원합니다 -- **권장**: 새로운 [Responses API](https://platform.openai.com/docs/api-reference/responses)를 사용해 OpenAI API를 호출하는 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] -- [Chat Completions API](https://platform.openai.com/docs/api-reference/chat)를 사용해 OpenAI API를 호출하는 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] +- **권장**: 새로운 [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) | +| websocket 전송으로 OpenAI Responses API 사용 | [Responses WebSocket 전송](#responses-websocket-transport) | +| OpenAI 이외 provider 사용 | [OpenAI 이외 모델](#non-openai-models) | +| 하나의 워크플로에서 모델/provider 혼합 | [고급 모델 선택 및 혼합](#advanced-model-selection-and-mixing) 및 [provider 간 모델 혼합](#mixing-models-across-providers) | +| provider 호환성 문제 디버깅 | [OpenAI 이외 provider 문제 해결](#troubleshooting-non-openai-providers) | ## 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)로 설정하는 것을 권장합니다. +`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) 같은 다른 모델로 전환하려면 에이전트를 구성하는 방법이 두 가지 있습니다. +[`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`를 통해 실행(run) 단위 기본 모델을 설정할 수 있습니다. 에이전트에 모델을 설정하지 않으면 이 실행의 모델이 사용됩니다. +둘째, `RunConfig`를 통해 실행 단위 기본 모델을 설정할 수 있습니다. 에이전트에 모델을 설정하지 않으면 이 실행의 모델이 사용됩니다 ```python from agents import Agent, RunConfig, Runner @@ -55,7 +55,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 +71,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 가 전송하는 컴퓨터 도구 payload 를 결정합니다. 명시적 `gpt-5.4` 요청은 GA 내장 `computer` 도구를 사용하고, 명시적 `computer-use-preview` 요청은 이전 `computer_use_preview` payload 를 유지합니다. -주요 예외는 프롬프트 관리 호출입니다. 프롬프트 템플릿이 모델을 소유하고 SDK가 요청에서 `model`을 생략하면, 프롬프트가 어떤 모델에 고정되어 있는지 추측하지 않도록 SDK는 preview 호환 컴퓨터 페이로드를 기본으로 사용합니다. 이 흐름에서 GA 경로를 유지하려면 요청에 `model="gpt-5.4"`를 명시하거나 `ModelSettings(tool_choice="computer")` 또는 `ModelSettings(tool_choice="computer_use")`로 GA 선택기를 강제하세요. +주된 예외는 프롬프트 관리 호출입니다. 프롬프트 템플릿이 모델을 소유하고 SDK 가 요청에서 `model`을 생략하면, SDK 는 프롬프트가 고정한 모델을 추측하지 않기 위해 preview 호환 컴퓨터 payload 를 기본값으로 사용합니다. 해당 흐름에서 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,11 +95,11 @@ preview 호환 요청은 `environment`와 디스플레이 크기를 미리 직 - [`tool_namespace()`][agents.tool.tool_namespace] - `@function_tool(defer_loading=True)` 및 기타 지연 로딩 Responses 도구 표면 -이 기능들은 Chat Completions 모델과 non-Responses 백엔드에서 거부됩니다. 지연 로딩 도구를 사용할 때는 에이전트에 `ToolSearchTool()`을 추가하고, 네임스페이스 이름만 또는 지연 전용 함수 이름을 강제하는 대신 `auto` 또는 `required` 도구 선택을 통해 모델이 도구를 로드하도록 하세요. 설정 세부 사항과 현재 제약은 [도구](../tools.md#hosted-tool-search)를 참조하세요. +이 기능들은 Chat Completions 모델 및 Responses 가 아닌 백엔드에서는 거부됩니다. 지연 로딩 도구를 사용할 때는 에이전트에 `ToolSearchTool()`을 추가하고, 네임스페이스 이름만 또는 지연 전용 함수 이름을 강제하지 말고 모델이 `auto` 또는 `required` tool choice 를 통해 도구를 로드하도록 하세요. 설정 세부 정보와 현재 제약 사항은 [도구](../tools.md#hosted-tool-search)를 참조하세요 ### 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 +107,11 @@ 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 단위로 websocket 전송을 구성할 수도 있습니다 ```python from agents import Agent, OpenAIProvider, RunConfig, Runner @@ -130,14 +130,14 @@ result = await Runner.run( ) ``` -접두사 기반 모델 라우팅이 필요하다면(예: 하나의 실행에서 `openai/...`와 `litellm/...` 모델 이름 혼합), 대신 [`MultiProvider`][agents.MultiProvider]를 사용하고 거기서 `openai_use_responses_websocket=True`를 설정하세요. +접두사 기반 모델 라우팅이 필요하다면(예: 한 실행에서 `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`를 발생시킵니다 -리터럴 네임스페이스 모델 ID를 기대하는 OpenAI 호환 엔드포인트에 OpenAI 공급자를 연결하는 경우, 명시적으로 pass-through 동작을 활성화하세요. websocket이 활성화된 설정에서는 `MultiProvider`에서도 `openai_use_responses_websocket=True`를 유지하세요 +OpenAI provider 를 리터럴 네임스페이스 모델 ID 를 기대하는 OpenAI 호환 엔드포인트로 지정하는 경우, 명시적으로 pass-through 동작을 활성화하세요. websocket 활성화 설정에서는 `MultiProvider`에도 `openai_use_responses_websocket=True`를 유지하세요 ```python from agents import Agent, MultiProvider, RunConfig, Runner @@ -163,56 +163,56 @@ 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 공급자에는 적용되지 않습니다 +- 이것은 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)를 참조하세요 +- websocket 전송 활성화 후 [`Runner.run_streamed()`][agents.run.Runner.run_streamed]를 직접 사용할 수 있습니다. 동일 websocket 연결을 턴 간(및 중첩된 agent-as-tool 호출 간) 재사용하려는 멀티턴 워크플로에서는 [`responses_websocket_session()`][agents.responses_websocket_session] 헬퍼를 권장합니다. [에이전트 실행](../running_agents.md) 가이드와 [`examples/basic/stream_ws.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/stream_ws.py)를 참조하세요 -## 비 OpenAI 모델 +## OpenAI 이외 모델 -대부분의 다른 비 OpenAI 모델은 [LiteLLM 통합](./litellm.md)을 통해 사용할 수 있습니다. 먼저 litellm 의존성 그룹을 설치하세요 +대부분의 OpenAI 이외 모델은 [LiteLLM 통합](./litellm.md)을 통해 사용할 수 있습니다. 먼저 litellm 의존성 그룹을 설치하세요 ```bash pip install "openai-agents[litellm]" ``` -그런 다음 `litellm/` 접두사로 [지원되는 모델](https://docs.litellm.ai/docs/providers)을 사용할 수 있습니다 +그다음 `litellm/` 접두사와 함께 [지원 모델](https://docs.litellm.ai/docs/providers) 중 아무 것이나 사용하세요 ```python claude_agent = Agent(model="litellm/anthropic/claude-3-5-sonnet-20240620", ...) gemini_agent = Agent(model="litellm/gemini/gemini-2.5-flash-preview-04-17", ...) ``` -### 비 OpenAI 모델을 사용하는 다른 방법 +### OpenAI 이외 모델 사용의 다른 방법 -다른 LLM 공급자는 3가지 방법으로 추가 통합할 수 있습니다(예제는 [여기](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)) +다른 LLM provider 를 통합하는 방법은 3가지가 더 있습니다(예제는 [여기](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)) -1. [`set_default_openai_client`][agents.set_default_openai_client]는 `AsyncOpenAI` 인스턴스를 LLM 클라이언트로 전역 사용하려는 경우에 유용합니다. LLM 공급자가 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)를 참조하세요. 대부분의 사용 가능한 모델을 쉽게 사용하는 방법은 [LiteLLM 통합](./litellm.md)입니다 -`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 사용을 권장합니다 + 이 예제들에서는 대부분의 LLM provider 가 아직 Responses API 를 지원하지 않기 때문에 Chat Completions 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 - 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 +248,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 @@ -263,15 +263,16 @@ english_agent = Agent( #### 일반적인 고급 `ModelSettings` 옵션 -OpenAI Responses API를 사용할 때는 여러 요청 필드가 이미 직접적인 `ModelSettings` 필드를 가지므로, 이를 위해 `extra_args`를 사용할 필요가 없습니다. +OpenAI Responses API 를 사용할 때는 여러 요청 필드에 대응하는 `ModelSettings` 필드가 이미 있으므로 `extra_args`가 필요하지 않습니다 | 필드 | 용도 | | --- | --- | -| `parallel_tool_calls` | 같은 턴에서 여러 도구 호출을 허용하거나 금지 | -| `truncation` | 컨텍스트가 넘칠 때 실패하는 대신 Responses API가 가장 오래된 대화 항목을 삭제하도록 `"auto"` 설정 | -| `prompt_cache_retention` | 예를 들어 `"24h"`로 캐시된 프롬프트 접두사를 더 오래 유지 | -| `response_include` | `web_search_call.action.sources`, `file_search_call.results`, `reasoning.encrypted_content` 같은 더 풍부한 응답 페이로드 요청 | -| `top_logprobs` | 출력 텍스트의 상위 토큰 logprobs 요청. SDK는 `message.output_text.logprobs`도 자동 추가 | +| `parallel_tool_calls` | 같은 턴에서 여러 도구 호출을 허용하거나 금지합니다 | +| `truncation` | 컨텍스트 초과 시 실패하는 대신 Responses API 가 가장 오래된 대화 항목을 삭제하도록 `"auto"`를 설정합니다 | +| `prompt_cache_retention` | 예를 들어 `"24h"`로 캐시된 프롬프트 접두사를 더 오래 유지합니다 | +| `response_include` | `web_search_call.action.sources`, `file_search_call.results`, `reasoning.encrypted_content` 같은 더 풍부한 응답 payload 를 요청합니다 | +| `top_logprobs` | 출력 텍스트의 상위 토큰 logprobs 를 요청합니다. SDK 는 `message.output_text.logprobs`도 자동 추가합니다 | +| `retry` | 모델 호출에 대해 runner 관리 재시도 설정을 선택적으로 활성화합니다. [Runner 관리 재시도](#runner-managed-retries)를 참조하세요 | ```python from agents import Agent, ModelSettings @@ -289,9 +290,94 @@ research_agent = Agent( ) ``` -SDK가 아직 최상위로 직접 노출하지 않은 공급자별 또는 최신 요청 필드가 필요하면 `extra_args`를 사용하세요. +#### Runner 관리 재시도 -또한 OpenAI의 Responses API를 사용할 때 [다른 선택적 매개변수](https://platform.openai.com/docs/api-reference/responses/create)(예: `user`, `service_tier` 등)가 몇 가지 있습니다. 최상위에서 사용할 수 없다면 `extra_args`로 함께 전달할 수 있습니다. +재시도는 런타임 전용이며 opt in 입니다. `ModelSettings(retry=...)`를 설정하고 재시도 정책이 재시도를 선택하지 않으면 SDK 는 일반 모델 요청을 재시도하지 않습니다 + +```python +from agents import Agent, ModelRetrySettings, ModelSettings, retry_policies + +agent = Agent( + name="Assistant", + model="gpt-5.4", + model_settings=ModelSettings( + retry=ModelRetrySettings( + max_retries=4, + backoff={ + "initial_delay": 0.5, + "max_delay": 5.0, + "multiplier": 2.0, + "jitter": True, + }, + policy=retry_policies.any( + retry_policies.provider_suggested(), + retry_policies.retry_after(), + retry_policies.network_error(), + retry_policies.http_status([408, 409, 429, 500, 502, 503, 504]), + ), + ) + ), +) +``` + +`ModelRetrySettings`에는 세 가지 필드가 있습니다 + +| 필드 | 타입 | 참고 | +| --- | --- | --- | +| `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` + +정책은 다음 중 하나를 반환할 수 있습니다 + +- 단순 재시도 결정을 위한 `True` / `False` +- 지연을 재정의하거나 진단 사유를 첨부하려는 경우 [`RetryDecision`][agents.retry.RetryDecision] + +SDK 는 `retry_policies`에 미리 준비된 헬퍼를 제공합니다 + +| 헬퍼 | 동작 | +| --- | --- | +| `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()`가 가장 안전한 첫 구성요소입니다. provider 가 구분할 수 있을 때 provider veto 와 replay-safety 승인을 보존하기 때문입니다. + +##### 안전 경계 + +일부 실패는 자동 재시도되지 않습니다 + +- Abort 오류 +- provider 권고에서 replay 가 안전하지 않다고 표시된 요청 +- replay 가 안전하지 않게 되는 방식으로 출력이 이미 시작된 이후의 스트리밍 실행 + +`previous_response_id` 또는 `conversation_id`를 사용하는 상태 저장 후속 요청도 더 보수적으로 처리됩니다. 이러한 요청에서는 `network_error()`나 `http_status([500])` 같은 비-provider 조건만으로는 충분하지 않습니다. 재시도 정책에는 일반적으로 `retry_policies.provider_suggested()`를 통한 provider 의 replay-safe 승인이 포함되어야 합니다. + +##### Runner 와 에이전트 병합 동작 + +`retry`는 runner 수준과 에이전트 수준 `ModelSettings` 사이에서 deep merge 됩니다 + +- 에이전트는 `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 가 아직 최상위에서 직접 노출하지 않는 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 @@ -307,26 +393,26 @@ english_agent = Agent( ) ``` -## 비 OpenAI 공급자 문제 해결 +## OpenAI 이외 provider 문제 해결 ### 트레이싱 클라이언트 오류 401 -트레이싱 관련 오류가 발생한다면, 트레이스가 OpenAI 서버로 업로드되는데 OpenAI API 키가 없기 때문입니다. 해결 방법은 세 가지입니다 +트레이싱 관련 오류가 발생한다면, trace 가 OpenAI 서버에 업로드되는데 OpenAI API 키가 없기 때문입니다. 해결 방법은 세 가지입니다 1. 트레이싱 완전 비활성화: [`set_tracing_disabled(True)`][agents.set_tracing_disabled] -2. 트레이싱용 OpenAI 키 설정: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]. 이 API 키는 트레이스 업로드에만 사용되며 [platform.openai.com](https://platform.openai.com/) 키여야 합니다 -3. 비 OpenAI 트레이스 프로세서 사용. [트레이싱 문서](../tracing.md#custom-tracing-processors) 참조 +2. 트레이싱용 OpenAI 키 설정: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]. 이 API 키는 trace 업로드에만 사용되며 [platform.openai.com](https://platform.openai.com/) 발급 키여야 합니다 +3. OpenAI 이외 trace 프로세서 사용. [트레이싱 문서](../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`을 설정하는 경우 동작합니다 +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)를 지원하지 않습니다. 이 경우 다음과 같은 오류가 발생할 수 있습니다 ``` @@ -334,12 +420,12 @@ BadRequestError: Error code: 400 - {'error': {'message': "'response_format.type' ``` -이는 일부 모델 공급자의 한계입니다. JSON 출력은 지원하지만 출력에 사용할 `json_schema`를 지정할 수는 없습니다. 이 문제는 수정 중이지만, 그렇지 않으면 앱이 잘못된 JSON 때문에 자주 깨질 수 있으므로 JSON schema 출력을 지원하는 공급자를 사용하는 것을 권장합니다. +이는 일부 모델 provider 의 한계입니다. JSON 출력은 지원하지만 출력에 사용할 `json_schema` 지정은 허용하지 않습니다. 이에 대한 수정 작업을 진행 중이지만, JSON schema 출력을 지원하는 provider 사용을 권장합니다. 그렇지 않으면 잘못된 JSON 때문에 앱이 자주 깨질 수 있습니다. -## 공급자 간 모델 혼합 +## provider 간 모델 혼합 -모델 공급자 간 기능 차이를 인지해야 하며, 그렇지 않으면 오류가 발생할 수 있습니다. 예를 들어 OpenAI는 structured outputs, 멀티모달 입력, 호스티드 file search 및 웹 검색을 지원하지만 많은 다른 공급자는 이러한 기능을 지원하지 않습니다. 다음 제한 사항에 유의하세요 +모델 provider 간 기능 차이를 인지해야 하며, 그렇지 않으면 오류가 발생할 수 있습니다. 예를 들어 OpenAI 는 structured outputs, 멀티모달 입력, 호스티드 파일 검색 및 웹 검색을 지원하지만, 다른 많은 provider 는 이러한 기능을 지원하지 않습니다. 다음 제한 사항에 유의하세요 -- 지원하지 않는 공급자에 이해할 수 없는 `tools`를 보내지 마세요 -- 텍스트 전용 모델을 호출하기 전에 멀티모달 입력을 필터링하세요 -- structured JSON 출력을 지원하지 않는 공급자는 때때로 유효하지 않은 JSON을 생성할 수 있다는 점에 유의하세요 \ No newline at end of file +- 지원하지 않는 `tools`를 이해하지 못하는 provider 에 보내지 마세요 +- 텍스트 전용 모델 호출 전 멀티모달 입력을 필터링하세요 +- structured JSON 출력을 지원하지 않는 provider 는 가끔 유효하지 않은 JSON 을 생성할 수 있음을 유의하세요 \ No newline at end of file diff --git a/docs/ko/running_agents.md b/docs/ko/running_agents.md index c6949b468b..00b9832ea2 100644 --- a/docs/ko/running_agents.md +++ b/docs/ko/running_agents.md @@ -4,7 +4,7 @@ search: --- # 에이전트 실행 -[`Runner`][agents.run.Runner] 클래스를 통해 에이전트를 실행할 수 있습니다. 방법은 3가지입니다 +[`Runner`][agents.run.Runner] 클래스를 통해 에이전트를 실행할 수 있습니다. 3가지 옵션이 있습니다: 1. [`Runner.run()`][agents.run.Runner.run]: 비동기로 실행되며 [`RunResult`][agents.result.RunResult]를 반환합니다 2. [`Runner.run_sync()`][agents.run.Runner.run_sync]: 동기 메서드이며 내부적으로 `.run()`을 실행합니다 @@ -23,19 +23,19 @@ async def main(): # Infinite loop's dance ``` -자세한 내용은 [결과 가이드](results.md)를 참고하세요 +자세한 내용은 [결과 가이드](results.md)에서 확인하세요 ## Runner 수명 주기 및 구성 ### 에이전트 루프 -`Runner`의 run 메서드를 사용할 때 시작 에이전트와 입력을 전달합니다. 입력은 다음 중 하나일 수 있습니다 +`Runner`에서 run 메서드를 사용할 때 시작 에이전트와 입력을 전달합니다. 입력은 다음 중 하나일 수 있습니다: -- 문자열(사용자 메시지로 처리) -- OpenAI Responses API 형식의 입력 항목 목록 -- 인터럽션(중단 처리)된 실행을 재개할 때의 [`RunState`][agents.run_state.RunState] +- 문자열(사용자 메시지로 처리됨) +- OpenAI Responses API 형식의 입력 항목 리스트 +- 중단된 실행을 재개할 때의 [`RunState`][agents.run_state.RunState] -그다음 runner는 루프를 실행합니다 +그런 다음 runner는 루프를 실행합니다: 1. 현재 입력으로 현재 에이전트에 대해 LLM을 호출합니다 2. LLM이 출력을 생성합니다 @@ -46,21 +46,21 @@ async def main(): !!! note - LLM 출력이 "final output"으로 간주되는 기준은 원하는 타입의 텍스트 출력을 생성하고, 도구 호출이 없는 경우입니다 + LLM 출력이 "최종 출력"으로 간주되는 기준은 원하는 타입의 텍스트 출력을 생성하고 도구 호출이 없는 경우입니다 ### 스트리밍 -스트리밍을 사용하면 LLM 실행 중 스트리밍 이벤트를 추가로 받을 수 있습니다. 스트림이 완료되면 [`RunResultStreaming`][agents.result.RunResultStreaming]에 실행에 관한 전체 정보(생성된 모든 신규 출력 포함)가 담깁니다. 스트리밍 이벤트는 `.stream_events()`를 호출해 받을 수 있습니다. 자세한 내용은 [스트리밍 가이드](streaming.md)를 참고하세요 +스트리밍을 사용하면 LLM 실행 중 스트리밍 이벤트를 추가로 받을 수 있습니다. 스트림이 완료되면 [`RunResultStreaming`][agents.result.RunResultStreaming]에는 새로 생성된 모든 출력을 포함한 실행 전체 정보가 담깁니다. 스트리밍 이벤트는 `.stream_events()`를 호출해 받을 수 있습니다. 자세한 내용은 [스트리밍 가이드](streaming.md)를 참고하세요 #### Responses WebSocket 전송(선택적 헬퍼) OpenAI Responses websocket 전송을 활성화하면 일반 `Runner` API를 계속 사용할 수 있습니다. websocket 세션 헬퍼는 연결 재사용에 권장되지만 필수는 아닙니다 -이것은 websocket 전송 기반 Responses API이며 [Realtime API](realtime/guide.md)가 아닙니다 +이것은 websocket 전송을 통한 Responses API이며, [Realtime API](realtime/guide.md)가 아닙니다 -구체적인 모델 객체 또는 커스텀 provider 관련 전송 선택 규칙과 주의사항은 [Models](models/index.md#responses-websocket-transport)를 참고하세요 +구체적인 model 객체 또는 사용자 지정 provider 관련 전송 선택 규칙과 주의 사항은 [Models](models/index.md#responses-websocket-transport)를 참고하세요 -##### 패턴 1: 세션 헬퍼 없음(작동함) +##### 패턴 1: 세션 헬퍼 미사용(작동함) websocket 전송만 원하고 SDK가 공유 provider/session을 관리할 필요가 없을 때 사용합니다 @@ -85,11 +85,11 @@ async def main(): asyncio.run(main()) ``` -이 패턴은 단일 실행에 적합합니다. `Runner.run()` / `Runner.run_streamed()`를 반복 호출하면 동일한 `RunConfig` / provider 인스턴스를 수동 재사용하지 않는 한 실행마다 재연결될 수 있습니다 +이 패턴은 단일 실행에 적합합니다. `Runner.run()` / `Runner.run_streamed()`를 반복 호출하면 동일한 `RunConfig` / provider 인스턴스를 수동으로 재사용하지 않는 한 실행마다 재연결될 수 있습니다 -##### 패턴 2: `responses_websocket_session()` 사용(멀티턴 재사용에 권장) +##### 패턴 2: `responses_websocket_session()` 사용(멀티턴 재사용 권장) -여러 실행(동일한 `run_config`를 상속하는 중첩 agent-as-tool 호출 포함)에서 websocket 지원 provider와 `RunConfig`를 공유하려면 [`responses_websocket_session()`][agents.responses_websocket_session]을 사용하세요 +여러 실행에서(동일한 `run_config`를 상속하는 중첩 agents-as-tools 호출 포함) websocket 지원 provider와 `RunConfig`를 공유하려면 [`responses_websocket_session()`][agents.responses_websocket_session]을 사용하세요 ```python import asyncio @@ -117,7 +117,7 @@ async def main(): asyncio.run(main()) ``` -컨텍스트를 종료하기 전에 스트리밍 결과 소비를 완료하세요. websocket 요청이 진행 중인 상태에서 컨텍스트를 종료하면 공유 연결이 강제 종료될 수 있습니다 +컨텍스트를 종료하기 전에 스트리밍 결과 소비를 마치세요. websocket 요청이 진행 중일 때 컨텍스트를 종료하면 공유 연결이 강제로 닫힐 수 있습니다 ### 실행 구성 @@ -129,48 +129,48 @@ asyncio.run(main()) ##### 모델, provider, 세션 기본값 -- [`model`][agents.run.RunConfig.model]: 각 Agent의 `model`과 관계없이 사용할 전역 LLM 모델을 설정할 수 있습니다 -- [`model_provider`][agents.run.RunConfig.model_provider]: 모델 이름 조회용 모델 provider이며 기본값은 OpenAI입니다 -- [`model_settings`][agents.run.RunConfig.model_settings]: 에이전트별 설정을 재정의합니다. 예: 전역 `temperature` 또는 `top_p` 설정 -- [`session_settings`][agents.run.RunConfig.session_settings]: 실행 중 히스토리 조회 시 세션 수준 기본값(예: `SessionSettings(limit=...)`)을 재정의합니다 -- [`session_input_callback`][agents.run.RunConfig.session_input_callback]: Sessions 사용 시 각 턴 전에 새 사용자 입력을 세션 히스토리와 병합하는 방식을 커스터마이즈합니다. 콜백은 sync 또는 async가 가능합니다 +- [`model`][agents.run.RunConfig.model]: 각 Agent의 `model`과 무관하게 사용할 전역 LLM 모델을 설정할 수 있습니다 +- [`model_provider`][agents.run.RunConfig.model_provider]: 모델 이름 조회를 위한 model provider로, 기본값은 OpenAI입니다 +- [`model_settings`][agents.run.RunConfig.model_settings]: 에이전트별 설정을 재정의합니다. 예를 들어 전역 `temperature` 또는 `top_p`를 설정할 수 있습니다 +- [`session_settings`][agents.run.RunConfig.session_settings]: 실행 중 히스토리를 조회할 때 세션 수준 기본값(예: `SessionSettings(limit=...)`)을 재정의합니다 +- [`session_input_callback`][agents.run.RunConfig.session_input_callback]: Sessions 사용 시 각 턴 전에 새 사용자 입력을 세션 히스토리와 병합하는 방법을 사용자 지정합니다. 콜백은 동기 또는 비동기일 수 있습니다 ##### 가드레일, 핸드오프, 모델 입력 형태 조정 -- [`input_guardrails`][agents.run.RunConfig.input_guardrails], [`output_guardrails`][agents.run.RunConfig.output_guardrails]: 모든 실행에 포함할 입력 또는 출력 가드레일 목록 -- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: 핸드오프에 이미 필터가 없는 경우 모든 핸드오프에 적용할 전역 입력 필터입니다. 입력 필터로 새 에이전트에 전송되는 입력을 편집할 수 있습니다. 자세한 내용은 [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] 문서를 참고하세요 -- [`nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]: 다음 에이전트 호출 전에 이전 transcript를 단일 assistant 메시지로 축약하는 opt-in 베타 기능입니다. 중첩 핸드오프 안정화 중이므로 기본 비활성화이며, 활성화하려면 `True`, 원문 transcript를 통과시키려면 `False`를 사용합니다. [Runner 메서드][agents.run.Runner]는 `RunConfig`를 전달하지 않으면 자동 생성하므로 quickstart와 코드 예제에서는 기본적으로 비활성화 상태를 유지하며, 명시적 [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] 콜백은 계속 우선 적용됩니다. 개별 핸드오프는 [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history]로 이 설정을 재정의할 수 있습니다 -- [`handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper]: `nest_handoff_history`를 사용할 때마다 정규화된 transcript(히스토리 + 핸드오프 항목)를 받아 다음 에이전트로 전달할 정확한 입력 항목 목록을 반환하는 선택적 callable입니다. 전체 핸드오프 필터를 작성하지 않고도 내장 요약을 대체할 수 있습니다 -- [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter]: 모델 호출 직전에 완전히 준비된 모델 입력(instructions 및 입력 항목)을 편집하는 훅입니다. 예: 히스토리 축약, 시스템 프롬프트 주입 -- [`reasoning_item_id_policy`][agents.run.RunConfig.reasoning_item_id_policy]: runner가 이전 출력을 다음 턴 모델 입력으로 변환할 때 reasoning 항목 ID를 유지할지 생략할지 제어합니다 +- [`input_guardrails`][agents.run.RunConfig.input_guardrails], [`output_guardrails`][agents.run.RunConfig.output_guardrails]: 모든 실행에 포함할 입력/출력 가드레일 리스트 +- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: 핸드오프에 이미 필터가 없는 경우 모든 핸드오프에 적용할 전역 입력 필터입니다. 입력 필터를 사용하면 새 에이전트로 전송되는 입력을 편집할 수 있습니다. 자세한 내용은 [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] 문서를 참고하세요 +- [`nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]: 다음 에이전트를 호출하기 전에 기존 트랜스크립트를 단일 assistant 메시지로 축약하는 opt-in 베타 기능입니다. 중첩 핸드오프 안정화 중이므로 기본값은 비활성화입니다. 활성화하려면 `True`, 원문 트랜스크립트를 그대로 전달하려면 `False`로 두세요. [Runner methods][agents.run.Runner]는 전달되지 않은 경우 `RunConfig`를 자동 생성하므로 빠른 시작과 예제에서는 기본 비활성화 상태를 유지하며, 명시적 [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] 콜백은 계속 이를 재정의합니다. 개별 핸드오프는 [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history]로 이 설정을 재정의할 수 있습니다 +- [`handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper]: `nest_handoff_history`를 opt-in한 경우마다 정규화된 트랜스크립트(히스토리 + 핸드오프 항목)를 받는 선택적 callable입니다. 다음 에이전트로 전달할 정확한 입력 항목 리스트를 반환해야 하며, 전체 핸드오프 필터를 작성하지 않고도 내장 요약을 대체할 수 있습니다 +- [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter]: 모델 호출 직전에 완전히 준비된 모델 입력(instructions 및 입력 항목)을 편집하는 훅입니다. 예: 히스토리 축소, 시스템 프롬프트 주입 +- [`reasoning_item_id_policy`][agents.run.RunConfig.reasoning_item_id_policy]: runner가 이전 출력을 다음 턴 모델 입력으로 변환할 때 reasoning item ID를 유지하거나 생략할지 제어합니다 ##### 트레이싱 및 관측 가능성 -- [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]: 전체 실행에 대해 [트레이싱](tracing.md)을 비활성화할 수 있습니다 -- [`tracing`][agents.run.RunConfig.tracing]: 이 실행의 exporter, processor 또는 트레이싱 메타데이터를 재정의하려면 [`TracingConfig`][agents.tracing.TracingConfig]를 전달합니다 -- [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]: 트레이스에 LLM/도구 호출 입력/출력 등 잠재적으로 민감한 데이터를 포함할지 구성합니다 -- [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]: 실행의 트레이싱 워크플로 이름, trace ID, trace group ID를 설정합니다. 최소한 `workflow_name` 설정을 권장합니다. group ID는 여러 실행 간 트레이스를 연결할 수 있는 선택 필드입니다 +- [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]: 전체 실행에 대해 [tracing](tracing.md)을 비활성화할 수 있습니다 +- [`tracing`][agents.run.RunConfig.tracing]: [`TracingConfig`][agents.tracing.TracingConfig]를 전달해 이 실행의 exporter, processor, tracing 메타데이터를 재정의합니다 +- [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]: 트레이스에 LLM 및 도구 호출 입력/출력 같은 민감할 수 있는 데이터 포함 여부를 구성합니다 +- [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]: 실행의 tracing 워크플로우 이름, trace ID, trace group ID를 설정합니다. 최소한 `workflow_name` 설정을 권장합니다. group ID는 여러 실행의 트레이스를 연결할 수 있는 선택 필드입니다 - [`trace_metadata`][agents.run.RunConfig.trace_metadata]: 모든 트레이스에 포함할 메타데이터 ##### 도구 승인 및 도구 오류 동작 -- [`tool_error_formatter`][agents.run.RunConfig.tool_error_formatter]: 승인 플로우 중 도구 호출이 거부될 때 모델에 보이는 메시지를 커스터마이즈합니다 +- [`tool_error_formatter`][agents.run.RunConfig.tool_error_formatter]: 승인 플로우에서 도구 호출이 거부될 때 모델에 보이는 메시지를 사용자 지정합니다 -중첩 핸드오프는 opt-in 베타로 제공됩니다. 축약 transcript 동작을 사용하려면 `RunConfig(nest_handoff_history=True)`를 전달하거나 특정 핸드오프에 `handoff(..., nest_handoff_history=True)`를 설정하세요. 원문 transcript(기본값)를 유지하려면 플래그를 설정하지 않거나, 대화를 원하는 그대로 전달하는 `handoff_input_filter`(또는 `handoff_history_mapper`)를 제공하세요. 커스텀 mapper 작성 없이 생성 요약에 사용되는 래퍼 텍스트를 변경하려면 [`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers]를 호출하세요(기본값 복원은 [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers]) +중첩 핸드오프는 opt-in 베타로 제공됩니다. 축약된 트랜스크립트 동작을 활성화하려면 `RunConfig(nest_handoff_history=True)`를 전달하거나 특정 핸드오프에 대해 `handoff(..., nest_handoff_history=True)`를 설정하세요. 원문 트랜스크립트(기본값)를 유지하려면 플래그를 설정하지 않거나, 필요한 형태로 대화를 그대로 전달하는 `handoff_input_filter`(또는 `handoff_history_mapper`)를 제공하세요. 사용자 지정 mapper를 작성하지 않고 생성된 요약의 래퍼 텍스트를 변경하려면 [`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers]를 호출하세요(기본값 복원은 [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers]) -#### 실행 구성 세부사항 +#### 실행 구성 상세 ##### `tool_error_formatter` -승인 플로우에서 도구 호출이 거부될 때 모델에 반환되는 메시지를 커스터마이즈하려면 `tool_error_formatter`를 사용하세요 +`tool_error_formatter`를 사용해 승인 플로우에서 도구 호출이 거부될 때 모델에 반환되는 메시지를 사용자 지정할 수 있습니다 -formatter는 다음이 포함된 [`ToolErrorFormatterArgs`][agents.run_config.ToolErrorFormatterArgs]를 받습니다 +formatter는 다음 항목을 포함한 [`ToolErrorFormatterArgs`][agents.run_config.ToolErrorFormatterArgs]를 받습니다: - `kind`: 오류 카테고리. 현재는 `"approval_rejected"`입니다 -- `tool_type`: 도구 런타임(`"function"`, `"computer"`, `"shell"`, `"apply_patch"`) +- `tool_type`: 도구 런타임(`"function"`, `"computer"`, `"shell"`, 또는 `"apply_patch"`) - `tool_name`: 도구 이름 - `call_id`: 도구 호출 ID -- `default_message`: SDK의 기본 모델 표시 메시지 +- `default_message`: SDK 기본 모델 표시 메시지 - `run_context`: 활성 실행 컨텍스트 래퍼 메시지를 대체할 문자열을 반환하거나 SDK 기본값을 사용하려면 `None`을 반환하세요 @@ -198,56 +198,56 @@ result = Runner.run_sync( ##### `reasoning_item_id_policy` -`reasoning_item_id_policy`는 runner가 히스토리를 다음 턴으로 전달할 때(예: `RunResult.to_input_list()` 또는 session 기반 실행) reasoning 항목을 다음 턴 모델 입력으로 변환하는 방식을 제어합니다 +`reasoning_item_id_policy`는 runner가 히스토리를 다음 턴으로 전달할 때(예: `RunResult.to_input_list()` 또는 session 기반 실행 사용 시) reasoning item을 다음 턴 모델 입력으로 변환하는 방식을 제어합니다 -- `None` 또는 `"preserve"`(기본값): reasoning 항목 ID 유지 -- `"omit"`: 생성된 다음 턴 입력에서 reasoning 항목 ID 제거 +- `None` 또는 `"preserve"`(기본값): reasoning item ID 유지 +- `"omit"`: 생성된 다음 턴 입력에서 reasoning item ID 제거 -`"omit"`은 주로 Responses API 400 오류의 한 유형에 대한 opt-in 완화책으로 사용합니다. 이 오류는 reasoning 항목이 `id`와 함께 전송되지만 필수 후속 항목 없이 전송될 때 발생합니다(예: `Item 'rs_...' of type 'reasoning' was provided without its required following item.`) +`"omit"`은 주로 Responses API 400 오류 유형에 대한 opt-in 완화책으로 사용합니다. 이 오류는 reasoning item이 `id`와 함께 전송되지만 필수 후속 항목이 없는 경우 발생합니다(예: `Item 'rs_...' of type 'reasoning' was provided without its required following item.`) -이는 SDK가 이전 출력으로 후속 입력을 구성하는 멀티턴 에이전트 실행에서 발생할 수 있습니다(세션 영속성, 서버 관리 대화 델타, 스트리밍/비스트리밍 후속 턴, 재개 경로 포함). 이때 reasoning 항목 ID는 유지되지만 provider가 해당 ID가 대응하는 후속 항목과 짝을 유지하도록 요구할 수 있습니다 +이 문제는 SDK가 이전 출력으로부터 후속 입력을 구성할 때(세션 영속성, 서버 관리 대화 델타, 스트리밍/비스트리밍 후속 턴, 재개 경로 포함) 다중 턴 에이전트 실행에서 발생할 수 있으며, reasoning item ID가 보존되었지만 provider가 해당 ID를 대응하는 후속 항목과 함께 유지하도록 요구할 때 나타납니다 -`reasoning_item_id_policy="omit"`을 설정하면 reasoning 내용은 유지하면서 reasoning 항목 `id`를 제거하므로 SDK가 생성한 후속 입력에서 해당 API 불변 조건을 트리거하지 않게 됩니다 +`reasoning_item_id_policy="omit"`를 설정하면 reasoning 내용은 유지하되 reasoning item `id`를 제거하여 SDK 생성 후속 입력에서 해당 API 불변 조건을 트리거하지 않도록 합니다 -적용 범위 참고사항 +범위 참고: -- 이는 SDK가 후속 입력을 구성할 때 생성/전달하는 reasoning 항목에만 영향을 줍니다 -- 사용자가 제공한 초기 입력 항목은 다시 작성하지 않습니다 +- 이 설정은 SDK가 후속 입력을 구성할 때 생성/전달하는 reasoning item에만 영향을 줍니다 +- 사용자가 제공한 초기 입력 항목은 다시 쓰지 않습니다 - `call_model_input_filter`는 이 정책 적용 후에도 의도적으로 reasoning ID를 다시 도입할 수 있습니다 ## 상태 및 대화 관리 ### 메모리 전략 선택 -다음 턴으로 상태를 전달하는 일반적인 방법은 4가지입니다 +다음 턴으로 상태를 전달하는 일반적인 방법은 4가지입니다: -| 전략 | 상태 저장 위치 | 적합한 경우 | 다음 턴에 전달할 내용 | +| Strategy | Where state lives | Best for | What you pass on the next turn | | --- | --- | --- | --- | -| `result.to_input_list()` | 앱 메모리 | 작은 채팅 루프, 완전 수동 제어, 모든 provider | `result.to_input_list()`의 목록 + 다음 사용자 메시지 | -| `session` | 사용자 저장소 + SDK | 영속 채팅 상태, 재개 가능한 실행, 커스텀 스토어 | 동일한 `session` 인스턴스 또는 같은 스토어를 가리키는 다른 인스턴스 | -| `conversation_id` | OpenAI Conversations API | 워커/서비스 간 공유할 이름 있는 서버 측 대화 | 동일한 `conversation_id` + 새 사용자 턴만 | -| `previous_response_id` | OpenAI Responses API | 대화 리소스 생성 없이 가벼운 서버 관리 연속 실행 | `result.last_response_id` + 새 사용자 턴만 | +| `result.to_input_list()` | 앱 메모리 | 소규모 채팅 루프, 완전 수동 제어, 모든 provider | `result.to_input_list()`의 리스트 + 다음 사용자 메시지 | +| `session` | 사용자 스토리지 + SDK | 영속 채팅 상태, 재개 가능한 실행, 사용자 지정 스토어 | 동일한 `session` 인스턴스 또는 동일한 스토어를 가리키는 다른 인스턴스 | +| `conversation_id` | OpenAI Conversations API | 워커/서비스 간 공유할 서버 측 이름 있는 대화 | 동일한 `conversation_id` + 새 사용자 턴만 | +| `previous_response_id` | OpenAI Responses API | 대화 리소스를 만들지 않는 경량 서버 관리 연속 처리 | `result.last_response_id` + 새 사용자 턴만 | -`result.to_input_list()`와 `session`은 클라이언트 관리 방식입니다. `conversation_id`와 `previous_response_id`는 OpenAI 관리 방식이며 OpenAI Responses API 사용 시에만 적용됩니다. 대부분의 애플리케이션에서는 대화당 하나의 영속화 전략을 선택하세요. 클라이언트 관리 히스토리와 OpenAI 관리 상태를 함께 쓰면 두 계층을 의도적으로 조정하지 않는 한 컨텍스트가 중복될 수 있습니다 +`result.to_input_list()`와 `session`은 클라이언트 관리 방식입니다. `conversation_id`와 `previous_response_id`는 OpenAI 관리 방식이며 OpenAI Responses API 사용 시에만 적용됩니다. 대부분의 애플리케이션에서는 대화당 하나의 영속화 전략을 선택하세요. 의도적으로 두 계층을 조정하지 않는 한 클라이언트 관리 히스토리와 OpenAI 관리 상태를 혼합하면 컨텍스트가 중복될 수 있습니다 !!! note 세션 영속성은 서버 관리 대화 설정 - (`conversation_id`, `previous_response_id`, `auto_previous_response_id`)과 - 동일 실행에서 함께 사용할 수 없습니다. 호출마다 한 가지 접근법을 선택하세요 + (`conversation_id`, `previous_response_id`, 또는 `auto_previous_response_id`)과 + 동일 실행에서 함께 사용할 수 없습니다. 호출마다 한 가지 접근 방식을 선택하세요 ### 대화/채팅 스레드 -어떤 run 메서드를 호출하든 하나 이상의 에이전트 실행(즉 하나 이상의 LLM 호출)이 발생할 수 있지만, 논리적으로는 채팅 대화의 단일 턴을 나타냅니다. 예를 들어 +어떤 run 메서드를 호출하더라도 하나 이상의 에이전트가 실행될 수 있고(즉, 하나 이상의 LLM 호출), 이는 채팅 대화에서 단일 논리 턴을 나타냅니다. 예: 1. 사용자 턴: 사용자가 텍스트 입력 2. Runner 실행: 첫 번째 에이전트가 LLM 호출, 도구 실행, 두 번째 에이전트로 핸드오프, 두 번째 에이전트가 추가 도구 실행 후 출력 생성 -에이전트 실행이 끝나면 사용자에게 무엇을 보여줄지 선택할 수 있습니다. 예를 들어 에이전트가 생성한 모든 신규 항목을 보여주거나 최종 출력만 보여줄 수 있습니다. 어느 쪽이든 사용자가 후속 질문을 하면 run 메서드를 다시 호출할 수 있습니다 +에이전트 실행이 끝나면 사용자에게 보여줄 내용을 선택할 수 있습니다. 예를 들어 에이전트가 생성한 모든 새 항목을 보여주거나 최종 출력만 보여줄 수 있습니다. 이후 사용자가 후속 질문을 하면 run 메서드를 다시 호출할 수 있습니다 #### 수동 대화 관리 -다음 턴 입력을 얻기 위해 [`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] 메서드로 대화 히스토리를 수동 관리할 수 있습니다 +[`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] 메서드를 사용해 다음 턴 입력을 받아 대화 히스토리를 수동으로 관리할 수 있습니다: ```python async def main(): @@ -267,9 +267,9 @@ async def main(): # California ``` -#### Sessions를 사용한 자동 대화 관리 +#### 세션을 이용한 자동 대화 관리 -더 간단한 방법으로 [Sessions](sessions/index.md)를 사용하면 `.to_input_list()`를 수동 호출하지 않고도 대화 히스토리를 자동 처리할 수 있습니다 +더 간단한 접근으로, [Sessions](sessions/index.md)를 사용해 `.to_input_list()`를 수동 호출하지 않고 대화 히스토리를 자동 처리할 수 있습니다: ```python from agents import Agent, Runner, SQLiteSession @@ -293,24 +293,24 @@ async def main(): # California ``` -Sessions는 자동으로 다음을 수행합니다 +Sessions는 자동으로 다음을 수행합니다: - 각 실행 전에 대화 히스토리 조회 - 각 실행 후 새 메시지 저장 -- 서로 다른 세션 ID에 대해 분리된 대화 유지 +- 서로 다른 세션 ID에 대해 별도 대화 유지 자세한 내용은 [Sessions 문서](sessions/index.md)를 참고하세요 #### 서버 관리 대화 -`to_input_list()` 또는 `Sessions`로 로컬 처리하는 대신 OpenAI 대화 상태 기능이 서버 측에서 대화 상태를 관리하도록 할 수도 있습니다. 이렇게 하면 과거 메시지 전체를 수동 재전송하지 않고 대화 히스토리를 유지할 수 있습니다. 아래의 서버 관리 방식에서는 요청마다 새 턴 입력만 전달하고 저장된 ID를 재사용하세요. 자세한 내용은 [OpenAI 대화 상태 가이드](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses)를 참고하세요 +`to_input_list()` 또는 `Sessions`로 로컬 처리하는 대신 OpenAI 대화 상태 기능으로 서버 측에서 대화 상태를 관리할 수도 있습니다. 이렇게 하면 과거 메시지를 모두 수동 재전송하지 않고도 대화 히스토리를 유지할 수 있습니다. 아래 두 서버 관리 방식 모두에서 요청마다 새 턴 입력만 전달하고 저장된 ID를 재사용하세요. 자세한 내용은 [OpenAI Conversation state 가이드](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses)를 참고하세요 -OpenAI는 턴 간 상태 추적을 위한 두 가지 방법을 제공합니다 +OpenAI는 턴 간 상태 추적을 위한 두 가지 방법을 제공합니다: ##### 1. `conversation_id` 사용 -먼저 OpenAI Conversations API로 대화를 생성한 뒤, 이후 모든 호출에서 해당 ID를 재사용합니다 +먼저 OpenAI Conversations API로 대화를 생성하고, 이후 모든 호출에서 해당 ID를 재사용합니다: ```python from agents import Agent, Runner @@ -333,7 +333,7 @@ async def main(): ##### 2. `previous_response_id` 사용 -다른 방법은 **응답 체이닝(response chaining)**으로, 각 턴을 이전 턴의 응답 ID에 명시적으로 연결합니다 +다른 옵션은 **응답 체이닝**으로, 각 턴이 이전 턴의 응답 ID에 명시적으로 연결됩니다 ```python from agents import Agent, Runner @@ -358,30 +358,33 @@ async def main(): print(f"Assistant: {result.final_output}") ``` -실행이 승인 대기로 일시 중지되어 [`RunState`][agents.run_state.RunState]에서 재개하는 경우, +실행이 승인 대기 상태로 일시 중지되고 [`RunState`][agents.run_state.RunState]에서 재개하는 경우 SDK는 저장된 `conversation_id` / `previous_response_id` / `auto_previous_response_id` 설정을 유지하므로 재개된 턴이 동일한 서버 관리 대화에서 계속됩니다 -`conversation_id`와 `previous_response_id`는 상호 배타적입니다. 시스템 간 공유 가능한 이름 있는 대화 리소스가 필요하면 `conversation_id`를 사용하세요. 턴 간 가장 가벼운 Responses API 연속 실행 기본 요소가 필요하면 `previous_response_id`를 사용하세요 +`conversation_id`와 `previous_response_id`는 상호 배타적입니다. 시스템 간 공유 가능한 이름 있는 대화 리소스가 필요하면 `conversation_id`를 사용하세요. 턴 간 가장 가벼운 Responses API 연속 처리 기본 요소가 필요하면 `previous_response_id`를 사용하세요 !!! note SDK는 `conversation_locked` 오류를 백오프와 함께 자동 재시도합니다. 서버 관리 - 대화 실행에서는 재시도 전에 내부 conversation-tracker 입력을 되감아 - 동일한 준비 항목을 깔끔하게 재전송할 수 있도록 합니다 + 대화 실행에서는 재시도 전에 내부 대화 추적기 입력을 되감아 동일하게 준비된 항목을 + 깔끔하게 다시 전송할 수 있게 합니다 - 로컬 session 기반 실행에서는(`conversation_id`, - `previous_response_id`, `auto_previous_response_id`와 함께 사용할 수 없음) SDK가 - 재시도 후 중복 히스토리 항목을 줄이기 위해 최근 저장된 입력 항목을 - 최선의 노력으로 롤백합니다 + 로컬 session 기반 실행(`conversation_id`, + `previous_response_id`, 또는 `auto_previous_response_id`와 함께 사용할 수 없음)에서는 + SDK가 재시도 후 중복 히스토리 항목을 줄이기 위해 최근 영속화된 입력 항목의 + 롤백도 가능한 범위에서 수행합니다 -## 훅 및 커스터마이즈 + 이 호환성 재시도는 `ModelSettings.retry`를 구성하지 않아도 수행됩니다. 모델 요청에 대한 + 더 광범위한 opt-in 재시도 동작은 [Runner 관리 재시도](models/index.md#runner-managed-retries)를 참고하세요 -### call model input filter +## 훅 및 사용자 지정 -모델 호출 직전에 모델 입력을 편집하려면 `call_model_input_filter`를 사용하세요. 이 훅은 현재 에이전트, 컨텍스트, 결합된 입력 항목(Session 히스토리 포함 가능)을 받고 새로운 `ModelInputData`를 반환합니다 +### 모델 호출 입력 필터 -반환값은 [`ModelInputData`][agents.run.ModelInputData] 객체여야 합니다. `input` 필드는 필수이며 입력 항목 목록이어야 합니다. 다른 형태를 반환하면 `UserError`가 발생합니다 +`call_model_input_filter`를 사용하면 모델 호출 직전에 모델 입력을 편집할 수 있습니다. 이 훅은 현재 에이전트, 컨텍스트, 결합된 입력 항목(세션 히스토리 포함 시 포함됨)을 받아 새 `ModelInputData`를 반환합니다 + +반환값은 [`ModelInputData`][agents.run.ModelInputData] 객체여야 합니다. `input` 필드는 필수이며 입력 항목 리스트여야 합니다. 다른 형태를 반환하면 `UserError`가 발생합니다 ```python from agents import Agent, Runner, RunConfig @@ -400,19 +403,19 @@ result = Runner.run_sync( ) ``` -runner는 준비된 입력 목록의 복사본을 훅에 전달하므로, 호출자가 가진 원본 목록을 제자리 변경하지 않고도 항목을 축약, 교체, 재정렬할 수 있습니다 +runner는 준비된 입력 리스트의 복사본을 훅에 전달하므로 호출자 원본 리스트를 제자리에서 변경하지 않고도 잘라내기, 교체, 재정렬할 수 있습니다 -session을 사용하는 경우 `call_model_input_filter`는 세션 히스토리가 이미 로드되어 현재 턴과 병합된 뒤에 실행됩니다. 이보다 이른 병합 단계 자체를 커스터마이즈하려면 [`session_input_callback`][agents.run.RunConfig.session_input_callback]을 사용하세요 +session을 사용하는 경우 `call_model_input_filter`는 세션 히스토리가 이미 로드되어 현재 턴과 병합된 후에 실행됩니다. 그보다 이른 병합 단계 자체를 사용자 지정하려면 [`session_input_callback`][agents.run.RunConfig.session_input_callback]을 사용하세요 -`conversation_id`, `previous_response_id`, `auto_previous_response_id`를 사용하는 OpenAI 서버 관리 대화 상태에서는 이 훅이 다음 Responses API 호출용 준비 payload에 대해 실행됩니다. 이 payload는 이미 이전 히스토리 전체 재생이 아닌 새 턴 델타만 나타낼 수 있습니다. 사용자가 반환한 항목만 해당 서버 관리 연속 실행에서 전송된 것으로 표시됩니다 +`conversation_id`, `previous_response_id`, 또는 `auto_previous_response_id`와 함께 OpenAI 서버 관리 대화 상태를 사용하는 경우 이 훅은 다음 Responses API 호출을 위한 준비된 페이로드에서 실행됩니다. 해당 페이로드는 이전 히스토리 전체 재생이 아니라 새 턴 델타만 나타낼 수 있습니다. 반환한 항목만 해당 서버 관리 연속 처리에서 전송됨으로 표시됩니다 -민감 정보 마스킹, 긴 히스토리 축약, 추가 시스템 가이드 주입을 위해 실행별로 `run_config`에서 이 훅을 설정하세요 +민감 데이터 비식별화, 긴 히스토리 축소, 추가 시스템 가이드 주입을 위해 실행별로 `run_config`에서 훅을 설정하세요 ## 오류 및 복구 ### 오류 핸들러 -모든 `Runner` 진입점은 오류 종류를 키로 하는 dict인 `error_handlers`를 받습니다. 현재 지원 키는 `"max_turns"`입니다. `MaxTurnsExceeded`를 발생시키는 대신 제어된 최종 출력을 반환하려면 사용하세요 +모든 `Runner` 진입점은 오류 종류를 키로 하는 dict인 `error_handlers`를 받습니다. 현재 지원 키는 `"max_turns"`입니다. `MaxTurnsExceeded`를 발생시키는 대신 제어된 최종 출력을 반환하려는 경우 사용하세요 ```python from agents import ( @@ -441,35 +444,35 @@ result = Runner.run_sync( print(result.final_output) ``` -대체 출력이 대화 히스토리에 추가되지 않도록 하려면 `include_in_history=False`를 설정하세요 +대체 출력을 대화 히스토리에 추가하지 않으려면 `include_in_history=False`로 설정하세요 ## 내구성 실행 통합 및 휴먼인더루프 (HITL) -도구 승인 일시중지/재개 패턴은 전용 [휴먼인더루프 가이드](human_in_the_loop.md)부터 참고하세요 -아래 통합은 실행이 긴 대기, 재시도, 프로세스 재시작을 걸칠 수 있는 내구성 오케스트레이션을 위한 것입니다 +도구 승인 일시 중지/재개 패턴은 전용 [Human-in-the-loop 가이드](human_in_the_loop.md)부터 확인하세요 +아래 통합은 실행이 긴 대기, 재시도, 또는 프로세스 재시작에 걸칠 수 있는 내구성 오케스트레이션용입니다 ### Temporal -Agents SDK의 [Temporal](https://temporal.io/) 통합을 사용하면 휴먼인더루프 작업을 포함한 내구성 있고 장시간 실행되는 워크플로를 실행할 수 있습니다. 장시간 작업을 완료하기 위해 Temporal과 Agents SDK가 함께 동작하는 데모는 [이 영상](https://www.youtube.com/watch?v=fFBZqzT4DD8)에서 확인할 수 있으며, 문서는 [여기](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/openai_agents)에서 확인할 수 있습니다 +Agents SDK [Temporal](https://temporal.io/) 통합을 사용해 휴먼인더루프 작업을 포함한 내구성 있는 장기 실행 워크플로우를 실행할 수 있습니다. Temporal과 Agents SDK가 함께 장기 실행 작업을 완료하는 데모는 [이 영상](https://www.youtube.com/watch?v=fFBZqzT4DD8)에서 확인할 수 있으며, [문서는 여기](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/openai_agents)에서 볼 수 있습니다 ### Restate -Agents SDK의 [Restate](https://restate.dev/) 통합을 사용하면 인간 승인, 핸드오프, 세션 관리를 포함한 경량의 내구성 있는 에이전트를 구현할 수 있습니다. 이 통합은 의존성으로 Restate의 단일 바이너리 런타임이 필요하며, 프로세스/컨테이너 또는 서버리스 함수로 에이전트를 실행할 수 있습니다 +Agents SDK [Restate](https://restate.dev/) 통합을 사용해 인적 승인, 핸드오프, 세션 관리를 포함한 경량의 내구성 에이전트를 실행할 수 있습니다. 이 통합은 Restate의 단일 바이너리 런타임을 의존성으로 요구하며, 프로세스/컨테이너 또는 서버리스 함수로 에이전트 실행을 지원합니다 자세한 내용은 [개요](https://www.restate.dev/blog/durable-orchestration-for-ai-agents-with-restate-and-openai-sdk) 또는 [문서](https://docs.restate.dev/ai)를 참고하세요 ### DBOS -Agents SDK의 [DBOS](https://dbos.dev/) 통합을 사용하면 실패 및 재시작 상황에서도 진행 상태를 보존하는 신뢰성 높은 에이전트를 실행할 수 있습니다. 장시간 실행 에이전트, 휴먼인더루프 워크플로, 핸드오프를 지원합니다. sync와 async 메서드를 모두 지원합니다. 이 통합에는 SQLite 또는 Postgres 데이터베이스만 필요합니다. 자세한 내용은 통합 [repo](https://github.com/dbos-inc/dbos-openai-agents)와 [문서](https://docs.dbos.dev/integrations/openai-agents)를 참고하세요 +Agents SDK [DBOS](https://dbos.dev/) 통합을 사용해 장애 및 재시작 간에도 진행 상황을 보존하는 신뢰할 수 있는 에이전트를 실행할 수 있습니다. 장기 실행 에이전트, 휴먼인더루프 워크플로우, 핸드오프를 지원합니다. 동기/비동기 메서드를 모두 지원합니다. 이 통합은 SQLite 또는 Postgres 데이터베이스만 필요합니다. 자세한 내용은 통합 [repo](https://github.com/dbos-inc/dbos-openai-agents)와 [문서](https://docs.dbos.dev/integrations/openai-agents)를 참고하세요 ## 예외 -SDK는 특정 경우 예외를 발생시킵니다. 전체 목록은 [`agents.exceptions`][]에 있습니다. 개요는 다음과 같습니다 +특정 경우 SDK는 예외를 발생시킵니다. 전체 목록은 [`agents.exceptions`][]에 있습니다. 개요는 다음과 같습니다: -- [`AgentsException`][agents.exceptions.AgentsException]: SDK 내부에서 발생하는 모든 예외의 기본 클래스입니다. 다른 모든 구체적인 예외가 이 클래스를 기반으로 파생됩니다 -- [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]: 에이전트 실행이 `Runner.run`, `Runner.run_sync`, `Runner.run_streamed` 메서드에 전달한 `max_turns` 제한을 초과할 때 발생합니다. 지정된 상호작용 턴 수 내에 에이전트가 작업을 완료하지 못했음을 의미합니다 -- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]: 기반 모델(LLM)이 예상치 못했거나 유효하지 않은 출력을 생성할 때 발생합니다. 예시는 다음과 같습니다 - - 잘못된 형식의 JSON: 모델이 도구 호출용 JSON 구조 또는 직접 출력에서 잘못된 형식의 JSON을 제공한 경우(특히 특정 `output_type`이 정의된 경우) - - 예상치 못한 도구 관련 실패: 모델이 예상된 방식으로 도구를 사용하지 못한 경우 -- [`ToolTimeoutError`][agents.exceptions.ToolTimeoutError]: 함수 도구 호출이 구성된 타임아웃을 초과했고 도구가 `timeout_behavior="raise_exception"`을 사용할 때 발생합니다 -- [`UserError`][agents.exceptions.UserError]: SDK를 사용하는 코드 작성자(사용자)가 SDK 사용 중 오류를 낼 때 발생합니다. 일반적으로 잘못된 코드 구현, 유효하지 않은 구성, SDK API 오용에서 비롯됩니다 -- [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]: 입력 가드레일 또는 출력 가드레일 조건이 각각 충족될 때 발생합니다. 입력 가드레일은 처리 전 들어오는 메시지를 점검하고, 출력 가드레일은 전달 전 에이전트의 최종 응답을 점검합니다 \ No newline at end of file +- [`AgentsException`][agents.exceptions.AgentsException]: SDK 내에서 발생하는 모든 예외의 기본 클래스입니다. 다른 모든 구체적 예외가 이 클래스에서 파생되는 일반 타입 역할을 합니다 +- [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]: 에이전트 실행이 `Runner.run`, `Runner.run_sync`, 또는 `Runner.run_streamed` 메서드에 전달된 `max_turns` 제한을 초과할 때 발생합니다. 지정된 상호작용 턴 수 내에 에이전트가 작업을 완료하지 못했음을 나타냅니다 +- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]: 기본 모델(LLM)이 예상치 못했거나 유효하지 않은 출력을 생성할 때 발생합니다. 예: + - 형식이 잘못된 JSON: 모델이 도구 호출 또는 직접 출력에서, 특히 특정 `output_type`이 정의된 경우 형식이 잘못된 JSON 구조를 제공할 때 + - 예상치 못한 도구 관련 실패: 모델이 예상된 방식으로 도구를 사용하지 못할 때 +- [`ToolTimeoutError`][agents.exceptions.ToolTimeoutError]: 함수 도구 호출이 구성된 타임아웃을 초과하고 도구가 `timeout_behavior="raise_exception"`을 사용할 때 발생합니다 +- [`UserError`][agents.exceptions.UserError]: SDK를 사용하는 과정에서(즉, SDK를 사용하는 코드를 작성하는 사용자) 오류를 냈을 때 발생합니다. 일반적으로 잘못된 코드 구현, 유효하지 않은 구성, 또는 SDK API 오용으로 인해 발생합니다 +- [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]: 입력 가드레일 또는 출력 가드레일의 조건이 각각 충족될 때 발생합니다. 입력 가드레일은 처리 전에 들어오는 메시지를 검사하고, 출력 가드레일은 전달 전에 에이전트의 최종 응답을 검사합니다 \ No newline at end of file diff --git a/docs/zh/examples.md b/docs/zh/examples.md index 75e6737021..486fb13041 100644 --- a/docs/zh/examples.md +++ b/docs/zh/examples.md @@ -4,59 +4,61 @@ search: --- # 示例 -请在 [repo](https://github.com/openai/openai-agents-python/tree/main/examples) 的示例部分查看 SDK 的各类示例实现。示例按多个目录组织，用于展示不同的模式和能力。 +请在 [repo](https://github.com/openai/openai-agents-python/tree/main/examples) 的示例部分查看 SDK 的多种 sample code 实现。这些示例按多个目录组织，展示了不同的模式与能力。 ## 目录 -- **[agent_patterns](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns)：** +- **[agent_patterns](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns):** 此目录中的示例展示了常见的智能体设计模式，例如 - 确定性工作流 - Agents as tools - 并行智能体执行 - - 条件化工具使用 + - 条件式工具使用 - 输入/输出安全防护措施 - - LLM 作为评审 + - LLM 作为评判者 - 路由 - 流式传输安全防护措施 -- **[basic](https://github.com/openai/openai-agents-python/tree/main/examples/basic)：** +- **[basic](https://github.com/openai/openai-agents-python/tree/main/examples/basic):** 这些示例展示了 SDK 的基础能力，例如 - Hello World 示例（默认模型、GPT-5、开放权重模型） - 智能体生命周期管理 - 动态系统提示词 - 流式传输输出（文本、条目、函数调用参数） - - 跨轮次使用共享会话辅助器的 Responses websocket 传输（`examples/basic/stream_ws.py`） + - 跨多轮共享会话辅助器的 Responses websocket 传输（`examples/basic/stream_ws.py`） - 提示词模板 - 文件处理（本地与远程、图像与 PDF） - 用量追踪 + - 由 Runner 管理的重试设置（`examples/basic/retry.py`） + - 结合 LiteLLM 的由 Runner 管理的重试（`examples/basic/retry_litellm.py`） - 非严格输出类型 - 先前响应 ID 的使用 -- **[customer_service](https://github.com/openai/openai-agents-python/tree/main/examples/customer_service)：** - 航空公司的客户服务系统示例。 +- **[customer_service](https://github.com/openai/openai-agents-python/tree/main/examples/customer_service):** + 面向航空公司的客户服务系统示例。 -- **[financial_research_agent](https://github.com/openai/openai-agents-python/tree/main/examples/financial_research_agent)：** - 一个金融研究智能体，演示了使用智能体和工具进行金融数据分析的结构化研究工作流。 +- **[financial_research_agent](https://github.com/openai/openai-agents-python/tree/main/examples/financial_research_agent):** + 一个金融研究智能体，展示了使用智能体和工具进行金融数据分析的结构化研究工作流。 -- **[handoffs](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs)：** - 查看带消息过滤的智能体任务转移实用示例。 +- **[handoffs](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs):** + 查看带有消息过滤的智能体任务转移实用示例。 -- **[hosted_mcp](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp)：** +- **[hosted_mcp](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp):** 演示如何使用托管 MCP（Model context protocol）连接器与审批的示例。 -- **[mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp)：** +- **[mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp):** 了解如何使用 MCP（Model context protocol）构建智能体，包括： - 文件系统示例 - Git 示例 - MCP 提示词服务示例 - - SSE（服务端发送事件）示例 - - 可流式 HTTP 示例 + - SSE（Server-Sent Events）示例 + - 可流式传输 HTTP 示例 -- **[memory](https://github.com/openai/openai-agents-python/tree/main/examples/memory)：** - 不同智能体记忆实现示例，包括： +- **[memory](https://github.com/openai/openai-agents-python/tree/main/examples/memory):** + 智能体不同内存实现的示例，包括： - SQLite 会话存储 - 高级 SQLite 会话存储 @@ -67,37 +69,37 @@ search: - OpenAI Conversations 会话存储 - Responses 压缩会话存储 -- **[model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers)：** - 了解如何在 SDK 中使用非 OpenAI 模型，包括自定义提供方和 LiteLLM 集成。 +- **[model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):** + 探索如何在 SDK 中使用非 OpenAI 模型，包括自定义提供方和 LiteLLM 集成。 -- **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime)：** +- **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):** 展示如何使用 SDK 构建实时体验的示例，包括： - - 使用结构化文本与图像消息的 Web 应用模式 + - 使用结构化文本和图像消息的 Web 应用模式 - 命令行音频循环与播放处理 - 通过 WebSocket 集成 Twilio Media Streams - 使用 Realtime Calls API 附加流程的 Twilio SIP 集成 -- **[reasoning_content](https://github.com/openai/openai-agents-python/tree/main/examples/reasoning_content)：** +- **[reasoning_content](https://github.com/openai/openai-agents-python/tree/main/examples/reasoning_content):** 演示如何处理推理内容和 structured outputs 的示例。 -- **[research_bot](https://github.com/openai/openai-agents-python/tree/main/examples/research_bot)：** - 一个简单的深度研究克隆示例，演示复杂的多智能体研究工作流。 +- **[research_bot](https://github.com/openai/openai-agents-python/tree/main/examples/research_bot):** + 简单的深度研究克隆示例，展示复杂的多智能体研究工作流。 -- **[tools](https://github.com/openai/openai-agents-python/tree/main/examples/tools)：** +- **[tools](https://github.com/openai/openai-agents-python/tree/main/examples/tools):** 了解如何实现由OpenAI托管的工具和实验性 Codex 工具能力，例如： - 网络检索以及带过滤器的网络检索 - 文件检索 - - Code Interpreter + - 代码解释器 - 带内联技能的托管容器 shell（`examples/tools/container_shell_inline_skill.py`） - 带技能引用的托管容器 shell（`examples/tools/container_shell_skill_reference.py`） - 带本地技能的本地 shell（`examples/tools/local_shell_skill.py`） - - 带命名空间和延迟工具的工具检索（`examples/tools/tool_search.py`） + - 带命名空间和延迟工具的工具搜索（`examples/tools/tool_search.py`） - 计算机操作 - 图像生成 - 实验性 Codex 工具工作流（`examples/tools/codex.py`） - 实验性 Codex 同线程工作流（`examples/tools/codex_same_thread.py`） -- **[voice](https://github.com/openai/openai-agents-python/tree/main/examples/voice)：** +- **[voice](https://github.com/openai/openai-agents-python/tree/main/examples/voice):** 查看语音智能体示例，使用我们的 TTS 和 STT 模型，包括流式语音示例。 \ No newline at end of file diff --git a/docs/zh/models/index.md b/docs/zh/models/index.md index a5df397df5..f6ad9499c4 100644 --- a/docs/zh/models/index.md +++ b/docs/zh/models/index.md @@ -4,39 +4,39 @@ search: --- # 模型 -Agents SDK 内置了对 OpenAI 模型的开箱即用支持，提供两种形式： +Agents SDK 开箱即用支持两种 OpenAI 模型形态： - **推荐**：[`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]，使用新的 [Responses API](https://platform.openai.com/docs/api-reference/responses) 调用 OpenAI API。 - [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]，使用 [Chat Completions API](https://platform.openai.com/docs/api-reference/chat) 调用 OpenAI API。 ## 模型设置选择 -根据你的设置，按以下顺序使用本页： +请根据你的设置按以下顺序使用本页： | 目标 | 从这里开始 | | --- | --- | | 使用 SDK 默认配置的 OpenAI 托管模型 | [OpenAI 模型](#openai-models) | | 通过 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) | +| 在一个工作流中混用模型/提供方 | [高级模型选择与混用](#advanced-model-selection-and-mixing) 和 [跨提供方混用模型](#mixing-models-across-providers) | +| 排查提供方兼容性问题 | [非 OpenAI 提供方故障排查](#troubleshooting-non-openai-providers) | ## 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`。 +当你在初始化 `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) 的其他模型，有两种方式配置你的智能体。 +如果你想切换到其他模型（如 [`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 +55,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,35 +71,35 @@ 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 发送哪种 computer-tool 载荷。显式请求 `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 兼容的 computer 载荷，以避免猜测提示词绑定了哪个模型。要在该流程中保持 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](../tools.md#computertool-and-the-responses-computer-tool)。 #### 非 GPT-5 模型 -如果你传入非 GPT-5 模型名称且未自定义 `model_settings`，SDK 会回退到与任意模型兼容的通用 `ModelSettings`。 +如果你传入非 GPT-5 模型名且未提供自定义 `model_settings`，SDK 会回退到与任意模型兼容的通用 `ModelSettings`。 -### 仅 Responses 的工具检索特性 +### 仅 Responses 的工具检索功能 -以下工具特性仅在 OpenAI Responses 模型上受支持： +以下工具功能仅受 OpenAI Responses 模型支持： - [`ToolSearchTool`][agents.tool.ToolSearchTool] - [`tool_namespace()`][agents.tool.tool_namespace] - `@function_tool(defer_loading=True)` 以及其他延迟加载的 Responses 工具接口 -这些特性在 Chat Completions 模型和非 Responses 后端上会被拒绝。使用延迟加载工具时，请将 `ToolSearchTool()` 添加到智能体中，并让模型通过 `auto` 或 `required` 的 tool choice 来加载工具，而不是强制使用裸命名空间名称或仅延迟加载函数名。配置细节和当前限制见 [工具](../tools.md#hosted-tool-search)。 +这些功能在 Chat Completions 模型和非 Responses 后端上会被拒绝。使用延迟加载工具时，请向智能体添加 `ToolSearchTool()`，并让模型通过 `auto` 或 `required` 的工具选择加载工具，而不是强制使用裸命名空间名或仅延迟加载函数名。配置细节和当前限制见 [Tools](../tools.md#hosted-tool-search)。 ### Responses WebSocket 传输 -默认情况下，OpenAI Responses API 请求使用 HTTP 传输。使用 OpenAI 支持的模型时，你可以选择启用 websocket 传输。 +默认情况下，OpenAI Responses API 请求使用 HTTP 传输。使用 OpenAI 后端模型时，你可以选择启用 websocket 传输。 ```python from agents import set_default_openai_responses_transport @@ -107,9 +107,9 @@ from agents import set_default_openai_responses_transport set_default_openai_responses_transport("websocket") ``` -这会影响由默认 OpenAI 提供方解析的 OpenAI Responses 模型（包括如 `"gpt-5.4"` 这样的字符串模型名）。 +这会影响由默认 OpenAI 提供方解析出的 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=...)`，则由该提供方控制传输选择，而不是全局默认值。 你也可以按提供方或按运行配置 websocket 传输： @@ -134,10 +134,10 @@ result = await Runner.run( `MultiProvider` 保留了两个历史默认行为： -- `openai/...` 被视为 OpenAI 提供方别名，因此 `openai/gpt-4.1` 会作为模型 `gpt-4.1` 路由。 -- 未知前缀会抛出 `UserError`，而不是直接透传。 +- `openai/...` 被视为 OpenAI 提供方别名，因此 `openai/gpt-4.1` 会按模型 `gpt-4.1` 路由。 +- 未知前缀会抛出 `UserError`，而不是透传。 -当你将 OpenAI 提供方指向一个期望字面命名空间模型 ID 的 OpenAI 兼容端点时，请显式启用透传行为。在启用 websocket 的配置中，也要在 `MultiProvider` 上保留 `openai_use_responses_websocket=True`： +当你将 OpenAI 提供方指向一个期望字面量命名空间模型 ID 的 OpenAI 兼容端点时，请显式启用透传行为。在启用 websocket 的设置中，也要在 `MultiProvider` 上保留 `openai_use_responses_websocket=True`： ```python from agents import Agent, MultiProvider, RunConfig, Runner @@ -163,15 +163,15 @@ 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)。除非支持 Responses websocket `/responses` 端点，否则不适用于 Chat Completions 或非 OpenAI 提供方。 -- 如果你的环境中尚未安装，请安装 `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)。除非支持 Responses websocket `/responses` 端点，否则不适用于 Chat Completions 或非 OpenAI 提供方。 +- 若你的环境尚未安装，请安装 `websockets` 包。 +- 启用 websocket 传输后，你可以直接使用 [`Runner.run_streamed()`][agents.run.Runner.run_streamed]。对于希望在多轮流程（以及嵌套 agent-as-tool 调用）中复用同一 websocket 连接的场景，建议使用 [`responses_websocket_session()`][agents.responses_websocket_session] 辅助方法。参见 [Running agents](../running_agents.md) 指南和 [`examples/basic/stream_ws.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/stream_ws.py)。 ## 非 OpenAI 模型 @@ -181,7 +181,7 @@ result = await Runner.run( pip install "openai-agents[litellm]" ``` -然后，使用任意[支持的模型](https://docs.litellm.ai/docs/providers)，并加上 `litellm/` 前缀： +然后，使用任意[受支持模型](https://docs.litellm.ai/docs/providers)，并加上 `litellm/` 前缀： ```python claude_agent = Agent(model="litellm/anthropic/claude-3-5-sonnet-20240620", ...) @@ -190,21 +190,21 @@ gemini_agent = Agent(model="litellm/gemini/gemini-2.5-flash-preview-04-17", ...) ### 使用非 OpenAI 模型的其他方式 -你还可以通过另外 3 种方式集成其他 LLM 提供方（代码示例在[这里](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)）： +你还可以通过另外 3 种方式集成其他 LLM 提供方（示例见[这里](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)）： -1. [`set_default_openai_client`][agents.set_default_openai_client] 适用于你希望在全局使用 `AsyncOpenAI` 实例作为 LLM 客户端的场景。这适用于 LLM 提供方提供 OpenAI 兼容 API 端点，且你可以设置 `base_url` 和 `api_key` 的情况。可配置示例见 [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py)。 -2. [`ModelProvider`][agents.models.interface.ModelProvider] 位于 `Runner.run` 层级。这让你可以说“在本次运行中为所有智能体使用自定义模型提供方”。可配置示例见 [examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py)。 -3. [`Agent.model`][agents.agent.Agent.model] 允许你在特定 Agent 实例上指定模型。这使你可以为不同智能体混合搭配不同提供方。可配置示例见 [examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py)。使用大多数可用模型的简便方式是通过 [LiteLLM 集成](./litellm.md)。 +1. [`set_default_openai_client`][agents.set_default_openai_client] 适用于你希望全局使用 `AsyncOpenAI` 实例作为 LLM 客户端的场景。适用于 LLM 提供方提供 OpenAI 兼容 API 端点，且你可设置 `base_url` 与 `api_key` 的情况。可配置示例见 [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py)。 +2. [`ModelProvider`][agents.models.interface.ModelProvider] 位于 `Runner.run` 层级。这使你可以声明“本次运行中所有智能体都使用自定义模型提供方”。可配置示例见 [examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py)。 +3. [`Agent.model`][agents.agent.Agent.model] 允许你在特定 Agent 实例上指定模型。这使你可为不同智能体混用不同提供方。可配置示例见 [examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py)。使用大多数可用模型的简单方式是通过 [LiteLLM 集成](./litellm.md)。 -在你没有 `platform.openai.com` API key 的情况下，我们建议通过 `set_tracing_disabled()` 禁用追踪，或配置[其他追踪进程](../tracing.md)。 +在你没有 `platform.openai.com` API 密钥的情况下，建议通过 `set_tracing_disabled()` 禁用追踪，或配置[其他追踪进程](../tracing.md)。 !!! note - 在这些示例中，我们使用 Chat Completions API/模型，因为多数 LLM 提供方尚不支持 Responses API。如果你的 LLM 提供方支持它，我们建议使用 Responses。 + 在这些示例中，我们使用 Chat Completions API/模型，因为大多数 LLM 提供方尚不支持 Responses API。如果你的 LLM 提供方支持，建议使用 Responses。 ## 高级模型选择与混用 -在单个工作流中，你可能希望为每个智能体使用不同模型。例如，你可以在分流环节使用更小、更快的模型，而在复杂任务上使用更大、能力更强的模型。配置 [`Agent`][agents.Agent] 时，你可以通过以下任一方式选择特定模型： +在单个工作流中，你可能希望为每个智能体使用不同模型。例如，你可以用更小、更快的模型做分流，用更大、能力更强的模型处理复杂任务。配置 [`Agent`][agents.Agent] 时，你可以通过以下任一方式选择特定模型： 1. 传入模型名称。 2. 传入任意模型名 + 可将该名称映射为 Model 实例的 [`ModelProvider`][agents.models.interface.ModelProvider]。 @@ -212,7 +212,7 @@ gemini_agent = Agent(model="litellm/gemini/gemini-2.5-flash-preview-04-17", ...) !!!note - 虽然我们的 SDK 同时支持 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 和 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] 两种形态，但我们建议每个工作流只使用一种模型形态，因为两者支持的特性与工具集合不同。如果你的工作流必须混用模型形态，请确保你使用的所有特性在两者上都可用。 + 虽然我们的 SDK 同时支持 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 和 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] 这两种形态，但我们建议每个工作流使用单一模型形态，因为两者支持的功能和工具集不同。如果你的工作流必须混用模型形态，请确保你使用的所有功能在两者上都可用。 ```python from agents import Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel @@ -248,7 +248,7 @@ async def main(): 1. 直接设置 OpenAI 模型名称。 2. 提供 [`Model`][agents.models.interface.Model] 实现。 -当你希望进一步配置智能体使用的模型时，可以传入 [`ModelSettings`][agents.models.interface.ModelSettings]，其中提供了如 temperature 等可选模型配置参数。 +当你希望进一步配置智能体所用模型时，可传入 [`ModelSettings`][agents.models.interface.ModelSettings]，它提供可选模型配置参数（如 temperature）。 ```python from agents import Agent, ModelSettings @@ -263,15 +263,16 @@ english_agent = Agent( #### 常见高级 `ModelSettings` 选项 -使用 OpenAI Responses API 时，多个请求字段在 `ModelSettings` 中已有直接对应字段，因此你不需要为它们使用 `extra_args`。 +使用 OpenAI Responses API 时，多个请求字段在 `ModelSettings` 中已有直接字段，因此无需用 `extra_args` 传递。 | 字段 | 用途 | | --- | --- | -| `parallel_tool_calls` | 允许或禁止在同一轮中进行多次工具调用。 | -| `truncation` | 设置为 `"auto"` 时，Responses API 会在上下文将要溢出时丢弃最旧对话项，而不是直接失败。 | -| `prompt_cache_retention` | 让缓存的提示词前缀保留更久，例如 `"24h"`。 | -| `response_include` | 请求更丰富的响应载荷，如 `web_search_call.action.sources`、`file_search_call.results` 或 `reasoning.encrypted_content`。 | -| `top_logprobs` | 请求输出文本的 top-token logprobs。SDK 也会自动添加 `message.output_text.logprobs`。 | +| `parallel_tool_calls` | 允许或禁止同一轮中的多个工具调用。 | +| `truncation` | 设为 `"auto"`，让 Responses API 在上下文将溢出时丢弃最旧对话项，而不是失败。 | +| `prompt_cache_retention` | 更长时间保留缓存的提示词前缀，例如 `"24h"`。 | +| `response_include` | 请求更丰富的响应负载，如 `web_search_call.action.sources`、`file_search_call.results` 或 `reasoning.encrypted_content`。 | +| `top_logprobs` | 为输出文本请求 top-token logprobs。SDK 也会自动添加 `message.output_text.logprobs`。 | +| `retry` | 为模型调用启用由运行器管理的重试设置。见[运行器管理的重试](#runner-managed-retries)。 | ```python from agents import Agent, ModelSettings @@ -289,9 +290,94 @@ research_agent = Agent( ) ``` -当你需要 SDK 尚未在顶层直接暴露的提供方特定字段或较新的请求字段时，请使用 `extra_args`。 +#### 运行器管理的重试 -此外，当你使用 OpenAI 的 Responses API 时，[还有一些其他可选参数](https://platform.openai.com/docs/api-reference/responses/create)（例如 `user`、`service_tier` 等）。如果它们在顶层不可用，也可以通过 `extra_args` 传入。 +重试仅在运行时生效，且需显式启用。除非你设置 `ModelSettings(retry=...)` 且重试策略决定重试，否则 SDK 不会重试通用模型请求。 + +```python +from agents import Agent, ModelRetrySettings, ModelSettings, retry_policies + +agent = Agent( + name="Assistant", + model="gpt-5.4", + model_settings=ModelSettings( + retry=ModelRetrySettings( + max_retries=4, + backoff={ + "initial_delay": 0.5, + "max_delay": 5.0, + "multiplier": 2.0, + "jitter": True, + }, + policy=retry_policies.any( + retry_policies.provider_suggested(), + retry_policies.retry_after(), + retry_policies.network_error(), + retry_policies.http_status([408, 409, 429, 500, 502, 503, 504]), + ), + ) + ), +) +``` + +`ModelRetrySettings` 有三个字段： + +| 字段 | 类型 | 说明 | +| --- | --- | --- | +| `max_retries` | `int \| None` | 初始请求之后允许的重试次数。 | +| `backoff` | `ModelRetryBackoffSettings \| dict \| None` | 当策略重试但未返回显式延迟时使用的默认延迟策略。 | +| `policy` | `RetryPolicy \| None` | 决定是否重试的回调。该字段仅运行时使用，不会被序列化。 | + +重试策略会收到一个 [`RetryPolicyContext`][agents.retry.RetryPolicyContext]，其中包含： + +- `attempt` 和 `max_retries`，用于做与尝试次数相关的决策。 +- `stream`，用于区分流式与非流式行为。 +- `error`，用于原始检查。 +- 标准化信息 `normalized`，如 `status_code`、`retry_after`、`error_code`、`is_network_error`、`is_timeout` 和 `is_abort`。 +- 当底层模型适配器可提供重试指导时的 `provider_advice`。 + +策略可返回： + +- `True` / `False`，用于简单重试决策。 +- [`RetryDecision`][agents.retry.RetryDecision]，用于覆盖延迟或附加诊断原因。 + +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(...)` | 仅当所有嵌套策略都启用时才重试。 | + +组合策略时，`provider_suggested()` 是最安全的首个构件，因为当提供方可区分时，它会保留提供方否决和重放安全批准。 + +##### 安全边界 + +某些失败永远不会自动重试： + +- Abort 错误。 +- 提供方建议标记为重放不安全的请求。 +- 流式运行中输出已开始且会导致重放不安全的情况。 + +使用 `previous_response_id` 或 `conversation_id` 的有状态后续请求也会被更保守地处理。对于这类请求，仅有 `network_error()` 或 `http_status([500])` 等非提供方谓词并不足够。重试策略应包含提供方的重放安全批准，通常通过 `retry_policies.provider_suggested()`。 + +##### 运行器与智能体合并行为 + +在运行器级和智能体级 `ModelSettings` 之间，`retry` 会深度合并： + +- 智能体可仅覆盖 `retry.max_retries`，并仍继承运行器的 `policy`。 +- 智能体可仅覆盖 `retry.backoff` 的部分字段，并保留运行器中的同级 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 @@ -311,22 +397,22 @@ english_agent = Agent( ### 追踪客户端错误 401 -如果你遇到与追踪相关的错误，这是因为追踪数据会上传到 OpenAI 服务，而你没有 OpenAI API key。你有三个解决方案： +如果你遇到与追踪相关的错误，这是因为追踪会上传到 OpenAI 服务器，而你没有 OpenAI API 密钥。你有三个解决选项： 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)。 +2. 为追踪设置 OpenAI 密钥：[`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]。该 API 密钥仅用于上传追踪，且必须来自 [platform.openai.com](https://platform.openai.com/)。 +3. 使用非 OpenAI 追踪进程。参见[追踪文档](../tracing.md#custom-tracing-processors)。 ### Responses API 支持 -SDK 默认使用 Responses API，但大多数其他 LLM 提供方尚不支持。因此你可能会看到 404 或类似问题。可通过以下两种方式解决： +SDK 默认使用 Responses API，但多数其他 LLM 提供方尚不支持。因此你可能会看到 404 或类似问题。你有两种解决方式： -1. 调用 [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api]。这在你通过环境变量设置 `OPENAI_API_KEY` 和 `OPENAI_BASE_URL` 时适用。 +1. 调用 [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api]。当你通过环境变量设置 `OPENAI_API_KEY` 和 `OPENAI_BASE_URL` 时可用。 2. 使用 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]。示例见[这里](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)。 ### structured outputs 支持 -部分模型提供方不支持 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)。这有时会导致类似如下错误： +一些模型提供方不支持 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)。这有时会导致类似如下错误： ``` @@ -334,12 +420,12 @@ BadRequestError: Error code: 400 - {'error': {'message': "'response_format.type' ``` -这是某些模型提供方的短板——它们支持 JSON 输出，但不允许你指定输出所用的 `json_schema`。我们正在修复这一问题，但建议你优先依赖支持 JSON schema 输出的提供方，否则你的应用会经常因 JSON 格式错误而中断。 +这是一些模型提供方的短板——它们支持 JSON 输出，但不允许你为输出指定 `json_schema`。我们正在修复此问题，但建议依赖支持 JSON schema 输出的提供方，否则你的应用会经常因 JSON 格式错误而中断。 ## 跨提供方混用模型 -你需要了解不同模型提供方之间的特性差异，否则可能遇到错误。例如，OpenAI 支持 structured outputs、多模态输入以及托管文件检索与网络检索，但许多其他提供方不支持这些能力。请注意以下限制： +你需要了解不同模型提供方的功能差异，否则可能遇到错误。例如，OpenAI 支持 structured outputs、多模态输入，以及托管文件检索和网络检索，但许多其他提供方不支持这些功能。请注意以下限制： -- 不要向不支持的提供方发送其无法理解的 `tools` -- 在调用纯文本模型前过滤掉多模态输入 -- 注意：不支持结构化 JSON 输出的提供方会偶发产出无效 JSON。 \ No newline at end of file +- 不要向不支持的提供方发送它们无法理解的 `tools` +- 在调用仅文本模型前过滤掉多模态输入 +- 注意：不支持结构化 JSON 输出的提供方会偶发产生无效 JSON。 \ No newline at end of file diff --git a/docs/zh/running_agents.md b/docs/zh/running_agents.md index 40b1259df8..14712941d8 100644 --- a/docs/zh/running_agents.md +++ b/docs/zh/running_agents.md @@ -4,11 +4,11 @@ search: --- # 运行智能体 -你可以通过 [`Runner`][agents.run.Runner] 类运行智能体。你有 3 个选项： +你可以通过 [`Runner`][agents.run.Runner] 类来运行智能体。你有 3 个选项： -1. [`Runner.run()`][agents.run.Runner.run]，异步运行并返回 [`RunResult`][agents.result.RunResult]。 +1. [`Runner.run()`][agents.run.Runner.run]，异步运行并返回一个 [`RunResult`][agents.result.RunResult]。 2. [`Runner.run_sync()`][agents.run.Runner.run_sync]，这是一个同步方法，底层只是运行 `.run()`。 -3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed]，异步运行并返回 [`RunResultStreaming`][agents.result.RunResultStreaming]。它会以流式模式调用 LLM，并在事件到达时将其流式传给你。 +3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed]，异步运行并返回一个 [`RunResultStreaming`][agents.result.RunResultStreaming]。它以流式模式调用 LLM，并在接收到事件时将这些事件流式返回给你。 ```python from agents import Agent, Runner @@ -29,40 +29,40 @@ async def main(): ### 智能体循环 -当你在 `Runner` 中使用 run 方法时，需要传入一个起始智能体和输入。输入可以是： +当你在 `Runner` 中使用 run 方法时，你需要传入一个起始智能体和输入。输入可以是： -- 字符串（视为一条用户消息）， +- 一个字符串（视为用户消息）， - OpenAI Responses API 格式的输入项列表，或 -- 在恢复中断运行时传入 [`RunState`][agents.run_state.RunState]。 +- 在恢复中断运行时传入一个 [`RunState`][agents.run_state.RunState]。 -随后 runner 会运行一个循环： +随后 runner 会执行一个循环： 1. 我们使用当前输入为当前智能体调用 LLM。 -2. LLM 生成输出。 +2. LLM 生成其输出。 1. 如果 LLM 返回 `final_output`，循环结束并返回结果。 - 2. 如果 LLM 执行任务转移，我们会更新当前智能体和输入，然后重新运行循环。 - 3. 如果 LLM 产生工具调用，我们会执行这些工具调用、追加结果，然后重新运行循环。 + 2. 如果 LLM 执行任务转移，我们更新当前智能体和输入，并重新运行循环。 + 3. 如果 LLM 生成工具调用，我们执行这些工具调用，追加结果，并重新运行循环。 3. 如果超过传入的 `max_turns`，我们会抛出 [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] 异常。 !!! note - 判断 LLM 输出是否为“最终输出”的规则是：它生成了目标类型的文本输出，且没有工具调用。 + 判断 LLM 输出是否被视为“最终输出”的规则是：它生成了目标类型的文本输出，且没有工具调用。 ### 流式传输 -流式传输让你在 LLM 运行时额外接收流式事件。流结束后，[`RunResultStreaming`][agents.result.RunResultStreaming] 将包含本次运行的完整信息，包括所有新生成的输出。你可以调用 `.stream_events()` 获取流式事件。在[流式传输指南](streaming.md)中阅读更多内容。 +流式传输允许你在 LLM 运行时额外接收流式事件。流结束后，[`RunResultStreaming`][agents.result.RunResultStreaming] 将包含此次运行的完整信息，包括所有新生成的输出。你可以调用 `.stream_events()` 获取流式事件。在[流式传输指南](streaming.md)中阅读更多内容。 #### Responses WebSocket 传输（可选辅助） -如果你启用 OpenAI Responses websocket 传输，仍可继续使用常规 `Runner` API。推荐使用 websocket 会话辅助器来复用连接，但并非必需。 +如果你启用了 OpenAI Responses websocket 传输，仍可继续使用常规的 `Runner` API。建议使用 websocket session helper 以复用连接，但这不是必需的。 -这是通过 websocket 传输的 Responses API，而不是 [Realtime API](realtime/guide.md)。 +这是基于 websocket 传输的 Responses API，而不是 [Realtime API](realtime/guide.md)。 -关于传输选择规则以及具体模型对象或自定义 provider 的注意事项，请参见[模型](models/index.md#responses-websocket-transport)。 +关于传输选择规则，以及具体模型对象或自定义 provider 的注意事项，请参见[模型](models/index.md#responses-websocket-transport)。 -##### 模式 1：不使用会话辅助器（可用） +##### 模式 1：不使用 session helper（可用） -当你只想使用 websocket 传输且不需要 SDK 为你管理共享 provider/session 时，请使用此模式。 +当你只想使用 websocket 传输，且不需要 SDK 为你管理共享 provider/session 时使用此模式。 ```python import asyncio @@ -85,11 +85,11 @@ async def main(): asyncio.run(main()) ``` -这种模式适用于单次运行。如果你反复调用 `Runner.run()` / `Runner.run_streamed()`，除非你手动复用相同的 `RunConfig` / provider 实例，否则每次运行都可能重新连接。 +此模式适用于单次运行。如果你反复调用 `Runner.run()` / `Runner.run_streamed()`，除非你手动复用同一个 `RunConfig` / provider 实例，否则每次运行都可能重新连接。 ##### 模式 2：使用 `responses_websocket_session()`（推荐用于多轮复用） -当你希望在多次运行之间共享支持 websocket 的 provider 和 `RunConfig`（包括继承同一 `run_config` 的嵌套 Agents-as-tools 调用）时，请使用 [`responses_websocket_session()`][agents.responses_websocket_session]。 +当你希望在多次运行中共享具备 websocket 能力的 provider 和 `RunConfig`（包括继承同一 `run_config` 的嵌套 agent-as-tool 调用）时，请使用 [`responses_websocket_session()`][agents.responses_websocket_session]。 ```python import asyncio @@ -117,7 +117,7 @@ async def main(): asyncio.run(main()) ``` -请在上下文退出前完成对流式结果的消费。如果 websocket 请求仍在进行时就退出上下文，可能会强制关闭共享连接。 +请在上下文退出前完成对流式结果的消费。在 websocket 请求仍在进行时退出上下文，可能会强制关闭共享连接。 ### 运行配置 @@ -125,55 +125,55 @@ asyncio.run(main()) #### 常见运行配置目录 -使用 `RunConfig` 可以在不修改每个智能体定义的情况下，为单次运行覆盖行为。 +使用 `RunConfig` 可在不修改每个智能体定义的前提下覆盖单次运行行为。 ##### 模型、provider 与 session 默认值 -- [`model`][agents.run.RunConfig.model]：允许设置全局 LLM 模型，不受各 Agent 自身 `model` 设置影响。 -- [`model_provider`][agents.run.RunConfig.model_provider]：用于查找模型名称的模型 provider，默认是 OpenAI。 +- [`model`][agents.run.RunConfig.model]：允许设置一个全局 LLM 模型，不受各 Agent 自身 `model` 设置影响。 +- [`model_provider`][agents.run.RunConfig.model_provider]：用于查找模型名称的模型 provider，默认为 OpenAI。 - [`model_settings`][agents.run.RunConfig.model_settings]：覆盖智能体特定设置。例如，你可以设置全局 `temperature` 或 `top_p`。 - [`session_settings`][agents.run.RunConfig.session_settings]：在运行期间检索历史时，覆盖 session 级默认值（例如 `SessionSettings(limit=...)`）。 -- [`session_input_callback`][agents.run.RunConfig.session_input_callback]：在使用 Sessions 时，自定义每轮前如何将新用户输入与会话历史合并。该回调可为同步或异步。 +- [`session_input_callback`][agents.run.RunConfig.session_input_callback]：在使用 Sessions 时，自定义每轮前新用户输入与 session 历史的合并方式。该回调可以是同步或异步。 -##### 安全防护措施、任务转移与模型输入整形 +##### 安全防护措施、任务转移与模型输入塑形 -- [`input_guardrails`][agents.run.RunConfig.input_guardrails], [`output_guardrails`][agents.run.RunConfig.output_guardrails]：要在所有运行中包含的输入或输出安全防护措施列表。 -- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]：应用于所有任务转移的全局输入过滤器（如果该任务转移尚未设置过滤器）。输入过滤器允许你编辑发送到新智能体的输入。更多细节见 [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] 文档。 -- [`nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]：可选启用的 beta 功能，在调用下一个智能体前将先前转录折叠为单条 assistant 消息。默认禁用（我们仍在稳定嵌套任务转移）；设为 `True` 可启用，保持 `False` 则透传原始转录。当你不传入 `RunConfig` 时，所有 [Runner 方法][agents.run.Runner] 会自动创建一个，因此快速入门和示例默认保持关闭；任何显式的 [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] 回调仍会覆盖它。单个任务转移可通过 [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history] 覆盖该设置。 -- [`handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper]：可选可调用对象，在你启用 `nest_handoff_history` 时，每次都会接收标准化转录（历史 + 任务转移项）。它必须返回要转发给下一个智能体的精确输入项列表，使你无需编写完整任务转移过滤器即可替换内置摘要。 -- [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter]：在模型调用前立即编辑已完整准备的模型输入（instructions 和输入项）的钩子，例如裁剪历史或注入系统提示词。 -- [`reasoning_item_id_policy`][agents.run.RunConfig.reasoning_item_id_policy]：控制 runner 在将先前输出转换为下一轮模型输入时，是否保留或省略 reasoning 项 ID。 +- [`input_guardrails`][agents.run.RunConfig.input_guardrails], [`output_guardrails`][agents.run.RunConfig.output_guardrails]：包含在所有运行中的输入或输出安全防护措施列表。 +- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]：应用于所有任务转移的全局输入过滤器（如果该任务转移尚未设置过滤器）。输入过滤器允许你编辑发送给新智能体的输入。更多细节见 [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] 文档。 +- [`nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]：可选启用的测试版功能，在调用下一个智能体前将先前对话记录折叠为一条 assistant 消息。为稳定嵌套任务转移，该功能默认禁用；设为 `True` 启用，或保持 `False` 以传递原始记录。所有 [Runner 方法][agents.run.Runner] 在你未传入 `RunConfig` 时都会自动创建一个，因此快速开始和示例默认保持关闭，且任何显式的 [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] 回调仍会覆盖它。单个任务转移可通过 [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history] 覆盖此设置。 +- [`handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper]：可选可调用对象；当你启用 `nest_handoff_history` 时，它会接收规范化后的对话记录（历史 + 任务转移项）。它必须返回要转发给下一个智能体的精确输入项列表，让你无需编写完整任务转移过滤器即可替换内置摘要。 +- [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter]：在模型调用前立即编辑完整准备好的模型输入（instructions 与输入项）的钩子，例如裁剪历史或注入系统提示词。 +- [`reasoning_item_id_policy`][agents.run.RunConfig.reasoning_item_id_policy]：控制 runner 在将先前输出转换为下一轮模型输入时，是否保留或省略 reasoning item ID。 ##### 追踪与可观测性 - [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]：允许你为整个运行禁用[追踪](tracing.md)。 - [`tracing`][agents.run.RunConfig.tracing]：传入 [`TracingConfig`][agents.tracing.TracingConfig] 以覆盖本次运行的导出器、进程或追踪元数据。 -- [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]：配置追踪是否包含潜在敏感数据，如 LLM 与工具调用输入/输出。 -- [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]：设置本次运行的追踪工作流名称、追踪 ID 与追踪组 ID。我们建议至少设置 `workflow_name`。group ID 是可选字段，可用于跨多次运行关联追踪。 -- [`trace_metadata`][agents.run.RunConfig.trace_metadata]：包含在所有追踪中的元数据。 +- [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]：配置追踪中是否包含潜在敏感数据，例如 LLM 和工具调用的输入/输出。 +- [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]：为本次运行设置追踪工作流名称、trace ID 和 trace group ID。建议至少设置 `workflow_name`。group ID 是可选字段，可用于关联多次运行的 traces。 +- [`trace_metadata`][agents.run.RunConfig.trace_metadata]：包含在所有 traces 中的元数据。 ##### 工具审批与工具错误行为 -- [`tool_error_formatter`][agents.run.RunConfig.tool_error_formatter]：在审批流程中工具调用被拒绝时，自定义模型可见消息。 +- [`tool_error_formatter`][agents.run.RunConfig.tool_error_formatter]：在审批流中工具调用被拒绝时，自定义对模型可见的消息。 -嵌套任务转移作为可选启用的 beta 功能提供。可通过传入 `RunConfig(nest_handoff_history=True)` 启用折叠转录行为，或设置 `handoff(..., nest_handoff_history=True)` 仅对特定任务转移启用。若你更希望保留原始转录（默认行为），请保持该标志未设置，或提供会按你的需要原样转发对话的 `handoff_input_filter`（或 `handoff_history_mapper`）。若要在不编写自定义 mapper 的情况下修改生成摘要使用的包装文本，请调用 [`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers]（并通过 [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers] 恢复默认值）。 +嵌套任务转移作为可选启用测试版提供。可通过传入 `RunConfig(nest_handoff_history=True)` 启用折叠对话记录行为，或设置 `handoff(..., nest_handoff_history=True)` 为特定任务转移启用。若你希望保留原始对话记录（默认行为），请保持该标志未设置，或提供一个按需原样转发会话的 `handoff_input_filter`（或 `handoff_history_mapper`）。若你想在不编写自定义 mapper 的情况下修改生成摘要所用的包装文本，请调用 [`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers]（并使用 [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers] 恢复默认值）。 #### 运行配置细节 ##### `tool_error_formatter` -使用 `tool_error_formatter` 可在审批流程中工具调用被拒绝时，自定义返回给模型的消息。 +使用 `tool_error_formatter` 自定义在审批流中工具调用被拒绝时返回给模型的消息。 -格式化器接收包含以下字段的 [`ToolErrorFormatterArgs`][agents.run_config.ToolErrorFormatterArgs]： +格式化器会接收 [`ToolErrorFormatterArgs`][agents.run_config.ToolErrorFormatterArgs]，其中包含： - `kind`：错误类别。当前为 `"approval_rejected"`。 - `tool_type`：工具运行时（`"function"`、`"computer"`、`"shell"` 或 `"apply_patch"`）。 - `tool_name`：工具名称。 - `call_id`：工具调用 ID。 - `default_message`：SDK 默认的模型可见消息。 -- `run_context`：当前活动运行上下文包装器。 +- `run_context`：当前运行上下文包装器。 -返回字符串以替换该消息，或返回 `None` 以使用 SDK 默认值。 +返回字符串可替换该消息，返回 `None` 则使用 SDK 默认值。 ```python from agents import Agent, RunConfig, Runner, ToolErrorFormatterArgs @@ -198,22 +198,22 @@ result = Runner.run_sync( ##### `reasoning_item_id_policy` -`reasoning_item_id_policy` 控制当 runner 继续携带历史时（例如使用 `RunResult.to_input_list()` 或基于 session 的运行），如何将 reasoning 项转换为下一轮模型输入。 +`reasoning_item_id_policy` 控制当 runner 延续历史时（例如使用 `RunResult.to_input_list()` 或基于 session 的运行），reasoning items 如何被转换为下一轮模型输入。 -- `None` 或 `"preserve"`（默认）：保留 reasoning 项 ID。 -- `"omit"`：从生成的下一轮输入中移除 reasoning 项 ID。 +- `None` 或 `"preserve"`（默认）：保留 reasoning item ID。 +- `"omit"`：从生成的下一轮输入中移除 reasoning item ID。 -`"omit"` 主要用于可选缓解一类 Responses API 400 错误：当发送了带 `id` 的 reasoning 项，但缺少必需的后续项时（例如 `Item 'rs_...' of type 'reasoning' was provided without its required following item.`）。 +`"omit"` 主要作为可选缓解手段，用于应对一类 Responses API 400 错误：发送 reasoning item 时带有 `id`，但缺少其必需的后续项（例如 `Item 'rs_...' of type 'reasoning' was provided without its required following item.`）。 -这可能发生在多轮智能体运行中：SDK 从先前输出构造后续输入（包括 session 持久化、服务端管理的会话增量、流式/非流式后续轮次与恢复路径）时，保留了 reasoning 项 ID，但 provider 要求该 ID 必须与其对应后续项保持配对。 +这可能发生在多轮智能体运行中：SDK 从先前输出构造后续输入时（包括 session 持久化、服务端管理的会话增量、流式/非流式后续轮次，以及恢复路径），保留了 reasoning item ID，但 provider 要求该 ID 必须与对应后续项保持配对。 -设置 `reasoning_item_id_policy="omit"` 会保留 reasoning 内容，但移除 reasoning 项 `id`，从而避免在 SDK 生成的后续输入中触发该 API 不变量约束。 +设置 `reasoning_item_id_policy="omit"` 会保留 reasoning 内容，但移除 reasoning item 的 `id`，从而避免在 SDK 生成的后续输入中触发该 API 不变量约束。 -作用范围说明： +作用域说明： -- 这只会影响 SDK 在构建后续输入时生成/转发的 reasoning 项。 +- 这只会影响 SDK 在构建后续输入时生成/转发的 reasoning items。 - 不会改写用户提供的初始输入项。 -- 在应用此策略后，`call_model_input_filter` 仍可有意重新引入 reasoning ID。 +- `call_model_input_filter` 仍可在该策略应用后有意重新引入 reasoning IDs。 ## 状态与会话管理 @@ -221,33 +221,33 @@ result = Runner.run_sync( 将状态带入下一轮有四种常见方式： -| Strategy | Where state lives | Best for | What you pass on the next turn | +| 策略 | 状态存储位置 | 最佳适用场景 | 下一轮传入内容 | | --- | --- | --- | --- | -| `result.to_input_list()` | 你的应用内存 | 小型聊天循环、完全手动控制、任意 provider | 来自 `result.to_input_list()` 的列表加上下一个用户消息 | +| `result.to_input_list()` | 你的应用内存 | 小型聊天循环、完全手动控制、任意 provider | 来自 `result.to_input_list()` 的列表加上下一条用户消息 | | `session` | 你的存储加 SDK | 持久聊天状态、可恢复运行、自定义存储 | 同一个 `session` 实例，或指向同一存储的另一个实例 | -| `conversation_id` | OpenAI Conversations API | 你希望在多个 worker 或服务间共享的命名服务端会话 | 相同的 `conversation_id`，外加仅新的用户轮次 | -| `previous_response_id` | OpenAI Responses API | 无需创建会话资源的轻量级服务端托管延续 | `result.last_response_id`，外加仅新的用户轮次 | +| `conversation_id` | OpenAI Conversations API | 你希望跨 worker 或服务共享的命名服务端会话 | 同一个 `conversation_id`，并且只传入新的用户轮次 | +| `previous_response_id` | OpenAI Responses API | 无需创建 conversation 资源的轻量服务端管理续接 | `result.last_response_id`，并且只传入新的用户轮次 | -`result.to_input_list()` 与 `session` 属于客户端管理。`conversation_id` 与 `previous_response_id` 属于 OpenAI 管理，且仅在你使用 OpenAI Responses API 时适用。在大多数应用中，每个会话选择一种持久化策略即可。除非你有意协调这两层，否则混用客户端管理历史与 OpenAI 托管状态可能导致上下文重复。 +`result.to_input_list()` 和 `session` 由客户端管理。`conversation_id` 和 `previous_response_id` 由 OpenAI 管理，且仅在你使用 OpenAI Responses API 时适用。在多数应用中，每段会话选择一种持久化策略即可。除非你有意协调两层状态，否则混用客户端管理历史与 OpenAI 管理状态会导致上下文重复。 !!! note - Session 持久化不能与服务端托管会话设置 - （`conversation_id`、`previous_response_id` 或 `auto_previous_response_id`） - 在同一次运行中组合使用。每次调用请选择一种方式。 + Session 持久化不能与服务端管理会话设置 + （`conversation_id`、`previous_response_id` 或 `auto_previous_response_id`）在 + 同一次运行中组合使用。每次调用请选择一种方式。 ### 会话/聊天线程 -调用任一 run 方法都可能导致一个或多个智能体运行（从而发生一次或多次 LLM 调用），但它在聊天会话中表示单个逻辑轮次。例如： +调用任何 run 方法都可能导致一个或多个智能体运行（因此也会有一次或多次 LLM 调用），但它在聊天会话中代表一个逻辑轮次。例如： 1. 用户轮次：用户输入文本 -2. Runner 运行：第一个智能体调用 LLM、运行工具、将任务转移给第二个智能体，第二个智能体运行更多工具，然后生成输出。 +2. Runner 运行：第一个智能体调用 LLM，运行工具，任务转移到第二个智能体，第二个智能体运行更多工具，然后产出输出。 -在智能体运行结束时，你可以选择向用户展示什么。例如，你可以向用户展示智能体生成的每个新项，或只展示最终输出。无论哪种方式，用户随后都可能提出追问，此时你可以再次调用 run 方法。 +在智能体运行结束时，你可以选择向用户展示什么。例如，你可以展示智能体生成的每个新项，或仅展示最终输出。无论哪种方式，用户都可能继续追问，此时你可以再次调用 run 方法。 #### 手动会话管理 -你可以使用 [`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] 方法获取下一轮输入，从而手动管理会话历史： +你可以通过 [`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] 方法手动管理会话历史，以获取下一轮输入： ```python async def main(): @@ -267,9 +267,9 @@ async def main(): # California ``` -#### 使用 session 自动会话管理 +#### 使用 Sessions 的自动会话管理 -更简单的方法是使用[Sessions](sessions/index.md) 自动处理会话历史，而无需手动调用 `.to_input_list()`： +更简单的方法是使用 [Sessions](sessions/index.md) 自动处理会话历史，无需手动调用 `.to_input_list()`： ```python from agents import Agent, Runner, SQLiteSession @@ -299,18 +299,18 @@ Sessions 会自动： - 在每次运行后存储新消息 - 为不同 session ID 维护独立会话 -更多细节请参见 [Sessions 文档](sessions/index.md)。 +更多细节请参见[Sessions 文档](sessions/index.md)。 -#### 服务端托管会话 +#### 服务端管理会话 -你也可以让 OpenAI 会话状态功能在服务端管理会话状态，而不是在本地使用 `to_input_list()` 或 `Sessions` 处理。这使你无需手动重发全部历史消息也能保留会话历史。对于下面任一种服务端托管方式，每次请求只传入新一轮输入并复用已保存 ID。更多细节见 [OpenAI 会话状态指南](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses)。 +你也可以让 OpenAI 会话状态功能在服务端管理会话状态，而不是通过 `to_input_list()` 或 `Sessions` 在本地处理。这使你无需手动重发全部历史消息即可保留会话历史。对于下述任一服务端管理方式，每次请求仅传入新轮次输入并复用已保存 ID。更多细节请参见 [OpenAI 会话状态指南](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses)。 -OpenAI 提供两种跨轮次跟踪状态的方法： +OpenAI 提供了两种跨轮次跟踪状态的方式： ##### 1. 使用 `conversation_id` -你先使用 OpenAI Conversations API 创建会话，然后在后续每次调用中复用其 ID： +你先通过 OpenAI Conversations API 创建会话，然后在后续每次调用中复用其 ID： ```python from agents import Agent, Runner @@ -333,7 +333,7 @@ async def main(): ##### 2. 使用 `previous_response_id` -另一种选项是**响应链式传递**，每一轮都显式链接到前一轮的响应 ID。 +另一个选项是**响应链式连接**，即每一轮都显式关联到上一轮的 response ID。 ```python from agents import Agent, Runner @@ -358,29 +358,32 @@ async def main(): print(f"Assistant: {result.final_output}") ``` -如果某次运行因审批而暂停，并且你从 [`RunState`][agents.run_state.RunState] 恢复， +如果运行因审批而暂停，并且你从 [`RunState`][agents.run_state.RunState] 恢复， SDK 会保留保存的 `conversation_id` / `previous_response_id` / `auto_previous_response_id` -设置，从而使恢复后的轮次继续在同一服务端托管会话中进行。 +设置，使恢复后的轮次在同一个服务端管理会话中继续进行。 -`conversation_id` 与 `previous_response_id` 互斥。若你希望使用可在系统间共享的命名会话资源，请使用 `conversation_id`。若你希望使用从一轮到下一轮最轻量的 Responses API 延续机制，请使用 `previous_response_id`。 +`conversation_id` 和 `previous_response_id` 互斥。当你希望使用可跨系统共享的命名会话资源时使用 `conversation_id`。当你希望使用从一轮到下一轮最轻量的 Responses API 续接原语时使用 `previous_response_id`。 !!! note - SDK 会自动对 `conversation_locked` 错误执行带退避的重试。在服务端托管 - 会话运行中，它会在重试前回滚内部会话跟踪器输入，以便可干净地重新发送 - 相同的已准备项。 + SDK 会自动重试 `conversation_locked` 错误并使用退避策略。在服务端管理 + 会话的运行中，它会在重试前回退内部的会话跟踪器输入，以便可干净地 + 重新发送相同的已准备项。 在本地基于 session 的运行中（不能与 `conversation_id`、 - `previous_response_id` 或 `auto_previous_response_id` 组合使用），SDK 也会尽力 + `previous_response_id` 或 `auto_previous_response_id` 结合使用），SDK 也会尽力 回滚最近持久化的输入项，以减少重试后重复历史条目。 + 即使你没有配置 `ModelSettings.retry`，此兼容性重试也会发生。有关模型请求 + 更广泛的可选重试行为，请参见[Runner 管理重试](models/index.md#runner-managed-retries)。 + ## 钩子与自定义 -### 模型调用输入过滤器 +### 调用模型输入过滤器 -使用 `call_model_input_filter` 可在模型调用前立即编辑模型输入。该钩子接收当前智能体、上下文和合并后的输入项（若存在 session 历史也包含在内），并返回新的 `ModelInputData`。 +使用 `call_model_input_filter` 在模型调用前编辑模型输入。该钩子接收当前智能体、上下文以及合并后的输入项（若存在 session 历史则包含其内容），并返回新的 `ModelInputData`。 -返回值必须是 [`ModelInputData`][agents.run.ModelInputData] 对象。其 `input` 字段为必填，且必须是输入项列表。返回其他结构会抛出 `UserError`。 +返回值必须是 [`ModelInputData`][agents.run.ModelInputData] 对象。其中 `input` 字段是必填项，且必须为输入项列表。返回任何其他结构都会抛出 `UserError`。 ```python from agents import Agent, Runner, RunConfig @@ -399,19 +402,19 @@ result = Runner.run_sync( ) ``` -runner 会将已准备输入列表的副本传给钩子，因此你可以裁剪、替换或重排它，而不会原地修改调用方的原始列表。 +runner 会将准备好的输入列表副本传递给该钩子，因此你可以裁剪、替换或重排输入，而无需原地修改调用方原始列表。 -如果你正在使用 session，`call_model_input_filter` 会在 session 历史已加载并与当前轮次合并后运行。如果你想自定义更早的合并步骤本身，请使用 [`session_input_callback`][agents.run.RunConfig.session_input_callback]。 +如果你使用 session，`call_model_input_filter` 会在 session 历史已加载并与当前轮次合并后运行。若你希望自定义更早阶段的合并步骤，请使用 [`session_input_callback`][agents.run.RunConfig.session_input_callback]。 -如果你正在使用 `conversation_id`、`previous_response_id` 或 `auto_previous_response_id` 的 OpenAI 服务端托管会话状态，该钩子会作用于下一次 Responses API 调用的已准备负载。该负载可能已仅表示新轮次增量，而非完整重放历史。只有你返回的项会被标记为已发送，用于该服务端托管延续。 +如果你使用 `conversation_id`、`previous_response_id` 或 `auto_previous_response_id` 的 OpenAI 服务端管理会话状态，该钩子会作用于下一次 Responses API 调用的已准备 payload。该 payload 可能已经只是新轮次增量，而不是完整重放早期历史。你返回的项才会被标记为该服务端管理续接中的已发送内容。 -通过 `run_config` 按运行设置该钩子，可用于脱敏、裁剪长历史或注入额外系统指引。 +通过 `run_config` 按次设置此钩子，以便脱敏敏感数据、裁剪过长历史或注入额外系统指导。 ## 错误与恢复 ### 错误处理器 -所有 `Runner` 入口都接受 `error_handlers`（按错误类型键控的字典）。当前支持的键是 `"max_turns"`。当你希望返回受控最终输出而非抛出 `MaxTurnsExceeded` 时可使用它。 +所有 `Runner` 入口点都接受 `error_handlers`，这是一个按错误类型键控的字典。当前支持的键是 `"max_turns"`。当你希望返回可控的最终输出而不是抛出 `MaxTurnsExceeded` 时可使用它。 ```python from agents import ( @@ -440,35 +443,35 @@ result = Runner.run_sync( print(result.final_output) ``` -当你不希望将回退输出追加到会话历史时，设置 `include_in_history=False`。 +当你不希望回退输出被追加到会话历史时，设置 `include_in_history=False`。 -## 持久执行集成与 human-in-the-loop +## 持久化执行集成与 human-in-the-loop -对于工具审批暂停/恢复模式，请先阅读专门的 [Human-in-the-loop 指南](human_in_the_loop.md)。 -下面的集成适用于运行可能跨越长时间等待、重试或进程重启的持久化编排场景。 +对于工具审批暂停/恢复模式，请先阅读专门的[Human-in-the-loop 指南](human_in_the_loop.md)。 +以下集成用于运行可能跨越长时间等待、重试或进程重启的持久化编排场景。 ### Temporal -你可以使用 Agents SDK 的 [Temporal](https://temporal.io/) 集成来运行持久化、长时工作流，包括 human-in-the-loop 任务。查看 Temporal 与 Agents SDK 协同完成长时任务的演示[视频](https://www.youtube.com/watch?v=fFBZqzT4DD8)，并在[此处查看文档](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/openai_agents)。 +你可以使用 Agents SDK 的 [Temporal](https://temporal.io/) 集成来运行持久化的长时间工作流，包括 human-in-the-loop 任务。你可以在[此视频](https://www.youtube.com/watch?v=fFBZqzT4DD8)中查看 Temporal 与 Agents SDK 协作完成长时任务的演示，也可以[在此查看文档](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/openai_agents)。 ### Restate -你可以使用 Agents SDK 的 [Restate](https://restate.dev/) 集成来实现轻量、持久的智能体能力，包括人工审批、任务转移和 session 管理。该集成依赖 Restate 的单二进制运行时，并支持将智能体作为进程/容器或无服务器函数运行。 -请阅读[概览](https://www.restate.dev/blog/durable-orchestration-for-ai-agents-with-restate-and-openai-sdk)或查看[文档](https://docs.restate.dev/ai)了解更多细节。 +你可以使用 Agents SDK 的 [Restate](https://restate.dev/) 集成来构建轻量、持久化智能体，支持人工审批、任务转移与会话管理。该集成依赖 Restate 的单二进制运行时，并支持将智能体作为进程/容器或无服务器函数运行。 +更多细节请阅读[概览](https://www.restate.dev/blog/durable-orchestration-for-ai-agents-with-restate-and-openai-sdk)或查看[文档](https://docs.restate.dev/ai)。 ### DBOS -你可以使用 Agents SDK 的 [DBOS](https://dbos.dev/) 集成来运行可靠智能体，在故障与重启间保留进度。它支持长时智能体、human-in-the-loop 工作流和任务转移，并同时支持同步与异步方法。该集成仅需 SQLite 或 Postgres 数据库。请查看集成 [repo](https://github.com/dbos-inc/dbos-openai-agents) 和[文档](https://docs.dbos.dev/integrations/openai-agents)了解更多细节。 +你可以使用 Agents SDK 的 [DBOS](https://dbos.dev/) 集成来运行可靠智能体，在故障与重启间保留进度。它支持长时间运行的智能体、human-in-the-loop 工作流与任务转移。它同时支持同步与异步方法。该集成仅需 SQLite 或 Postgres 数据库。更多细节请查看集成 [repo](https://github.com/dbos-inc/dbos-openai-agents) 和[文档](https://docs.dbos.dev/integrations/openai-agents)。 ## 异常 SDK 在某些情况下会抛出异常。完整列表见 [`agents.exceptions`][]。概览如下： -- [`AgentsException`][agents.exceptions.AgentsException]：这是 SDK 内所有异常的基类，作为其他具体异常派生的通用类型。 +- [`AgentsException`][agents.exceptions.AgentsException]：这是 SDK 内抛出的所有异常的基类。它作为通用类型，其他具体异常均派生自它。 - [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]：当智能体运行超过传给 `Runner.run`、`Runner.run_sync` 或 `Runner.run_streamed` 方法的 `max_turns` 限制时抛出。它表示智能体无法在指定交互轮次数内完成任务。 -- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]：当底层模型（LLM）产生意外或无效输出时发生。包括： - - JSON 格式错误：当模型在工具调用或其直接输出中提供了格式错误的 JSON 结构，尤其是在定义了特定 `output_type` 时。 +- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]：当底层模型（LLM）生成意外或无效输出时发生。包括： + - JSON 格式错误：当模型为工具调用或直接输出提供了格式错误的 JSON 结构时，尤其是定义了特定 `output_type` 的情况下。 - 与工具相关的意外失败：当模型未按预期方式使用工具时 -- [`ToolTimeoutError`][agents.exceptions.ToolTimeoutError]：当工具调用超过其配置超时时间，且该工具使用 `timeout_behavior="raise_exception"` 时抛出。 -- [`UserError`][agents.exceptions.UserError]：当你（使用 SDK 编写代码的人）在使用 SDK 时发生错误而抛出。通常源于代码实现不正确、配置无效或误用 SDK API。 -- [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]：当输入安全防护措施或输出安全防护措施的触发条件分别满足时抛出。输入安全防护措施会在处理前检查传入消息，而输出安全防护措施会在交付前检查智能体最终响应。 \ No newline at end of file +- [`ToolTimeoutError`][agents.exceptions.ToolTimeoutError]：当工具调用超过配置超时时间且工具使用 `timeout_behavior="raise_exception"` 时抛出。 +- [`UserError`][agents.exceptions.UserError]：当你（使用 SDK 编写代码的人）在使用 SDK 时出错而抛出。通常由代码实现不正确、配置无效或误用 SDK API 导致。 +- [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]：当输入安全防护措施或输出安全防护措施的触发条件分别满足时抛出。输入安全防护措施在处理前检查传入消息，输出安全防护措施在交付前检查智能体最终响应。 \ No newline at end of file